diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index 3610957414..6d7574fe4f 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -9,6 +9,20 @@ Enum that contains the following elements: - JERRY_INIT_SHOW_REGEXP_OPCODES - dump regexp byte-code to log after compilation - JERRY_INIT_MEM_STATS - dump memory statistics + *`JERRY_INIT_MEM_STATS_SEPARATE` and `JERRY_INIT_DEBUGGER`, which were deprecated in version 2.0, have been completely removed in version 3.0*. + +## jerry_log_level_t + +Enum that represents the configurable logging levels. +The levels are ordered by severity, with the most serious levels listed first.. + + - JERRY_LOG_LEVEL_ERROR - the engine will terminate after the message is printed + - JERRY_LOG_LEVEL_WARNING - a request is aborted, but the engine continues its operation + - JERRY_LOG_LEVEL_DEBUG - debug messages from the engine, low volume + - JERRY_LOG_LEVEL_TRACE - detailed info about engine internals, potentially high volume + +*Introduced in version 3.0*. + ## jerry_type_t Enum that contains JerryScript API value types: @@ -25,9 +39,9 @@ Enum that contains JerryScript API value types: - JERRY_TYPE_SYMBOL - symbol type - JERRY_TYPE_BIGINT - bigint type -*New in version 2.0*. +*Introduced in version 2.0*. -*Changed in version 2.4*: Added `JERRY_TYPE_BIGINT` value. +*Updated in version 2.4*: Added `JERRY_TYPE_BIGINT` value. ## jerry_object_type_t @@ -49,7 +63,6 @@ Enum that contains JerryScript **object** value types: - JERRY_OBJECT_TYPE_ERROR - Error object (see [jerry_error_type](#jerry_error_type)) - JERRY_OBJECT_TYPE_ARRAYBUFFER - ArrayBuffer object - JERRY_OBJECT_TYPE_SHARED_ARRAYBUFFER - SharedArrayBuffer object - - JERRY_OBJECT_TYPE_ARGUMENTS - Arguments object - JERRY_OBJECT_TYPE_BOOLEAN - Boolean object - JERRY_OBJECT_TYPE_DATE - Date object @@ -61,9 +74,9 @@ Enum that contains JerryScript **object** value types: - JERRY_OBJECT_TYPE_BIGINT - BigInt object - JERRY_OBJECT_TYPE_WEAKREF - WeakRef object -*New in version 2.4*. +*Introduced in version 2.4*. -*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_OBJECT_TYPE_MODULE_NAMESPACE`, `JERRY_OBJECT_TYPE_PROMISE`, `JERRY_OBJECT_TYPE_DATAVIEW`, +*Updated in version 3.0*: Added `JERRY_OBJECT_TYPE_MODULE_NAMESPACE`, `JERRY_OBJECT_TYPE_PROMISE`, `JERRY_OBJECT_TYPE_DATAVIEW`, `JERRY_OBJECT_TYPE_ERROR`, `JERRY_OBJECT_TYPE_SHARED_ARRAYBUFFER`, `JERRY_OBJECT_TYPE_WEAKREF`, `JERRY_OBJECT_TYPE_SCRIPT`, and `JERRY_OBJECT_TYPE_MODULE` values. @@ -78,7 +91,7 @@ Enum that contains JerryScript **function** value types: - JERRY_FUNCTION_TYPE_ARROW - Arrow function - JERRY_FUNCTION_TYPE_GENERATOR - Generator function object -*New in version 2.4*. +*Introduced in version 2.4*. ## jerry_iterator_type_t @@ -90,7 +103,7 @@ Enum that contains JerryScript **iterator** value types: - JERRY_ITERATOR_TYPE_MAP - Map iterator - JERRY_ITERATOR_TYPE_SET - Set iterator -*New in version 2.4*. +*Introduced in version 2.4*. ## jerry_proxy_custom_behavior_t @@ -98,11 +111,11 @@ These option bits allow specializing Proxies with non-standard behaviour. These flags are recommended only for those trusted Proxies, whose handlers produce correct results. -- JERRY_PROXY_SKIP_RESULT_VALIDATION - skip result validation for [[GetPrototypeOf]], [[SetPrototypeOf]], [[IsExtensible]], - [[PreventExtensions]], [[GetOwnProperty]], [[DefineOwnProperty]], [[HasProperty]], - [[Get]], [[Set]], [[Delete]] and [[OwnPropertyKeys]] +- JERRY_PROXY_SKIP_RESULT_VALIDATION - skip result validation for `[[GetPrototypeOf]]`, `[[SetPrototypeOf]]`, `[[IsExtensible]]`, + `[[PreventExtensions]]`, `[[GetOwnProperty]]`, `[[DefineOwnProperty]]`, `[[HasProperty]]`, + `[[Get]]`, `[[Set]]`, `[[Delete]]` and `[[OwnPropertyKeys]]` -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. ## jerry_property_filter_t @@ -118,9 +131,9 @@ Enum that contains JerryScript **property filter** options bits: - JERRY_PROPERTY_FILTER_EXCLUDE_INTEGER_INDICES - Exclude property key if it is an integer index - JERRY_PROPERTY_FILTER_INTEGER_INDICES_AS_NUMBER - By default integer index property keys are converted to string. Enabling this flags keeps integer index property keys as numbers -*New in version 2.4*. +*Introduced in version 2.4*. -*Changed in version [[NEXT_RELEASE]]*: The following values are modified due to a typo in their names (exlcude/exclude): +*Updated in version 3.0*: The following values have been modified due to typos in their names: `JERRY_PROPERTY_FILTER_EXLCUDE_NON_CONFIGURABLE`, `JERRY_PROPERTY_FILTER_EXLCUDE_NON_ENUMERABLE`, `JERRY_PROPERTY_FILTER_EXLCUDE_NON_WRITABLE`, `JERRY_PROPERTY_FILTER_EXLCUDE_STRINGS`, `JERRY_PROPERTY_FILTER_EXLCUDE_SYMBOLS`, `JERRY_PROPERTY_FILTER_EXLCUDE_INTEGER_INDICES`. @@ -129,18 +142,19 @@ Enum that contains JerryScript **property filter** options bits: Possible types of an Error object: - - JERRY_ERROR_COMMON - common error - - JERRY_ERROR_EVAL - eval error - - JERRY_ERROR_RANGE - range error - - JERRY_ERROR_REFERENCE - reference error - - JERRY_ERROR_SYNTAX - syntax error - - JERRY_ERROR_TYPE - type error - - JERRY_ERROR_URI - URI error + - JERRY_ERROR_COMMON - Error + - JERRY_ERROR_EVAL - EvalError + - JERRY_ERROR_RANGE - RangeError + - JERRY_ERROR_REFERENCE - ReferenceError + - JERRY_ERROR_SYNTAX - SyntaxError + - JERRY_ERROR_TYPE - TypeError + - JERRY_ERROR_URI - URIError + - JERRY_ERROR_AGGREGATE - AggregateError There is also a special value `JERRY_ERROR_NONE` which is not an error type this value can only be returned by the [jerry_error_type](#jerry_error_type). -*Changed in version 2.0*: The `JERRY_ERROR_NONE` was added to be used by the [jerry_error_type](#jerry_error_type) method. +*Updated in version 2.0*: The `JERRY_ERROR_NONE` was added to be used by the [jerry_error_type](#jerry_error_type) method. ## jerry_feature_t @@ -158,7 +172,6 @@ Possible compile time enabled feature types: - JERRY_FEATURE_VM_EXEC_STOP - stopping ECMAScript execution - JERRY_FEATURE_VM_THROW - capturing ECMAScript throws - JERRY_FEATURE_JSON - JSON support - - JERRY_FEATURE_PROMISE - promise support - JERRY_FEATURE_TYPEDARRAY - Typedarray support - JERRY_FEATURE_DATE - Date support - JERRY_FEATURE_REGEXP - RegExp support @@ -179,15 +192,16 @@ Possible compile time enabled feature types: - JERRY_FEATURE_WEAKREF - WeakRef support - JERRY_FEATURE_FUNCTION_TO_STRING - function toString support -*New in version 2.0*. +*Introduced in version 2.0*. -*Changed in version 2.3*: Added `JERRY_FEATURE_WEAKMAP`, `JERRY_FEATURE_WEAKSET` values. +*Updated in version 2.3*: Added `JERRY_FEATURE_WEAKMAP`, `JERRY_FEATURE_WEAKSET` values. -*Changed in version 2.4*: Added `JERRY_FEATURE_BIGINT`, `JERRY_FEATURE_REALM` values. +*Updated in version 2.4*: Added `JERRY_FEATURE_BIGINT`, `JERRY_FEATURE_REALM` values. -*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_FEATURE_VM_THROW`, `JERRY_FEATURE_GLOBAL_THIS`, - `JERRY_FEATURE_PROMISE_CALLBACK`, and `JERRY_FEATURE_MODULE`, - `JERRY_FEATURE_WEAKREF`, and `JERRY_FEATURE_FUNCTION_TO_STRING` values. +*Updated in version 3.0*: Added `JERRY_FEATURE_VM_THROW`, `JERRY_FEATURE_GLOBAL_THIS`, + `JERRY_FEATURE_PROMISE_CALLBACK`, and `JERRY_FEATURE_MODULE`, + `JERRY_FEATURE_WEAKREF`, and `JERRY_FEATURE_FUNCTION_TO_STRING` values. + Removed `JERRY_FEATURE_PROMISE.` ## jerry_container_type_t @@ -199,7 +213,7 @@ Container object types: - JERRY_CONTAINER_TYPE_WEAKMAP - WeakMap type - JERRY_CONTAINER_TYPE_WEAKSET - WeakSet type - *New in version 2.3*. + *Introduced in version 2.3*. ## jerry_well_known_symbol_t @@ -219,7 +233,7 @@ Well-known symbols: - JERRY_SYMBOL_UNSCOPABLES - @@unscopables well-known symbol - JERRY_SYMBOL_MATCH_ALL - @@matchAll well-known symbol - *New in version 2.4*. + *Introduced in version 2.4*. ## jerry_regexp_flags_t @@ -238,9 +252,9 @@ RegExp object optional flags: additionally match the following line terminator ("newline") characters in a string; -*New in version 2.0*. +*Introduced in version 2.0*. -*Changed in version 2.4*: Added `JERRY_REGEXP_FLAG_STICKY`, `JERRY_REGEXP_FLAG_UNICODE` , `JERRY_REGEXP_FLAG_DOTALL` values. +*Updated in version 2.4*: Added `JERRY_REGEXP_FLAG_STICKY`, `JERRY_REGEXP_FLAG_UNICODE` , `JERRY_REGEXP_FLAG_DOTALL` values. ## jerry_parse_option_enable_feature_t @@ -255,7 +269,7 @@ Option bits for [jerry_parse_options_t](#jerry_parse_options_t). - JERRY_PARSE_HAS_START - `start_line` and `start_column` fields are valid - JERRY_PARSE_HAS_USER_VALUE - `user_value` field is valid -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. Using both `JERRY_PARSE_MODULE` and `JERRY_PARSE_HAS_ARGUMENT_LIST` is an invalid combination and will result in an exception during parsing. @@ -264,6 +278,7 @@ an exception during parsing. - [jerry_parse_options_t](#jerry_parse_options_t) + ## jerry_gc_mode_t Set garbage collection operational mode @@ -276,7 +291,8 @@ is that the former keeps memory allocated for performance improvements such as property hash tables for large objects. The latter frees all possible memory blocks but the performance may drop after the garbage collection. -*New in version 2.0*. +*Introduced in version 2.0*. + ## jerry_frame_type_t @@ -285,7 +301,8 @@ List of backtrace frame types returned by - JERRY_BACKTRACE_FRAME_JS - indicates that the frame is created for a JavaScript function/method -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. + ## jerry_generate_snapshot_opts_t @@ -313,9 +330,10 @@ strings are set by [jerry_register_magic_strings](#jerry_register_magic_strings) when the snapshot is generated and executed. Furthermore the `JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed. -*New in version 2.0*. +*Introduced in version 2.0*. + +*Updated in version 3.0*: The `JERRY_SNAPSHOT_SAVE_STRICT` value is removed, `JERRY_PARSE_STRICT_MODE` should be used instead. -*Changed in version [[NEXT_RELEASE]]*: The `JERRY_SNAPSHOT_SAVE_STRICT` value is removed, `JERRY_PARSE_STRICT_MODE` should be used instead. ## jerry_exec_snapshot_opts_t @@ -329,7 +347,7 @@ Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) functions: - JERRY_SNAPSHOT_EXEC_HAS_USER_VALUE - `user_value` field is valid in [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t) -*Changed in version [[NEXT_RELEASE]]*: The `JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION` value is added, +*Updated in version 3.0*: The `JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION` value is added, which replaces the `jerry_load_function_snapshot` function. **Copy snapshot data into memory** @@ -344,7 +362,8 @@ parts of the snapshot buffer into memory. The `JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed for static snapshots. -*New in version 2.0*. +*Introduced in version 2.0*. + ## jerry_char_t @@ -382,6 +401,15 @@ Jerry's length typedef uint32_t jerry_length_t; ``` +## jerry_encoding_t + +Supported string encodings. + + - JERRY_ENCODING_CESU8 - cesu-8 encoding + - JERRY_ENCODING_UTF8 - utf-8 encoding + +*Introduced in version 3.0*. + ## jerry_value_t **Summary** @@ -399,6 +427,7 @@ Returned and created values by the API functions must be freed with typedef uint32_t jerry_value_t; ``` + ## jerry_context_data_manager_t **Summary** @@ -456,7 +485,8 @@ typedef struct } jerry_context_data_manager_t; ``` -*New in version 2.0*. +*Introduced in version 2.0*. + ## jerry_context_alloc_t @@ -473,7 +503,9 @@ typedef void *(*jerry_context_alloc_t) (size_t size, void *cb_data_p); - `size` - allocation size - `cb_data_p` - pointer to user data -*New in version 2.0*. +**Introduced in version 2.0*.* +*External context allocation has been moved to the port API in version 3.0.* + ## jerry_context_t @@ -487,7 +519,7 @@ An opaque declaration of the JerryScript context structure. typedef struct jerry_context_t jerry_context_t; ``` -*New in version 2.0*. +*Introduced in version 2.0*. ## jerry_container_op_t @@ -500,7 +532,7 @@ Enum that contains the supported container operation types - JERRY_CONTAINER_OP_SIZE - Set/WeakSet/Map/WeakMap size operation - JERRY_CONTAINER_OP_CLEAR - Set/Map clear operation -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. ## jerry_binary_op_t @@ -518,7 +550,7 @@ Enum that contains the supported binary operation types - JERRY_BIN_OP_DIV - division operator (/) - JERRY_BIN_OP_REM - remainder operator (%) -*New in version 2.0*. +*Introduced in version 2.0*. **See also** @@ -540,7 +572,7 @@ Enum that contains the flags of property descriptors. - JERRY_PROP_IS_SET_DEFINED - Is [[Set]] defined? - JERRY_PROP_SHOULD_THROW - Should throw in case of an exception, instead of returning with false -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -570,7 +602,7 @@ typedef struct } jerry_parse_options_t; ``` -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -604,10 +636,10 @@ typedef struct } jerry_property_descriptor_t; ``` -*Changed in version [[NEXT_RELEASE]]*: The `is_value_defined`, `is_get_defined`, `is_set_defined`, - `is_writable_defined`, `is_writable`, `is_enumerable_defined`, - `is_enumerable`, `is_configurable_defined`, and `is_configurable` - fields are replaced by the `flags` field. +*Updated in version 3.0*: The `is_value_defined`, `is_get_defined`, `is_set_defined`, + `is_writable_defined`, `is_writable`, `is_enumerable_defined`, + `is_enumerable`, `is_configurable_defined`, and `is_configurable` + fields are replaced by the `flags` field. **See also** @@ -632,7 +664,7 @@ typedef struct } jerry_frame_location_t; ``` -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_backtrace_location_t` in earlier versions.* ## jerry_frame_t @@ -656,7 +688,7 @@ struct jerry_frame_internal_t; typedef struct jerry_frame_internal_t jerry_frame_t; ``` -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. ## jerry_heap_stats_t @@ -678,7 +710,7 @@ typedef struct } jerry_heap_stats_t; ``` -*New in version 2.0*. +*Introduced in version 2.0*. **See also** @@ -701,7 +733,7 @@ typedef struct jerry_call_info_t } jerry_call_info_t; ``` -*New in version [[NEXT_RELEASE]]*. Contents of this struct replaces the `jerry_get_new_target` function. +*Introduced in version 3.0*. Contents of this struct replaces the `jerry_get_new_target` function. **See also** @@ -747,7 +779,7 @@ Native free callback of generic value types. typedef void (*jerry_value_free_callback_t) (void *native_p); ``` -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -774,11 +806,11 @@ typedef void (*jerry_object_native_free_cb_t) (void *native_p, struct jerry_obje - `native_p` - native pointer passed to [jerry_object_set_native_ptr](#jerry_object_set_native_ptr). - `info_p` - native type info passed to [jerry_object_set_native_ptr](#jerry_object_set_native_ptr). -*New in version 2.0*: Renamed from `jerry_object_free_callback_t`. +*Introduced in version 2.0*: Renamed from `jerry_object_free_callback_t`. -*Changed in version 2.2*: API calls are once again allowed. (See note) +*Updated in version 2.2*: API calls are once again allowed. (See note) -*Changed in version [[NEXT_RELEASE]]*: `info_p` argument is added +*Updated in version 3.0*: `info_p` argument is added and renamed, it was previously known as `jerry_object_native_free_callback_t` in earlier versions. **See also** @@ -804,7 +836,7 @@ typedef void (*jerry_external_string_free_cb_t) (jerry_char_t *string_p, - `string_size` - size of external string - `user_p` - pointer passed when the external string is created -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_external_string_free_callback_t` in earlier versions.* **See also** @@ -833,7 +865,9 @@ typedef void (*jerry_error_object_created_cb_t) (const jerry_value_t error_objec - `error_object` - the newly created Error object. - `user_p` - pointer passed to [jerry_error_on_created](#jerry_error_on_created). -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_error_object_created_callback_t` in earlier versions.* **See also** @@ -851,7 +885,7 @@ An enum representing the current status of a module - JERRY_MODULE_STATE_EVALUATED - Module has been evaluated (its source code has been executed) - JERRY_MODULE_STATE_ERROR - An exception has been encountered before the evaluated state is reached -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. ## jerry_module_resolve_cb_t @@ -878,7 +912,7 @@ typedef jerry_value_t (*jerry_module_resolve_cb_t) (const jerry_value_t specifie - a module object - if it can be resolved successfully - an exception - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_resolve_callback_t` in earlier versions.* **See also** - [jerry_module_link](#jerry_module_link) @@ -920,7 +954,7 @@ typedef jerry_value_t (*jerry_module_import_cb_t) (const jerry_value_t specifier - promise or resolved module - if the operation is successful - an exception - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_import_callback_t` in earlier versions.* **See also** - [jerry_module_on_import](#jerry_module_on_import) @@ -947,7 +981,7 @@ typedef void (*jerry_module_state_changed_cb_t) (jerry_module_state_t new_state, and exception value for error state. - `user_p` - pointer passed to [jerry_module_on_state_changed](#jerry_module_on_state_changed). -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_state_changed_callback_t` in earlier versions.* **See also** - [jerry_module_on_state_changed](#jerry_module_on_state_changed) @@ -972,7 +1006,7 @@ typedef void (*jerry_module_import_meta_cb_t) (const jerry_value_t module, - `meta_object` - import.meta object created for the module. - `user_p` - pointer passed to [jerry_module_on_import_meta](#jerry_module_on_import_meta). -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_import_meta_callback_t` in earlier versions.* **See also** - [jerry_module_on_import_meta](#jerry_module_on_import_meta) @@ -998,7 +1032,7 @@ typedef jerry_value_t (*jerry_native_module_evaluate_cb_t) (const jerry_value_t - any non-exception value - if the module is evaluated successfully - an exception - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_native_module_evaluate_callback_t` in earlier versions.* **See also** - [jerry_module_evaluate](#jerry_module_evaluate) @@ -1022,7 +1056,7 @@ typedef bool (*jerry_backtrace_cb_t) (jerry_frame_t *frame_p, void *user_p); - true, to continue capturing more frames - false, to end the stack capturing -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_backtrace_callback_t` in earlier versions.* **See also** @@ -1071,9 +1105,9 @@ typedef struct } jerry_object_native_info_t; ``` -*New in version 2.0*. +*Introduced in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: Added `number_of_references`, and `offset_of_references` fields. +*Updated in version 3.0*: Added `number_of_references`, and `offset_of_references` fields. **See also** @@ -1107,6 +1141,8 @@ typedef bool (*jerry_object_property_foreach_cb_t) (const jerry_value_t property - true, to continue the iteration - false, to stop the iteration +*Renamed in version 3.0, it was previously known as `jerry_object_property_foreach_t` in earlier versions.* + **See also** - [jerry_object_foreach](#jerry_object_foreach) @@ -1132,7 +1168,9 @@ typedef bool (*jerry_foreach_live_object_cb_t) (const jerry_value_t object, - true, to continue the iteration - false, to stop the iteration -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_objects_foreach_t` in earlier versions.* **See also** @@ -1161,7 +1199,9 @@ typedef bool (*jerry_foreach_live_object_with_info_cb_t) (const jerry_value_t ob - true, to continue the iteration - false, to stop the iteration -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_objects_foreach_by_native_info_t` in earlier versions.* **See also** @@ -1182,7 +1222,7 @@ threw an exception. In this case the function must throw the same exception agai typedef jerry_value_t (*jerry_halt_cb_t) (void *user_p); ``` -*New in version 2.0*. +*Introduced in version 2.0*. **See also** @@ -1205,15 +1245,38 @@ Note: **Prototype** ```c -typedef void (*jerry_throw_cb_t) (const jerry_value_t error_value, void *user_p); +typedef void (*jerry_throw_cb_t) (const jerry_value_t exception_value, void *user_data_p); ``` + - `exception_value` - the thrown exception + - `user_data_p` - optional user data pointer -*New in [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_vm_throw_callback_t` in earlier versions.* **See also** - [jerry_on_throw](#jerry_on_throw) + +## jerry_string_iterate_cb_t + +**Summary** + +**Prototype** + +```c +typedef void (*jerry_string_iterate_cb_t) (uint32_t value, void *user_data_p); +``` + +- `value` - encoded byte value +- `user_data_p` - optional user data pointer supplied via the (jerry_string_iterate)[#jerry_string_iterate] method. + +*Introduced in version 3.0*. + +**See also** + +- [jerry_string_iterate](#jerry_string_iterate) + + ## jerry_promise_state_t Enum which describes the state of a Promise. @@ -1225,7 +1288,7 @@ Possible values: - JERRY_PROMISE_STATE_FULFILLED - Promise is in "Fulfilled" state. - JERRY_PROMISE_STATE_REJECTED - Promise is in "Rejected" state. -*New in version 2.2*. +*Introduced in version 2.2*. **See also** @@ -1282,7 +1345,7 @@ Possible values: - object - internal object representing the execution status - value - value for rejecting -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -1321,7 +1384,7 @@ Possible values: - JERRY_PROMISE_EVENT_ASYNC_AFTER_RESOLVE - JERRY_PROMISE_EVENT_ASYNC_AFTER_REJECT -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -1350,7 +1413,7 @@ typedef void (*jerry_promise_event_cb_t) (jerry_promise_event_type_t event_type, - `value` - optional value argument. - `user_data_p` - optional user data pointer supplied via the (jerry_promise_on_event)[#jerry_promise_on_event] method. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_promise_callback_t` in earlier versions.* **See also** @@ -1378,9 +1441,9 @@ Possible values: API functions can return the `JERRY_TYPEDARRAY_INVALID` value if the TypedArray support is not in the engine. -*New in version 2.0*. +*Introduced in version 2.0*. -*Changed in version 2.4*: Added `JERRY_TYPEDARRAY_BIGINT64`, `JERRY_TYPEDARRAY_BIGUINT64` values. +*Updated in version 2.4*: Added `JERRY_TYPEDARRAY_BIGINT64`, `JERRY_TYPEDARRAY_BIGUINT64` values. **See also** @@ -1407,7 +1470,7 @@ typedef struct } jerry_exec_snapshot_option_values_t; ``` -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -1422,7 +1485,7 @@ Possible values: - JERRY_SOURCE_INFO_HAS_FUNCTION_ARGUMENTS - function_arguments field is valid - JERRY_SOURCE_INFO_HAS_SOURCE_RANGE - both source_range_start and source_range_length fields are valid -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -1448,7 +1511,7 @@ typedef struct } jerry_source_info_t; ``` -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -1464,7 +1527,7 @@ Enum that contains the JerryScript type of an array buffer: - JERRY_ARRAYBUFFER_TYPE_ARRAYBUFFER - the object is an array buffer object - JERRY_ARRAYBUFFER_TYPE_SHARED_ARRAYBUFFER - the object is a shared array buffer object -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -1500,7 +1563,7 @@ typedef uint8_t *(*jerry_arraybuffer_allocate_cb_t) (jerry_arraybuffer_type_t bu - return value - Pointer to the buffer, if the allocation is successful, NULL otherwise. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_arraybuffer_allocate_t` in earlier versions.* **See also** @@ -1534,7 +1597,7 @@ typedef void (*jerry_arraybuffer_free_cb_t) (jerry_arraybuffer_type_t buffer_typ - `arraybuffer_user_p` - [in/out] user pointer assigned to the array buffer or shared array buffer object. - `user_p` - user pointer passed to [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_arraybuffer_free_t` in earlier versions.* **See also** @@ -1627,7 +1690,9 @@ jerry_context_data (const jerry_context_data_manager *manager_p); by `manager_p`, which will be stored for future identical calls to `jerry_context_data ()`, and which will be deinitialized using the `deinit_cb` callback provided by `manager_p` when the context will be destroyed. -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_context_data` in earlier versions.* **Example** @@ -1709,7 +1774,7 @@ jerry_register_magic_strings (const jerry_char_t * const *ex_str_items_p, - `count` - number of elements in `ext_str_items_p` array - `str_lengths_p` - array of lengths for each magic string -*Changed in version 2.0*: The first function argument type was changed. +*Updated in version 2.0*: The first function argument type was changed. **Example** @@ -1775,7 +1840,9 @@ jerry_heap_stats (jerry_heap_stats_t *out_stats_p); - true, if stats were written into the `out_stats_p` pointer. - false, otherwise. Usually it is because the `JERRY_FEATURE_HEAP_STATS` feature is not enabled. -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_memory_stats` in earlier versions.* **Example** @@ -1807,7 +1874,9 @@ jerry_heap_gc (jerry_gc_mode_t mode); - `mode` - operational mode, see [jerry_gc_mode_t](#jerry_gc_mode_t) -*Changed in version 2.0*: Added `mode` argument. +*Updated in version 2.0*: Added `mode` argument. + +*Renamed in version 3.0, it was previously known as `jerry_gc` in earlier versions.* **Example** @@ -1865,9 +1934,9 @@ jerry_parse (const jerry_char_t *source_p, - function object value, if script was parsed successfully, - thrown exception, otherwise -*Changed in version 2.0*: Added `source_name_p`, and `source_name_length` arguments. +*Updated in version 2.0*: Added `source_name_p`, and `source_name_length` arguments. -*Changed in version [[NEXT_RELEASE]]*: The `source_name_p`, `source_name_length`, and `parse_opts` arguments are replaced by `options_p`. +*Updated in version 3.0*: The `source_name_p`, `source_name_length`, and `parse_opts` arguments are replaced by `options_p`. This function replaces the `jerry_parse_function` method. **Example 1** @@ -1976,7 +2045,7 @@ jerry_parse_value (const jerry_value_t source_value, - function object value, if script was parsed successfully, - thrown exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **Example** @@ -2138,7 +2207,9 @@ jerry_run_jobs (void) - return value - result of last executed job, may be an exception value. -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_run_all_enqueued_jobs` in earlier versions.* **Example** @@ -2208,6 +2279,8 @@ jerry_current_realm (void); - return value - api value of global object +*Renamed in version 3.0, it was previously known as `jerry_get_global_object` in earlier versions.* + **Example** ```c @@ -2248,7 +2321,7 @@ jerry_value_is_abort (const jerry_value_t value); - true, if the given `jerry_value_t` is an abort exception - false, otherwise -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -2319,7 +2392,6 @@ Returns whether the given `jerry_value_t` is an ArrayBuffer object. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -2333,7 +2405,7 @@ jerry_value_is_arraybuffer (const jerry_value_t value) - true, if the given `jerry_value_t` is an ArrayBuffer object. - false, otherwise -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -2366,7 +2438,6 @@ Returns whether the given `jerry_value_t` is a SharedArrayBuffer object. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -2380,7 +2451,7 @@ jerry_value_is_shared_arraybuffer (const jerry_value_t value); - true, if the given `jerry_value_t` is a SharedArrayBuffer object. - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **Example** @@ -2460,7 +2531,7 @@ jerry_value_is_true (const jerry_value_t value); - true, if the given `jerry_value_t` is true value - false, otherwise -*New in version [[NEXT_RELEASE]]*. Replaces the `jerry_get_boolean_value` method. +*Introduced in version 3.0*. Replaces the `jerry_get_boolean_value` method. **Example** @@ -2500,7 +2571,7 @@ jerry_value_is_false (const jerry_value_t value); - true, if the given `jerry_value_t` is false value - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **Example** @@ -2570,7 +2641,6 @@ Returns whether the given `jerry_value_t` is a DataView object value. - This API depends on a build option (`JERRY_BUILTIN_DATAVIEW`) and can be checked in runtime with the `JERRY_FEATURE_DATAVIEW` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -2584,7 +2654,7 @@ jerry_value_is_dataview (const jerry_value_t value) - true, if the given `jerry_value_t` is a DataView object - false, otherwise -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -2638,7 +2708,7 @@ jerry_value_is_exception (const jerry_value_t value); - true, if the given `jerry_value_t` is an exception value. - false, otherwise -*New in version 2.0*. +*Renamed in version 3.0 from `jerry_value_is_error` to `jerry_value_is_exception`*. **Example** @@ -2718,7 +2788,7 @@ jerry_value_is_async_function (const jerry_value_t value) - true, if the given `jerry_value_t` is an async function - false, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. **Example** @@ -2875,7 +2945,7 @@ jerry_value_is_promise (const jerry_value_t value) - true, if the given `jerry_value_t` is a promise - false, otherwise -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -2909,7 +2979,6 @@ Returns whether the given `jerry_value_t` is a proxy value. - This API depends on a build option (`JERRY_BUILTIN_PROXY`) and can be checked in runtime with the `JERRY_FEATURE_PROXY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -2924,7 +2993,7 @@ jerry_value_is_proxy (const jerry_value_t value) - true, if the given `jerry_value_t` is a proxy object - false, otherwise -*New in version 2.3*. +*Introduced in version 2.3*. **Example** @@ -3006,7 +3075,7 @@ jerry_value_is_symbol (const jerry_value_t value) - true, if the given `jerry_value_t` is a symbol - false, otherwise -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -3053,7 +3122,6 @@ Returns whether the given `jerry_value_t` is a bigint value. - This API depends on a build option (`JERRY_BUILTIN_BIGINT`) and can be checked in runtime with the `JERRY_FEATURE_BIGINT` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -3067,7 +3135,7 @@ jerry_value_is_bigint (const jerry_value_t value) - true, if the given `jerry_value_t` is a BigInt - false, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. **Example** @@ -3115,7 +3183,6 @@ Checks whether the given `jerry_value_t` is a TypedArray object or not. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -3129,7 +3196,7 @@ jerry_value_is_typedarray (const jerry_value_t value) - true, if the given `jerry_value_t` is a TypedArray object. - false, otherwise -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -3174,7 +3241,6 @@ Checks whether the given `jerry_value_t` is the given `jerry_container_type_t` t runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` feature enum values. see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -3188,7 +3254,9 @@ jerry_container_type (const jerry_value_t value) - The corresponding enum value of `jerry_container_type_t`, or `JERRY_CONTAINER_TYPE_INVALID` if the container was not a valid container object. -*New in version 2.3*. +*Introduced in version 2.3*. + +*Renamed in version 3.0, it was previously known as `jerry_get_container_type` in earlier versions.* **Example** @@ -3282,7 +3350,9 @@ jerry_value_type (const jerry_value_t value); - return value - One of the [jerry_type_t](#jerry_type_t) value. -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_value_get_type` in earlier versions.* **Example** @@ -3330,7 +3400,9 @@ jerry_object_type (const jerry_value_t value); - return value - One of the [jerry_object_type_t](#jerry_object_type_t) value. -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_object_get_type` in earlier versions.* **Example** @@ -3373,7 +3445,9 @@ jerry_function_type (const jerry_value_t value); Note: For non-function parameters `JERRY_FUNCTION_TYPE_NONE` is returned. -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_function_get_type` in earlier versions.* **Example** @@ -3417,7 +3491,9 @@ jerry_iterator_type (const jerry_value_t value); Note: For non-iterator parameters `JERRY_ITERATOR_TYPE_NONE` is returned. -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_iterator_get_type` in earlier versions.* **Example** @@ -3459,7 +3535,7 @@ jerry_feature_enabled (const jerry_feature_t feature); - true, if the given `jerry_feature_t` is enabled - false, otherwise -*New in version 2.0*. +*Renamed in version 3.0 from `jerry_is_feature_enabled` to `jerry_feature_enabled`*. **Example** @@ -3508,7 +3584,9 @@ jerry_binary_op (jerry_binary_op_t op, - exception, if operation is unsuccessful or unsupported - the result of the binary operation on the given operands otherwise -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_binary_operation` in earlier versions.* **Example - JERRY_BIN_OP_EQUAL** @@ -3600,7 +3678,7 @@ main (void) # Exception manipulation functions -*Changed in version 2.0*: The exception handling and manipulation was modified and the old methods were replaced. +*Updated in version 2.0*: The exception handling and manipulation have been modified, and the old methods were replaced. ## jerry_throw_abort @@ -3626,7 +3704,9 @@ jerry_throw_abort (jerry_value_t value, bool take_ownersip); - `take_ownership` - raw boolean, defines whether input value should be copied - return value - abort exception value -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_abort_from_value` in earlier versions.* **Example 1** @@ -3685,7 +3765,9 @@ jerry_throw (jerry_value_t value, bool take_ownership); - `take_ownership` - raw boolean, defines whether input value should be copied - return value - exception value -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_value_from_error` in earlier versions.* **Example 1** @@ -3744,7 +3826,9 @@ jerry_error_type (const jerry_value_t value); - JERRY_ERROR_NONE if the input is not an error object - one of the [jerry_error_t](#jerry_error_t) value -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_error_type` in earlier versions.* **Example** @@ -3792,7 +3876,9 @@ jerry_exception_value (jerry_value_t value, bool release) - `release` - raw boolean, defines whether input value must be released - return value - api value -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_error_from_value` in earlier versions.* **Example 1** @@ -3848,7 +3934,9 @@ void jerry_error_on_created (jerry_error_object_created_cb_t callback, void *use disables the operation - `user_p` - pointer passed to the callback function, can be NULL -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_set_error_object_created_callback` in earlier versions.* **Example** @@ -3902,7 +3990,7 @@ jerry_on_throw (jerry_throw_cb_t throw_cb, - `throw_cb` - callback which is called on throws (passing NULL disables this feature) - `user_p` - user pointer passed to the `throw_cb` function -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_set_vm_throw_callback` in earlier versions.* **Example** @@ -3947,6 +4035,7 @@ main (void) - [jerry_exception_is_captured](#jerry_exception_is_captured) - [jerry_exception_allow_capture](#jerry_exception_allow_capture) + ## jerry_exception_is_captured **Summary** @@ -3970,7 +4059,7 @@ bool jerry_exception_is_captured (jerry_value_t value); - true, if the vm throw callback captured the exception - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0 from `jerry_error_is_throw_captured` to `jerry_exception_is_captured`*. **Example** @@ -4036,7 +4125,7 @@ void jerry_exception_allow_capture (jerry_value_t value, bool should_capture); - `value` - api value (should be an exception) - `should_capture` - callback should capture this error -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_error_set_throw_capture` in earlier versions.* **Example** @@ -4124,6 +4213,8 @@ jerry_value_as_number (const jerry_value_t value); - the number value of the given `jerry_value_t` parameter as a raw double. - `0.0` if the api value passed is not a number. +*Renamed in version 3.0, it was previously known as `jerry_get_number_value` in earlier versions.* + **Example** ```c @@ -4161,12 +4252,14 @@ This is effectively the number of bytes required to store the string's character **Prototype** ```c -jerry_size_t -jerry_string_size (const jerry_value_t value, JERRY_ENCODING_CESU8); +jerry_size_t jerry_string_size (const jerry_value_t value, jerry_encoding_t encoding); ``` - `value` - api value +- `encoding` - the requested [encoding](#jerry_encoding_t) for the string - return value - number of bytes in the buffer needed to represent the string. +*Renamed in version 3.0, it was previously known as `jerry_get_string_size` in earlier versions.* + **Example** ```c @@ -4210,6 +4303,8 @@ jerry_string_length (const jerry_value_t value); - `value` - api value - return value - number of characters in the string +*Renamed in version 3.0, it was previously known as `jerry_get_string_length` in earlier versions.* + **Example** ```c @@ -4232,6 +4327,96 @@ jerry_string_length (const jerry_value_t value); - [jerry_validate_string](#jerry_validate_string) +## jerry_string_substr + +**Summary** + +Create a substring of the input string value. +Return an empty string if input value is not a string. + +**Prototype** + +```c +jerry_size_t jerry_string_substr (const jerry_value_t value, jerry_length_t start, jerry_length_t end); +``` + +- `value` - the input string value +- `start` - start position of the substring +- `end` - end position of the substring +- return value - created string + +*Introduced in version 3.0. There were `jerry_substring_to_char_buffer` and `jerry_substring_to_utf8_char_buffer` in previous versions with a similar functionality. + +**Example** + +```c +{ + jerry_value_t str = jerry_string_sz ("Demo string"); + + // Read the string into a byte buffer. + jerry_value_t sub_str = jerry_string_substr (str, 0, 3); + + // usage of 'sub_str' + + jerry_value_free (sub_str); + jerry_value_free (str); +} +``` + +**See also** + +- [jerry_string_sz](#jerry_string_sz) + + +## jerry_string_iterate + +**Summary** + +Iterate over the input string value in the specified encoding, visiting each unit of the encoded string once. If the input value is not a string, the function will do nothing. + + +**Prototype** + +```c +void jerry_string_iterate (const jerry_value_t value, + jerry_encoding_t encoding, + jerry_string_iterate_cb_t callback, + void *user_p); +``` + +- `value` - the input string value +- `encoding` - the requested [encoding](#jerry_encoding_t) for the string +- `callback` - callback function called for each byte of the encoded string, see [jerry_string_iterate_cb_t](#jerry_string_iterate_cb_t) +- `user_p` - user pointer passed to the callback function + +*Introduced in version 3.0.* + +**Example** + +```c +static void my_str_iterator_cb_func (uint32_t value, void *user_p) +{ + // usage of the encoded byte value and the user pointer (if non-null) +} + +... + +void foo () { + jerry_value_t string = jerry_string_sz ("Demo string"); + + jerry_string_iterate (string, JERRY_ENCODING_UTF8, &jerryx_buffered_print, NULL); + + jerry_value_free (string); +} +``` + +**See also** + +- [jerry_string_sz](#jerry_string_sz) +- [jerry_encoding_t](#jerry_encoding_t) +- [jerry_string_iterate_cb_t](#jerry_string_iterate_cb_t) + + ## jerry_string_to_buffer **Summary** @@ -4263,6 +4448,8 @@ jerry_string_to_buffer (const jerry_value_t value, - `buffer_size` - size of the buffer - return value - number of bytes copied to the buffer +*Renamed in version 3.0, it was previously known as `jerry_string_to_char_buffer` in earlier versions.* + **Example** [doctest]: # () @@ -4301,12 +4488,12 @@ main (void) **See also** +- [jerry_encoding_t](#jerry_encoding_t) - [jerry_string_sz](#jerry_string_sz) - [jerry_string_size](#jerry_string_size) -- [jerry_strig_to_buffer](#jerry_strig_to_buffer) -# jerry_string_external_on_free +## jerry_string_external_on_free **Summary** @@ -4328,7 +4515,7 @@ void jerry_string_external_on_free (jerry_external_string_free_cb_t callback_p); - `callback_p` - callback which is called when an external string is freed. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_string_set_external_free_callback` in earlier versions.* **Example** @@ -4371,7 +4558,7 @@ main (void) - [jerry_string_external](#jerry_string_external) -# jerry_string_user_ptr +## jerry_string_user_ptr **Summary** @@ -4397,7 +4584,7 @@ void *jerry_string_user_ptr (const jerry_value_t value, - user pointer - if `value` argument is an external string - NULL - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_string_get_external_user_pointer` in earlier versions.* **Example** @@ -4459,6 +4646,8 @@ jerry_array_length (const jerry_value_t value); - `value` - input array value - return value - length of the given array +*Renamed in version 3.0, it was previously known as `jerry_get_array_length` in earlier versions.* + **Example** ```c @@ -4696,7 +4885,7 @@ jerry_value_to_bigint (const jerry_value_t value); - converted BigInt value, if success - thrown exception, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. **Example** @@ -4737,7 +4926,7 @@ jerry_value_as_integer (const jerry_value_t value); - 0, if value is not a number - integer representation of the number, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. **Example** @@ -4768,7 +4957,7 @@ jerry_value_as_int32 (const jerry_value_t value); - 0, if value is not a number - int32 representation of the number, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. **Example** @@ -4799,7 +4988,7 @@ jerry_value_as_uint32 (const jerry_value_t value); - 0, if value is not a number - uint32 representation of the number, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. **Example** @@ -4843,7 +5032,7 @@ jerry_value_t jerry_module_link (const jerry_value_t module_val, - true - if linking is successful - exception - otherwise -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **Example** @@ -4922,7 +5111,7 @@ jerry_value_t jerry_module_evaluate (const jerry_value_t module_val); - result of module bytecode execution - if evaluation was successful - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **Example** @@ -4960,6 +5149,37 @@ main (void) - [jerry_module_link](#jerry_module_link) + +## jerry_module_cleanup + +**Summary** + +Release known modules in the current context. If realm parameter is supplied, cleans up modules native to that realm only. This function should be called by the user application when the module database in the current context is no longer needed. + +**Prototype** + +```c +void jerry_module_cleanup (const jerry_value_t realm); +``` + +- `realm` - release only those modules whose realm value is equal to this argument. + +*Introduced in version 3.0* + +**Example** + +```c +jerry_module_cleanup (jerry_current_realm ()); +``` + +**See also** + +- [jerry_current_realm](#jerry_current_realm) +- [jerry_module_state](#jerry_module_state) +- [jerry_module_evaluate](#jerry_module_evaluate) +- [jerry_module_link](#jerry_module_link) + + ## jerry_module_state **Summary** @@ -4983,7 +5203,7 @@ jerry_module_state_t jerry_module_state (const jerry_value_t module_val); - current status - if module_val is a module - JERRY_MODULE_STATE_INVALID - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_get_state` in earlier versions.* **Example** @@ -5044,7 +5264,7 @@ void jerry_module_on_state_changed (jerry_module_state_changed_cb_t callback, - `callback` - callback, which is called after the state change. - `user_p` - pointer passed to the callback function. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_set_state_changed_callback` in earlier versions.* **Example** @@ -5122,7 +5342,7 @@ void jerry_module_on_import_meta (jerry_module_import_meta_cb_t callback, expression of a module is evaluated the first time - `user_p` - pointer passed to the callback function. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_set_import_meta_callback` in earlier versions.* **Example** @@ -5200,7 +5420,7 @@ size_t jerry_module_request_count (const jerry_value_t module_val); - number of import/export requests of a module, if `module_val` is module, - 0, otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_get_number_of_requests` in earlier versions.* **Example** @@ -5272,7 +5492,7 @@ jerry_value_t jerry_module_request (const jerry_value_t module_val, size_t reque - module object, if the request has been resolved successfully - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_get_request` in earlier versions.* **Example** @@ -5340,7 +5560,7 @@ jerry_value_t jerry_module_namespace (const jerry_value_t module_val); - object, if namespace object is available - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_get_namespace` in earlier versions.* **Example** @@ -5408,7 +5628,7 @@ jerry_module_on_import (jerry_module_import_cb_t callback_p, - `callback_p` - a [jerry_module_import_cb_t](#jerry_module_import_cb_t) callback which handles `import()` calls - `user_p` - user pointer passed to the callback -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_module_set_import_callback` in earlier versions.* **Example** @@ -5540,7 +5760,7 @@ jerry_native_module (jerry_native_module_evaluate_cb_t callback, - a native module, if the module is successfully created - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_native_module_create` in earlier versions.* **Example** @@ -5603,7 +5823,7 @@ jerry_native_module_get (const jerry_value_t native_module_val, - value of the export, if success - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_native_module_get_export` in earlier versions.* **Example** @@ -5664,7 +5884,7 @@ jerry_value_t jerry_native_module_set (const jerry_value_t native_module_val, - true, if success - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **Example** @@ -5728,7 +5948,9 @@ jerry_promise_result (const jerry_value_t promise); - A TypeError is returned if the input argument was not a Promise object or the Promise support was not built into the library. -*New in version 2.2*. +*Introduced in version 2.2*. + +*Renamed in version 3.0, it was previously known as `jerry_get_promise_result` in earlier versions.* **Example** @@ -5788,7 +6010,9 @@ jerry_promise_state (const jerry_value_t promise); - `JERRY_PROMISE_STATE_NONE` is returned if the input argument was not a promise object or the Promise support was not built into the library. -*New in version 2.2*. +*Introduced in version 2.2*. + +*Renamed in version 3.0, it was previously known as `jerry_get_promise_state` in earlier versions.* **Example** @@ -5854,7 +6078,7 @@ void jerry_promise_on_event (jerry_promise_event_filter_t filters, jerry_promise and setting NULL disables the tracking - `user_p` - pointer passed to the callback function, can be NULL -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_promise_set_callback` in earlier versions.* **Example** @@ -5929,7 +6153,9 @@ jerry_property_descriptor_to_object (const jerry_property_descriptor_t *src_prop - object value - if success - exception - otherwise -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_from_property_descriptor` in earlier versions.* **Example** @@ -5981,7 +6207,7 @@ jerry_property_descriptor_from_object (jerry_value_t obj_value, jerry_property_d - true, if success - thrown exception, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. **Example** @@ -6009,6 +6235,7 @@ example (void) } ``` + ## jerry_promise_resolve **Summary** @@ -6018,11 +6245,6 @@ Resolve the promise with an argument. *Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. -- This API depends on a build option (`JERRY_ESNEXT`) and can be checked - in runtime with the `JERRY_FEATURE_PROMISE` feature enum value, - see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. - **Prototype** @@ -6037,9 +6259,9 @@ jerry_promise_resolve (jerry_value_t promise, jerry_value_t argument); - undefined - if resolve call was successful - exception - otherwise -*New in version 2.0*. +*Introduced in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: Build option dependency changed from `JERRY_BUILTIN_PROMISE` to `JERRY_ESNEXT`. +*Renamed in version 3.0, it was previously known as `jerry_resolve_or_reject_promise` in earlier versions.* **Example** @@ -6069,6 +6291,7 @@ jerry_promise_resolve (jerry_value_t promise, jerry_value_t argument); - [jerry_value_free](#jerry_value_free) - [jerry_value_is_exception](#jerry_value_is_exception) + ## jerry_promise_reject **Summary** @@ -6092,7 +6315,9 @@ jerry_promise_reject (jerry_value_t promise, jerry_value_t argument); - undefined - if reject call was successful - exception - otherwise -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_resolve_or_reject_promise` in earlier versions.* **Example** @@ -6149,7 +6374,9 @@ jerry_symbol (jerry_well_known_symbol_t symbol); - undefined value - if invalid well-known symbol was requested - well-known symbol value, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_get_well_known_symbol` in earlier versions.* **Example** @@ -6204,7 +6431,9 @@ jerry_symbol_description (const jerry_value_t value); - string or undefined value containing the symbol's description - if success - thrown exception, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_get_symbol_description` in earlier versions.* **Example** @@ -6262,7 +6491,9 @@ jerry_symbol_descriptive_string (const jerry_value_t value); - string value containing the symbol's descriptive string - if success - thrown exception, otherwise -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_symbol_descriptive_string` in earlier versions.* **Example** @@ -6328,7 +6559,9 @@ jerry_bigint_digit_count (jerry_value_t value) - number of digits (can be zero for BigInt zero) - if value is not a BigInt value, it returns with zero -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_get_bigint_size_in_digits` in earlier versions.* **Example** @@ -6393,7 +6626,9 @@ jerry_bigint_to_digits (jerry_value_t value, uint64_t *digits_p, uint32_t size, - `sign_p` - the boolean passed to the function is set to false when the BigInt is positive, and set to true otherwise (this parameter can be NULL) -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_get_bigint_digits` in earlier versions.* **Example** @@ -6441,7 +6676,6 @@ Gets the target object of a Proxy object. - This API depends on a build option (`JERRY_BUILTIN_PROXY`) and can be checked in runtime with the `JERRY_FEATURE_PROXY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -6456,7 +6690,9 @@ jerry_proxy_target (jerry_value_t proxy_value); - type error exception - if proxy_value is not a Proxy object - target object - otherwise -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_get_proxy_target` in earlier versions.* **Example** @@ -6494,7 +6730,6 @@ Gets the handler object of a Proxy object. - This API depends on a build option (`JERRY_BUILTIN_PROXY`) and can be checked in runtime with the `JERRY_FEATURE_PROXY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -6509,7 +6744,7 @@ jerry_proxy_handler (jerry_value_t proxy_value); - type error exception - if proxy_value is not a Proxy object - handler object - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_get_proxy_handler` in earlier versions.* **Example** @@ -6559,6 +6794,8 @@ jerry_value_copy (jerry_value_t value); - `value` - api value - return value - copied value +*Renamed in version 3.0, it was previously known as `jerry_acquire_value` in earlier versions.* + **Example** ```c @@ -6597,6 +6834,8 @@ jerry_value_free (jerry_value_t value); - `value` - api value +*Renamed in version 3.0, it was previously known as `jerry_release_value` in earlier versions.* + **Example** ```c @@ -6636,6 +6875,8 @@ jerry_array (uint32_t size); - `size` - size of array; - return value - value of the constructed array object +*Renamed in version 3.0, it was previously known as `jerry_create_array` in earlier versions.* + **Example** ```c @@ -6677,7 +6918,9 @@ jerry_arraybuffer (jerry_length_t size); - `size` - size of the backing store allocated for the array buffer **in bytes**. - return value - the new ArrayBuffer as a `jerry_value_t` -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_arraybuffer` in earlier versions.* **Example** @@ -6734,9 +6977,11 @@ jerry_arraybuffer_external (uint8_t *buffer_p, - return value - value of the newly constructed array buffer object. -*New in version 2.0*. +*Introduced in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: `free_cb` has been replaced by `arraybuffer_user_p`. +*Updated in version 3.0*: `free_cb` has been replaced by `arraybuffer_user_p`. + +*Renamed in version 3.0, it was previously known as `jerry_create_arraybuffer_external` in earlier versions.* **Example** @@ -6782,7 +7027,7 @@ jerry_shared_arraybuffer (jerry_length_t size); - `size` - size of the backing store allocated for the shared array buffer **in bytes**. - return value - the new SharedArrayBuffer as a `jerry_value_t` -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_create_shared_arraybuffer` in earlier versions.* **Example** @@ -6837,7 +7082,7 @@ jerry_shared_arraybuffer_external (uint8_t *buffer_p, - return value - value of the newly constructed shared array buffer object. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_create_shared_arraybuffer_external` in earlier versions.* **Example** @@ -6882,6 +7127,8 @@ jerry_boolean (bool value); - `value` - raw boolean value. - return value - a `jerry_value_t` created from the given boolean argument. +*Renamed in version 3.0, it was previously known as `jerry_create_boolean` in earlier versions.* + **Example** ```c @@ -6922,6 +7169,8 @@ jerry_error (jerry_error_t error_type, jerry_value_t message); - `message` - error message string - return value - constructed error object +*Renamed in version 3.0, it was previously known as `jerry_create_error` in earlier versions.* + **Example** ```c @@ -6964,6 +7213,8 @@ jerry_error_sz (jerry_error_t error_type, const char *message_p); - `message_p` - value of 'message' property of the constructed error object - return value - constructed error object +*Renamed in version 3.0, it was previously known as `jerry_create_error` in earlier versions.* + **Example** ```c @@ -7010,7 +7261,9 @@ jerry_dataview (const jerry_value_t array_buffer, - value of the constructed DataView object - if success - exception - otherwise -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_dataview` in earlier versions.* **Example** @@ -7062,6 +7315,8 @@ jerry_function_external (jerry_external_handler_t handler_p); - `handler_p` - pointer to native handler of the function object - return value - value of the constructed function object +*Renamed in version 3.0, it was previously known as `jerry_create_external_function` in earlier versions.* + **Example** [doctest]: # () @@ -7136,6 +7391,8 @@ jerry_number (double value); - `value` - double value from which a `jerry_value_t` will be created - return value - a `jerry_value_t` created from the given double argument +*Renamed in version 3.0, it was previously known as `jerry_create_number` in earlier versions.* + **Example** ```c @@ -7174,6 +7431,8 @@ jerry_infinity (bool sign); - `sign` - true for negative Infinity and false for positive Infinity - return value - a `jerry_value_t` representing the infinity value +*Renamed in version 3.0, it was previously known as `jerry_create_number_infinity` in earlier versions.* + **Example** ```c @@ -7211,6 +7470,8 @@ jerry_nan (void); - return value - a `jerry_value_t` representing the not-a-number value +*Renamed in version 3.0, it was previously known as `jerry_create_number_nan` in earlier versions.* + **Example** ```c @@ -7249,6 +7510,8 @@ jerry_null (void); - return value - a `jerry_value_t` representing null. +*Renamed in version 3.0, it was previously known as `jerry_create_null` in earlier versions.* + **Example** ```c @@ -7284,6 +7547,8 @@ jerry_object (void); - return value - value of the created object +*Renamed in version 3.0, it was previously known as `jerry_create_object` in earlier versions.* + **Example** ```c @@ -7321,7 +7586,9 @@ jerry_promise (void) - return value - value of the newly created promise -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_promise` in earlier versions.* **Example** @@ -7367,7 +7634,9 @@ jerry_proxy (const jerry_value_t target, const jerry_value_t handler); - return exception - if the Proxy construction fails value of the newly created proxy object - otherwise -*New in version 2.3*. +*Introduced in version 2.3*. + +*Renamed in version 3.0, it was previously known as `jerry_create_proxy` in earlier versions.* **Example** @@ -7432,7 +7701,7 @@ jerry_proxy_custom (const jerry_value_t target, - return thrown exception - if the Proxy construction fails value of the newly created proxy object - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_create_special_proxy` in earlier versions.* **Example** @@ -7484,9 +7753,11 @@ jerry_value_t jerry_string_sz (const char *str_p); ``` -- `str_p` - non-null pointer to string +- `str_p` - non-null pointer to zero-terminated string - return value - created string +*Renamed in version 3.0, it was previously known as `jerry_create_string` in earlier versions.* + **Example** ```c @@ -7528,6 +7799,8 @@ jerry_string (const jerry_char_t *buffer_p, - `encoding` - encoding of the string data - return value - value of the created string +*Renamed in version 3.0, it was previously known as `jerry_create_string_sz` in earlier versions.* + **Example** ```c @@ -7570,13 +7843,15 @@ jerry_value_t jerry_string_external_sz (const char *str_p, void *user_p); ``` -- `str_p` - non-null pointer to string +- `str_p` - non-null pointer to a zero-terminated string - `user_p` - user pointer passed to the callback when the string is freed - return value - value of the created string -*New in version 2.4*. +*Introduced in version 2.4*. + +*Updated in version 3.0*: `free_cb` is replaced by `user_p`. -*Changed in version [[NEXT_RELEASE]]*: `free_cb` is replaced by `user_p`. +*Renamed in version 3.0, it was previously known as `jerry_create_external_string` in earlier versions.* **Example** @@ -7624,9 +7899,11 @@ jerry_string_external (const jerry_char_t *str_p, - `user_p` - user pointer passed to the callback when the string is freed - return value - value of the created string -*New in version 2.4*. +*Introduced in version 2.4*. -*Changed in version [[NEXT_RELEASE]]*: `free_cb` is replaced by `user_p`. +*Updated in version 3.0*: `free_cb` is replaced by `user_p`. + +*Renamed in version 3.0, it was previously known as `jerry_create_external_string_sz` in earlier versions.* **Example** @@ -7651,7 +7928,7 @@ jerry_string_external (const jerry_char_t *str_p, - [jerry_string_external_on_free](#jerry_string_external_on_free) -## jerry_symbol +## jerry_symbol_with_description **Summary** @@ -7674,7 +7951,9 @@ jerry_symbol_with_description (const jerry_value_t value) - value of the created symbol, if success - thrown exception, otherwise -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_symbol` in earlier versions.* **Example** @@ -7735,7 +8014,9 @@ jerry_bigint (const uint64_t *digits_p, uint32_t size, bool sign) - value of the created bigint, if success - thrown exception, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_create_bigint` in earlier versions.* **Example** @@ -7771,9 +8052,9 @@ main (void) **Summary** -Returns a RegExp object created from the argument ASCII string pattern, or an exception if the construction of the -object fails. Optional flags can be set using [jerry_regexp_flags_t](#jerry_regexp_flags_t). These flags can be -combined together with the binary OR operator or used on their own as enum values. +Returns a RegExp object created from the argument of a zero-terminated UTF-8 string pattern, or an exception +if the construction of the object fails. Optional flags can be set using [jerry_regexp_flags_t](#jerry_regexp_flags_t). +These flags can be combined together with the binary OR operator or used on their own as enum values. *Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. @@ -7788,7 +8069,9 @@ jerry_regexp_sz (const jerry_char_t *pattern_p, uint16_t flags); - `flags` - optional flags for the RegExp object, see [jerry_regexp_flags_t](#jerry_regexp_flags_t) - return value - the RegExp object as a `jerry_value_t` -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_regexp` in earlier versions.* **Example** @@ -7828,7 +8111,9 @@ jerry_regexp (const jerry_value_t pattern, uint16_t flags); - `flags` - optional flags for the RegExp object, see [jerry_regexp_flags_t](#jerry_regexp_flags_t) - return value - the RegExp object as a `jerry_value_t` -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_regexp_sz` in earlier versions.* **Example** @@ -7865,7 +8150,7 @@ and element count can be specified. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -7878,7 +8163,9 @@ jerry_typedarray (jerry_typedarray_type_t type_name, jerry_length_t item_count); - `item_count` - number of items in the new TypedArray - return value - the new TypedArray as a `jerry_value_t` -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_typedarray` in earlier versions.* **Example** @@ -7921,7 +8208,7 @@ one of the allowed TypedArray functions. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -7937,7 +8224,9 @@ jerry_typedarray_with_buffer (jerry_typedarray_type_t type_name, - the new TypedArray as a `jerry_value_t` - exception if the ArrayBuffer does not have enough space for the given type of TypedArray -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_typedarray_for_arraybuffer` in earlier versions.* **Example** @@ -7982,7 +8271,7 @@ one of the allowed TypedArray functions. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -8002,7 +8291,9 @@ jerry_typedarray_with_buffer_span (jerry_typedarray_type_t type_name, - the new TypedArray as a `jerry_value_t` - exception if the ArrayBuffer does not have enough space for the given type of TypedArray -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_create_typedarray_for_arraybuffer_sz` in earlier versions.* **Example** @@ -8039,7 +8330,7 @@ Create a jerry_value_t representing a given type container object. in runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` feature enum values. see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -8055,7 +8346,9 @@ jerry_container (jerry_container_type_t container_type, - `arguments_list_len` - The length of the above arguments. - return value - the new container object as a `jerry_value_t` -*New in version 2.3*. +*Introduced in version 2.3*. + +*Renamed in version 3.0, it was previously known as `jerry_create_container` in earlier versions.* **Example** @@ -8108,6 +8401,8 @@ jerry_undefined (void); - return value - value of undefined +*Renamed in version 3.0, it was previously known as `jerry_create_undefined` in earlier versions.* + **Example** ```c @@ -8137,7 +8432,7 @@ Creates a `jerry_value_t` representing a new global object. - This API depends on a build option (`JERRY_BUILTIN_REALMS`) and can be checked in runtime with the `JERRY_FEATURE_REALM` feature enum value. see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -8148,7 +8443,9 @@ jerry_realm (void); - return value - realm object value -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_create_realm` in earlier versions.* **Example** @@ -8203,9 +8500,11 @@ jerry_object_has (const jerry_value_t obj_val, - exception - if the operation fail - true/false API value - depend on whether the property exists -*Changed in version 2.0*: The return value type is now a JavaScript value and not a primitive boolean value. +*Updated in version 2.0*: The return value type is now a JavaScript value and not a primitive boolean value. + +*Updated in version 2.3*: The return value can be an exception value. -*Changed in version 2.3*: The return value can be an exception value. +*Renamed in version 3.0, it was previously known as `jerry_has_property` in earlier versions.* **Example** @@ -8241,6 +8540,59 @@ main (void) - [jerry_object_delete](#jerry_object_delete) +## jerry_object_has_sz + +**Summary** + +Checks whether the object or its prototype objects have the given property. + +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. + +**Prototype** + +```c +jerry_value_t jerry_object_has_sz (const jerry_value_t object, const char *key_p); +``` + +- `object` - object value +- `key_p` - property name (zero-terminated string) +- return value - JavaScript value that evaluates to + - exception - if the operation fail + - true/false API value - depend on whether the property exists + +*Introduced in version 3.0* + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t global_object = jerry_current_realm (); + + jerry_value_t has_prop_js = jerry_object_has_sz (global_object, "handler_field"); + bool has_prop = jerry_value_is_true (has_prop_js); + + jerry_value_free (has_prop_js); + jerry_value_free (global_object); + + jerry_cleanup (); + + return 0; +} +``` + +**See also** + +- [jerry_object_has](#jerry_object_has) + + ## jerry_object_has_own **Summary** @@ -8264,9 +8616,11 @@ jerry_object_has_own (const jerry_value_t obj_val, - exception - if the operation fails - true/false API value - depend on whether the property exists -*Changed in version 2.0*: The return value type is now a JavaScript value and not a primitive boolean value. +*Updated in version 2.0*: The return value type is now a JavaScript value and not a primitive boolean value. -*Changed in version 2.3*: The return value can be an exception value. +*Updated in version 2.3*: The return value can be an exception value. + +*Renamed in version 3.0, it was previously known as `jerry_has_own_property` in earlier versions.* **Example** @@ -8328,7 +8682,9 @@ jerry_object_has_internal (const jerry_value_t obj_val, - true, if the property exists - false, otherwise -*New in version 2.2*. +*Introduced in version 2.2*. + +*Renamed in version 3.0, it was previously known as `jerry_has_internal_property` in earlier versions.* **Example** @@ -8381,6 +8737,8 @@ jerry_object_delete (const jerry_value_t obj_val, - true, if property was deleted successfully - exception, otherwise +*Renamed in version 3.0, it was previously known as `jerry_delete_property` in earlier versions.* + **Example** ```c @@ -8405,33 +8763,74 @@ jerry_object_delete (const jerry_value_t obj_val, - [jerry_object_get](#jerry_object_get) -## jerry_object_delete_index +## jerry_object_delete_sz **Summary** -Delete indexed property from the specified object. +Delete a property from an object. **Prototype** ```c -jerry_value_t -jerry_object_delete_index (const jerry_value_t obj_val, - uint32_t index); +jerry_value_t jerry_object_delete_sz (const jerry_value_t object, const char *key_p); ``` - `obj_val` - object value -- `index` - index number +- `key_p` - property name (zero-terminated string) - return value - - true value, if property was deleted successfully + - true, if property was deleted successfully - exception, otherwise -*New in version 2.0*. +*Introduced in version 3.0* **Example** ```c { - jerry_value_t object; + jerry_value_t global_object = jerry_current_realm (); + + jerry_value_t delete_result = jerry_object_delete_sz (global_object, "my_prop"); + /* use "delete_result" */ + + jerry_value_free (delete_result); + jerry_value_free (global_object); +} +``` + +**See also** + +- [jerry_object_delete](#jerry_object_delete) + + +## jerry_object_delete_index + +**Summary** + +Delete indexed property from the specified object. + +**Prototype** + +```c +jerry_value_t +jerry_object_delete_index (const jerry_value_t obj_val, + uint32_t index); +``` + +- `obj_val` - object value +- `index` - index number +- return value + - true value, if property was deleted successfully + - exception, otherwise + +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_delete_property_by_index` in earlier versions.* + +**Example** + +```c +{ + jerry_value_t object; ... // create or copy object @@ -8475,7 +8874,9 @@ jerry_object_delete_internal (const jerry_value_t obj_val, - true, if property was deleted successfully - false, otherwise -*New in version 2.2*. +*Introduced in version 2.2*. + +*Renamed in version 3.0, it was previously known as `jerry_delete_internal_property` in earlier versions.* **Example** @@ -8522,6 +8923,8 @@ jerry_object_get (const jerry_value_t obj_val, - value of property, if success - thrown exception, otherwise +*Renamed in version 3.0, it was previously known as `jerry_get_property` in earlier versions.* + **Example** [doctest]: # () @@ -8560,6 +8963,59 @@ main (void) - [jerry_object_set_index](#jerry_object_set_index) +## jerry_object_get_sz + +**Summary** + +Get value of a property to the specified object with the given name. + +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t jerry_object_get_sz (const jerry_value_t object, const char *key_p); +``` + +- `obj_val` - object value +- `key_p` - property name (zero-terminated string) +- return value + - value of property, if success + - thrown exception, otherwise + +*Introduced in version 3.0* + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t global_object = jerry_current_realm (); + + jerry_value_t prop_value = jerry_object_get_sz (global_object, "Object"); + + /* use "prop_value" then release it. */ + + jerry_value_free (prop_value); + jerry_value_free (global_object); + + return 0; +} +``` + +**See also** + +- [jerry_object_get](#jerry_object_get) + + ## jerry_object_get_index **Summary** @@ -8583,6 +9039,8 @@ jerry_object_get_index (const jerry_value_t obj_val, - stored value on the specified index, if success - thrown exception, otherwise. +*Renamed in version 3.0, it was previously known as `jerry_get_property_by_index` in earlier versions.* + **Example** ```c @@ -8642,6 +9100,8 @@ jerry_object_find_own (const jerry_value_t obj_val, - value of property, if success - thrown exception, otherwise +*Renamed in version 3.0, it was previously known as `jerry_get_own_property` in earlier versions.* + **Example** [doctest]: # () @@ -8708,7 +9168,9 @@ jerry_object_get_internal (const jerry_value_t obj_val, - undefined value, if the, if the internal does not property exists - thrown exception, otherwise -*New in version 2.2*. +*Introduced in version 2.2*. + +*Renamed in version 3.0, it was previously known as `jerry_get_internal_property` in earlier versions.* **Example** @@ -8769,6 +9231,8 @@ jerry_object_set (const jerry_value_t obj_val, - true, if success - thrown exception, otherwise +*Renamed in version 3.0, it was previously known as `jerry_set_property` in earlier versions.* + **Example** ```c @@ -8805,6 +9269,58 @@ jerry_object_set (const jerry_value_t obj_val, - [jerry_object_set_index](#jerry_object_set_index) +## jerry_object_set_sz + +**Summary** + +Set a property to the specified object with the given name. + +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t jerry_object_set_sz (jerry_value_t object, const char *key_p, const jerry_value_t value); +``` + +- `obj_val` - object value +- `key_p` - property name (zero-terminated string) +- `value_to_set` - value to set +- return value + - true, if success + - thrown exception, otherwise + +*Introduced in version 3.0* + +**Example** + +```c +{ + jerry_value_t value_to_set; + + ... // create or copy value to set + + jerry_value_t glob_obj = jerry_current_realm (); + + jerry_value_t set_result = jerry_object_set_sz (glob_obj, "my_prop", value_to_set); + + ... // check result of property set call + + jerry_value_free (set_result); + + ... + + jerry_value_free (value_to_set); + jerry_value_free (glob_obj); +} +``` + +**See also** + +- [jerry_object_set](#jerry_object_set) + + ## jerry_object_set_index **Summary** @@ -8830,6 +9346,8 @@ jerry_object_set_index (const jerry_value_t obj_val, - true, if field value was set successfully - thrown exception, otherwise +*Renamed in version 3.0, it was previously known as `jerry_set_property_by_index` in earlier versions.* + **Example** ```c @@ -8887,7 +9405,9 @@ jerry_object_set_internal (const jerry_value_t obj_val, - true, if success - thrown exception, otherwise -*New in version 2.2*. +*Introduced in version 2.2*. + +*Renamed in version 3.0, it was previously known as `jerry_set_internal_property` in earlier versions.* **Example** @@ -8938,7 +9458,7 @@ jerry_property_descriptor_t jerry_property_descriptor (void); ``` -*New in version [[NEXT_RELEASE]]*: Replaces `jerry_init_property_descriptor_fields`. +*Renamed in version 3.0, it was previously known as `jerry_property_descriptor_create` in earlier versions.* **Example** @@ -8987,6 +9507,8 @@ jerry_object_define_own_prop (const jerry_value_t obj_val, - true, if success - thrown exception, otherwise +*Renamed in version 3.0, it was previously known as `jerry_define_own_property` in earlier versions.* + **Example** Registering a simple value property via the `jerry_object_define_own_prop` method: @@ -9168,7 +9690,7 @@ jerry_object_get_own_prop (const jerry_value_t obj_val, - `prop_desc_p` - pointer to property descriptor - return value -*Changed in version [[NEXT_RELEASE]]*: Return value type is changed to `jerry_value_t`. +*Renamed in version 3.0, it was previously known as `jerry_get_own_property_descriptor` in earlier versions. Return value type is changed to `jerry_value_t`.* **Example** @@ -9212,7 +9734,7 @@ jerry_property_descriptor_free (const jerry_property_descriptor_t *prop_desc_p); - `prop_desc_p` - pointer to property descriptor -*New in version [[NEXT_RELEASE]]*: Replaces `jerry_free_property_descriptor_fields`. +*Introduced in version 3.0*: Replaces `jerry_free_property_descriptor_fields`. **Example** @@ -9259,6 +9781,8 @@ jerry_call (const jerry_value_t func_obj_val, - `args_count` - number of arguments - return value - returned jerry value of the called function +*Renamed in version 3.0, it was previously known as `jerry_call_function` in earlier versions.* + **Example** ```c @@ -9315,6 +9839,8 @@ jerry_construct (const jerry_value_t func_obj_val, - `args_count` - number of arguments - return value - returned value of the invoked constructor +*Renamed in version 3.0, it was previously known as `jerry_construct_object` in earlier versions.* + **Example** ```c @@ -9363,6 +9889,8 @@ jerry_object_keys (const jerry_value_t obj_val); - array object value, if success - thrown exception, otherwise +*Renamed in version 3.0, it was previously known as `jerry_get_object_keys` in earlier versions.* + **Example** ```c @@ -9405,6 +9933,8 @@ jerry_object_proto (const jerry_value_t obj_val); - object value, if success - null or thrown exception, otherwise +*Renamed in version 3.0, it was previously known as `jerry_get_prototype` in earlier versions.* + **Example** ```c @@ -9449,6 +9979,8 @@ jerry_object_set_proto (const jerry_value_t obj_val, - true, if success - thrown exception, otherwise +*Renamed in version 3.0, it was previously known as `jerry_set_prototype` in earlier versions.* + **Example** ```c @@ -9494,7 +10026,9 @@ jerry_object_get_native_ptr (const jerry_value_t object, - return value - native pointer associated with the argument object for the given native type info -*New in version 2.0*: Changed from `jerry_get_object_native_handle`. +*Introduced in version 2.0*: Changed from `jerry_get_object_native_handle`. + +*Renamed in version 3.0, it was previously known as `jerry_get_object_native_pointer` in earlier versions.* **Example** @@ -9590,14 +10124,14 @@ print_buffer (char *data_p, static void do_stuff (jerry_value_t object) { - void *native_p = jerry_object_get_native_ptr (object, &buffer_obj_type_info); - - if (native_p == NULL) + if (!jerry_object_has_native_ptr (object, &buffer_obj_type_info)) { // Process the error return; } + void *native_p = jerry_object_get_native_ptr (object, &buffer_obj_type_info); + // It is safe to cast to buffer_native_object_t * and dereference the pointer: buffer_native_object_t *buffer_p = (buffer_native_object_t *) native_p; print_buffer (buffer_p->data_p, buffer_p->length); // Usage of buffer_p @@ -9606,14 +10140,14 @@ do_stuff (jerry_value_t object) if (need_shape_info) { - native_p = jerry_object_get_native_ptr (object, &shape_obj_type_info); - - if (native_p == NULL) + if (!jerry_object_has_native_ptr (object, &shape_obj_type_info)) { // Process the error return; } + native_p = jerry_object_get_native_ptr (object, &shape_obj_type_info); + // It is safe to cast to shape_native_object_t * and dereference the pointer: shape_native_object_t *shape_p = (shape_native_object_t *) native_p; @@ -9684,6 +10218,38 @@ main (void) - [jerry_object_native_info_t](#jerry_object_native_info_t) +## jerry_object_has_native_ptr + +**Summary** + +Checks whether the argument object has a native pointer set for the specified native type info. + +**Prototype** + +```c +bool jerry_object_has_native_ptr (const jerry_value_t object, const jerry_object_native_info_t *native_info_p); +``` + +- `object` - object to set native pointer in +- `native_info_p` - object's native type info +- return value + - true if the native pointer has been set, + - false otherwise + +*Introduced in version 3.0* + +**Example** + +See [jerry_object_get_native_ptr](#jerry_object_get_native_ptr) for a +best-practice example. + +**See also** + +- [jerry_object_set_native_ptr](#jerry_object_set_native_ptr) +- [jerry_object_get_native_ptr](#jerry_object_get_native_ptr) +- [jerry_object_native_info_t](#jerry_object_native_info_t) + + ## jerry_object_set_native_ptr **Summary** @@ -9717,7 +10283,9 @@ jerry_object_set_native_ptr (const jerry_value_t obj_val, `static const jerry_object_native_info_t` makes most sense. - `native_p` - native pointer. -*New in version 2.0*: Changed from `jerry_set_object_native_handle`. +*Introduced in version 2.0*: Changed from `jerry_set_object_native_handle`. + +*Renamed in version 3.0, it was previously known as `jerry_set_object_native_pointer` in earlier versions.* **Example** @@ -9754,7 +10322,9 @@ jerry_object_delete_native_ptr (const jerry_value_t obj_val, - `obj_val` - object to delete native pointer from. - `info_p` - native pointer's type information. -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_delete_object_native_pointer` in earlier versions.* **Example** @@ -9793,7 +10363,7 @@ jerry_native_ptr_init (void *native_pointer_p, - `native_pointer_p` - a valid non-NULL pointer to a native buffer. - `native_info_p` - native pointer's type information. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_native_pointer_release_references` in earlier versions.* **Example** @@ -9884,7 +10454,7 @@ jerry_native_ptr_free (void *native_pointer_p, - `native_pointer_p` - a valid non-NULL pointer to a native buffer. - `native_info_p` - native pointer's type information. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_native_pointer_init_references` in earlier versions.* **Example** @@ -9921,7 +10491,7 @@ jerry_native_ptr_set (jerry_value_t *reference_p, - `reference_p` - a valid non-NULL pointer to a reference in a native buffer. - `value` - new value of the reference. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_native_pointer_set_reference` in earlier versions.* **Example** @@ -9954,7 +10524,9 @@ jerry_object_property_names (jerry_value_t obj_val, - array containing the filtered property keys in successful operation - exception, otherwise -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_object_get_property_names` in earlier versions.* **Example** @@ -10001,8 +10573,9 @@ jerry_object_foreach (jerry_value_t obj_val, - object fields traversal was stopped on callback that returned false - false, otherwise -**Example** +*Renamed in version 3.0, it was previously known as `jerry_foreach_object_property` in earlier versions.* +**Example** [doctest]: # (name="02.API-REFERENCE-foreach-property.c") @@ -10102,7 +10675,9 @@ jerry_foreach_live_object (jerry_foreach_live_object_cb_t foreach_p, - `true`, if the search function terminated the traversal by returning `false` - `false`, if the end of the list of objects was reached -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_objects_foreach` in earlier versions.* **Example** @@ -10241,7 +10816,9 @@ jerry_foreach_live_object_with_info (const jerry_object_native_info_t *native_in - `true`, if the search function terminated the traversal by returning `false` - `false`, if the end of the list of objects was reached -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_objects_foreach_by_native_info` in earlier versions.* **Example** @@ -10402,7 +10979,9 @@ jerry_validate_string (const jerry_char_t *buffer_p, /**< string data */ - true, if the provided string was a valid UTF-8 string. - false, if the string is not valid as an UTF-8 string. -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_is_valid_cesu8_string` or `jerry_is_valid_utf8_string` in earlier versions.* **Example** @@ -10455,7 +11034,7 @@ void *jerry_heap_alloc (size_t size); - return value: non-NULL pointer, if the memory is successfully allocated, NULL otherwise. -*New in version 2.0*. +*Introduced in version 2.0*. **See also** @@ -10476,7 +11055,7 @@ void jerry_heap_free (void *mem_p, size_t size); - `mem_p`: value returned by `jerry_heap_alloc`. - `size`: same size as passed to `jerry_heap_alloc`. -*New in version 2.0*. +*Introduced in version 2.0*. **See also** @@ -10518,9 +11097,9 @@ jerry_generate_snapshot (jerry_value_t compiled_code, current configuration through JERRY_SNAPSHOT_SAVE) - thrown exception, otherwise. -*New in version 2.0*. +*Introduced in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: The `source_p`, `source_size`, `source_name_p`, +*Updated in version 3.0*: The `source_p`, `source_size`, `source_name_p`, and `source_name_length` arguments are replaced by `compiled_code` which should contain a compiled ECMAScript script / function. The `jerry_generate_function_snapshot` is now removed and can be reproduced @@ -10606,9 +11185,9 @@ jerry_exec_snapshot (const uint32_t *snapshot_p, - result of bytecode, if run was successful. - thrown exception, otherwise (an exception is reported if the snapshot execution feature is not enabled). -*Changed in version 2.0*: Added `func_index` and `exec_snapshot_opts` arguments. Removed the `copy_bytecode` last argument. +*Updated in version 2.0*: Added `func_index` and `exec_snapshot_opts` arguments. Removed the `copy_bytecode` last argument. -*Changed in version [[NEXT_RELEASE]]*: Added `options_p` argument. +*Updated in version 3.0*: Added `options_p` argument. **Example 1** @@ -10733,6 +11312,96 @@ main (void) - [jerry_cleanup](#jerry_cleanup) - [jerry_generate_snapshot](#jerry_generate_snapshot) +## jerry_merge_snapshots + +**Summary** + +Merge multiple snapshots into a single buffer + +**Prototype** + +```c +size_t jerry_merge_snapshots (const uint32_t **inp_buffers_p, + size_t *inp_buffer_sizes_p, + size_t number_of_snapshots, + uint32_t *out_buffer_p, + size_t out_buffer_size, + const char **error_p); +``` + +- `inp_buffers_p` - array of (pointers to start of) input buffers +- `inp_buffer_sizes_p` - array of input buffer sizes +- `number_of_snapshots` - number of snapshots +- `out_buffer_p` - output buffer +- `out_buffer_size` - output buffer size +- `error_p` - error description +- return value + - length of the merged snapshot file + - 0 on error + +**Example** + +```c + static uint32_t snapshot_buffer_0[SNAPSHOT_BUFFER_SIZE]; + static uint32_t snapshot_buffer_1[SNAPSHOT_BUFFER_SIZE]; + size_t snapshot_sizes[2]; + static uint32_t merged_snapshot_buffer[SNAPSHOT_BUFFER_SIZE]; + + const jerry_char_t code_to_snapshot1[] = "var a = 'hello'; 123"; + + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t parse_result = jerry_parse (code_to_snapshot1, sizeof (code_to_snapshot1) - 1, NULL); + jerry_value_t generate_result = jerry_generate_snapshot (parse_result, 0, snapshot_buffer_0, SNAPSHOT_BUFFER_SIZE); + jerry_value_free (parse_result); + + snapshot_sizes[0] = (size_t) jerry_value_as_number (generate_result); + jerry_value_free (generate_result); + + jerry_cleanup (); + + const jerry_char_t code_to_snapshot2[] = "var b = 'hello'; 456"; + + jerry_init (JERRY_INIT_EMPTY); + + parse_result = jerry_parse (code_to_snapshot2, sizeof (code_to_snapshot2) - 1, NULL); + generate_result = jerry_generate_snapshot (parse_result, 0, snapshot_buffer_1, SNAPSHOT_BUFFER_SIZE); + jerry_value_free (parse_result); + + snapshot_sizes[1] = (size_t) jerry_value_as_number (generate_result); + jerry_value_free (generate_result); + + jerry_cleanup (); + + jerry_init (JERRY_INIT_EMPTY); + + const char *error_p; + const uint32_t *snapshot_buffers[2]; + + snapshot_buffers[0] = snapshot_buffer_0; + snapshot_buffers[1] = snapshot_buffer_1; + + static uint32_t snapshot_buffer_0_bck[SNAPSHOT_BUFFER_SIZE]; + static uint32_t snapshot_buffer_1_bck[SNAPSHOT_BUFFER_SIZE]; + + memcpy (snapshot_buffer_0_bck, snapshot_buffer_0, SNAPSHOT_BUFFER_SIZE); + memcpy (snapshot_buffer_1_bck, snapshot_buffer_1, SNAPSHOT_BUFFER_SIZE); + + size_t merged_size = jerry_merge_snapshots (snapshot_buffers, + snapshot_sizes, + 2, + merged_snapshot_buffer, + SNAPSHOT_BUFFER_SIZE, + &error_p); + + jerry_cleanup (); +``` + +**See also** + +- [jerry_generate_snapshot](#jerry_generate_snapshot) +- [jerry_exec_snapshot](#jerry_exec_snapshot) + ## jerry_get_literals_from_snapshot @@ -10764,10 +11433,10 @@ jerry_get_literals_from_snapshot (const uint32_t *snapshot_p, - `is_c_format` - the output format would be C-style (true) or a simple list (false). - return value - the size of the literal-list, if it was generated successfully (i.e. the list of literals isn't empty, - and literal-save support is enabled in current configuration through JERRY_SNAPSHOT_SAVE) + and literal-save support is enabled in current configuration through `JERRY_SNAPSHOT_SAVE`) - 0 otherwise. -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -10855,7 +11524,9 @@ jerry_backtrace (uint32_t max_depth); - return value - a newly constructed JS array -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_backtrace` in earlier versions.* **Example** @@ -10973,7 +11644,7 @@ jerry_backtrace_capture (jerry_backtrace_cb_t callback, void *user_p); which is called for each captured frame - `user_p` - pointer passed to the `callback` function, can be NULL -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **Example** @@ -11081,7 +11752,7 @@ jerry_frame_type (jerry_frame_t *frame_p); - return value - frame type listed in [jerry_frame_type_t](#jerry_frame_type_t) -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_backtrace_get_frame_type` in earlier versions.* **Example** @@ -11144,7 +11815,7 @@ jerry_frame_location (jerry_frame_t *frame_p); - pointer to the location private field if the location is available, - NULL otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_backtrace_get_location` in earlier versions.* **Example** @@ -11207,7 +11878,7 @@ jerry_frame_callee (jerry_frame_t *frame_p); - pointer to the called function if the function is available, - NULL otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_backtrace_get_function` in earlier versions.* **Example** @@ -11264,7 +11935,7 @@ jerry_frame_this (jerry_frame_t *frame_p); - pointer to the 'this' binding if the binding is available, - NULL otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_backtrace_get_this` in earlier versions.* **Example** @@ -11315,7 +11986,7 @@ jerry_frame_is_strict (jerry_frame_t *frame_p); - true, if strict mode code is bound to the frame - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_backtrace_is_strict` in earlier versions.* **Example** @@ -11345,6 +12016,73 @@ backtrace_callback (jerry_frame_t *frame_p, # Miscellaneous functions +## jerry_log + +**Summary** + + Log a zero-terminated formatted message with the specified log level. + +**Prototype** + +```c +void jerry_log (jerry_log_level_t level, const char *format_p, ...); +``` + +- `level` - message log level, see [jerry_log_level_t](#jerry_log_level_t) +- `format_p` - format string + Supported format specifiers: + `%s`: zero-terminated string + `%c`: character + `%u`: unsigned integer + `%d`: decimal integer + `%x`: unsigned hexadecimal + Width and padding sub-modifiers are also supported. +- rest - variables to substitue into the format string + +*Introduced in version 3.0*. + +**Example** + +```c +jerry_log (JERRY_LOG_LEVEL_DEBUG, + "My debug message with a number param: %d.\n", 42); +``` + +**See also** + +- [jerry_log_level_t](#jerry_log_level_t) +- [jerry_log_set_level](#jerry_log_set_level) + + +## jerry_log_set_level + +**Summary** + +Set the log level of the engine. +Log messages with lower significance than the current log level will be ignored by `jerry_log`. + +**Prototype** + +```c +void jerry_log_set_level (jerry_log_level_t level); +``` + +- `level` - log level to be set, see [jerry_log_level_t](#jerry_log_level_t) + +*Introduced in version 3.0*. + +**Example** + +```c +jerry_log_set_level (JERRY_LOG_LEVEL_WARNING); +``` + +**See also** + +- [jerry_log_level_t](#jerry_log_level_t) +- [jerry_log](#jerry_log) + + ## jerry_halt_handler **Summary** @@ -11381,7 +12119,9 @@ jerry_halt_handler (uint32_t interval, - `callback` - periodically called callback (passing NULL disables this feature) - `user_p` - user pointer passed to the `callback` function -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_set_vm_exec_stop_callback` in earlier versions.* **Example** @@ -11454,7 +12194,9 @@ jerry_source_name (jerry_value_t value); - source name of the function object, if the given value is a function object - "", otherwise -*New in version 2.2*. +*Introduced in version 2.2*. + +*Renamed in version 3.0, it was previously known as `jerry_get_resource_name` in earlier versions.* **Example** @@ -11552,7 +12294,7 @@ jerry_source_user_value (const jerry_value_t value); - user value - if available, - undefined - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_get_user_value` in earlier versions.* **Example** @@ -11612,7 +12354,7 @@ bool jerry_function_is_dynamic (const jerry_value_t value); - true - if code is compiled by eval like command - false - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_is_eval_code` in earlier versions.* **Example** @@ -11674,7 +12416,7 @@ jerry_source_info_t *jerry_source_info (const jerry_value_t value); - source info - a newly created source info, if at least one field is available, - NULL - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_get_source_info` in earlier versions.* **Example** @@ -11730,7 +12472,7 @@ void jerry_source_info_free (jerry_source_info_t *source_info_p) ``` - `source_info_p` - source info structure returned by [jerry_source_info](#jerry_source_info) -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_free_source_info` in earlier versions.* **Example** @@ -11767,7 +12509,7 @@ which was active when the code was parsed or loaded regardless of the current re - This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked in runtime with the `JERRY_FEATURE_REALM` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -11780,7 +12522,7 @@ jerry_set_realm (jerry_value_t realm_value); - previous realm value - if the passed value is a realm - exception - otherwise -*New in version 2.4*. +*Introduced in version 2.4*. **Example** @@ -11812,7 +12554,7 @@ changed by [jerry_realm_set_this](#jerry_realm_set_this). - This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked in runtime with the `JERRY_FEATURE_REALM` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -11825,7 +12567,9 @@ jerry_realm_this (jerry_value_t realm_value) - type error exception- if realm_value is not a realm - 'this' binding object - otherwise -*New in version 2.4*. +*Introduced in version 2.4*. + +*Renamed in version 3.0, it was previously known as `jerry_realm_get_this` in earlier versions.* **Example** @@ -11858,7 +12602,7 @@ any script on the realm. Otherwise the operation is undefined. - This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked in runtime with the `JERRY_FEATURE_REALM` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -11872,7 +12616,7 @@ jerry_realm_set_this (jerry_value_t realm_value, jerry_value_t this_value) - type error exception- if realm_value is not a realm or this_value is not object - true - otherwise -*New in version 2.4*. +*Introduced in version 2.4*. **Example** @@ -11922,7 +12666,9 @@ jerry_arraybuffer_size (const jerry_value_t value); - size of the ArrayBuffer in bytes - 0 if the `value` parameter is not an ArrayBuffer -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_arraybuffer_byte_length` in earlier versions.* **Example** @@ -11974,7 +12720,7 @@ jerry_arraybuffer_read (const jerry_value_t value, - 0 if the `value` is not an ArrayBuffer object - 0 if the `buf_size` is zero or there is nothing to read -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -12038,7 +12784,7 @@ jerry_arraybuffer_write (const jerry_value_t value, - 0 if the `value` is not an ArrayBuffer object - 0 if the `buf_size` is zero or there is nothing to write -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -12102,7 +12848,9 @@ jerry_arraybuffer_data (const jerry_value_t value); - not an ArrayBuffer object - an external ArrayBuffer has been detached -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_arraybuffer_pointer` in earlier versions.* **Example** @@ -12147,7 +12895,9 @@ jerry_arraybuffer_is_detachable (const jerry_value_t value); - true if the arraybuffer is detachable - false otherwise -*New in version 2.2*. +*Introduced in version 2.2*. + +*Renamed in version 3.0, it was previously known as `jerry_is_arraybuffer_detachable` in earlier versions.* **Example** @@ -12190,7 +12940,9 @@ jerry_arraybuffer_detach (const jerry_value_t value); - null value if success - exception otherwise -*New in version 2.2*. +*Introduced in version 2.2*. + +*Renamed in version 3.0, it was previously known as `jerry_detach_arraybuffer` in earlier versions.* **Example** @@ -12236,7 +12988,7 @@ jerry_arraybuffer_has_buffer (const jerry_value_t value); - true, if a buffer is allocated for an array buffer or typed array - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **Example** @@ -12302,7 +13054,7 @@ jerry_arraybuffer_heap_allocation_limit (const jerry_length_t allocation_limit); - `allocation_limit` - maximum size of compact allocation. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_arraybuffer_set_compact_allocation_limit` in earlier versions.* **Example** @@ -12378,7 +13130,7 @@ jerry_arraybuffer_allocator (jerry_arraybuffer_allocate_cb_t allocate_callback, - `free_callback` - callback for freeing array buffer memory. - `user_p` - user pointer passed to the callbacks. -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_arraybuffer_set_allocator_callbacks` in earlier versions.* **Example** @@ -12465,7 +13217,9 @@ jerry_dataview_buffer (const jerry_value_t value, - DataView object's underlying ArrayBuffer object - TypeError if the `value` is not a DataView object -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_dataview_buffer` in earlier versions.* **Example** @@ -12525,7 +13279,9 @@ jerry_typedarray_type (jerry_value_t value); - the type of the TypedArray - JERRY_TYPEDARRAY_INVALID if the object was not a TypedArray -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_typedarray_type` in earlier versions.* **Example** @@ -12568,7 +13324,9 @@ jerry_typedarray_length (jerry_value_t value); - length (element count) of the TypedArray object - 0 if the object is not a TypedArray -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_typedarray_length` in earlier versions.* **Example** @@ -12619,7 +13377,9 @@ jerry_typedarray_buffer (jerry_value_t value, - TypedArray object's underlying ArrayBuffer object - TypeError if the `value` is not a TypedArray object -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_get_typedarray_buffer` in earlier versions.* **Example** @@ -12670,7 +13430,7 @@ jerry_json_parse (const jerry_char_t *string_p, - `jerry_value_t` containing a JavaScript value. - exception value in case of any parse error. -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -12721,7 +13481,7 @@ jerry_json_stringify (const jerry_value_t input_value); - `jerry_value_t` containing a JSON string. - exception value in case of any stringification error. -*New in version 2.0*. +*Introduced in version 2.0*. **Example** @@ -12774,16 +13534,16 @@ if the container object contains key-value structure and false if not. runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` feature enum values. see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. -*New in version [[NEXT_RELEASE]]*. + +*Introduced in version 3.0*. **Prototype** ```c jerry_value_t -jerry_container_to_array(jerry_value_t value, - bool *is_key_value_p); +jerry_container_to_array (jerry_value_t value, + bool *is_key_value_p); ``` - `value` - Map/Set or iterator object @@ -12842,7 +13602,7 @@ Perform container operation on the given operands (add, delete, set, etc.). runtime with the `JERRY_FEATURE_MAP` , `JERRY_FEATURE_SET` , `JERRY_FEATURE_WEAKMAP` , `JERRY_FEATURE_WEAKSET` feature enum values. see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -12861,7 +13621,7 @@ jerry_container_op (jerry_container_op_t operation, - result if the operation is successful - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0, it was previously known as `jerry_container_operation` in earlier versions.* **Example** diff --git a/jerry-core/api/jerry-module.c b/jerry-core/api/jerry-module.c index c0443866a8..0e5f6eae02 100644 --- a/jerry-core/api/jerry-module.c +++ b/jerry-core/api/jerry-module.c @@ -237,7 +237,7 @@ jerry_module_resolve (const jerry_value_t specifier, /**< module specifier strin */ void jerry_module_cleanup (const jerry_value_t realm) /**< if this argument is object, release only those modules, - * which realm value is equal to this argument. */ + * whose realm value is equal to this argument. */ { #if JERRY_MODULE_SYSTEM jerry_module_free ((jerry_module_manager_t *) jerry_context_data (&jerry_module_manager), realm); diff --git a/jerry-core/api/jerryscript.c b/jerry-core/api/jerryscript.c index 60f8023fd0..033e03de39 100644 --- a/jerry-core/api/jerryscript.c +++ b/jerry-core/api/jerryscript.c @@ -4294,7 +4294,7 @@ jerry_object_set_native_ptr (jerry_value_t object, /**< object to set native poi } /* jerry_object_set_native_ptr */ /** - * Checks wether the argument object has a native poitner set for the specified native type info. + * Checks whether the argument object has a native pointer set for the specified native type info. * * @return true if the native pointer has been set, * false otherwise diff --git a/jerry-core/include/jerryscript-types.h b/jerry-core/include/jerryscript-types.h index f0766b91ca..908382b237 100644 --- a/jerry-core/include/jerryscript-types.h +++ b/jerry-core/include/jerryscript-types.h @@ -41,8 +41,8 @@ typedef enum } jerry_init_flag_t; /** - * Jerry log levels. The levels are in severity order - * where the most serious levels come first. + * Jerry log levels. The levels are ordered by severity, + * with the most serious levels listed first. */ typedef enum { @@ -86,7 +86,6 @@ typedef enum JERRY_FEATURE_VM_EXEC_STOP, /**< stopping ECMAScript execution */ JERRY_FEATURE_VM_THROW, /**< capturing ECMAScript throws */ JERRY_FEATURE_JSON, /**< JSON support */ - JERRY_FEATURE_PROMISE, /**< promise support */ JERRY_FEATURE_TYPEDARRAY, /**< Typedarray support */ JERRY_FEATURE_DATE, /**< Date support */ JERRY_FEATURE_REGEXP, /**< Regexp support */ @@ -315,8 +314,10 @@ typedef void (*jerry_error_object_created_cb_t) (const jerry_value_t error_objec * * Note: if the function returns with a non-undefined value it * must return with the same value for future calls. + * + * @param user_data_p: optional user data pointer */ -typedef jerry_value_t (*jerry_halt_cb_t) (void *user_p); +typedef jerry_value_t (*jerry_halt_cb_t) (void *user_data_p); /** * Callback function which is called when an exception is thrown in an ECMAScript code. @@ -324,13 +325,19 @@ typedef jerry_value_t (*jerry_halt_cb_t) (void *user_p); * until the value is caught. * * Note: the engine considers exceptions thrown by external functions as never caught. + * + * @param exception_value: the thrown exception + * @param user_data_p: optional user data pointer */ -typedef void (*jerry_throw_cb_t) (const jerry_value_t exception_value, void *user_p); +typedef void (*jerry_throw_cb_t) (const jerry_value_t exception_value, void *user_data_p); /** * Function type applied to each unit of encoding when iterating over a string. + * + * @param value: encoded byte value + * @param user_data_p: optional user data pointer */ -typedef void (*jerry_string_iterate_cb_t) (uint32_t value, void *user_p); +typedef void (*jerry_string_iterate_cb_t) (uint32_t value, void *user_data_p); /** * Function type applied for each data property of an object. diff --git a/jerry-ext/util/print.c b/jerry-ext/util/print.c index 6e79a8eb75..82ac7bc52b 100644 --- a/jerry-ext/util/print.c +++ b/jerry-ext/util/print.c @@ -36,7 +36,7 @@ #define JERRYX_SYNTAX_ERROR_MAX_LINE_LENGTH 256 /** - * Struct for buffering print outpu + * Struct for buffering print output */ typedef struct { diff --git a/tests/unit-core/test-api-objecttype.c b/tests/unit-core/test-api-objecttype.c index 0e35c8fc78..4c0337d1c1 100644 --- a/tests/unit-core/test-api-objecttype.c +++ b/tests/unit-core/test-api-objecttype.c @@ -126,7 +126,7 @@ main (void) ENTRY (JERRY_OBJECT_TYPE_SCRIPT, PARSE (NULL)), ENTRY_IF (JERRY_OBJECT_TYPE_MODULE, PARSE (&module_parse_options), JERRY_FEATURE_MODULE), - ENTRY_IF (JERRY_OBJECT_TYPE_PROMISE, jerry_promise (), JERRY_FEATURE_PROMISE), + ENTRY (JERRY_OBJECT_TYPE_PROMISE, jerry_promise ()), ENTRY_IF (JERRY_OBJECT_TYPE_DATAVIEW, test_dataview (), JERRY_FEATURE_DATAVIEW), ENTRY_IF (JERRY_OBJECT_TYPE_FUNCTION, EVALUATE (arrow_function), JERRY_FEATURE_SYMBOL), ENTRY_IF (JERRY_OBJECT_TYPE_FUNCTION, EVALUATE (async_arrow_function), JERRY_FEATURE_SYMBOL),