diff --git a/01.CONFIGURATION.md b/01.CONFIGURATION.md index 227b5192f3..1246eb4cab 100644 --- a/01.CONFIGURATION.md +++ b/01.CONFIGURATION.md @@ -301,6 +301,58 @@ This option is disabled by default. | CMake: | `-DJERRY_MEM_GC_BEFORE_EACH_ALLOC=ON/OFF` | | Python: | `--mem-stress-test=ON/OFF` | +### MSVC CRT + +This option enables the use of the MSVC CRT library and is disabled by default. + +| Options | | +|---------|----------------------------------------------| +| C: | `` | +| CMake: | `-DENABLE_STATIC_CRT=ON/OFF` | +| Python: | `--static-crt=ON/OFF` | + +### Architecture + +Specify the platform name if it is supported by the generator. + +| Options | | +|---------|----------------------------------------------| +| C: | `` | +| CMake: | `-A (string)` | +| Python: | `--arch=(string)` | + +### Tostring function + +Enable function toString. + +| Options | | +|---------|----------------------------------------------| +| C: | `-DJERRY_FUNCTION_TO_STRING=0/1` | +| CMake: | `-DJERRY_FUNCTION_TO_STRING=ON/OFF` | +| Python: | `--function-to-string=ON/OFF` | + + +### VM throw + +Enable VM throw. + +| Options | | +|---------|----------------------------------------------| +| C: | `-DJERRY_VM_THROW=0/1` | +| CMake: | `-DJERRY_VM_THROW=ON/OFF` | +| Python: | `--vm-throw=ON/OFF` | + + +### Promise callback + +Enable Promise callback. + +| Options | | +|---------|----------------------------------------------| +| C: | `-DJERRY_PROMISE_CALLBACK=0/1` | +| CMake: | `-DJERRY_PROMISE_CALLBACK=ON/OFF` | +| Python: | `--promise-callback=ON/OFF` | + # Amalgamated sources diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 6bbf320230..8f5f450d29 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -19,6 +19,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: @@ -35,9 +49,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 @@ -59,7 +73,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 @@ -71,9 +84,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. @@ -88,7 +101,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 @@ -100,7 +113,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 @@ -108,11 +121,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 @@ -128,9 +141,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`. @@ -139,18 +152,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 @@ -168,7 +182,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 @@ -189,15 +202,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 @@ -209,7 +223,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 @@ -229,7 +243,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 @@ -248,9 +262,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 @@ -265,7 +279,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. @@ -274,6 +288,7 @@ an exception during parsing. - [jerry_parse_options_t](#jerry_parse_options_t) + ## jerry_gc_mode_t Set garbage collection operational mode @@ -286,7 +301,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 @@ -295,7 +311,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 @@ -323,9 +340,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 @@ -339,7 +357,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** @@ -354,7 +372,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 @@ -392,6 +411,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** @@ -409,6 +437,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** @@ -466,7 +495,8 @@ typedef struct } jerry_context_data_manager_t; ``` -*New in version 2.0*. +*Introduced in version 2.0*. + ## jerry_context_alloc_t @@ -483,7 +513,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 @@ -497,7 +529,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 @@ -510,7 +542,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 @@ -528,7 +560,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** @@ -550,7 +582,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** @@ -580,7 +612,7 @@ typedef struct } jerry_parse_options_t; ``` -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -614,10 +646,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** @@ -642,7 +674,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 @@ -666,7 +698,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 @@ -688,7 +720,7 @@ typedef struct } jerry_heap_stats_t; ``` -*New in version 2.0*. +*Introduced in version 2.0*. **See also** @@ -711,7 +743,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** @@ -757,7 +789,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** @@ -784,11 +816,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** @@ -814,7 +846,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** @@ -843,7 +875,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** @@ -861,7 +895,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 @@ -888,7 +922,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) @@ -930,7 +964,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) @@ -957,7 +991,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) @@ -982,7 +1016,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) @@ -1008,7 +1042,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) @@ -1032,7 +1066,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** @@ -1081,9 +1115,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** @@ -1117,6 +1151,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) @@ -1142,7 +1178,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** @@ -1171,7 +1209,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** @@ -1192,7 +1232,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** @@ -1215,15 +1255,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. @@ -1235,7 +1298,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** @@ -1292,7 +1355,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** @@ -1331,7 +1394,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** @@ -1360,7 +1423,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** @@ -1388,9 +1451,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** @@ -1417,7 +1480,7 @@ typedef struct } jerry_exec_snapshot_option_values_t; ``` -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -1432,7 +1495,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** @@ -1458,7 +1521,7 @@ typedef struct } jerry_source_info_t; ``` -*New in version [[NEXT_RELEASE]]*. +*Introduced in version 3.0*. **See also** @@ -1474,7 +1537,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** @@ -1510,7 +1573,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** @@ -1544,7 +1607,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** @@ -1637,7 +1700,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** @@ -1719,7 +1784,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** @@ -1785,7 +1850,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** @@ -1817,7 +1884,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** @@ -1875,9 +1944,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** @@ -1986,7 +2055,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** @@ -2148,7 +2217,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** @@ -2218,6 +2289,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 @@ -2258,7 +2331,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** @@ -2329,7 +2402,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** @@ -2343,7 +2415,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** @@ -2376,7 +2448,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** @@ -2390,7 +2461,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** @@ -2470,7 +2541,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** @@ -2510,7 +2581,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** @@ -2580,7 +2651,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** @@ -2594,7 +2664,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** @@ -2648,7 +2718,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** @@ -2728,7 +2798,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** @@ -2885,7 +2955,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** @@ -2919,7 +2989,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** @@ -2934,7 +3003,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** @@ -3016,7 +3085,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** @@ -3063,7 +3132,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** @@ -3077,7 +3145,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** @@ -3125,7 +3193,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** @@ -3139,7 +3206,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** @@ -3184,7 +3251,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** @@ -3198,7 +3264,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** @@ -3292,7 +3360,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** @@ -3340,7 +3410,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** @@ -3383,7 +3455,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** @@ -3427,7 +3501,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** @@ -3469,7 +3545,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** @@ -3518,7 +3594,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** @@ -3610,7 +3688,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 @@ -3636,7 +3714,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** @@ -3695,7 +3775,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** @@ -3754,7 +3836,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** @@ -3802,7 +3886,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** @@ -3858,7 +3944,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** @@ -3912,11 +4000,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include "jerryscript.h" @@ -3957,6 +4045,7 @@ main (void) - [jerry_exception_is_captured](#jerry_exception_is_captured) - [jerry_exception_allow_capture](#jerry_exception_allow_capture) + ## jerry_exception_is_captured **Summary** @@ -3980,11 +4069,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include "jerryscript.h" @@ -4046,11 +4135,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include "jerryscript.h" @@ -4134,6 +4223,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 @@ -4171,12 +4262,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 @@ -4220,6 +4313,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 @@ -4242,6 +4337,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** @@ -4273,6 +4458,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]: # () @@ -4311,12 +4498,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** @@ -4338,7 +4525,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** @@ -4381,7 +4568,7 @@ main (void) - [jerry_string_external](#jerry_string_external) -# jerry_string_user_ptr +## jerry_string_user_ptr **Summary** @@ -4407,7 +4594,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** @@ -4469,6 +4656,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 @@ -4706,7 +4895,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** @@ -4747,7 +4936,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** @@ -4778,7 +4967,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** @@ -4809,7 +4998,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** @@ -4853,11 +5042,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # (test="link") ```c #include @@ -4932,11 +5121,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -4970,6 +5159,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** @@ -4993,11 +5213,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -5054,11 +5274,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -5132,11 +5352,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -5210,11 +5430,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -5282,11 +5502,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -5350,11 +5570,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -5418,11 +5638,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -5550,11 +5770,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -5613,11 +5833,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -5674,11 +5894,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include @@ -5738,7 +5958,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** @@ -5798,7 +6020,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** @@ -5864,7 +6088,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** @@ -5939,7 +6163,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** @@ -5991,7 +6217,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** @@ -6019,6 +6245,7 @@ example (void) } ``` + ## jerry_promise_resolve **Summary** @@ -6028,11 +6255,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** @@ -6047,9 +6269,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** @@ -6079,6 +6301,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** @@ -6102,7 +6325,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** @@ -6159,7 +6384,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** @@ -6214,7 +6441,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** @@ -6272,7 +6501,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** @@ -6338,7 +6569,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** @@ -6403,7 +6636,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** @@ -6451,7 +6686,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** @@ -6466,7 +6700,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** @@ -6504,7 +6740,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** @@ -6519,7 +6754,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** @@ -6569,6 +6804,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 @@ -6607,6 +6844,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 @@ -6646,6 +6885,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 @@ -6687,7 +6928,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** @@ -6744,9 +6987,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** @@ -6792,7 +7037,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** @@ -6847,7 +7092,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** @@ -6892,6 +7137,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 @@ -6932,6 +7179,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 @@ -6974,6 +7223,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 @@ -7020,7 +7271,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** @@ -7072,6 +7325,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]: # () @@ -7146,6 +7401,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 @@ -7184,6 +7441,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 @@ -7221,6 +7480,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 @@ -7259,6 +7520,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 @@ -7294,6 +7557,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 @@ -7331,7 +7596,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** @@ -7377,7 +7644,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** @@ -7442,7 +7711,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** @@ -7494,9 +7763,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 @@ -7538,6 +7809,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 @@ -7580,13 +7853,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** @@ -7634,9 +7909,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** @@ -7661,7 +7938,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** @@ -7684,7 +7961,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** @@ -7745,7 +8024,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** @@ -7781,9 +8062,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. @@ -7798,7 +8079,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** @@ -7838,7 +8121,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** @@ -7875,7 +8160,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** @@ -7888,7 +8173,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** @@ -7931,7 +8218,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** @@ -7947,7 +8234,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** @@ -7992,7 +8281,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** @@ -8012,7 +8301,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** @@ -8049,7 +8340,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** @@ -8065,7 +8356,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** @@ -8118,6 +8411,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 @@ -8147,7 +8442,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** @@ -8158,7 +8453,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** @@ -8213,9 +8510,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** @@ -8251,32 +8550,27 @@ main (void) - [jerry_object_delete](#jerry_object_delete) -## jerry_object_has_own +## jerry_object_has_sz **Summary** -Checks whether the object has the given property. +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. +*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_own (const jerry_value_t obj_val, - const jerry_value_t prop_name_val); +jerry_value_t jerry_object_has_sz (const jerry_value_t object, const char *key_p); ``` -- `obj_val` - object value -- `prop_name_val` - property name +- `object` - object value +- `key_p` - property name (zero-terminated string) - return value - JavaScript value that evaluates to - - exception - if the operation fails + - 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. - -*Changed in version 2.3*: The return value can be an exception value. +*Introduced in version 3.0* **Example** @@ -8291,13 +8585,11 @@ main (void) jerry_init (JERRY_INIT_EMPTY); jerry_value_t global_object = jerry_current_realm (); - jerry_value_t prop_name = jerry_string_sz ("handler_field"); - jerry_value_t has_prop_js = jerry_object_has_own (global_object, prop_name); + 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 (prop_name); jerry_value_free (global_object); jerry_cleanup (); @@ -8309,28 +8601,90 @@ main (void) **See also** - [jerry_object_has](#jerry_object_has) -- [jerry_object_delete](#jerry_object_delete) -## jerry_object_has_internal +## jerry_object_has_own **Summary** -Checks whether the object has the given internal property. +Checks whether the object has the given property. -*Note*: - - Properties which were not created with [jerry_object_set_internal](#jerry_object_set_internal) are excluded - during the operation. - - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c -bool -jerry_object_has_internal (const jerry_value_t obj_val, - const jerry_value_t prop_name_val); -``` +jerry_value_t +jerry_object_has_own (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); +``` + +- `obj_val` - object value +- `prop_name_val` - property name +- return value - JavaScript value that evaluates to + - exception - if the operation fails + - true/false API value - depend on whether the property exists + +*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. + +*Renamed in version 3.0, it was previously known as `jerry_has_own_property` in earlier versions.* + +**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_name = jerry_string_sz ("handler_field"); + + jerry_value_t has_prop_js = jerry_object_has_own (global_object, prop_name); + bool has_prop = jerry_value_is_true (has_prop_js); + + jerry_value_free (has_prop_js); + jerry_value_free (prop_name); + jerry_value_free (global_object); + + jerry_cleanup (); + + return 0; +} +``` + +**See also** + +- [jerry_object_has](#jerry_object_has) +- [jerry_object_delete](#jerry_object_delete) + + +## jerry_object_has_internal + +**Summary** + +Checks whether the object has the given internal property. + +*Note*: + - Properties which were not created with [jerry_object_set_internal](#jerry_object_set_internal) are excluded + during the operation. + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it +is no longer needed. + +**Prototype** + +```c +bool +jerry_object_has_internal (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); +``` - `obj_val` - object value - `prop_name_val` - property name @@ -8338,7 +8692,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** @@ -8391,6 +8747,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 @@ -8415,6 +8773,45 @@ jerry_object_delete (const jerry_value_t obj_val, - [jerry_object_get](#jerry_object_get) +## jerry_object_delete_sz + +**Summary** + +Delete a property from an object. + +**Prototype** + +```c +jerry_value_t jerry_object_delete_sz (const jerry_value_t object, const char *key_p); +``` + +- `obj_val` - object value +- `key_p` - property name (zero-terminated string) +- return value + - true, if property was deleted successfully + - exception, otherwise + +*Introduced in version 3.0* + +**Example** + +```c +{ + 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** @@ -8435,7 +8832,9 @@ jerry_object_delete_index (const jerry_value_t obj_val, - true value, if property was deleted successfully - exception, otherwise -*New in version 2.0*. +*Introduced in version 2.0*. + +*Renamed in version 3.0, it was previously known as `jerry_delete_property_by_index` in earlier versions.* **Example** @@ -8485,7 +8884,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** @@ -8532,6 +8933,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]: # () @@ -8570,6 +8973,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** @@ -8593,6 +9049,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 @@ -8652,6 +9110,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]: # () @@ -8718,7 +9178,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** @@ -8779,6 +9241,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 @@ -8815,6 +9279,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** @@ -8840,6 +9356,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 @@ -8897,7 +9415,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** @@ -8948,7 +9468,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** @@ -8997,6 +9517,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: @@ -9178,7 +9700,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** @@ -9222,7 +9744,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** @@ -9269,6 +9791,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 @@ -9325,6 +9849,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 @@ -9373,6 +9899,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 @@ -9415,6 +9943,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 @@ -9459,6 +9989,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 @@ -9504,7 +10036,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** @@ -9600,14 +10134,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 @@ -9616,14 +10150,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; @@ -9694,6 +10228,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** @@ -9727,7 +10293,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** @@ -9764,7 +10332,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** @@ -9803,7 +10373,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** @@ -9894,7 +10464,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** @@ -9931,7 +10501,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** @@ -9964,7 +10534,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** @@ -10011,8 +10583,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") @@ -10112,7 +10685,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** @@ -10251,7 +10826,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** @@ -10412,7 +10989,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** @@ -10465,7 +11044,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** @@ -10486,7 +11065,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** @@ -10528,9 +11107,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 @@ -10616,9 +11195,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** @@ -10743,6 +11322,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 @@ -10774,10 +11443,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** @@ -10865,7 +11534,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** @@ -10983,7 +11654,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** @@ -11091,7 +11762,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** @@ -11154,7 +11825,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** @@ -11217,7 +11888,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** @@ -11274,7 +11945,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** @@ -11325,7 +11996,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** @@ -11355,6 +12026,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** @@ -11391,7 +12129,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** @@ -11464,7 +12204,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** @@ -11562,7 +12304,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** @@ -11622,7 +12364,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** @@ -11684,7 +12426,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** @@ -11740,7 +12482,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** @@ -11777,7 +12519,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** @@ -11790,7 +12532,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** @@ -11822,7 +12564,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** @@ -11835,7 +12577,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** @@ -11868,7 +12612,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** @@ -11882,7 +12626,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** @@ -11932,7 +12676,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** @@ -11984,7 +12730,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** @@ -12048,7 +12794,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** @@ -12112,7 +12858,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** @@ -12157,7 +12905,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** @@ -12200,7 +12950,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** @@ -12246,11 +12998,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include "jerryscript.h" @@ -12312,11 +13064,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include "jerryscript.h" @@ -12388,11 +13140,11 @@ 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** -[doctest]: # (test="compile") +[doctest]: # () ```c #include "jerryscript.h" @@ -12475,7 +13227,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** @@ -12535,7 +13289,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** @@ -12578,7 +13334,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** @@ -12629,7 +13387,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** @@ -12680,7 +13440,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** @@ -12731,7 +13491,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** @@ -12784,16 +13544,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 @@ -12852,7 +13612,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** @@ -12871,7 +13631,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/05.PORT-API.md b/05.PORT-API.md index 14ffc48d73..ee557016d0 100644 --- a/05.PORT-API.md +++ b/05.PORT-API.md @@ -14,6 +14,13 @@ permalink: /port-api/ It is questionable whether a library should be able to terminate an application. Any API function can signal an error (ex.: cannot allocate memory), so the engine use the termination approach with this port function. +```c +/** + * Init the program + */ +void jerry_port_init (void); +``` + ```c /** * Signal the port that jerry experienced a fatal failure from which it cannot @@ -126,18 +133,6 @@ void jerry_port_context_free (void); void jerry_port_log (const char *message_p); ``` -```c -/** - * Print a single character to standard output. - * - * This port function is never called from jerry-core directly, it is only used by jerry-ext components to print - * information. - * - * @param byte: the byte to print. - */ -void jerry_port_print_byte (jerry_char_t byte); -``` - ```c /** * Print a buffer to standard output diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md index 515c2a1ccc..b5b13ab277 100644 --- a/07.DEBUGGER.md +++ b/07.DEBUGGER.md @@ -110,7 +110,8 @@ typedef jerry_value_t (*jerry_debugger_wait_for_source_callback_t) (const jerry_char_t *source_name_p, size_t source_name_size, const jerry_char_t *source_p, - size_t source_size, void *user_p); + size_t source_size, + void *user_p); ``` - `source_name_p` - source (usually a file) name of the source code @@ -303,7 +304,8 @@ return value of the function. ```c jerry_debugger_wait_for_source_status_t jerry_debugger_wait_for_client_source (jerry_debugger_wait_for_source_callback_t callback_p, - void *user_p, jerry_value_t *return_value) + void *user_p, + jerry_value_t *return_value) ``` **Example** @@ -395,7 +397,7 @@ Sends the program's output to the debugger client. ```c void -jerry_debugger_send_output (const jerry_char_t *buffer, jerry_size_t string_size) +jerry_debugger_send_output (const jerry_char_t *buffer, jerry_size_t str_size) ``` **Example** diff --git a/09.EXT-REFERENCE-ARG.md b/09.EXT-REFERENCE-ARG.md index 942197b789..5009dc4d08 100644 --- a/09.EXT-REFERENCE-ARG.md +++ b/09.EXT-REFERENCE-ARG.md @@ -371,6 +371,28 @@ jerryx_arg_transform_array (const jerry_value_t array_val, - [jerryx_arg_array](#jerryx_arg_array) +## jerryx_arg_transform_optional + +**Summary** + +The common function to deal with optional arguments. The core transform function is provided by argument `func`. + +**Prototype** + +```c +jerry_value_t jerryx_arg_transform_optional (jerryx_arg_js_iterator_t *js_arg_iter_p, + const jerryx_arg_t *c_arg_p, + jerryx_arg_transform_func_t func); +``` + + - `js_arg_iter_p` - the JS arg iterator. + - `c_arg_p` - the native arg. + - `func` - the core transform function. + - return value - a `jerry_value_t` representing `undefined` if all validators passed or an `Error` if a validator failed. + +**See also** + +- [jerryx_arg_transform_func_t](#jerryx_arg_transform_func_t) # Helpers for commonly used validations @@ -587,11 +609,11 @@ User should prepare the `jerryx_arg_object_props_t` instance, and pass it to thi ```c static inline jerryx_arg_t -jerryx_arg_object_properties (const jerryx_arg_object_props_t *object_props_p, +jerryx_arg_object_properties (const jerryx_arg_object_props_t *obj_prop_p, jerryx_arg_optional_t opt_flag); ``` - return value - the created `jerryx_arg_t` instance. - - `object_props_p` - provides information for properties transform. + - `obj_prop_p` - provides information for properties transform. - `opt_flag` - whether the argument is optional. **Example** @@ -764,6 +786,23 @@ my_external_handler (const jerry_value_t function_obj, # Functions to create custom validations +## jerryx_arg_ignore + +**Summary** + +Create a jerryx_arg_t instance for ignored argument. + +**Prototype** + +```c +static inline jerryx_arg_t jerryx_arg_ignore (void); +``` + - return value - the created `jerryx_arg_t` instance. + +**See also** + +- [jerryx_arg_t](#jerryx_arg_t) + ## jerryx_arg_custom **Summary** diff --git a/10.EXT-REFERENCE-HANDLER.md b/10.EXT-REFERENCE-HANDLER.md index c5d1019140..e9e770bb51 100644 --- a/10.EXT-REFERENCE-HANDLER.md +++ b/10.EXT-REFERENCE-HANDLER.md @@ -34,7 +34,7 @@ The engine must be initialized before specifying the `jerry_value_t` in the stru typedef struct { const char *name; jerry_value_t value; -} jerryx_function_list_entry; +} jerryx_property_entry; ``` **See also** @@ -262,7 +262,7 @@ For example usage see [jerryx_set_properties](#jerryx_set_properties). # Common external function handlers -## jerryx_handler_assert_fatal +## jerryx_handler_assert **Summary** @@ -275,12 +275,13 @@ a backtrace is also printed out. ```c jerry_value_t -jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, const jerry_value_t this_p, - const jerry_value_t args_p[], const jerry_length_t args_cnt); +jerryx_handler_assert (const jerry_call_info_t *call_info_p, + const jerry_value_t args_p[], + const jerry_length_t args_cnt); ``` -- `func_obj_val` - the function object that was called (unused). -- `this_p` - the `this` value of the call (unused). +- `call_info_p` - pointer to a [jerry_call_info_t](#jerry_call_info_t) + structure which holds call related information (unused). - `args_p` - the array of function arguments. - `args_cnt` - the number of function arguments. - return value - `jerry_value_t` representing boolean true, if only one argument @@ -292,43 +293,6 @@ jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, const jerry_value - [jerryx_register_global](#jerryx_register_global) -## jerryx_handler_assert_throw - -**Summary** - -Soft assert for scripts. The routine throws an error on assertion failure. - -**Prototype** - -```c -jerry_value_t -jerryx_handler_assert_throw (const jerry_value_t func_obj_val, const jerry_value_t this_p, - const jerry_value_t args_p[], const jerry_length_t args_cnt); -``` - -- `func_obj_val` - the function object that was called (unused). -- `this_p` - the `this` value of the call (unused). -- `args_p` - the array of function arguments. -- `args_cnt` - the number of function arguments. -- return value - `jerry_value_t` representing boolean true, if only one argument - was passed and that argument was a boolean true, an error otherwise. - -**See also** - -- [jerryx_register_global](#jerryx_register_global) - - -## jerryx_handler_assert - -**Summary** - -An alias to `jerryx_handler_assert_fatal`. - -**See also** - -- [jerryx_handler_assert_fatal](#jerryx_handler_assert_fatal) - - ## jerryx_handler_gc **Summary** @@ -341,12 +305,13 @@ gc is performed, which is also the default if no parameters passed. ```c jerry_value_t -jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p, - const jerry_value_t args_p[], const jerry_length_t args_cnt); +jerryx_handler_gc (const jerry_call_info_t *call_info_p, + const jerry_value_t args_p[], + const jerry_length_t args_cnt); ``` -- `func_obj_val` - the function object that was called (unused). -- `this_p` - the `this` value of the call (unused). +- `call_info_p` - pointer to a [jerry_call_info_t](#jerry_call_info_t) + structure which holds call related information (unused). - `args_p` - the array of function arguments (unused). - `args_cnt` - the number of function arguments (unused). - return value - `jerry_value_t` representing `undefined`. @@ -361,26 +326,26 @@ jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p, **Summary** Provide a `print` implementation for scripts. The routine converts all of its -arguments to strings and outputs them char-by-char using -`jerry_port_print_byte`. The NULL character is output as "\u0000", -other characters are output bytewise. +arguments to strings and outputs them by using `jerry_port_print_buffer`. +The NULL character is output as "\u0000", other characters are output bytewise. *Note*: This implementation does not use standard C `printf` to print its output. This allows more flexibility but also extends the core JerryScript engine port API. Applications that want to use `jerryx_handler_print` must ensure that their port implementation also provides -`jerry_port_print_byte`. +`jerry_port_print_buffer`. **Prototype** ```c jerry_value_t -jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this_p, - const jerry_value_t args_p[], const jerry_length_t args_cnt); +jerryx_handler_print (const jerry_call_info_t *call_info_p, + const jerry_value_t args_p[], + const jerry_length_t args_cnt); ``` -- `func_obj_val` - the function object that was called (unused). -- `this_p` - the `this` value of the call (unused). +- `call_info_p` - pointer to a [jerry_call_info_t](#jerry_call_info_t) + structure which holds call related information (unused). - `args_p` - the array of function arguments. - `args_cnt` - the number of function arguments. - return value - `jerry_value_t` representing `undefined` if all arguments could @@ -389,7 +354,7 @@ jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this **See also** - [jerryx_register_global](#jerryx_register_global) -- [jerry_port_print_byte](05.PORT-API.md#jerry_port_print_char) +- [jerry_port_print_buffer](05.PORT-API.md#jerry_port_print_buffer) # Handler registration helper @@ -408,7 +373,7 @@ longer needed. ```c jerry_value_t jerryx_register_global (const char *name_p, - jerry_external_handler_t handler_p); + jerry_external_handler_t handler_p); ``` - `name_p` - the name of the function to be registered. diff --git a/12.EXT-REFERENCE-MODULE.md b/12.EXT-REFERENCE-MODULE.md index 6d54c59dcc..fa5dc57f9a 100644 --- a/12.EXT-REFERENCE-MODULE.md +++ b/12.EXT-REFERENCE-MODULE.md @@ -73,7 +73,7 @@ to `jerryx_module_resolve` with a module name whose canonical name matches an al ```c jerry_value_t jerryx_module_resolve (const jerry_value_t name, - const jerryx_module_resolver_t *resolvers_p, + const jerryx_module_resolver_t **resolvers_p, size_t resolver_count); ``` @@ -94,7 +94,7 @@ Remove a module from the current context's cache, or clear the cache entirely. ```c void jerryx_module_clear_cache (const jerry_value_t name, - const jerryx_module_resolver_t *resolvers_p, + const jerryx_module_resolver_t **resolvers_p, size_t resolver_count); ``` diff --git a/13.DEBUGGER-TRANSPORT.md b/13.DEBUGGER-TRANSPORT.md index d1b7749779..5523d14b76 100644 --- a/13.DEBUGGER-TRANSPORT.md +++ b/13.DEBUGGER-TRANSPORT.md @@ -87,7 +87,8 @@ the `header_p->next_p->send()` method. ```c typedef bool (*jerry_debugger_transport_send_t) (struct jerry_debugger_transport_interface_t *header_p, - uint8_t *message_p, size_t message_length); + uint8_t *message_p, + size_t message_length); ``` ## jerry_debugger_transport_receive_t @@ -117,8 +118,10 @@ will be the first item of the interface chain. ```c void jerry_debugger_transport_add (jerry_debugger_transport_header_t *header_p, - size_t send_message_header_size, size_t max_send_message_size, - size_t receive_message_header_size, size_t max_receive_message_size); + size_t send_message_header_size, + size_t max_send_message_size, + size_t receive_message_header_size, + size_t max_receive_message_size); ``` - `header_p`: header of a transportation interface. diff --git a/14.EXT-REFERENCE-HANDLE-SCOPE.md b/14.EXT-REFERENCE-HANDLE-SCOPE.md index 6ffb6002ad..0877e05017 100644 --- a/14.EXT-REFERENCE-HANDLE-SCOPE.md +++ b/14.EXT-REFERENCE-HANDLE-SCOPE.md @@ -21,7 +21,7 @@ JerryScript only supports a single nested hierarchy of scopes. There is only one **Example** -[doctest]: # (test="compile") +[doctest]: # () ```c #include "jerryscript.h" @@ -65,7 +65,7 @@ It is necessary in common cases that a handle has to be promote to outer scope a **Example** -[doctest]: # (test="compile") +[doctest]: # () ```c #include "jerryscript.h" diff --git a/16.MIGRATION-GUIDE.md b/16.MIGRATION-GUIDE.md index dffd665bb5..b2790bf8a5 100644 --- a/16.MIGRATION-GUIDE.md +++ b/16.MIGRATION-GUIDE.md @@ -780,3 +780,4 @@ In this section the new API functions are listed. - [`jerry_port_get_current_context`](05.PORT-API.md#jerry_port_get_current_context) - [`jerry_port_fatal`](05.PORT-API.md#jerry_port_fatal) - [`jerry_port_sleep`](05.PORT-API.md#jerry_port_sleep) +- [`jerry_port_print_byte`](05.PORT-API.md#jerry_port_print_byte)