diff options
| -rw-r--r-- | 00.GETTING-STARTED.md | 12 | ||||
| -rw-r--r-- | 01.CONFIGURATION.md | 11 | ||||
| -rw-r--r-- | 02.API-REFERENCE.md | 5039 | ||||
| -rw-r--r-- | 03.API-EXAMPLE.md | 317 | ||||
| -rw-r--r-- | 05.PORT-API.md | 441 | ||||
| -rw-r--r-- | 06.REFERENCE-COUNTING.md | 62 | ||||
| -rw-r--r-- | 07.DEBUGGER.md | 69 | ||||
| -rw-r--r-- | 08.CODING-STANDARDS.md | 2 | ||||
| -rw-r--r-- | 09.EXT-REFERENCE-ARG.md | 12 | ||||
| -rw-r--r-- | 10.EXT-REFERENCE-HANDLER.md | 234 | ||||
| -rw-r--r-- | 11.EXT-REFERENCE-AUTORELEASE.md | 14 | ||||
| -rw-r--r-- | 12.EXT-REFERENCE-MODULE.md | 12 | ||||
| -rw-r--r-- | 14.EXT-REFERENCE-HANDLE-SCOPE.md | 12 | ||||
| -rw-r--r-- | _includes/header.html | 2 |
14 files changed, 2662 insertions, 3577 deletions
diff --git a/00.GETTING-STARTED.md b/00.GETTING-STARTED.md index 57bf5e63..a136573b 100644 --- a/00.GETTING-STARTED.md +++ b/00.GETTING-STARTED.md @@ -21,11 +21,11 @@ Several scripts and tools help the building and development process, thus it is - `bash` >= `4.3.11` - `cppcheck` >= `1.61` -- `vera++` >= `1.2.1` +- `clang-format-10` >= `10.0.0` - `python` >= `2.7.6` ```bash -sudo apt-get install gcc gcc-arm-none-eabi cmake cppcheck vera++ python +sudo apt-get install gcc gcc-arm-none-eabi cmake cppcheck clang-format-10 python ``` To make our scripts run correctly, several shell utilities should be available on the system: @@ -61,10 +61,10 @@ tools/build.py --debug --logging=on --error-messages=on --line-info=on python tools/build.py --cmake-param=CMAKE_PARAM ``` -**Set a profile mode (ES.next, ES5.1, minimal)** +**Set a profile mode (es.next, minimal)** ```bash -python tools/build.py --profile=es.next|es5.1|minimal +python tools/build.py --profile=es.next|minimal ``` See also the related [README.md](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md). @@ -183,10 +183,10 @@ python tools/run-tests.py --check-signed-off python tools/run-tests.py --check-cppcheck ``` -**To run vera check** +**To run format check** ```bash -python tools/run-tests.py --check-vera +python tools/run-tests.py --check-format ``` **To get a list of all the available test options** diff --git a/01.CONFIGURATION.md b/01.CONFIGURATION.md index ea0c67ca..227b5192 100644 --- a/01.CONFIGURATION.md +++ b/01.CONFIGURATION.md @@ -54,7 +54,7 @@ that can be used by the debugger to identify the currently executed source conte ### Profiles This option can be used to enable/disable available JavaScript language features by providing profile files. Profile files contain a list of C definitions that configure each individual feature. -The `path` value for CMake and Python arguments should be a file path to the profile file, or one of `es.next`, `es5.1`, or `minimal`, which are the pre-defined profiles. +The `path` value for CMake and Python arguments should be a file path to the profile file, or one of `es.next` or `minimal`, which are the pre-defined profiles. To see how a profile file should be created, or what configuration options are available in C, see the profile [README](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md). | Options | | @@ -200,7 +200,7 @@ This option is enabled by default. ### Memory statistics -This option can be used to provide memory usage statistics either upon engine termination, or during runtime using the `jerry_get_memory_stats` jerry API function. +This option can be used to provide memory usage statistics either upon engine termination, or during runtime using the `jerry_heap_stats` jerry API function. The feature can create a significant performance overhead, and should only be used for measurement purposes. This option is disabled by default. | Options | | @@ -309,7 +309,7 @@ in other projects. To achieve this, the following command can be executed to cre into the `amalgam` directory: ```sh -$ python tools/amalgam.py --output-dir amalgam --jerry-core --jerry-port-default --jerry-math +$ python tools/amalgam.py --output-dir amalgam --jerry-core --jerry-port --jerry-math ``` (Note: In the example above, the command is executed from the project's root directory, but that is @@ -320,8 +320,7 @@ The command creates the following files in the `amalgam` dir: * `jerryscript.c` * `jerryscript.h` * `jerryscript-config.h` -* `jerryscript-port-default.c` -* `jerryscript-port-default.h` +* `jerryscript-port.c` * `jerryscript-math.c` * `math.h` @@ -333,7 +332,7 @@ These files can be directly compiled with an application using the JerryScript A E.g., using a command similar to the one below: ```sh -$ gcc -Wall -o demo_app demo_app.c amalgam/jerryscript.c amalgam/jerryscript-port-default.c amalgam/jerryscript-math.c -Iamalgam/ +$ gcc -Wall -o demo_app demo_app.c amalgam/jerryscript.c amalgam/jerryscript-port.c amalgam/jerryscript-math.c -Iamalgam/ ``` (Note: The headers must be available on the include path.) diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 1b403c83..6bbf3202 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -18,10 +18,6 @@ Enum that contains the following elements: - JERRY_INIT_SHOW_OPCODES - dump byte-code to log after parse - 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 - **deprecated**, dump memory statistics and reset peak values after parse - - JERRY_INIT_DEBUGGER - **deprecated**, an unused placeholder now - -*Changed in version 2.0*: `JERRY_INIT_MEM_STATS_SEPARATE` and `JERRY_INIT_DEBUGGER` are now deprecated and not used internally. ## jerry_type_t @@ -35,7 +31,7 @@ Enum that contains JerryScript API value types: - JERRY_TYPE_STRING - string type - JERRY_TYPE_OBJECT - object type - JERRY_TYPE_FUNCTION - function type - - JERRY_TYPE_ERROR - error/abort type + - JERRY_TYPE_EXCEPTION - exception/abort type - JERRY_TYPE_SYMBOL - symbol type - JERRY_TYPE_BIGINT - bigint type @@ -56,13 +52,13 @@ Enum that contains JerryScript **object** value types: - JERRY_OBJECT_TYPE_MODULE - Module object (see [jerry_parse](#jerry_parse)) - JERRY_OBJECT_TYPE_PROMISE - Promise object - JERRY_OBJECT_TYPE_DATAVIEW - Dataview object - - JERRY_OBJECT_TYPE_FUNCTION - Function object (see [jerry_function_get_type](#jerry_function_get_type)) - - JERRY_OBJECT_TYPE_TYPEDARRAY - %TypedArray% object (see [jerry_get_typedarray_type](#jerry_get_typedarray_type)) - - JERRY_OBJECT_TYPE_ITERATOR - Iterator object (see [jerry_iterator_get_type](#jerry_get_typedarray_type)) - - JERRY_OBJECT_TYPE_CONTAINER - Container object (see [jerry_get_container_type](#jerry_get_container_type)) - - JERRY_OBJECT_TYPE_ERROR - Error object - - JERRY_OBJECT_TYPE_ARRAYBUFFER - Array buffer object - - JERRY_OBJECT_TYPE_SHARED_ARRAYBUFFER - Shared Array buffer object + - JERRY_OBJECT_TYPE_FUNCTION - Function object (see [jerry_function_type](#jerry_function_type)) + - JERRY_OBJECT_TYPE_TYPEDARRAY - %TypedArray% object (see [jerry_typedarray_type](#jerry_typedarray_type)) + - JERRY_OBJECT_TYPE_ITERATOR - Iterator object (see [jerry_iterator_type](#jerry_typedarray_type)) + - JERRY_OBJECT_TYPE_CONTAINER - Container object (see [jerry_container_type](#jerry_container_type)) + - 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 @@ -106,7 +102,7 @@ Enum that contains JerryScript **iterator** value types: *New in version 2.4*. -## jerry_proxy_object_options_t +## jerry_proxy_custom_behavior_t These option bits allow specializing Proxies with non-standard behaviour. These flags are recommended only for those trusted Proxies, whose handlers @@ -141,7 +137,7 @@ Enum that contains JerryScript **property filter** options bits: ## jerry_error_t -Possible types of an error: +Possible types of an Error object: - JERRY_ERROR_COMMON - common error - JERRY_ERROR_EVAL - eval error @@ -152,9 +148,9 @@ Possible types of an error: - JERRY_ERROR_URI - URI error There is also a special value `JERRY_ERROR_NONE` which is not an error type -this value can only be returned by the [jerry_get_error_type](#jerry_get_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_get_error_type](#jerry_get_error_type) method. +*Changed 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 @@ -163,7 +159,7 @@ Possible compile time enabled feature types: - JERRY_FEATURE_CPOINTER_32_BIT - 32 bit compressed pointers - JERRY_FEATURE_ERROR_MESSAGES - error messages - JERRY_FEATURE_JS_PARSER - js-parser - - JERRY_FEATURE_MEM_STATS - memory statistics + - JERRY_FEATURE_HEAP_STATS - memory statistics - JERRY_FEATURE_PARSER_DUMP - parser byte-code dumps - JERRY_FEATURE_REGEXP_DUMP - regexp byte-code dumps - JERRY_FEATURE_SNAPSHOT_SAVE - saving snapshot files @@ -265,14 +261,14 @@ Option bits for [jerry_parse_options_t](#jerry_parse_options_t). - JERRY_PARSE_STRICT_MODE - Enable strict mode - JERRY_PARSE_MODULE - Parse source as an ECMAScript module - JERRY_PARSE_HAS_ARGUMENT_LIST - `argument_list` field is valid, this also means that function parsing will be done - - JERRY_PARSE_HAS_RESOURCE - `resource_name` field is valid + - JERRY_PARSE_HAS_SOURCE_NAME - `source_name` field is valid - 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]]*. Using both `JERRY_PARSE_MODULE` and `JERRY_PARSE_HAS_ARGUMENT_LIST` is an invalid combination and will result in -an error during parsing. +an exception during parsing. **See also** @@ -292,10 +288,10 @@ memory blocks but the performance may drop after the garbage collection. *New in version 2.0*. -## jerry_backtrace_frame_types_t +## jerry_frame_type_t List of backtrace frame types returned by -[jerry_backtrace_get_frame_type](#jerry_backtrace_get_frame_type). +[jerry_frame_type](#jerry_frame_type). - JERRY_BACKTRACE_FRAME_JS - indicates that the frame is created for a JavaScript function/method @@ -338,7 +334,7 @@ Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) functions: - JERRY_SNAPSHOT_EXEC_COPY_DATA - copy snapshot data into memory (see below) - JERRY_SNAPSHOT_EXEC_ALLOW_STATIC - allow executing static snapshots - JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION - load snapshot as function instead of executing it - - JERRY_SNAPSHOT_EXEC_HAS_RESOURCE - `resource_name` field is valid + - JERRY_SNAPSHOT_EXEC_HAS_SOURCE_NAME - `source_name` field is valid in [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t) - JERRY_SNAPSHOT_EXEC_HAS_USER_VALUE - `user_value` field is valid in [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t) @@ -400,13 +396,12 @@ typedef uint32_t jerry_length_t; **Summary** -JerryScript value can be a boolean, number, null, object, string or undefined. The value has an error flag, -that indicates whether is an error or not. Every type has an error flag not only objects. The error flag should -be cleared before the value is passed as an argument, otherwise it can lead to a type error. The error objects -created by API functions has the error flag set. +A JerryScript value can be undefined, null, boolean, number, string, object, or an exception value. Exception values +represent thrown exceptions during execution. Exception values cannot be passed as an argument to regular API function, +only to those that work with exception values specifically. Returned and created values by the API functions must be freed with -[jerry_release_value](#jerry_release_value) when they are no longer needed. +[jerry_value_free](#jerry_value_free) when they are no longer needed. **Prototype** @@ -432,7 +427,7 @@ typedef struct { /** * Callback responsible for initializing a context item, or NULL to zero out the memory. This is called lazily, the - * first time jerry_get_context_data () is called with this manager. + * first time jerry_context_data () is called with this manager. * * @param [in] data The buffer that JerryScript allocated for the manager. The buffer is zeroed out. The size is * determined by the bytes_needed field. The buffer is kept alive until jerry_cleanup () is called. @@ -465,7 +460,7 @@ typedef struct /** * Number of bytes to allocate for this manager. This is the size of the buffer that JerryScript will allocate on * behalf of the manager. The pointer to this buffer is passed into init_cb, deinit_cb and finalize_cb. It is also - * returned from the jerry_get_context_data () API. + * returned from the jerry_context_data () API. */ size_t bytes_needed; } jerry_context_data_manager_t; @@ -504,7 +499,7 @@ typedef struct jerry_context_t jerry_context_t; *New in version 2.0*. -## jerry_container_operation_t +## jerry_container_op_t Enum that contains the supported container operation types - JERRY_CONTAINER_OP_ADD - Set/WeakSet add operation @@ -517,7 +512,7 @@ Enum that contains the supported container operation types *New in version [[NEXT_RELEASE]]*. -## jerry_binary_operation_t +## jerry_binary_op_t Enum that contains the supported binary operation types - JERRY_BIN_OP_EQUAL - equal comparison (==) @@ -537,7 +532,7 @@ Enum that contains the supported binary operation types **See also** -- [jerry_binary_operation](#jerry_binary_operation) +- [jerry_binary_op](#jerry_binary_op) ## jerry_property_descriptor_flags_t @@ -553,7 +548,7 @@ Enum that contains the flags of property descriptors. - JERRY_PROP_IS_VALUE_DEFINED - Is [[Value]] defined? - JERRY_PROP_IS_GET_DEFINED - Is [[Get]] defined? - JERRY_PROP_IS_SET_DEFINED - Is [[Set]] defined? - - JERRY_PROP_SHOULD_THROW - Should throw on error, instead of returning with false + - JERRY_PROP_SHOULD_THROW - Should throw in case of an exception, instead of returning with false *New in version [[NEXT_RELEASE]]*. @@ -575,9 +570,9 @@ typedef struct uint32_t options; /**< combination of jerry_parse_option_enable_feature_t values */ jerry_value_t argument_list; /**< function argument list if JERRY_PARSE_HAS_ARGUMENT_LIST is set in options * Note: must be string value */ - jerry_value_t resource_name; /**< resource name string (usually a file name) - * if JERRY_PARSE_HAS_RESOURCE is set in options - * Note: must be string value */ + jerry_value_t source_name; /**< source name string (usually a file name) + * if JERRY_PARSE_HAS_SOURCE_NAME is set in options + * Note: must be string value */ uint32_t start_line; /**< start line of the source code if JERRY_PARSE_HAS_START is set in options */ uint32_t start_column; /**< start column of the source code if JERRY_PARSE_HAS_START is set in options */ jerry_value_t user_value; /**< user value assigned to all functions created by this script including eval @@ -599,7 +594,7 @@ typedef struct **Summary** Description of ECMA property descriptor. This struct can be used -for the [jerry_define_own_property](#jerry_define_own_property) method to +for the [jerry_object_define_own_prop](#jerry_object_define_own_prop) method to configure how the property should be registered. The naming scheme is similar to the JavaScript `Object.defineProperty` method. @@ -627,48 +622,48 @@ typedef struct **See also** - [jerry_property_descriptor_flags_t](#jerry_property_descriptor_flags_t) -- [jerry_define_own_property](#jerry_define_own_property) +- [jerry_object_define_own_prop](#jerry_object_define_own_prop) -## jerry_backtrace_location_t +## jerry_frame_location_t **Summary** Source code location data retrieved by -[jerry_backtrace_get_location](#jerry_backtrace_get_location). +[jerry_frame_location](#jerry_frame_location). **Prototype** ```c typedef struct { - jerry_value_t resource_name; /**< resource name */ + jerry_value_t source_name; /**< source name */ jerry_size_t line; /**< line index */ jerry_size_t column; /**< column index */ -} jerry_backtrace_location_t; +} jerry_frame_location_t; ``` *New in version [[NEXT_RELEASE]]*. -## jerry_backtrace_frame_t +## jerry_frame_t **Summary** -Backtrace frame data passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) +Backtrace frame data passed to the [jerry_backtrace_cb_t](#jerry_backtrace_cb_t) handler. This is an internal data structure which fields can be accessed by helper functions -such as [jerry_backtrace_get_location](#jerry_backtrace_get_location). +such as [jerry_frame_location](#jerry_frame_location). **Prototype** ```c /** - * Internal data structure for jerry_backtrace_frame_t definition. + * Internal data structure for jerry_frame_t definition. */ -struct jerry_backtrace_frame_internal_t; +struct jerry_frame_internal_t; /** - * Backtrace frame data passed to the jerry_backtrace_callback_t handler. + * Backtrace frame data passed to the jerry_backtrace_cb_t handler. */ -typedef struct jerry_backtrace_frame_internal_t jerry_backtrace_frame_t; +typedef struct jerry_frame_internal_t jerry_frame_t; ``` *New in version [[NEXT_RELEASE]]*. @@ -697,7 +692,7 @@ typedef struct **See also** -- [jerry_get_memory_stats](#jerry_get_memory_stats) +- [jerry_heap_stats](#jerry_heap_stats) ## jerry_call_info_t @@ -711,7 +706,7 @@ Call related information passed to [jerry_external_handler_t](#jerry_external_ha typedef struct jerry_call_info_t { jerry_value_t function; /**< invoked function object */ - jerry_value_t this_value; /**< this value passed to the function */ + jerry_value_t this_value; /**< this value passed to the function */ jerry_value_t new_target; /**< current new target value, undefined for non-constructor calls */ } jerry_call_info_t; ``` @@ -741,11 +736,11 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_call_info_t *call - `args_p` - the function arguments, array of JavaScript values. - `args_count` - the number of arguments. - return value - - The function's return value. If there is no return value, use [jerry_create_undefined()](#jerry_create_undefined). + - The function's return value. If there is no return value, use [jerry_undefined()](#jerry_undefined). **See also** -- [jerry_create_external_function](#jerry_create_external_function) +- [jerry_function_external](#jerry_function_external) ## jerry_value_free_callback_t @@ -766,16 +761,16 @@ typedef void (*jerry_value_free_callback_t) (void *native_p); **See also** -- [jerry_create_external_string](#jerry_create_external_string) -- [jerry_create_external_string_sz](#jerry_create_external_string_sz) -- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) +- [jerry_string_external_sz](#jerry_string_external_sz) +- [jerry_string_external](#jerry_string_external) +- [jerry_arraybuffer_external](#jerry_arraybuffer_external) -## jerry_object_native_free_callback_t +## jerry_object_native_free_cb_t **Summary** Native free callback of an object. The callback receives both the memory pointer and the type -information passed to [jerry_set_object_native_pointer](#jerry_set_object_native_pointer). +information passed to [jerry_object_set_native_ptr](#jerry_object_set_native_ptr). *Note*: - Referred values by this method must have at least 1 reference. (Correct API usage satisfies this condition) @@ -783,11 +778,11 @@ information passed to [jerry_set_object_native_pointer](#jerry_set_object_native **Prototype** ```c -typedef void (*jerry_object_native_free_callback_t) (void *native_p, struct jerry_object_native_info_t *info_p); +typedef void (*jerry_object_native_free_cb_t) (void *native_p, struct jerry_object_native_info_t *info_p); ``` -- `native_p` - native pointer passed to [jerry_set_object_native_pointer](#jerry_set_object_native_pointer). -- `info_p` - native type info passed to [jerry_set_object_native_pointer](#jerry_set_object_native_pointer). +- `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`. @@ -799,20 +794,20 @@ typedef void (*jerry_object_native_free_callback_t) (void *native_p, struct jerr - [jerry_object_native_info_t](#jerry_object_native_info_t) -## jerry_external_string_free_callback_t +## jerry_external_string_free_cb_t **Summary** Free callback for external strings. See -[jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback) +[jerry_string_external_on_free](#jerry_string_external_on_free) for more information. **Prototype** ```c -typedef void (*jerry_external_string_free_callback_t) (jerry_char_t *string_p, - jerry_size_t string_size, - void *user_p); +typedef void (*jerry_external_string_free_cb_t) (jerry_char_t *string_p, + jerry_size_t string_size, + void *user_p); ``` - `string_p` - external string pointer @@ -823,11 +818,11 @@ typedef void (*jerry_external_string_free_callback_t) (jerry_char_t *string_p, **See also** -- [jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback) -- [jerry_create_external_string](#jerry_create_external_string) -- [jerry_create_external_string_sz](#jerry_create_external_string_sz) +- [jerry_string_external_on_free](#jerry_string_external_on_free) +- [jerry_string_external_sz](#jerry_string_external_sz) +- [jerry_string_external](#jerry_string_external) -## jerry_error_object_created_callback_t +## jerry_error_object_created_cb_t **Summary** @@ -842,33 +837,33 @@ Error object. **Prototype** ```c -typedef void (*jerry_error_object_created_callback_t) (const jerry_value_t error_object, void *user_p); +typedef void (*jerry_error_object_created_cb_t) (const jerry_value_t error_object, void *user_p); ``` - `error_object` - the newly created Error object. -- `user_p` - pointer passed to [jerry_set_error_object_created_callback](#jerry_set_error_object_created_callback). +- `user_p` - pointer passed to [jerry_error_on_created](#jerry_error_on_created). *New in version 2.4*. **See also** -- [jerry_set_error_object_created_callback](#jerry_set_error_object_created_callback) +- [jerry_error_on_created](#jerry_error_on_created) ## jerry_module_state_t An enum representing the current status of a module - - JERRY_MODULE_STATE_INVALID - Return value for jerry_module_get_state when its argument is not a module + - JERRY_MODULE_STATE_INVALID - Return value for jerry_module_state when its argument is not a module - JERRY_MODULE_STATE_UNLINKED - Module is currently unlinked - JERRY_MODULE_STATE_LINKING - Module is currently being linked - JERRY_MODULE_STATE_LINKED - Module has been linked (its dependencies has been resolved) - JERRY_MODULE_STATE_EVALUATING - Module is currently being evaluated - JERRY_MODULE_STATE_EVALUATED - Module has been evaluated (its source code has been executed) - - JERRY_MODULE_STATE_ERROR - An error has been encountered before the evaluated state is reached + - JERRY_MODULE_STATE_ERROR - An exception has been encountered before the evaluated state is reached *New in version [[NEXT_RELEASE]]*. -## jerry_module_resolve_callback_t +## jerry_module_resolve_cb_t **Summary** @@ -876,14 +871,14 @@ Callback which is called by [jerry_module_link](#jerry_module_link) to get the r *Note*: - If realms are enabled, the returned module should be created in the current realm - (see: [jerry_get_global_object](#jerry_get_global_object)) + (see: [jerry_current_realm](#jerry_current_realm)) **Prototype** ```c -typedef jerry_value_t (*jerry_module_resolve_callback_t) (const jerry_value_t specifier, - const jerry_value_t referrer, - void *user_p); +typedef jerry_value_t (*jerry_module_resolve_cb_t) (const jerry_value_t specifier, + const jerry_value_t referrer, + void *user_p); ``` - `specifier` - a module specifier string (usually used as a path to the module) @@ -891,15 +886,15 @@ typedef jerry_value_t (*jerry_module_resolve_callback_t) (const jerry_value_t sp - `user_p` - pointer passed to [jerry_module_link](#jerry_module_link). - return value - a module object - if it can be resolved successfully - - an error - otherwise + - an exception - otherwise *New in version [[NEXT_RELEASE]]*. **See also** - [jerry_module_link](#jerry_module_link) -- [jerry_get_global_object](#jerry_get_global_object) +- [jerry_current_realm](#jerry_current_realm) -## jerry_module_import_callback_t +## jerry_module_import_cb_t **Summary** @@ -909,39 +904,39 @@ Callback which is called when an import is resolved dynamically to get the refer - If the function returns with a promise, the import call returns with this promise. The application should try to resolve the requested module later. If the module is evaluated successfully, the returned promise should be resolved with the namespace object of the - module. Otherwise, the returned promise should be rejected with an error. + module. Otherwise, the returned promise should be rejected with an exception. - If the function returns with a resolved module, a promise is created and resolved with the namespace object of the module. The import call returns with the resolved promise. - - If the function returns with an error, a promise is created and rejected with the - return error. The import call returns with the rejected promise. + - If the function returns with an exception, a promise is created and rejected with the + returned exception. The import call returns with the rejected promise. - All other return values are considered invalid. In this case the import call returns with a rejected promise. The rejected promise has a fixed error message, it does not specify the reason of the fail. - If realms are enabled, the returned module should be created in the current realm - (see: [jerry_get_global_object](#jerry_get_global_object)) + (see: [jerry_current_realm](#jerry_current_realm)) **Prototype** ```c -typedef jerry_value_t (*jerry_module_import_callback_t) (const jerry_value_t specifier, - const jerry_value_t user_value, - void *user_p); +typedef jerry_value_t (*jerry_module_import_cb_t) (const jerry_value_t specifier, + const jerry_value_t user_value, + void *user_p); ``` - `specifier` - a module specifier string (usually used as a path to the module) - `user_value` - the user value assigned to the script (see [jerry_parse_options_t](#jerry_parse_options_t)) -- `user_p` - pointer passed to [jerry_module_set_import_callback](#jerry_module_set_import_callback). +- `user_p` - pointer passed to [jerry_module_on_import](#jerry_module_on_import). - return value - promise or resolved module - if the operation is successful - - an error - otherwise + - an exception - otherwise *New in version [[NEXT_RELEASE]]*. **See also** -- [jerry_module_set_import_callback](#jerry_module_set_import_callback) -- [jerry_get_global_object](#jerry_get_global_object) +- [jerry_module_on_import](#jerry_module_on_import) +- [jerry_current_realm](#jerry_current_realm) -## jerry_module_state_changed_callback_t +## jerry_module_state_changed_cb_t **Summary** @@ -950,24 +945,24 @@ Callback which is called after the module enters into linked, evaluated or error **Prototype** ```c -typedef void (*jerry_module_state_changed_callback_t) (jerry_module_state_t new_state, - const jerry_value_t module, - const jerry_value_t value, - void *user_p); +typedef void (*jerry_module_state_changed_cb_t) (jerry_module_state_t new_state, + const jerry_value_t module, + const jerry_value_t value, + void *user_p); ``` - `new_state` - new state of the module. - `module` - a module whose state is changed - `value` - depends on the state: undefined for linked, module script result for evaluated, - and error value for error state. -- `user_p` - pointer passed to [jerry_module_set_state_changed_callback](#jerry_module_set_state_changed_callback). + 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]]*. **See also** -- [jerry_module_set_state_changed_callback](#jerry_module_set_state_changed_callback) +- [jerry_module_on_state_changed](#jerry_module_on_state_changed) -## jerry_module_import_meta_callback_t +## jerry_module_import_meta_cb_t **Summary** @@ -978,21 +973,21 @@ the callback can set the initial status of the object (e.g. add properties or se **Prototype** ```c -typedef void (*jerry_module_import_meta_callback_t) (const jerry_value_t module, - const jerry_value_t meta_object, - void *user_p); +typedef void (*jerry_module_import_meta_cb_t) (const jerry_value_t module, + const jerry_value_t meta_object, + void *user_p); ``` - `module` - module whose import.meta object is requested. - `meta_object` - import.meta object created for the module. -- `user_p` - pointer passed to [jerry_module_set_import_meta_callback](#jerry_module_set_import_meta_callback). +- `user_p` - pointer passed to [jerry_module_on_import_meta](#jerry_module_on_import_meta). *New in version [[NEXT_RELEASE]]*. **See also** -- [jerry_module_set_import_meta_callback](#jerry_module_set_import_meta_callback) +- [jerry_module_on_import_meta](#jerry_module_on_import_meta) -## jerry_native_module_evaluate_callback_t +## jerry_native_module_evaluate_cb_t **Summary** @@ -1000,25 +995,25 @@ Callback which is called by [jerry_module_evaluate](#jerry_module_evaluate) to e Note: - Native pointers can be used to assign private data to a native module, - see [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) + see [jerry_object_set_native_ptr](#jerry_object_set_native_ptr) **Prototype** ```c -typedef jerry_value_t (*jerry_native_module_evaluate_callback_t) (const jerry_value_t native_module); +typedef jerry_value_t (*jerry_native_module_evaluate_cb_t) (const jerry_value_t native_module); ``` - `native_module` - a native module - return value - - any non-error value - if the module is evaluated successfully - - an error - otherwise + - any non-exception value - if the module is evaluated successfully + - an exception - otherwise *New in version [[NEXT_RELEASE]]*. **See also** - [jerry_module_evaluate](#jerry_module_evaluate) -## jerry_backtrace_callback_t +## jerry_backtrace_cb_t **Summary** @@ -1028,10 +1023,10 @@ for each stack frame. **Prototype** ```c -typedef bool (*jerry_backtrace_callback_t) (jerry_backtrace_frame_t *frame_p, void *user_p); +typedef bool (*jerry_backtrace_cb_t) (jerry_frame_t *frame_p, void *user_p); ``` -- `frame_p` - pointer to [jerry_backtrace_frame_t](#jerry_backtrace_frame_t) data. +- `frame_p` - pointer to [jerry_frame_t](#jerry_frame_t) data. - `user_p` - pointer passed to [jerry_backtrace_capture](#jerry_backtrace_capture). - return value - true, to continue capturing more frames @@ -1042,7 +1037,7 @@ typedef bool (*jerry_backtrace_callback_t) (jerry_backtrace_frame_t *frame_p, vo **See also** - [jerry_backtrace_capture](#jerry_backtrace_capture) -- [jerry_backtrace_frame_t](#jerry_backtrace_frame_t) +- [jerry_frame_t](#jerry_frame_t) ## jerry_object_native_info_t @@ -1060,15 +1055,15 @@ The buffer pointed by the native pointer can have a fixed number of jerry values which refer to other values as long as the object is alive. The starting byte offset and the number of these values are specified by `offset_of_references` and `number_of_references` fields respectively. Before a buffer is attached to an -object by [jerry_set_object_native_pointer](#jerry_set_object_native_pointer), +object by [jerry_object_set_native_ptr](#jerry_object_set_native_ptr), the values must be initialized to undefined by -[jerry_native_pointer_init_references](#jerry_native_pointer_init_references). +[jerry_native_ptr_init](#jerry_native_ptr_init). When a buffer is no longer attached to any object, the -[jerry_native_pointer_release_references](#jerry_native_pointer_release_references) +[jerry_native_ptr_free](#jerry_native_ptr_free) must be called to release the values. A single buffer can be attached to any number of living objects. When a buffer is currently attached to at least one object, the references can be updated by -[jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference). +[jerry_native_ptr_set](#jerry_native_ptr_set). However, if the buffer is no longer attached to an object, the finalize function must be called even if the buffer is reattached to another object later. In this case, calling the init function after the finalization is optional, because the @@ -1079,7 +1074,7 @@ finalize function also initializes all values to undefined. ```c typedef struct { - jerry_object_native_free_callback_t free_cb; /**< the free callback of the native pointer */ + jerry_object_native_free_cb_t free_cb; /**< the free callback of the native pointer */ uint16_t number_of_references; /**< the number of value references which are marked by the garbage collector */ uint16_t offset_of_references; /**< byte offset indicating the start offset of value * references in the user allocated buffer */ @@ -1092,57 +1087,57 @@ typedef struct **See also** -- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) -- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) -- [jerry_delete_object_native_pointer](#jerry_delete_object_native_pointer) -- [jerry_native_pointer_init_references](#jerry_native_pointer_init_references) -- [jerry_native_pointer_release_references](#jerry_native_pointer_release_references) -- [jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference) +- [jerry_object_set_native_ptr](#jerry_object_set_native_ptr) +- [jerry_object_get_native_ptr](#jerry_object_get_native_ptr) +- [jerry_object_delete_native_ptr](#jerry_object_delete_native_ptr) +- [jerry_native_ptr_init](#jerry_native_ptr_init) +- [jerry_native_ptr_free](#jerry_native_ptr_free) +- [jerry_native_ptr_set](#jerry_native_ptr_set) -## jerry_object_property_foreach_t +## jerry_object_property_foreach_cb_t **Summary** -Function type used as a callback for the [jerry_foreach_object_property](#jerry_foreach_object_property) +Function type used as a callback for the [jerry_object_foreach](#jerry_object_foreach) method. A function with this type must return "true" to continue the iteration or "false" to finish the iteration on the object's properties. **Prototype** ```c -typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name, - const jerry_value_t property_value, - void *user_data_p); +typedef bool (*jerry_object_property_foreach_cb_t) (const jerry_value_t property_name, + const jerry_value_t property_value, + void *user_data_p); ``` - `property_name` - a property name, this is not always a string. - `property_value` - the value for the given property. -- `user_data_p` - optional user data pointer supplied via the (jerry_foreach_object_property)[#jerry_foreach_object_property] method. +- `user_data_p` - optional user data pointer supplied via the (jerry_object_foreach)[#jerry_object_foreach] method. - return value - true, to continue the iteration - false, to stop the iteration **See also** -- [jerry_foreach_object_property](#jerry_foreach_object_property) +- [jerry_object_foreach](#jerry_object_foreach) -## jerry_objects_foreach_t +## jerry_foreach_live_object_cb_t **Summary** -Function type used as a callback for the (jerry_objects_foreach)[#jerry_objects_foreach] method. +Function type used as a callback for the (jerry_foreach_live_object)[#jerry_foreach_live_object] method. A function with this type must return "true" to continue the iteration or "false" to finish the iteration on the object's properties. **Prototype** ```c -typedef bool (*jerry_objects_foreach_t) (const jerry_value_t object, - void *user_data_p); +typedef bool (*jerry_foreach_live_object_cb_t) (const jerry_value_t object, + void *user_data_p); ``` - `object` - the current JavaScript object in the for-each iteration. -- `user_data_p` - optional user data pointer supplied via the (jerry_objects_foreach)[#jerry_objects_foreach] method. +- `user_data_p` - optional user data pointer supplied via the (jerry_foreach_live_object)[#jerry_foreach_live_object] method. - return value - true, to continue the iteration - false, to stop the iteration @@ -1151,27 +1146,27 @@ typedef bool (*jerry_objects_foreach_t) (const jerry_value_t object, **See also** -- [jerry_objects_foreach](#jerry_objects_foreach) +- [jerry_foreach_live_object](#jerry_foreach_live_object) -## jerry_objects_foreach_by_native_info_t +## jerry_foreach_live_object_with_info_cb_t **Summary** -Function type used as a callback for the (jerry_objects_foreach_by_native_info)[#jerry_objects_foreach_by_native_info] +Function type used as a callback for the (jerry_foreach_live_object_with_info)[#jerry_foreach_live_object_with_info] method. A function with this type must return "true" to continue the iteration or "false" to finish the iteration on the object's properties. **Prototype** ```c -typedef bool (*jerry_objects_foreach_by_native_info_t) (const jerry_value_t object, - void *object_data_p, - void *user_data_p); +typedef bool (*jerry_foreach_live_object_with_info_cb_t) (const jerry_value_t object, + void *object_data_p, + void *user_data_p); ``` - `object` - the current JavaScript object in the for-each iteration. - `object_data_p` - the current object's native data pointer. -- `user_data_p` - optional user data pointer supplied via the (jerry_objects_foreach_by_native_info)[#jerry_objects_foreach_by_native_info] method. +- `user_data_p` - optional user data pointer supplied via the (jerry_foreach_live_object_with_info)[#jerry_foreach_live_object_with_info] method. - return value - true, to continue the iteration - false, to stop the iteration @@ -1180,56 +1175,54 @@ typedef bool (*jerry_objects_foreach_by_native_info_t) (const jerry_value_t obje **See also** -- [jerry_objects_foreach_by_native_info](#jerry_objects_foreach_by_native_info) +- [jerry_foreach_live_object_with_info](#jerry_foreach_live_object_with_info) -## jerry_vm_exec_stop_callback_t +## jerry_halt_cb_t **Summary** -Callback which tells whether the ECMAScript execution should be stopped. -If it returns with undefined value the ECMAScript execution continues. -Otherwise the result is thrown by the engine (if the error flag is not -set for the returned value the engine automatically sets it). The -callback function might be called again even if it threw an error. -In this case the function must throw the same error again. +Callback which is called periodically by the engine, and polls whether the ECMAScript execution should be stopped. If +the callback returns with an undefined value the ECMAScript execution continues. Otherwise the result is thrown by the +engine as an exception, and execution returns to the caller. The callback function might be called again even if it +threw an exception. In this case the function must throw the same exception again. **Prototype** ```c -typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p); +typedef jerry_value_t (*jerry_halt_cb_t) (void *user_p); ``` *New in version 2.0*. **See also** -- [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback) +- [jerry_halt_handler](#jerry_halt_handler) -## jerry_vm_throw_callback_t +## jerry_throw_cb_t **Summary** Callback which is called when a value is thrown in an ECMAScript code. The callback -should not change the `error_value`. The callback is not called again until the value +should not change the `exception_value`. The callback is not called again until the value is caught. Note: - - The engine considers errors thrown by external functions as never caught. The + - The engine considers exceptions thrown by external functions as never caught. The application can maintain a status flag to ignore the next call of the callback if necessary. - See: [jerry_create_external_function](#jerry_create_external_function) + See: [jerry_function_external](#jerry_function_external) **Prototype** ```c -typedef void (*jerry_vm_throw_callback_t) (const jerry_value_t error_value, void *user_p); +typedef void (*jerry_throw_cb_t) (const jerry_value_t error_value, void *user_p); ``` *New in [[NEXT_RELEASE]]*. **See also** -- [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback) +- [jerry_on_throw](#jerry_on_throw) ## jerry_promise_state_t @@ -1246,11 +1239,11 @@ Possible values: **See also** -- [jerry_get_promise_result](#jerry_get_promise_result) +- [jerry_promise_result](#jerry_promise_result) ## jerry_promise_event_type_t -Event types for [jerry_promise_callback_t](#jerry_promise_callback_t) callback function. +Event types for [jerry_promise_event_cb_t](#jerry_promise_event_cb_t) callback function. The description of the `object` and `value` arguments are provided for each type. Possible values: @@ -1303,13 +1296,13 @@ Possible values: **See also** -- [jerry_promise_callback_t](#jerry_promise_callback_t) -- [jerry_promise_set_callback](#jerry_promise_set_callback) +- [jerry_promise_event_cb_t](#jerry_promise_event_cb_t) +- [jerry_promise_on_event](#jerry_promise_on_event) ## jerry_promise_event_filter_t -Filter types for [jerry_promise_set_callback](#jerry_promise_set_callback) callback function. +Filter types for [jerry_promise_on_event](#jerry_promise_on_event) callback function. The callback is only called for those events which are enabled by the filters. The events are described in [jerry_promise_event_type_t](#jerry_promise_event_type_t). @@ -1343,10 +1336,10 @@ Possible values: **See also** - [jerry_promise_event_type_t](#jerry_promise_event_type_t) -- [jerry_promise_set_callback](#jerry_promise_set_callback) +- [jerry_promise_on_event](#jerry_promise_on_event) -## jerry_promise_callback_t +## jerry_promise_event_cb_t **Summary** @@ -1357,7 +1350,7 @@ description of [jerry_promise_event_type_t](#jerry_promise_event_type_t). **Prototype** ```c -typedef void (*jerry_promise_callback_t) (jerry_promise_event_type_t event_type, +typedef void (*jerry_promise_event_cb_t) (jerry_promise_event_type_t event_type, const jerry_value_t object, const jerry_value_t value, void *user_p); ``` @@ -1365,14 +1358,14 @@ typedef void (*jerry_promise_callback_t) (jerry_promise_event_type_t event_type, - `event_type` - type of the event notification. - `object` - object corresponding to the event. - `value` - optional value argument. -- `user_data_p` - optional user data pointer supplied via the (jerry_promise_set_callback)[#jerry_promise_set_callback] method. +- `user_data_p` - optional user data pointer supplied via the (jerry_promise_on_event)[#jerry_promise_on_event] method. *New in version [[NEXT_RELEASE]]*. **See also** - [jerry_promise_event_type_t](#jerry_promise_event_type_t) -- [jerry_promise_set_callback](#jerry_promise_set_callback) +- [jerry_promise_on_event](#jerry_promise_on_event) ## jerry_typedarray_type_t @@ -1401,7 +1394,7 @@ TypedArray support is not in the engine. **See also** -- [jerry_get_typedarray_type](#jerry_get_typedarray_type) +- [jerry_typedarray_type](#jerry_typedarray_type) ## jerry_exec_snapshot_option_values_t @@ -1415,9 +1408,9 @@ Various configuration options for [jerry_exec_snapshot](#jerry_exec_snapshot) ```c typedef struct { - jerry_value_t resource_name; /**< resource name string (usually a file name) - * if JERRY_SNAPSHOT_EXEC_HAS_RESOURCE is set in exec_snapshot_opts - * Note: non-string values are ignored */ + jerry_value_t source_name; /**< source name string (usually a file name) + * if JERRY_SNAPSHOT_EXEC_HAS_SOURCE_NAME is set in exec_snapshot_opts + * Note: non-string values are ignored */ jerry_value_t user_value; /**< user value assigned to all functions created by this script including * eval calls executed by the script if JERRY_SNAPSHOT_EXEC_HAS_USER_VALUE * is set in exec_snapshot_opts */ @@ -1444,7 +1437,7 @@ Possible values: **See also** - [jerry_source_info_t](#jerry_source_info_t) -- [jerry_get_source_info](#jerry_get_source_info) +- [jerry_source_info](#jerry_source_info) ## jerry_source_info_t @@ -1470,7 +1463,7 @@ typedef struct **See also** - [jerry_source_info_enabled_fields_t](#jerry_source_info_enabled_fields_t) -- [jerry_get_source_info](#jerry_get_source_info) +- [jerry_source_info](#jerry_source_info) ## jerry_arraybuffer_type_t @@ -1485,10 +1478,10 @@ Enum that contains the JerryScript type of an array buffer: **See also** -- [jerry_arraybuffer_allocate_t](#jerry_arraybuffer_allocate_t) -- [jerry_arraybuffer_free_t](#jerry_arraybuffer_free_t) +- [jerry_arraybuffer_allocate_cb_t](#jerry_arraybuffer_allocate_cb_t) +- [jerry_arraybuffer_free_cb_t](#jerry_arraybuffer_free_cb_t) -## jerry_arraybuffer_allocate_t +## jerry_arraybuffer_allocate_cb_t **Summary** @@ -1496,22 +1489,24 @@ Callback for allocating the backing store of array buffer or shared array buffer *Note*: - The value referenced by `arraybuffer_user_p` is always NULL unless the buffer is created by - [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) or - [jerry_create_shared_arraybuffer_external](#jerry_create_shared_arraybuffer_external). + [jerry_arraybuffer_external](#jerry_arraybuffer_external) or + [jerry_shared_arraybuffer_external](#jerry_shared_arraybuffer_external). The value referenced by `arraybuffer_user_p` can be changed, and the new value is passed to - [jerry_arraybuffer_free_t](#jerry_arraybuffer_free_t). + [jerry_arraybuffer_free_cb_t](#jerry_arraybuffer_free_cb_t). **Prototype** ```c -typedef uint8_t *(*jerry_arraybuffer_allocate_t) (jerry_arraybuffer_type_t buffer_type, uint32_t buffer_size, - void **arraybuffer_user_p, void *user_p); +typedef uint8_t *(*jerry_arraybuffer_allocate_cb_t) (jerry_arraybuffer_type_t buffer_type, + uint32_t buffer_size, + void **arraybuffer_user_p, + void *user_p); ``` - `buffer_type` - type of the array buffer object, see: [jerry_arraybuffer_type_t](#jerry_arraybuffer_type_t). - `buffer_size` - size of the requested buffer. - `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_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks) +- `user_p` - user pointer passed to [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) - return value - Pointer to the buffer, if the allocation is successful, NULL otherwise. @@ -1519,9 +1514,9 @@ typedef uint8_t *(*jerry_arraybuffer_allocate_t) (jerry_arraybuffer_type_t buffe **See also** -- [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks) +- [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) -## jerry_arraybuffer_free_t +## jerry_arraybuffer_free_cb_t **Summary** @@ -1529,28 +1524,31 @@ Callback for freeing the backing store of array buffer or shared array buffer ob *Note*: - The value passed to `arraybuffer_user_p` is always NULL unless the buffer is created by - [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) or - [jerry_create_shared_arraybuffer_external](#jerry_create_shared_arraybuffer_external), - or the value is modified by [jerry_arraybuffer_allocate_t](#jerry_arraybuffer_allocate_t). + [jerry_arraybuffer_external](#jerry_arraybuffer_external) or + [jerry_shared_arraybuffer_external](#jerry_shared_arraybuffer_external), + or the value is modified by [jerry_arraybuffer_allocate_cb_t](#jerry_arraybuffer_allocate_cb_t). **Prototype** ```c -typedef void (*jerry_arraybuffer_free_t) (jerry_arraybuffer_type_t buffer_type, uint8_t *buffer_p, - uint32_t buffer_size, void *arraybuffer_user_p, void *user_p); +typedef void (*jerry_arraybuffer_free_cb_t) (jerry_arraybuffer_type_t buffer_type, + uint8_t *buffer_p, + uint32_t buffer_size, + void *arraybuffer_user_p, + void *user_p); ``` - `buffer_type` - type of the array buffer object, see: [jerry_arraybuffer_type_t](#jerry_arraybuffer_type_t). - `buffer_p` - pointer to the allocated buffer. - `buffer_size` - size of the allocated buffer. - `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_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks) +- `user_p` - user pointer passed to [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) *New in version [[NEXT_RELEASE]]*. **See also** -- [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks) +- [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) # General engine functions @@ -1616,7 +1614,7 @@ jerry_cleanup (void); - [jerry_init](#jerry_init) -## jerry_get_context_data +## jerry_context_data **Summary** @@ -1631,12 +1629,12 @@ Retrieve a pointer to the item stored within the current context by the given ma ```c void * -jerry_get_context_data (const jerry_context_data_manager *manager_p); +jerry_context_data (const jerry_context_data_manager *manager_p); ``` - `manager_p`: the manager of this context data item. -- return value: the item created by `manager_p` when `jerry_get_context_data ()` was first called, or a new item created - by `manager_p`, which will be stored for future identical calls to `jerry_get_context_data ()`, and which will be +- return value: the item created by `manager_p` when `jerry_context_data ()` was first called, or a new item created + 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*. @@ -1663,7 +1661,7 @@ my_context_data_new (void *user_data_p) /* * Initialize my_data_p. JerryScript will store it on the current context and return it whenever - * jerry_get_context_data () is called with a pointer to my_manager as defined below. + * jerry_context_data () is called with a pointer to my_manager as defined below. */ } @@ -1691,7 +1689,7 @@ static const jerry_context_data_manager_t my_manager = static void someplace_in_the_code (void) { - my_context_data_t *my_data = (my_context_data_t *) jerry_get_context_data (&my_manager); + my_context_data_t *my_data = (my_context_data_t *) jerry_context_data (&my_manager); /* Perform useful things using the data found in my_data */ } ``` @@ -1712,9 +1710,9 @@ Registers an external magic string array. ```c void -jerry_register_magic_strings (const jerry_char_t * const *ex_str_items_p, - uint32_t count, - const jerry_length_t *str_lengths_p); +jerry_register_magic_strings (const jerry_char_t * const *ex_str_items_p, + uint32_t count, + const jerry_length_t *str_lengths_p); ``` - `ex_str_items_p` - character arrays, representing external magic strings' contents @@ -1761,7 +1759,7 @@ main (void) - [jerry_get_literals_from_snapshot](#jerry_get_literals_from_snapshot) -## jerry_get_memory_stats +## jerry_heap_stats **Summary** @@ -1771,21 +1769,21 @@ Get heap memory stats. - The engine must be initialized with the `JERRY_INIT_MEM_STATS` option to allow heap statistic collections. See [jerry_init](#jerry_init) - This API depends on a build option (`JERRY_MEM_STATS`) and can be checked - in runtime with the `JERRY_FEATURE_MEM_STATS` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + in runtime with the `JERRY_FEATURE_HEAP_STATS` feature enum value, + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c bool -jerry_get_memory_stats (jerry_heap_stats_t *out_stats_p); +jerry_heap_stats (jerry_heap_stats_t *out_stats_p); ``` - `out_stats_p` - out parameter, that provides the heap statistics. - return value - true, if stats were written into the `out_stats_p` pointer. - - false, otherwise. Usually it is because the `JERRY_FEATURE_MEM_STATS` feature is not enabled. + - false, otherwise. Usually it is because the `JERRY_FEATURE_HEAP_STATS` feature is not enabled. *New in version 2.0*. @@ -1796,7 +1794,7 @@ jerry_init (JERRY_INIT_MEM_STATS); // ... jerry_heap_stats_t stats = {0}; -bool get_stats_ret = jerry_get_memory_stats (&stats); +bool get_stats_ret = jerry_heap_stats (&stats); ``` **See also** @@ -1804,7 +1802,7 @@ bool get_stats_ret = jerry_get_memory_stats (&stats); - [jerry_init](#jerry_init) -## jerry_gc +## jerry_heap_gc **Summary** @@ -1814,7 +1812,7 @@ Performs garbage collection. ```c void -jerry_gc (jerry_gc_mode_t mode); +jerry_heap_gc (jerry_gc_mode_t mode); ``` - `mode` - operational mode, see [jerry_gc_mode_t](#jerry_gc_mode_t) @@ -1833,10 +1831,10 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t object_value = jerry_create_object (); - jerry_release_value (object_value); + jerry_value_t object_value = jerry_object (); + jerry_value_free (object_value); - jerry_gc (JERRY_GC_PRESSURE_LOW); + jerry_heap_gc (JERRY_GC_PRESSURE_LOW); jerry_cleanup (); } @@ -1852,60 +1850,13 @@ main (void) Functions to parse and run JavaScript source code. -## jerry_run_simple - -**Summary** - -The simplest way to run JavaScript. - -**Prototype** - -```c -bool -jerry_run_simple (const jerry_char_t *script_source_p, - size_t script_source_size, - jerry_init_flag_t flags); -``` - -- `script_source_p` - source code, it must be a valid utf8 string. -- `script_source_size` - size of source code buffer, in bytes. -- `jerry_init_flag_t` - combination of various engine configuration flags -- return value - - true, if run was successful - - false, otherwise - -**Example** - -[doctest]: # () - -```c -#include "jerryscript.h" - -int -main (void) -{ - const jerry_char_t script[] = "print ('Hello, World!');"; - - jerry_run_simple (script, sizeof (script) - 1, JERRY_INIT_EMPTY); - return 0; -} -``` - -**See also** - -- [jerry_init](#jerry_init) -- [jerry_cleanup](#jerry_cleanup) -- [jerry_parse](#jerry_parse) -- [jerry_run](#jerry_run) - - ## jerry_parse **Summary** Parse a script, module, or function and create a compiled code using a character string. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -1922,11 +1873,11 @@ jerry_parse (const jerry_char_t *source_p, - `options_p` - additional parsing options, can be NULL if not used - return value - function object value, if script was parsed successfully, - - thrown error, otherwise + - thrown exception, otherwise -*Changed in version 2.0*: Added `resource_name_p`, and `resource_name_length` arguments. +*Changed in version 2.0*: Added `source_name_p`, and `source_name_length` arguments. -*Changed in version [[NEXT_RELEASE]]*: The `resource_name_p`, `resource_name_length`, and `parse_opts` arguments are replaced by `options_p`. +*Changed in version [[NEXT_RELEASE]]*: 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** @@ -1945,19 +1896,19 @@ main (void) const jerry_char_t script[] = "print ('Hello, World!');"; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_STRICT_MODE | JERRY_PARSE_HAS_RESOURCE | JERRY_PARSE_HAS_START; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "hello.js"); + parse_options.options = JERRY_PARSE_STRICT_MODE | JERRY_PARSE_HAS_SOURCE_NAME | JERRY_PARSE_HAS_START; + parse_options.source_name = jerry_string_sz ("hello.js"); /* This example script is extracted from the middle of a file. */ parse_options.start_line = 10; parse_options.start_column = 1; jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); /* Run the "parsed_code" script with "jerry_run". */ - jerry_release_value (jerry_run (parsed_code)); - jerry_release_value (parsed_code); + jerry_value_free (jerry_run (parsed_code)); + jerry_value_free (parsed_code); jerry_cleanup (); return 0; @@ -1979,27 +1930,27 @@ main (void) /* Specify the argument list to parse a function. */ jerry_parse_options_t parse_options; parse_options.options = JERRY_PARSE_HAS_ARGUMENT_LIST; - parse_options.argument_list = jerry_create_string ((const jerry_char_t *) "a, b"); + parse_options.argument_list = jerry_string_sz ("a, b"); const jerry_char_t function_code[] = "return a + b;"; jerry_value_t parsed_function = jerry_parse (function_code, sizeof (function_code) - 1, &parse_options); - jerry_release_value (parse_options.argument_list); + jerry_value_free (parse_options.argument_list); /* Use the "parsed_function" as a normal JavaScript function. */ jerry_value_t args[] = { - jerry_create_number (3), - jerry_create_number (4), + jerry_number (3), + jerry_number (4), }; jerry_size_t argc = sizeof (args) / sizeof (args[0]); - jerry_value_t call_result = jerry_call_function (parsed_function, - jerry_create_undefined(), - args, - argc); + jerry_value_t call_result = jerry_call (parsed_function, + jerry_undefined(), + args, + argc); /* use the function result */ - jerry_release_value (call_result); - jerry_release_value (parsed_function); + jerry_value_free (call_result); + jerry_value_free (parsed_function); jerry_cleanup (); return 0; @@ -2018,7 +1969,7 @@ main (void) Parse a script, module, or function and create a compiled code using a string value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -2033,7 +1984,7 @@ jerry_parse_value (const jerry_value_t source_value, - `options_p` - additional parsing options, can be NULL if not used - return value - function object value, if script was parsed successfully, - - thrown error, otherwise + - thrown exception, otherwise *New in version [[NEXT_RELEASE]]*. @@ -2049,19 +2000,19 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t script_value = jerry_create_string ((const jerry_char_t *) "print ('Hello, World!');"); + jerry_value_t script_value = jerry_string_sz ("print ('Hello, World!');"); jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_STRICT_MODE | JERRY_PARSE_HAS_RESOURCE | JERRY_PARSE_HAS_START; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "hello.js"); + parse_options.options = JERRY_PARSE_STRICT_MODE | JERRY_PARSE_HAS_SOURCE_NAME | JERRY_PARSE_HAS_START; + parse_options.source_name = jerry_string_sz ("hello.js"); /* This example script is extracted from the middle of a file. */ parse_options.start_line = 10; parse_options.start_column = 1; jerry_value_t parsed_code = jerry_parse_value (script_value, &parse_options); - jerry_release_value (parse_options.resource_name); - jerry_release_value (script_value); - jerry_release_value (parsed_code); + jerry_value_free (parse_options.source_name); + jerry_value_free (script_value); + jerry_value_free (parsed_code); jerry_cleanup (); return 0; @@ -2082,7 +2033,7 @@ Run a Script or Module created by [jerry_parse](#jerry_parse). *Notes*: - The code should be previously parsed with `jerry_parse`. - - Returned value must be freed with [jerry_release_value](#jerry_release_value) + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -2095,7 +2046,7 @@ jerry_run (const jerry_value_t func_val); - `func_val` - function to run - return value - result of bytecode, if run was successful - - thrown error, otherwise + - thrown exception, otherwise **Example** @@ -2115,17 +2066,17 @@ main (void) /* Setup Global scope code */ jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL); - if (!jerry_value_is_error (parsed_code)) + if (!jerry_value_is_exception (parsed_code)) { /* Execute the parsed source code in the Global scope */ jerry_value_t ret_value = jerry_run (parsed_code); /* Returned value must be freed */ - jerry_release_value (ret_value); + jerry_value_free (ret_value); } /* Parsed source code must be freed */ - jerry_release_value (parsed_code); + jerry_value_free (parsed_code); /* Cleanup engine */ jerry_cleanup (); @@ -2143,7 +2094,7 @@ main (void) Perform JavaScript `eval` function call (ECMA-262 v5.1 sec-15.1.2.1). -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -2159,7 +2110,7 @@ jerry_eval (const jerry_char_t *source_p, - `source_size` - length of the source code - `parse_opts` - combination of [jerry_parse_option_enable_feature_t](#jerry_parse_option_enable_feature_t) flags. The following flags are allowed: JERRY_PARSE_STRICT_MODE -- return value - result of eval, may be an error value. +- return value - result of eval, may be an exception value. **Example** @@ -2173,29 +2124,29 @@ jerry_eval (const jerry_char_t *source_p, **See also** -- [jerry_create_external_function](#jerry_create_external_function) +- [jerry_function_external](#jerry_function_external) - [jerry_external_handler_t](#jerry_external_handler_t) -## jerry_run_all_enqueued_jobs +## jerry_run_jobs **Summary** -Run enqueued Promise jobs until the first thrown error or until all get executed. +Run enqueued Promise tasks until the first thrown exception or until all tasks get executed. -*Important Note*: The job queue is not guaranteed to be empty, after the function call has returned a value. -Therefore, this function is best used in a while loop, handling each error it returns, until the job queue is empty. +*Important Note*: The task queue is not guaranteed to be empty after the function call has returned a value. +Therefore, this function is best used in a while loop, handling each exception it returns, until the queue is empty. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_run_all_enqueued_jobs (void) +jerry_run_jobs (void) ``` -- return value - result of last executed job, may be error value. +- return value - result of last executed job, may be an exception value. *New in version 2.0*. @@ -2219,16 +2170,16 @@ main (void) jerry_value_t job_value; while (true) { - job_value = jerry_run_all_enqueued_jobs (); + job_value = jerry_run_jobs (); - if (jerry_value_is_error (job_value)) + if (jerry_value_is_exception (job_value)) { if (jerry_value_is_abort (job_value)) { // Terminate the engine } - // Handle the error here + // Handle the exception here } else { @@ -2237,9 +2188,9 @@ main (void) } } - jerry_release_value (job_value); - jerry_release_value (script_value); - jerry_release_value (parsed_code); + jerry_value_free (job_value); + jerry_value_free (script_value); + jerry_value_free (parsed_code); jerry_cleanup (); return 0; @@ -2249,20 +2200,20 @@ main (void) # Get the global context -## jerry_get_global_object +## jerry_current_realm **Summary** Get the Global object. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_get_global_object (void); +jerry_current_realm (void); ``` - return value - api value of global object @@ -2271,18 +2222,18 @@ jerry_get_global_object (void); ```c { - jerry_value_t glob_obj_val = jerry_get_global_object (); + jerry_value_t glob_obj_val = jerry_current_realm (); ... // Do something with global object, ex: add properties - jerry_release_value (glob_obj_val); + jerry_value_free (glob_obj_val); } ``` **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_define_own_property](#jerry_define_own_property) +- [jerry_value_free](#jerry_value_free) +- [jerry_object_define_own_prop](#jerry_object_define_own_prop) # Checker functions @@ -2293,7 +2244,7 @@ Functions to check the type of an API value ([jerry_value_t](#jerry_value_t)). **Summary** -Returns whether the given `jerry_value_t` has the error and abort value set. +Returns whether the given `jerry_value_t` is an abort exception value. **Prototype** @@ -2304,7 +2255,7 @@ jerry_value_is_abort (const jerry_value_t value); - `value` - api value - return value - - true, if the given `jerry_value_t` has the error and abort value set + - true, if the given `jerry_value_t` is an abort exception - false, otherwise *New in version 2.0*. @@ -2314,21 +2265,21 @@ jerry_value_is_abort (const jerry_value_t value); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_abort (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** - [jerry_value_t](#jerry_value_t) -- [jerry_value_is_error](#jerry_value_is_error) +- [jerry_value_is_exception](#jerry_value_is_exception) ## jerry_value_is_array @@ -2353,20 +2304,20 @@ jerry_value_is_array (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_array (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_arraybuffer @@ -2377,7 +2328,7 @@ Returns whether the given `jerry_value_t` is an ArrayBuffer object. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** @@ -2399,21 +2350,21 @@ jerry_value_is_arraybuffer (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_arraybuffer (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_create_arraybuffer](#jerry_create_arraybuffer) -- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) +- [jerry_arraybuffer](#jerry_arraybuffer) +- [jerry_arraybuffer_external](#jerry_arraybuffer_external) ## jerry_value_is_shared_arraybuffer @@ -2424,7 +2375,7 @@ Returns whether the given `jerry_value_t` is a SharedArrayBuffer object. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** @@ -2446,21 +2397,21 @@ jerry_value_is_shared_arraybuffer (const jerry_value_t value); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_shared_arraybuffer (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_create_shared_arraybuffer](#jerry_create_shared_arraybuffer) -- [jerry_create_shared_arraybuffer_external](#jerry_create_shared_arraybuffer_external) +- [jerry_shared_arraybuffer](#jerry_shared_arraybuffer) +- [jerry_shared_arraybuffer_external](#jerry_shared_arraybuffer_external) ## jerry_value_is_boolean @@ -2486,20 +2437,20 @@ jerry_value_is_boolean (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_boolean (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_true @@ -2526,20 +2477,20 @@ jerry_value_is_true (const jerry_value_t value); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_true (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_false @@ -2566,20 +2517,20 @@ jerry_value_is_false (const jerry_value_t value); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_false (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_constructor @@ -2604,20 +2555,20 @@ jerry_value_is_constructor (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_constructor (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_dataview @@ -2628,7 +2579,7 @@ Returns whether the given `jerry_value_t` is a DataView object value. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** @@ -2657,16 +2608,16 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t arraybuffer = jerry_create_arraybuffer (16); - jerry_value_t dataview = jerry_create_dataview (arraybuffer, 0, 16); + jerry_value_t arraybuffer = jerry_arraybuffer (16); + jerry_value_t dataview = jerry_dataview (arraybuffer, 0, 16); if (jerry_value_is_dataview (dataview)) { // usage of dataview } - jerry_release_value (dataview); - jerry_release_value (arraybuffer); + jerry_value_free (dataview); + jerry_value_free (arraybuffer); jerry_cleanup (); return 0; @@ -2675,26 +2626,26 @@ main (void) **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_create_dataview](#jerry_create_dataview) +- [jerry_value_free](#jerry_value_free) +- [jerry_dataview](#jerry_dataview) -## jerry_value_is_error +## jerry_value_is_exception **Summary** -Returns whether the given `jerry_value_t` is error value. +Returns whether the given `jerry_value_t` is an exception value. **Prototype** ```c bool -jerry_value_is_error (const jerry_value_t value); +jerry_value_is_exception (const jerry_value_t value); ``` - `value` - api value - return value - - true, if the given `jerry_value_t` is error value. + - true, if the given `jerry_value_t` is an exception value. - false, otherwise *New in version 2.0*. @@ -2704,14 +2655,14 @@ jerry_value_is_error (const jerry_value_t value); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value - if (jerry_value_is_error (value)) + if (jerry_value_is_exception (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` @@ -2743,20 +2694,20 @@ jerry_value_is_function (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_function (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_async_function @@ -2784,20 +2735,20 @@ jerry_value_is_async_function (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_async_function (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_number @@ -2822,20 +2773,20 @@ jerry_value_is_number (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_number (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_null @@ -2861,20 +2812,20 @@ jerry_value_is_null (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_null (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_object @@ -2900,20 +2851,20 @@ jerry_value_is_object (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_object (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_promise @@ -2922,13 +2873,6 @@ jerry_value_is_object (const jerry_value_t value) Returns whether the given `jerry_value_t` is a promise value. -*Notes*: -- 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_is_feature_enabled](#jerry_is_feature_enabled). -- The es.next profile enables this by default. - - **Prototype** ```c @@ -2943,28 +2887,26 @@ jerry_value_is_promise (const jerry_value_t value) *New in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: Build option dependency changed from `JERRY_BUILTIN_PROMISE` to `JERRY_ESNEXT`. - **Example** ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_promise (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_create_promise](#jerry_create_promise) +- [jerry_value_free](#jerry_value_free) +- [jerry_promise](#jerry_promise) ## jerry_value_is_proxy @@ -2976,7 +2918,7 @@ Returns whether the given `jerry_value_t` is a proxy value. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. @@ -2999,22 +2941,22 @@ jerry_value_is_proxy (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_proxy (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_create_proxy](#jerry_create_proxy) -- [jerry_create_special_proxy](#jerry_create_special_proxy) +- [jerry_value_free](#jerry_value_free) +- [jerry_proxy](#jerry_proxy) +- [jerry_proxy_custom](#jerry_proxy_custom) ## jerry_value_is_string @@ -3040,20 +2982,20 @@ jerry_value_is_string (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_string (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) ## jerry_value_is_symbol @@ -3062,12 +3004,6 @@ jerry_value_is_string (const jerry_value_t value) Returns whether the given `jerry_value_t` is a symbol value. -*Notes*: -- This API depends on a build option (`JERRY_BUILTIN_SYMBOL`) and can be checked - in runtime with the `JERRY_FEATURE_SYMBOL` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). -- The es.next profile enables this by default. - **Prototype** ```c @@ -3094,17 +3030,17 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "Symbol description string"); - jerry_value_t symbol_value = jerry_create_symbol (string_value); + jerry_value_t string_value = jerry_string_sz ("Symbol description string"); + jerry_value_t symbol_value = jerry_symbol_with_description (string_value); - jerry_release_value (string_value); + jerry_value_free (string_value); if (jerry_value_is_symbol (symbol_value)) { // usage of symbol_value } - jerry_release_value (symbol_value); + jerry_value_free (symbol_value); jerry_cleanup (); return 0; @@ -3113,8 +3049,8 @@ main (void) **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_create_symbol](#jerry_create_symbol) +- [jerry_value_free](#jerry_value_free) +- [jerry_symbol](#jerry_symbol) ## jerry_value_is_bigint @@ -3126,7 +3062,7 @@ Returns whether the given `jerry_value_t` is a bigint value. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** @@ -3155,17 +3091,17 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "12345678"); + jerry_value_t string_value = jerry_string_sz ("12345678"); jerry_value_t bigint_value = jerry_value_to_bigint (string_value); - jerry_release_value (string_value); + jerry_value_free (string_value); if (jerry_value_is_bigint (bigint_value)) { // usage of bigint_value } - jerry_release_value (bigint_value); + jerry_value_free (bigint_value); jerry_cleanup (); return 0; @@ -3174,8 +3110,8 @@ main (void) **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_create_bigint](#jerry_create_bigint) +- [jerry_value_free](#jerry_value_free) +- [jerry_bigint](#jerry_bigint) - [jerry_value_to_bigint](#jerry_value_to_bigint) @@ -3188,7 +3124,7 @@ Checks whether the given `jerry_value_t` is a TypedArray object or not. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** @@ -3217,14 +3153,14 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t value = jerry_create_typedarray (JERRY_TYPEDARRAY_UINT16, 15); + jerry_value_t value = jerry_typedarray (JERRY_TYPEDARRAY_UINT16, 15); if (jerry_value_is_typedarray (value)) { /* "value" is a typedarray. */ } - jerry_release_value (value); + jerry_value_free (value); jerry_cleanup (); @@ -3234,10 +3170,10 @@ main (void) **See also** -- [jerry_create_typedarray](#jerry_create_typedarray) +- [jerry_typedarray](#jerry_typedarray) -## jerry_get_container_type +## jerry_container_type **Summary** @@ -3247,14 +3183,14 @@ Checks whether the given `jerry_value_t` is the given `jerry_container_type_t` t - This API function depends on a build option (`JERRY_BUILTIN_CONTAINER`) and can be checked runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` feature enum values. - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** ```c jerry_container_type_t -jerry_get_container_type (const jerry_value_t value) +jerry_container_type (const jerry_value_t value) ``` - `value` - Container object @@ -3275,14 +3211,14 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t value = jerry_create_container (JERRY_CONTAINER_TYPE_MAP, NULL, 0); + jerry_value_t value = jerry_container (JERRY_CONTAINER_TYPE_MAP, NULL, 0); - if (jerry_get_container_type (value) == JERRY_CONTAINER_TYPE_MAP) + if (jerry_container_type (value) == JERRY_CONTAINER_TYPE_MAP) { /* "value" is a map. */ } - jerry_release_value (value); + jerry_value_free (value); jerry_cleanup (); @@ -3292,7 +3228,7 @@ main (void) **See also** -- [jerry_create_container](#jerry_create_container) +- [jerry_container](#jerry_container) - [jerry_container_type_t](#jerry_container_type_t) @@ -3319,22 +3255,22 @@ jerry_value_is_undefined (const jerry_value_t value) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_undefined (value)) { ... } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_value_get_type +## jerry_value_type **Summary** @@ -3349,7 +3285,7 @@ value has its own enum value. ```c jerry_type_t -jerry_value_get_type (const jerry_value_t value); +jerry_value_type (const jerry_value_t value); ``` - `value` - JavaScript value to check. @@ -3362,16 +3298,16 @@ jerry_value_get_type (const jerry_value_t value); ```c { - jerry_value_t number = jerry_create_number (3.3); + jerry_value_t number = jerry_number (3.3); - jerry_type_t type_info = jerry_value_get_type (number); + jerry_type_t type_info = jerry_value_type (number); if (type_info == JERRY_TYPE_NUMBER) { /* ... */ } - jerry_release_value (number); + jerry_value_free (number); } ``` @@ -3379,7 +3315,7 @@ jerry_value_get_type (const jerry_value_t value); - [jerry_type_t](#jerry_type_t) -## jerry_object_get_type +## jerry_object_type **Summary** @@ -3389,15 +3325,15 @@ for a given value as a [jerry_object_type_t](#jerry_object_type_t) enum value. Note: For non-object parameters `JERRY_OBJECT_TYPE_NONE` is returned. Note: the returned type can be checked for more detailed type information in the following cases: - `JERRY_OBJECT_TYPE_CONTAINER`, *see also:* [jerry_container_get_type](#jerry_container_get_type) - - `JERRY_OBJECT_TYPE_FUNCTION`, *see also:* [jerry_function_get_type](#jerry_function_get_type) - - `JERRY_OBJECT_TYPE_ITERATOR`, *see also:* [jerry_iterator_get_type](#jerry_iterator_get_type) - - `JERRY_OBJECT_TYPE_TYPEDARRAY`, *see also:* [jerry_get_typedarray_type](#jerry_get_typedarray_type) + - `JERRY_OBJECT_TYPE_FUNCTION`, *see also:* [jerry_function_type](#jerry_function_type) + - `JERRY_OBJECT_TYPE_ITERATOR`, *see also:* [jerry_iterator_type](#jerry_iterator_type) + - `JERRY_OBJECT_TYPE_TYPEDARRAY`, *see also:* [jerry_typedarray_type](#jerry_typedarray_type) **Prototype** ```c jerry_object_type_t -jerry_object_get_type (const jerry_value_t value); +jerry_object_type (const jerry_value_t value); ``` - `value` - JavaScript value to check. @@ -3410,16 +3346,16 @@ jerry_object_get_type (const jerry_value_t value); ```c { - jerry_value_t object = jerry_create_object (); + jerry_value_t object = jerry_object (); - jerry_object_type_t object_type_info = jerry_object_get_type (object); + jerry_object_type_t object_type_info = jerry_object_type (object); if (type_info == JERRY_OBJECT_TYPE_GENERIC) { /* ... */ } - jerry_release_value (object); + jerry_value_free (object); } ``` @@ -3427,7 +3363,7 @@ jerry_object_get_type (const jerry_value_t value); - [jerry_object_type_t](#jerry_object_type_t) -## jerry_function_get_type +## jerry_function_type **Summary** @@ -3438,7 +3374,7 @@ for a given value as a [jerry_function_type_t](#jerry_function_type_t) enum valu ```c jerry_function_type_t -jerry_function_get_type (const jerry_value_t value); +jerry_function_type (const jerry_value_t value); ``` - `value` - JavaScript value to check. @@ -3456,14 +3392,14 @@ Note: For non-function parameters `JERRY_FUNCTION_TYPE_NONE` is returned. const jerry_char_t script[] = "function f() {}; f"; jerry_value_t function_object = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); - jerry_function_type_t function_type_info = jerry_function_get_type (function_object); + jerry_function_type_t function_type_info = jerry_function_type (function_object); if (type_info == JERRY_FUNCTION_TYPE_GENERIC) { /* ... */ } - jerry_release_value (function_object); + jerry_value_free (function_object); } ``` @@ -3471,7 +3407,7 @@ Note: For non-function parameters `JERRY_FUNCTION_TYPE_NONE` is returned. - [jerry_function_type_t](#jerry_function_type_t) -## jerry_iterator_get_type +## jerry_iterator_type **Summary** @@ -3482,7 +3418,7 @@ for a given value as a [jerry_iterator_type_t](#jerry_iterator_type_t) enum valu ```c jerry_iterator_type_t -jerry_iterator_get_type (const jerry_value_t value); +jerry_iterator_type (const jerry_value_t value); ``` - `value` - JavaScript value to check. @@ -3500,14 +3436,14 @@ Note: For non-iterator parameters `JERRY_ITERATOR_TYPE_NONE` is returned. const jerry_char_t script[] = "[1, 2, 3].values()"; jerry_value_t iterator = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); - jerry_iterator_type_t iterator_type_info = jerry_iterator_get_type (iterator); + jerry_iterator_type_t iterator_type_info = jerry_iterator_type (iterator); if (type_info == JERRY_ITERATOR_TYPE_ARRAY) { /* ... */ } - jerry_release_value (iterator); + jerry_value_free (iterator); } ``` @@ -3515,7 +3451,7 @@ Note: For non-iterator parameters `JERRY_ITERATOR_TYPE_NONE` is returned. - [jerry_iterator_type_t](#jerry_iterator_type_t) -## jerry_is_feature_enabled +## jerry_feature_enabled **Summary** @@ -3525,7 +3461,7 @@ Returns whether the specified compile time feature is enabled. ```c bool -jerry_is_feature_enabled (const jerry_feature_t feature); +jerry_feature_enabled (const jerry_feature_t feature); ``` - `feature` - jerry feature @@ -3542,7 +3478,7 @@ jerry_is_feature_enabled (const jerry_feature_t feature); /* ... */ jerry_feature_t feature = JERRY_FEATURE_SNAPSHOT_SAVE; - if (jerry_is_feature_enabled (feature)) + if (jerry_feature_enabled (feature)) { /* ... */ } @@ -3557,30 +3493,30 @@ jerry_is_feature_enabled (const jerry_feature_t feature); # Binary operations -## jerry_binary_operation +## jerry_binary_op **Summary** Perform binary operation on the given operands (==, ===, <, >, etc.). -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_binary_operation (jerry_binary_operation_t op, - const jerry_value_t lhs, - const jerry_value_t rhs); +jerry_binary_op (jerry_binary_op_t op, + const jerry_value_t lhs, + const jerry_value_t rhs); ``` - `op` - binary operation - `lhs` - left-hand side operand - `rhs` - right-hand side operand - return value - - error, if argument has an error flag or operation is unsuccessful or unsupported - - true/false, the result of the binary operation on the given operands otherwise + - exception, if operation is unsuccessful or unsupported + - the result of the binary operation on the given operands otherwise *New in version 2.0*. @@ -3590,10 +3526,10 @@ jerry_binary_operation (jerry_binary_operation_t op, { jerry_value_t value1; jerry_value_t value2; - ... // create or acquire value - jerry_value_t result = jerry_binary_operation (JERRY_BIN_OP_EQUAL, value1, value2) + ... // create or copy value + jerry_value_t result = jerry_binary_op (JERRY_BIN_OP_EQUAL, value1, value2) - if (!jerry_value_is_error (result)) + if (!jerry_value_is_exception (result)) { if (jerry_value_is_true (result)) { @@ -3609,9 +3545,9 @@ jerry_binary_operation (jerry_binary_operation_t op, ... // handle error } - jerry_release_value (value1); - jerry_release_value (value2); - jerry_release_value (result); + jerry_value_free (value1); + jerry_value_free (value2); + jerry_value_free (result); } ``` @@ -3627,7 +3563,7 @@ my_constructor (const jerry_call_info_t *call_info_p, const jerry_value_t argv[], const jerry_length_t argc) { - return jerry_create_undefined (); + return jerry_undefined (); } int @@ -3635,32 +3571,32 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t base_obj = jerry_create_object (); - jerry_value_t constructor = jerry_create_external_function (my_constructor); + jerry_value_t base_obj = jerry_object (); + jerry_value_t constructor = jerry_function_external (my_constructor); /* External functions does not have a prototype by default, so we need to create one */ - jerry_value_t prototype_str = jerry_create_string ((const jerry_char_t *) ("prototype")); - jerry_release_value (jerry_set_property (constructor, prototype_str, base_obj)); - jerry_release_value (prototype_str); + jerry_value_t prototype_str = jerry_string_sz ("prototype"); + jerry_value_free (jerry_object_set (constructor, prototype_str, base_obj)); + jerry_value_free (prototype_str); /* Construct the instance. */ - jerry_value_t instance_val = jerry_construct_object (constructor, NULL, 0); + jerry_value_t instance_val = jerry_construct (constructor, NULL, 0); /* Call the API function of 'instanceof'. */ - jerry_value_t is_instance = jerry_binary_operation (JERRY_BIN_OP_INSTANCEOF, - instance_val, - constructor); - if (!jerry_value_is_error (is_instance) + jerry_value_t is_instance = jerry_binary_op (JERRY_BIN_OP_INSTANCEOF, + instance_val, + constructor); + if (!jerry_value_is_exception (is_instance) && jerry_value_is_true (is_instance)) { /* ... */ } /* Free all of the jerry values and cleanup the engine. */ - jerry_release_value (base_obj); - jerry_release_value (constructor); - jerry_release_value (instance_val); - jerry_release_value (is_instance); + jerry_value_free (base_obj); + jerry_value_free (constructor); + jerry_value_free (instance_val); + jerry_value_free (is_instance); jerry_cleanup (); return 0; @@ -3669,14 +3605,14 @@ main (void) **See also** -- [jerry_binary_operation_t](#jerry_binary_operation_t) +- [jerry_binary_op_t](#jerry_binary_op_t) -# Error manipulation functions +# Exception manipulation functions -*Changed in version 2.0*: The error handling and manipulation was modified and the old methods were replaced. +*Changed in version 2.0*: The exception handling and manipulation was modified and the old methods were replaced. -## jerry_create_abort_from_value +## jerry_throw_abort **Summary** @@ -3684,21 +3620,21 @@ Create (api) abort from a value. This function creates an API abort value from an API value. The second argument defines whether the input value must be released or not. If it is set to `true`, -then a [`jerry_release_value`](#jerry_release_value) function will be called +then a [`jerry_value_free`](#jerry_value_free) function will be called for the first argument, so the api value won't be available after the call of -`jerry_create_abort_from_value`. The second argument should be false if both value +`jerry_throw_abort`. The second argument should be false if both value and created abort value are needed. **Prototype** ```c jerry_value_t -jerry_create_abort_from_value (jerry_value_t value, bool release); +jerry_throw_abort (jerry_value_t value, bool take_ownersip); ``` - `value` - api value -- `release` - raw boolean, defines whether input value must be released -- return value - abort (api) value +- `take_ownership` - raw boolean, defines whether input value should be copied +- return value - abort exception value *New in version 2.0*. @@ -3707,12 +3643,12 @@ jerry_create_abort_from_value (jerry_value_t value, bool release); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value - jerry_value_t abort = jerry_create_abort_from_value (value, true); + jerry_value_t abort = jerry_throw_abort (value, true); // using the 'value' variable after release is invalid. - jerry_release_value (abort); + jerry_value_free (abort); } ``` @@ -3721,45 +3657,43 @@ jerry_create_abort_from_value (jerry_value_t value, bool release); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value - jerry_value_t abort = jerry_create_abort_from_value (value, false); + jerry_value_t abort = jerry_throw_abort (value, false); // both 'abort' and 'value' can be used and must be released when they are no longer needed - jerry_release_value (abort); - jerry_release_value (value); + jerry_value_free (abort); + jerry_value_free (value); } ``` **See also** - [jerry_value_t](#jerry_value_t) -- [jerry_get_value_from_error](#jerry_get_value_from_error) -- [jerry_create_error_from_value](#jerry_create_error_from_value) +- [jerry_exception_value](#jerry_exception_value) +- [jerry_throw](#jerry_throw) -## jerry_create_error_from_value +## jerry_throw **Summary** -Create (api) error from a value. +Create exception from a value. -This function creates an API error value from an API value. The second argument defines -whether the input value must be released or not. If it is set to `true`, -then a [`jerry_release_value`](#jerry_release_value) function will be called -for the first argument, so the api value won't be available after the call of -`jerry_create_error_from_value`. The second argument should be false if both value -and created error value are needed. +This function creates an API exception value from an API value. The second argument defines +whether the input value should be taken by the exception or copied. If it is set to `true`, +then then the ownership of the argument value is taken, so it won't be available after the call to +`jerry_throw`. The second argument should be false if both the original value and created exception are needed. **Prototype** ```c jerry_value_t -jerry_create_error_from_value (jerry_value_t value, bool release); +jerry_throw (jerry_value_t value, bool take_ownership); ``` - `value` - api value -- `release` - raw boolean, defines whether input value must be released -- return value - error (api) value +- `take_ownership` - raw boolean, defines whether input value should be copied +- return value - exception value *New in version 2.0*. @@ -3768,13 +3702,13 @@ jerry_create_error_from_value (jerry_value_t value, bool release); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value - jerry_value_t error = jerry_create_error_from_value (value, true); + jerry_value_t exception = jerry_throw (value, true); // using the 'value' variable after release is invalid. - jerry_release_value (error); + jerry_value_free (exception); } ``` @@ -3783,42 +3717,39 @@ jerry_create_error_from_value (jerry_value_t value, bool release); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value - jerry_value_t error = jerry_create_error_from_value (value, false); - // both 'error' and 'value' can be used and must be released when they are no longer needed + jerry_value_t exception = jerry_throw_value (value, false); + // both 'exception' and 'value' can be used and must be released when they are no longer needed - jerry_release_value (error); - jerry_release_value (value); + jerry_value_free (exception); + jerry_value_free (value); } ``` **See also** - [jerry_value_t](#jerry_value_t) -- [jerry_get_value_from_error](#jerry_get_value_from_error) -- [jerry_create_abort_from_value](#jerry_create_abort_from_value) +- [jerry_exception_value](#jerry_exception_value) +- [jerry_throw_abort](#jerry_throw_abort) -## jerry_get_error_type +## jerry_error_type **Summary** -Returns the type of the Error object if possible. +Returns the type of the Error object if possible. If a non-error object is used as the input for the function the +method will return `JERRY_ERROR_NONE` indicating that the value was not an Error object. -If a non-error object is used as the input for the function the method -will return `JERRY_ERROR_NONE` indicating that the value was not -an Error object. However it is still possible that the value contains -error semantics. To correctly detect if a value have error use the -[jerry_value_is_error](#jerry_value_is_error) method. +Note: If an exception value is passed as an argument, the function will inspect the contained value instead. **Prototype** ```c jerry_error_t -jerry_get_error_type (const jerry_value_t value); +jerry_error_type (const jerry_value_t value); ``` -- `value` - api value (possible error object) +- `value` - api value (possible exception object) - return value - JERRY_ERROR_NONE if the input is not an error object - one of the [jerry_error_t](#jerry_error_t) value @@ -3829,46 +3760,45 @@ jerry_get_error_type (const jerry_value_t value); ```c { - jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_RANGE, - (const jerry_char_t *) "error msg"); - jerry_error_t error_type = jerry_get_error_type (error_obj); + jerry_value_t error_obj = jerry_error_sz (JERRY_ERROR_RANGE, "error msg"); + jerry_error_t error_type = jerry_error_type (error_obj); // error_type is now JERRY_ERROR_RANGE. - jerry_release_value (error_obj); + jerry_value_free (error_obj); } ``` **See also** -- [jerry_create_error](#jerry_create_error) -- [jerry_value_is_error](#jerry_value_is_error) +- [jerry_error](#jerry_error) +- [jerry_value_is_exception](#jerry_value_is_exception) -## jerry_get_value_from_error +## jerry_exception_value **Summary** -Get the value from an error. +Get the value contained in an exception. -Many API functions cannot be called with an error value. -This function extracts the API value from an error. The second argument defines -whether the input error value must be released or not. If it is set to `true`, -then a [`jerry_release_value`](#jerry_release_value) function will be called -for the first argument, so the error value won't be available after the call of -`jerry_get_value_from_error`. The second argument should be false if both error -and its represented value are needed. +Many API functions cannot be called with an exception value. +This function extracts the API value from an exception. The second argument defines +whether the input exception value should be released or not. If it is set to `true`, +then a [`jerry_value_free`](#jerry_value_free) function will be called +for the first argument, so the exception value won't be available after the call of +`jerry_exception_value`. The second argument should be false if both the exception +and its contained value are needed. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_get_value_from_error (jerry_value_t value, bool release) +jerry_exception_value (jerry_value_t value, bool release) ``` -- `value` - error (api) value +- `value` - exception value - `release` - raw boolean, defines whether input value must be released - return value - api value @@ -3879,13 +3809,13 @@ jerry_get_value_from_error (jerry_value_t value, bool release) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value - jerry_value_t error = jerry_create_error_from_value (value, true); - jerry_value_t value_from_error = jerry_get_value_from_error (error, true); - // using the 'error' variable after release is invalid. + jerry_value_t exception = jerry_throw_value (value, true); + jerry_value_t value_from_error = jerry_exception_value (exception, true); + // using the 'exception' variable after release is invalid. - jerry_release_value (value_from_error); + jerry_value_free (value_from_error); } ``` @@ -3894,34 +3824,34 @@ jerry_get_value_from_error (jerry_value_t value, bool release) ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value - jerry_value_t error = jerry_create_error_from_value (value, true); - jerry_value_t value_from_error = jerry_get_value_from_error (error, false); - // both 'error' and 'value_from_error' can be used and must be released when they are no longer needed + jerry_value_t exception = jerry_throw_value (value, true); + jerry_value_t value_from_error = jerry_exception_value (exception, false); + // both 'exception' and 'value_from_error' can be used and must be released when they are no longer needed - jerry_release_value (value_from_error); - jerry_release_value (error); + jerry_value_free (value_from_error); + jerry_value_free (exception); } ``` **See also** - [jerry_value_t](#jerry_value_t) -- [jerry_create_error_from_value](#jerry_create_error_from_value) -- [jerry_create_abort_from_value](#jerry_create_abort_from_value) +- [jerry_throw](#jerry_throw) +- [jerry_throw_abort](#jerry_throw_abort) -## jerry_set_error_object_created_callback +## jerry_error_on_created **Summary** Set the decorator callback for newly created Error objects. The operation of the callback -is described in [jerry_error_object_created_callback_t](#jerry_error_object_created_callback_t). +is described in [jerry_error_object_created_cb_t](#jerry_error_object_created_cb_t). **Prototype** ```c -void jerry_set_error_object_created_callback (jerry_error_object_created_callback_t callback, void *user_p); +void jerry_error_on_created (jerry_error_object_created_cb_t callback, void *user_p); ``` - `callback` - callback function, the previously set value is overwritten, and setting NULL @@ -3946,10 +3876,9 @@ void main(void) { jerry_init (JERRY_INIT_EMPTY); - jerry_set_error_object_created_callback (error_object_created_callback, NULL); + jerry_error_on_created (error_object_created_callback, NULL); - jerry_release_value (jerry_create_error (JERRY_ERROR_COMMON, - (const jerry_char_t *) "Message")); + jerry_value_free (jerry_error_sz (JERRY_ERROR_COMMON, "Message")); jerry_cleanup (); } /* main */ @@ -3957,27 +3886,27 @@ void main(void) **See also** -- [jerry_error_object_created_callback_t](#jerry_error_object_created_callback_t) +- [jerry_error_object_created_cb_t](#jerry_error_object_created_cb_t) -## jerry_set_vm_throw_callback +## jerry_on_throw **Summary** -The callback passed to this function is called when an error is thrown +The callback passed to this function is called when an exception is thrown in ECMAScript code. The callback is not called again until the value is -caught. See: [jerry_vm_throw_callback_t](#jerry_vm_throw_callback_t). +caught. See: [jerry_throw_cb_t](#jerry_throw_cb_t). *Notes*: - This API depends on a build option (`JERRY_VM_THROW`) and can be checked in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c void -jerry_set_vm_throw_callback (jerry_vm_throw_callback_t throw_cb, - void *user_p); +jerry_on_throw (jerry_throw_cb_t throw_cb, + void *user_p); ``` - `throw_cb` - callback which is called on throws (passing NULL disables this feature) @@ -3993,7 +3922,7 @@ jerry_set_vm_throw_callback (jerry_vm_throw_callback_t throw_cb, #include "jerryscript.h" static void -vm_throw_callback (const jerry_value_t error_value, /**< captured error */ +vm_throw_callback (const jerry_value_t error_value, /**< captured exception */ void *user_p) /**< user pointer */ { (void) error_value; @@ -4009,11 +3938,11 @@ main (void) jerry_init (JERRY_INIT_EMPTY); int counter = 0; - jerry_set_vm_throw_callback (vm_throw_callback, &counter); + jerry_on_throw (vm_throw_callback, &counter); const jerry_char_t script[] = "try { throw new Error('1') } catch (e) { throw new Error('2') }"; - jerry_release_value (jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS)); + jerry_value_free (jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS)); /* The counter contains 2. */ @@ -4024,31 +3953,31 @@ main (void) **See also** -- [jerry_vm_throw_callback_t](#jerry_vm_throw_callback_t) -- [jerry_error_is_throw_captured](#jerry_error_is_throw_captured) -- [jerry_error_set_throw_capture](#jerry_error_set_throw_capture) +- [jerry_throw_cb_t](#jerry_throw_cb_t) +- [jerry_exception_is_captured](#jerry_exception_is_captured) +- [jerry_exception_allow_capture](#jerry_exception_allow_capture) -## jerry_error_is_throw_captured +## jerry_exception_is_captured **Summary** -Checks whether the callback set by [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback) -captured the error. +Checks whether the callback set by [jerry_on_throw](#jerry_on_throw) +captured the exception. *Notes*: - This API depends on a build option (`JERRY_VM_THROW`) and can be checked in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -bool jerry_error_is_throw_captured (jerry_value_t value); +bool jerry_exception_is_captured (jerry_value_t value); ``` -- `value` - api value (should be an error reference) +- `value` - api value (should be an exception) - return value - - true, if the vm throw callback captured the error + - true, if the vm throw callback captured the exception - false, otherwise *New in version [[NEXT_RELEASE]]*. @@ -4061,7 +3990,7 @@ bool jerry_error_is_throw_captured (jerry_value_t value); #include "jerryscript.h" static void -vm_throw_callback (const jerry_value_t error_value, /**< captured error */ +vm_throw_callback (const jerry_value_t error_value, /**< captured exception */ void *user_p) /**< user pointer */ { (void) error_value; @@ -4074,17 +4003,17 @@ main (void) jerry_init (JERRY_INIT_EMPTY); int counter = 0; - jerry_set_vm_throw_callback (vm_throw_callback, &counter); + jerry_on_throw (vm_throw_callback, &counter); const jerry_char_t script[] = "throw new Error()"; jerry_value_t result_value = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); - if (jerry_error_is_throw_captured (result_value)) + if (jerry_exception_is_captured (result_value)) { /* Code enters here, because the vm_throw_callback function is called. */ } - jerry_release_value (result_value); + jerry_value_free (result_value); jerry_cleanup (); return 0; @@ -4093,28 +4022,28 @@ main (void) **See also** -- [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback) -- [jerry_error_set_throw_capture](#jerry_error_set_throw_capture) +- [jerry_on_throw](#jerry_on_throw) +- [jerry_exception_allow_capture](#jerry_exception_allow_capture) -## jerry_error_set_throw_capture +## jerry_exception_allow_capture **Summary** -Sets whether the callback set by [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback) -should capture the error or not. +Sets whether the callback set by [jerry_on_throw](#jerry_on_throw) +should capture the exception or not. *Notes*: - This API depends on a build option (`JERRY_VM_THROW`) and can be checked in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -void jerry_error_set_throw_capture (jerry_value_t value, bool should_capture); +void jerry_exception_allow_capture (jerry_value_t value, bool should_capture); ``` -- `value` - api value (should be an error reference) +- `value` - api value (should be an exception) - `should_capture` - callback should capture this error *New in version [[NEXT_RELEASE]]*. @@ -4127,7 +4056,7 @@ void jerry_error_set_throw_capture (jerry_value_t value, bool should_capture); #include "jerryscript.h" static void -vm_throw_callback (const jerry_value_t error_value, /**< captured error */ +vm_throw_callback (const jerry_value_t error_value, /**< captured exception */ void *user_p) /**< user pointer */ { (void) error_value; @@ -4143,10 +4072,10 @@ throw_exception (const jerry_call_info_t *call_info_p, /**< call info */ (void) argv; (void) argc; - jerry_value_t result_value = jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Error!"); + jerry_value_t result_value = jerry_throw_sz (JERRY_ERROR_COMMON, "Error!"); /* Ignore calling the vm_throw_callback function. */ - jerry_error_set_throw_capture (result_value, false); + jerry_exception_allow_capture (result_value, false); return result_value; } @@ -4156,19 +4085,19 @@ main (void) jerry_init (JERRY_INIT_EMPTY); int counter = 0; - jerry_set_vm_throw_callback (vm_throw_callback, &counter); + jerry_on_throw (vm_throw_callback, &counter); - jerry_value_t global_object_value = jerry_get_global_object (); - jerry_value_t function_value = jerry_create_external_function (throw_exception); - jerry_value_t function_name_value = jerry_create_string ((const jerry_char_t *) "throw_exception"); + jerry_value_t global_object_value = jerry_current_realm (); + jerry_value_t function_value = jerry_function_external (throw_exception); + jerry_value_t function_name_value = jerry_string_sz ("throw_exception"); - jerry_release_value (jerry_set_property (global_object_value, function_name_value, function_value)); - jerry_release_value (function_name_value); - jerry_release_value (function_value); - jerry_release_value (global_object_value); + jerry_value_free (jerry_object_set (global_object_value, function_name_value, function_value)); + jerry_value_free (function_name_value); + jerry_value_free (function_value); + jerry_value_free (global_object_value); const jerry_char_t script[] = "throw_exception()"; - jerry_release_value (jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS)); + jerry_value_free (jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS)); jerry_cleanup (); return 0; @@ -4177,15 +4106,15 @@ main (void) **See also** -- [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback) -- [jerry_error_is_throw_captured](#jerry_error_is_throw_captured) +- [jerry_on_throw](#jerry_on_throw) +- [jerry_exception_is_captured](#jerry_exception_is_captured) # Getter functions of 'jerry_value_t' Get raw data from API values. -## jerry_get_number_value +## jerry_value_as_number **Summary** @@ -4197,7 +4126,7 @@ If the argument passed is not a number `0.0` will be returned. ```c double -jerry_get_number_value (const jerry_value_t value); +jerry_value_as_number (const jerry_value_t value); ``` - `value` - api value @@ -4210,29 +4139,29 @@ jerry_get_number_value (const jerry_value_t value); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value if (jerry_value_is_number (value)) { - double raw_value = jerry_get_number_value (value); + double raw_value = jerry_value_as_number (value); ... // usage of raw value } - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** - [jerry_value_is_number](#jerry_value_is_number) -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) # Functions for string values -## jerry_get_string_size +## jerry_string_size **Summary** @@ -4243,7 +4172,7 @@ This is effectively the number of bytes required to store the string's character ```c jerry_size_t -jerry_get_string_size (const jerry_value_t value); +jerry_string_size (const jerry_value_t value, JERRY_ENCODING_CESU8); ``` - `value` - api value - return value - number of bytes in the buffer needed to represent the string. @@ -4252,75 +4181,32 @@ jerry_get_string_size (const jerry_value_t value); ```c { - const jerry_char_t char_array[] = "a string"; - jerry_value_t string = jerry_create_string (char_array); + const char char_array[] = "a string"; + jerry_value_t string = jerry_string_sz (char_array); - jerry_size_t string_size = jerry_get_string_size (string); + jerry_size_t string_size = jerry_string_size (string, JERRY_ENCODING_CESU8); ... // usage of string_size - jerry_release_value (string); + jerry_value_free (string); } ``` **See also** -- [jerry_create_string](#jerry_create_string) -- [jerry_get_string_length](#jerry_get_string_length) -- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) +- [jerry_string_sz](#jerry_string_sz) +- [jerry_string_length](#jerry_string_length) +- [jerry_validate_string](#jerry_validate_string) -## jerry_get_utf8_string_size - -**Summary** - -Get the size of an utf8-encoded string. Returns zero, if the value parameter is not a string. -This is effectively the number of bytes required to store the utf8 encoded string's characters. - -*Note*: The difference from [jerry_get_string_size](#jerry_get_string_size) is that it returns with utf-8 string size -instead of the cesu-8 string size. - -**Prototype** - -```c -jerry_size_t -jerry_get_utf8_string_size (const jerry_value_t value); -``` -- `value` - api value -- return value - number of bytes in the buffer needed to represent the utf8-encoded string. - -*New in version 2.0*. - -**Example** - -```c -{ - const jerry_char_t char_array[] = "a string"; - jerry_value_t string = jerry_create_string (char_array); - - jerry_size_t string_size = jerry_get_utf8_string_size (string); - - ... // usage of string_size - - jerry_release_value (string); -} -``` - -**See also** - -- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) -- [jerry_get_utf8_string_length](#jerry_get_utf8_string_length) -- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) - - -## jerry_get_string_length +## jerry_string_length **Summary** Get the length of a string. Returns zero, if the value parameter is not a string. *Notes:* -- The difference from [jerry_get_string_size](#jerry_get_string_size) is that it +- The difference from [jerry_string_size](#jerry_string_size) is that it returns the number of bytes used for the string. - This is **not** the number of bytes required to store the string. @@ -4328,7 +4214,7 @@ Get the length of a string. Returns zero, if the value parameter is not a string ```c jerry_length_t -jerry_get_string_length (const jerry_value_t value); +jerry_string_length (const jerry_value_t value); ``` - `value` - api value @@ -4338,100 +4224,54 @@ jerry_get_string_length (const jerry_value_t value); ```c { - const jerry_char_t char_array[] = "a string"; - jerry_value_t string = jerry_create_string (char_array); + const char char_array[] = "a string"; + jerry_value_t string = jerry_string_sz (char_array); - jerry_length_t string_length = jerry_get_string_length (string); + jerry_length_t string_length = jerry_string_length (string); ... // usage of string_length - jerry_release_value (string); + jerry_value_free (string); } ``` **See also** -- [jerry_create_string](#jerry_create_string) -- [jerry_get_string_size](#jerry_get_string_size) -- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) +- [jerry_string_sz](#jerry_string_sz) +- [jerry_string_size](#jerry_string_size) +- [jerry_validate_string](#jerry_validate_string) -## jerry_get_utf8_string_length - -**Summary** - -Get the length of an UTF-8 encoded string. Returns zero, if the value parameter is not a string. - -*Notes*: -- The difference from [jerry_get_string_length](#jerry_get_string_length) is that it - returns with utf-8 string length instead of the cesu-8 string length. -- This is **not** the number of bytes required to store the string. - -**Prototype** - -```c -jerry_length_t -jerry_get_utf8_string_length (const jerry_value_t value); -``` - -- `value` - input string value -- return value - number of characters in the string - -*New in version 2.0*. - -**Example** - -```c -{ - const jerry_char_t char_array[] = "a string"; - jerry_value_t string = jerry_create_string_from_utf8 (char_array); - - jerry_length_t string_length = jerry_get_utf8_string_length (string); - - ... // usage of string_length - - jerry_release_value (string); -} -``` - -**See also** - -- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) -- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size) -- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) - - -## jerry_string_to_char_buffer +## jerry_string_to_buffer **Summary** Copy the characters of a string into a specified cesu-8 buffer. The '\0' character could occur in the character buffer. Returns 0, -if the value parameter is not a string or the buffer is not large -enough for the whole string. +if the input value is not a string. *Note*: Does not put '\0' to the end of string, the return value identifies the number of valid bytes in the output buffer. -*Note*: If the size of the string in jerry value is larger than the size of the -target buffer, the copy will fail. To copy a substring the -[jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer) API function -is recommended instead. +*Note*: If the size of the string is larger than the size of the +target buffer, the string will be cropped. **Prototype** ```c jerry_size_t -jerry_string_to_char_buffer (const jerry_value_t value, - jerry_char_t *buffer_p, - jerry_size_t buffer_size); +jerry_string_to_buffer (const jerry_value_t value, + jerry_encoding_t encoding, + jerry_char_t *buffer_p, + jerry_size_t buffer_size); ``` - `value` - input string value +- `encoding` - encoding oh the string data - `buffer_p` - pointer to output buffer - `buffer_size` - size of the buffer -- return value - number of bytes, actually copied to the buffer +- return value - number of bytes copied to the buffer **Example** @@ -4448,17 +4288,17 @@ main (void) jerry_init (JERRY_INIT_EMPTY); jerry_value_t value; - // create or acquire value - value = jerry_create_string ((const jerry_char_t *) "Demo string"); + // create or copy value + value = jerry_string_sz ("Demo string"); // Read the string into a byte buffer. - jerry_size_t string_size = jerry_get_string_size (value); + jerry_size_t string_size = jerry_string_size (value, JERRY_ENCODING_CESU8); jerry_char_t *string_buffer_p = (jerry_char_t *) malloc (sizeof (jerry_char_t) * (string_size + 1)); - jerry_size_t copied_bytes = jerry_string_to_char_buffer (value, string_buffer_p, string_size); + jerry_size_t copied_bytes = jerry_string_to_buffer (value, JERRY_ENCODING_CESU8, string_buffer_p, string_size); string_buffer_p[copied_bytes] = '\0'; - jerry_release_value (value); + jerry_value_free (value); jerry_cleanup (); @@ -4471,188 +4311,12 @@ main (void) **See also** -- [jerry_create_string](#jerry_create_string) -- [jerry_get_string_size](#jerry_get_string_size) -- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) -- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer) - - -## jerry_string_to_utf8_char_buffer - -**Summary** - -Copy the characters of a string into a specified utf-8 buffer. -The '\0' character could occur in character buffer. Returns 0, -if the value parameter is not a string or the buffer is not -large enough for the whole string. - -*Note*: Does not put '\0' to the end of string, the return value identifies -the number of valid bytes in the output buffer. - -*Note*: If the size of the string in jerry value is larger than the size of the -target buffer, the copy will fail. To copy a substring the -[jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer) -API function is recommended instead. - -**Prototype** - -```c -jerry_size_t -jerry_string_to_utf8_char_buffer (const jerry_value_t value, - jerry_char_t *buffer_p, - jerry_size_t buffer_size); -``` - -- `value` - input string value -- `buffer_p` - pointer to output buffer -- `buffer_size` - size of the buffer -- return value - number of bytes, actually copied to the buffer - -*New in version 2.0*. - -**Example** - -```c -{ - jerry_value_t value; - ... // create or acquire value - - jerry_size_t req_sz = jerry_get_utf8_string_size (value); - jerry_char_t str_buf_p[req_sz]; - - jerry_size_t bytes_copied = jerry_string_to_utf8_char_buffer (value, str_buf_p, req_sz); - - jerry_release_value (value); -} -``` - -**See also** - -- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) -- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size) -- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) -- [jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer) +- [jerry_string_sz](#jerry_string_sz) +- [jerry_string_size](#jerry_string_size) +- [jerry_strig_to_buffer](#jerry_strig_to_buffer) -## jerry_substring_to_char_buffer - -**Summary** - -Copy the characters of a cesu-8 encoded substring into a specified buffer. -The '\0' character could occur in character buffer. Returns 0, if the value -parameter is not a string. It will extract the substring between the -specified start position and the end position (or the end of the string, -whichever comes first). - -*Note*: Does not put '\0' to the end of string, the return value identifies -the number of valid bytes in the output buffer. - -**Prototype** - -```c -jerry_size_t -jerry_substring_to_char_buffer (const jerry_value_t value, - jerry_length_t start_pos, - jerry_length_t end_pos, - jerry_char_t *buffer_p, - jerry_size_t buffer_size); -``` - -- `value` - input string value -- `start_pos` - position of the first character -- `end_pos` - position of the last character -- `buffer_p` - pointer to output buffer -- `buffer_size` - size of the buffer -- return value - number of bytes, actually copied to the buffer - -*New in version 2.0*. - -**Example** - -```c -{ - jerry_value_t value; - ... // create or acquire value - - jerry_size_t req_sz = jerry_get_string_size (value); - jerry_char_t str_buf_p[req_sz]; - jerry_length_t start_pos = 0; - jerry_length_t end_pos = jerry_get_string_length (value); - - jerry_substring_to_char_buffer (value, start_pos, end_pos, str_buf_p, req_sz); - - jerry_release_value (value); -} -``` - -**See also** - -- [jerry_create_string](#jerry_create_string) -- [jerry_get_string_size](#jerry_get_string_size) -- [jerry_get_string_length](#jerry_get_string_length) -- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) - - -## jerry_substring_to_utf8_char_buffer - -**Summary** - -Copy the characters of an utf-8 encoded substring into a specified buffer. -The '\0' character could occur in character buffer. Returns 0, if the value -parameter is not a string. It will extract the substring between the specified -start position and the end position (or the end of the string, whichever -comes first). - -*Note*: Does not put '\0' to the end of string, the return value identifies -the number of valid bytes in the output buffer. - -**Prototype** - -```c -jerry_size_t -jerry_substring_to_utf8_char_buffer (const jerry_value_t value, - jerry_length_t start_pos, - jerry_length_t end_pos, - jerry_char_t *buffer_p, - jerry_size_t buffer_size); -``` - -- `value` - input string value -- `start_pos` - position of the first character -- `end_pos` - position of the last character -- `buffer_p` - pointer to output buffer -- `buffer_size` - size of the buffer -- return value - number of bytes, actually copied to the buffer - -*New in version 2.0*. - -**Example** - -```c -{ - jerry_value_t value; - ... // create or acquire value - - jerry_size_t req_sz = jerry_get_utf8_string_size (value); - jerry_char_t str_buf_p[req_sz]; - jerry_length_t start_pos = 0; - jerry_length_t end_pos = jerry_get_utf8_string_length (value); - - jerry_substring_to_utf8_char_buffer (value, start_pos, end_pos, str_buf_p, req_sz); - - jerry_release_value (value); -} -``` - -**See also** - -- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) -- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size) -- [jerry_get_utf8_string_length](#jerry_get_utf8_string_length) -- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) - - -# jerry_string_set_external_free_callback +# jerry_string_external_on_free **Summary** @@ -4669,7 +4333,7 @@ first external string is created. **Prototype** ```c -void jerry_string_set_external_free_callback (jerry_external_string_free_callback_t callback_p); +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. @@ -4697,12 +4361,12 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_string_set_external_free_callback (external_string_free_callback); + jerry_string_external_on_free (external_string_free_callback); const char *string_p = "This is a long external string, should not be duplicated!"; - jerry_value_t external_string = jerry_create_external_string ((jerry_char_t *) string_p, NULL); + jerry_value_t external_string = jerry_string_external_sz (string_p, NULL); /* The external_string_free_callback is called. */ - jerry_release_value (external_string); + jerry_value_free (external_string); jerry_cleanup (); return 0; @@ -4711,13 +4375,13 @@ main (void) **See also** -- [jerry_external_string_free_callback_t](#jerry_external_string_free_callback_t) -- [jerry_string_get_external_user_pointer](#jerry_string_get_external_user_pointer) -- [jerry_create_external_string](#jerry_create_external_string) -- [jerry_create_external_string_sz](#jerry_create_external_string_sz) +- [jerry_external_string_free_cb_t](#jerry_external_string_free_cb_t) +- [jerry_string_user_ptr](#jerry_string_user_ptr) +- [jerry_string_external_sz](#jerry_string_external_sz) +- [jerry_string_external](#jerry_string_external) -# jerry_string_get_external_user_pointer +# jerry_string_user_ptr **Summary** @@ -4727,13 +4391,13 @@ Returns the user pointer assigned to an external string. - In some cases (e.g. when the string is also a magic string registered by [jerry_register_magic_strings](#jerry_register_magic_strings)), the string is a normal string without a user pointer even if it is created - by [jerry_create_external_string](#jerry_create_external_string). + by [jerry_string_external_sz](#jerry_string_external_sz). **Prototype** ```c -void *jerry_string_get_external_user_pointer (const jerry_value_t value, - bool *is_external); +void *jerry_string_user_ptr (const jerry_value_t value, + bool *is_external); ``` - `value` - string value. @@ -4762,10 +4426,10 @@ main (void) const char *string_p = "This is a long external string, should not be duplicated!"; - jerry_value_t external_string = jerry_create_external_string ((jerry_char_t *) string_p, (void *) &user_value); + jerry_value_t external_string = jerry_string_external_sz (string_p, (void *) &user_value); bool is_external; - void *user_p = jerry_string_get_external_user_pointer (external_string, &is_external); + void *user_p = jerry_string_user_ptr (external_string, &is_external); if (is_external) { @@ -4773,7 +4437,7 @@ main (void) printf("User pointer of an external string: %p\n", user_p); } - jerry_release_value (external_string); + jerry_value_free (external_string); jerry_cleanup (); return 0; @@ -4783,13 +4447,13 @@ main (void) **See also** - [jerry_string_set_external_string_free_callback](#jerry_string_set_external_string_free_callback) -- [jerry_create_external_string](#jerry_create_external_string) -- [jerry_create_external_string_sz](#jerry_create_external_string_sz) +- [jerry_string_external_sz](#jerry_string_external_sz) +- [jerry_string_external](#jerry_string_external) # Functions for array object values -## jerry_get_array_length +## jerry_array_length **Summary** @@ -4799,7 +4463,7 @@ Get length of an array object. Returns zero, if the given parameter is not an ar ```c uint32_t -jerry_get_array_length (const jerry_value_t value); +jerry_array_length (const jerry_value_t value); ``` - `value` - input array value @@ -4810,17 +4474,17 @@ jerry_get_array_length (const jerry_value_t value); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value - uint32_t len = jerry_get_array_length (value); + uint32_t len = jerry_array_length (value); - jerry_release_value (value); + jerry_value_free (value); } ``` **See also** -- [jerry_create_array](#jerry_create_array) +- [jerry_array](#jerry_array) # Converters of 'jerry_value_t' @@ -4850,11 +4514,11 @@ jerry_value_to_boolean (const jerry_value_t value); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value bool b = jerry_value_to_boolean (value); - jerry_release_value (value); + jerry_value_free (value); } ``` @@ -4869,7 +4533,7 @@ jerry_value_to_boolean (const jerry_value_t value); Call ToNumber operation on the api value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -4882,19 +4546,19 @@ jerry_value_to_number (const jerry_value_t value); - `value` - api value - return value - converted number value, if success - - thrown error, otherwise + - thrown exception, otherwise **Example** ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value jerry_value_t number_value = jerry_value_to_number (value); - jerry_release_value (number_value); - jerry_release_value (value); + jerry_value_free (number_value); + jerry_value_free (value); } ``` @@ -4909,7 +4573,7 @@ jerry_value_to_number (const jerry_value_t value); Call ToObject operation on the api value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -4922,19 +4586,19 @@ jerry_value_to_object (const jerry_value_t value); - `value` - api value - return value - converted object value, if success - - thrown error, otherwise + - thrown exception, otherwise **Example** ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value jerry_value_t object_value = jerry_value_to_object (value); - jerry_release_value (object_value); - jerry_release_value (value); + jerry_value_free (object_value); + jerry_value_free (value); } ``` @@ -4948,7 +4612,7 @@ jerry_value_to_object (const jerry_value_t value); Call ToPrimitive operation on the api value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -4961,19 +4625,19 @@ jerry_value_to_primitive (const jerry_value_t value); - `value` - api value - return value - converted primitive value, if success - - thrown error, otherwise + - thrown exception, otherwise **Example** ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value jerry_value_t prim_value = jerry_value_to_primitive (value); - jerry_release_value (prim_value); - jerry_release_value (value); + jerry_value_free (prim_value); + jerry_value_free (value); } ``` @@ -4987,7 +4651,7 @@ jerry_value_to_primitive (const jerry_value_t value); Call the ToString ecma builtin operation on the api value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -5000,19 +4664,19 @@ jerry_value_to_string (const jerry_value_t value); - `value` - api value - return value - converted string value, if success - - thrown error, otherwise + - thrown exception, otherwise **Example** ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value jerry_value_t string_value = jerry_value_to_string (value); - jerry_release_value (string_value); - jerry_release_value (value); + jerry_value_free (string_value); + jerry_value_free (value); } ``` @@ -5027,7 +4691,7 @@ jerry_value_to_string (const jerry_value_t value); Call the BigInt constructor ecma builtin operation on the api value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -5040,7 +4704,7 @@ jerry_value_to_bigint (const jerry_value_t value); - `value` - api value - return value - converted BigInt value, if success - - thrown error, otherwise + - thrown exception, otherwise *New in version 2.4*. @@ -5049,20 +4713,20 @@ jerry_value_to_bigint (const jerry_value_t value); ```c { jerry_value_t value; - ... // create or acquire value + ... // create or copy value jerry_value_t bigint_value = jerry_value_to_bigint (value); - jerry_release_value (bigint_value); - jerry_release_value (value); + jerry_value_free (bigint_value); + jerry_value_free (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) - [jerry_value_is_bigint](#jerry_value_is_bigint) -- [jerry_get_bigint_digits](#jerry_get_bigint_digits) +- [jerry_bigint_to_digits](#jerry_bigint_to_digits) ## jerry_value_as_integer @@ -5089,9 +4753,9 @@ jerry_value_as_integer (const jerry_value_t value); ```c { - jerry_value_t number_val = jerry_create_number (123321); + jerry_value_t number_val = jerry_number (123321); double number = jerry_value_as_integer (number_val); - jerry_release_value (number_val); + jerry_value_free (number_val); } ``` @@ -5120,9 +4784,9 @@ jerry_value_as_int32 (const jerry_value_t value); ```c { - jerry_value_t number_val = jerry_create_number (123321); + jerry_value_t number_val = jerry_number (123321); int32_t number = jerry_value_as_int32 (number_val); - jerry_release_value (number_val); + jerry_value_free (number_val); } ``` @@ -5151,9 +4815,9 @@ jerry_value_as_uint32 (const jerry_value_t value); ```c { - jerry_value_t number_val = jerry_create_number (123321); + jerry_value_t number_val = jerry_number (123321); uint32_t number = jerry_value_as_uint32 (number_val); - jerry_release_value (number_val); + jerry_value_free (number_val); } ``` @@ -5168,17 +4832,17 @@ These APIs all depend on module support. Link modules to their dependencies. The dependencies are resolved by a user callback. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- 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_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c jerry_value_t jerry_module_link (const jerry_value_t module_val, - jerry_module_resolve_callback_t callback, void *user_p) + jerry_module_resolve_cb_t callback, void *user_p) ``` - `module_val` - module object in unlinked state @@ -5187,7 +4851,7 @@ jerry_value_t jerry_module_link (const jerry_value_t module_val, - `user_p` - user pointer passed to the callback - return - true - if linking is successful - - error - otherwise + - exception - otherwise *New in version [[NEXT_RELEASE]]*. @@ -5212,11 +4876,11 @@ module_resolve_callback (const jerry_value_t specifier, const jerry_char_t script[] = "export var a = 5"; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "b.mjs"); + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("b.mjs"); jerry_value_t result = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); return result; } /* module_resolve_callback */ @@ -5228,15 +4892,15 @@ main (void) const jerry_char_t script[] = "import a from 'b.mjs'"; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs"); + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("a.mjs"); jerry_value_t ret_value = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); jerry_module_link (ret_value, module_resolve_callback, NULL); - jerry_release_value (ret_value); + jerry_value_free (ret_value); jerry_cleanup (); return 0; @@ -5244,18 +4908,18 @@ main (void) ``` **See also** -- [jerry_module_resolve_callback_t](#jerry_module_resolve_callback_t) +- [jerry_module_resolve_cb_t](#jerry_module_resolve_cb_t) ## jerry_module_evaluate Evaluate a module and its dependencies. The module must be in linked state. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- 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_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** @@ -5266,7 +4930,7 @@ jerry_value_t jerry_module_evaluate (const jerry_value_t module_val); - `module_val` - module object - return - result of module bytecode execution - if evaluation was successful - - error, otherwise + - exception, otherwise *New in version [[NEXT_RELEASE]]*. @@ -5286,16 +4950,16 @@ main (void) const jerry_char_t script[] = "export var a = 6"; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs"); + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("a.mjs"); jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); - jerry_release_value (jerry_module_link (module_value, NULL, NULL)); - jerry_release_value (jerry_module_evaluate (module_value)); + jerry_value_free (jerry_module_link (module_value, NULL, NULL)); + jerry_value_free (jerry_module_evaluate (module_value)); - jerry_release_value (module_value); + jerry_value_free (module_value); jerry_cleanup (); return 0; @@ -5306,7 +4970,7 @@ main (void) - [jerry_module_link](#jerry_module_link) -## jerry_module_get_state +## jerry_module_state **Summary** @@ -5316,12 +4980,12 @@ are listed in [jerry_module_state_t](#jerry_module_state_t) *Notes*: - This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -jerry_module_state_t jerry_module_get_state (const jerry_value_t module_val); +jerry_module_state_t jerry_module_state (const jerry_value_t module_val); ``` - `module_val` - module object @@ -5347,18 +5011,18 @@ main (void) const jerry_char_t script[] = "import a from 'b.mjs'"; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs"); + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("a.mjs"); jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); - if (jerry_module_get_state (module_value) == JERRY_MODULE_STATE_UNLINKED) + if (jerry_module_state (module_value) == JERRY_MODULE_STATE_UNLINKED) { printf ("Module parsing has been successful\n"); } - jerry_release_value (module_value); + jerry_value_free (module_value); jerry_cleanup (); return 0; @@ -5369,7 +5033,7 @@ main (void) - [jerry_module_state_t](#jerry_module_state_t) -## jerry_module_set_state_changed_callback +## jerry_module_on_state_changed **Summary** @@ -5378,13 +5042,13 @@ Sets a callback which is called after a module state is changed to linked, evalu *Notes*: - This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -void jerry_module_set_state_changed_callback (jerry_module_state_changed_callback_t callback, - void *user_p); +void jerry_module_on_state_changed (jerry_module_state_changed_cb_t callback, + void *user_p); ``` - `callback` - callback, which is called after the state change. @@ -5423,18 +5087,18 @@ main (void) const jerry_char_t script[] = "12"; - jerry_module_set_state_changed_callback (module_state_changed, NULL); + jerry_module_on_state_changed (module_state_changed, NULL); jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs"); + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("a.mjs"); jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); - jerry_release_value (jerry_module_link (module_value, NULL, NULL)); + jerry_value_free (jerry_module_link (module_value, NULL, NULL)); - jerry_release_value (module_value); + jerry_value_free (module_value); jerry_cleanup (); return 0; @@ -5444,9 +5108,9 @@ main (void) **See also** - [jerry_module_state_t](#jerry_module_state_t) -- [jerry_module_state_changed_callback_t](#jerry_module_state_changed_callback_t) +- [jerry_module_state_changed_cb_t](#jerry_module_state_changed_cb_t) -## jerry_module_set_import_meta_callback +## jerry_module_on_import_meta **Summary** @@ -5455,13 +5119,13 @@ Sets a callback which is called when an import.meta expression of a module is ev *Notes*: - This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -void jerry_module_set_import_meta_callback (jerry_module_import_meta_callback_t callback, - void *user_p); +void jerry_module_on_import_meta (jerry_module_import_meta_cb_t callback, + void *user_p); ``` - `callback` - callback, which is called when an import.meta @@ -5486,12 +5150,12 @@ module_import_meta_callback (const jerry_value_t module, /**< module */ (void) user_p; /* Create a property for the meta object */ - jerry_value_t property_name_value = jerry_create_string ((const jerry_char_t *) "prop"); - jerry_value_t property_value = jerry_create_string ((const jerry_char_t *) "prop"); - jerry_value_t result_value = jerry_set_property (meta_object, property_name_value, property_value); - jerry_release_value (result_value); - jerry_release_value (property_value); - jerry_release_value (property_name_value); + jerry_value_t property_name_value = jerry_string_sz ("prop"); + jerry_value_t property_value = jerry_string_sz ("prop"); + jerry_value_t result_value = jerry_object_set (meta_object, property_name_value, property_value); + jerry_value_free (result_value); + jerry_value_free (property_value); + jerry_value_free (property_name_value); } /* module_import_meta_callback */ int @@ -5501,17 +5165,17 @@ main (void) const jerry_char_t script[] = "import.meta"; - jerry_module_set_import_meta_callback (module_import_meta_callback, NULL); + jerry_module_on_import_meta (module_import_meta_callback, NULL); jerry_parse_options_t parse_options; parse_options.options = JERRY_PARSE_MODULE; jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (jerry_module_link (module_value, NULL, NULL)); - jerry_release_value (jerry_module_evaluate (module_value)); + jerry_value_free (jerry_module_link (module_value, NULL, NULL)); + jerry_value_free (jerry_module_evaluate (module_value)); - jerry_release_value (module_value); + jerry_value_free (module_value); jerry_cleanup (); return 0; @@ -5520,25 +5184,25 @@ main (void) **See also** -- [jerry_module_import_meta_callback_t](#jerry_module_import_meta_callback_t) +- [jerry_module_import_meta_cb_t](#jerry_module_import_meta_cb_t) -## jerry_module_get_number_of_requests +## jerry_module_request_count **Summary** Returns the number of import/export requests of a module. -The requests can be queried by [jerry_module_get_request](#jerry_module_get_request). +The requests can be queried by [jerry_module_request](#jerry_module_request). *Notes*: - This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -size_t jerry_module_get_number_of_requests (const jerry_value_t module_val); +size_t jerry_module_request_count (const jerry_value_t module_val); ``` - `module_val` - module object @@ -5565,16 +5229,16 @@ main (void) "import a from 'c.mjs'"; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs"); + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("a.mjs"); jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); /* Prints 2. */ - printf ("Number of requests: %d\n", (int) jerry_module_get_number_of_requests (module_value)); + printf ("Number of requests: %d\n", (int) jerry_module_request_count (module_value)); - jerry_release_value (module_value); + jerry_value_free (module_value); jerry_cleanup (); return 0; @@ -5583,11 +5247,11 @@ main (void) **See also** -- [jerry_module_get_request](#jerry_module_get_request) +- [jerry_module_request](#jerry_module_request) - [jerry_parse](#jerry_parse) - [jerry_module_link](#jerry_module_link) -## jerry_module_get_request +## jerry_module_request **Summary** @@ -5597,26 +5261,26 @@ are strings. If [jerry_module_link](#jerry_module_link) is completed successfull all returned values are module objects instead. If linking is in progress or fails, the successfully resolved dependencies are module objects, the rest are strings. The number of requests can be queried by -[jerry_module_get_number_of_requests](#jerry_module_get_number_of_requests). +[jerry_module_request_count](#jerry_module_request_count). *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- 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_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -jerry_value_t jerry_module_get_request (const jerry_value_t module_val, size_t request_index); +jerry_value_t jerry_module_request (const jerry_value_t module_val, size_t request_index); ``` - `module_val` - module object - return - string, if the request has not been resolved yet - module object, if the request has been resolved successfully - - error, otherwise + - exception, otherwise *New in version [[NEXT_RELEASE]]*. @@ -5637,21 +5301,21 @@ main (void) const jerry_char_t file[] = "a.mjs"; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs"); + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("a.mjs"); jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); - jerry_value_t request_value = jerry_module_get_request (module_value, 0); + jerry_value_t request_value = jerry_module_request (module_value, 0); /* Returns with b.mjs */ - jerry_release_value (request_value); + jerry_value_free (request_value); - request_value = jerry_module_get_request (module_value, 1); + request_value = jerry_module_request (module_value, 1); /* Returns with c.mjs */ - jerry_release_value (request_value); + jerry_value_free (request_value); - jerry_release_value (module_value); + jerry_value_free (module_value); jerry_cleanup (); return 0; @@ -5660,31 +5324,31 @@ main (void) **See also** -- [jerry_module_get_number_of_requests](#jerry_module_get_number_of_requests) +- [jerry_module_request_count](#jerry_module_request_count) - [jerry_parse](#jerry_parse) - [jerry_module_link](#jerry_module_link) -## jerry_module_get_namespace +## jerry_module_namespace Returns the namespace object of a module *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- 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_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -jerry_value_t jerry_module_get_namespace (const jerry_value_t module_val); +jerry_value_t jerry_module_namespace (const jerry_value_t module_val); ``` - `module_val` - module object - return - object, if namespace object is available - - error, otherwise + - exception, otherwise *New in version [[NEXT_RELEASE]]*. @@ -5704,21 +5368,21 @@ main (void) const jerry_char_t script[] = "export var a = 6"; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs"); + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("a.mjs"); jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); - jerry_release_value (jerry_module_link (module_value, NULL, NULL)); - jerry_release_value (jerry_module_evaluate (module_value)); + jerry_value_free (jerry_module_link (module_value, NULL, NULL)); + jerry_value_free (jerry_module_evaluate (module_value)); - jerry_value_t namespace_value = jerry_module_get_namespace (module_value); + jerry_value_t namespace_value = jerry_module_namespace (module_value); /* Exports can be checked. */ - jerry_release_value (namespace_value); - jerry_release_value (module_value); + jerry_value_free (namespace_value); + jerry_value_free (module_value); jerry_cleanup (); return 0; @@ -5730,7 +5394,7 @@ main (void) - [jerry_module_link](#jerry_module_link) - [jerry_module_evaluate](#jerry_module_evaluate) -## jerry_module_set_import_callback +## jerry_module_on_import Sets the callback which is called when dynamic imports are resolved. The resolver receives the `user_value` assigned to the currently executed script, which should @@ -5739,19 +5403,19 @@ provide all the information that is necessary for the resolve. *Notes*: - This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The possible return values of the callback is explained - in [jerry_module_import_callback_t](#jerry_module_import_callback_t) + in [jerry_module_import_cb_t](#jerry_module_import_cb_t) **Prototype** ```c void -jerry_module_set_import_callback (jerry_module_import_callback_t callback_p, - void *user_p) +jerry_module_on_import (jerry_module_import_cb_t callback_p, + void *user_p) ``` -- `callback_p` - a [jerry_module_import_callback_t](#jerry_module_import_callback_t) callback which handles `import()` calls +- `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]]*. @@ -5781,12 +5445,12 @@ resolve_dynamic (const jerry_value_t specifier, /**< module specifier */ /* This very simple command queue supports only one task. */ resolve_module_task_t *task_p = (resolve_module_task_t *) user_p; - task_p->specifier = jerry_acquire_value (specifier); - task_p->user_value = jerry_acquire_value (user_value); + task_p->specifier = jerry_value_copy (specifier); + task_p->user_value = jerry_value_copy (user_value); /* This Promise should be evaluated later. */ - jerry_value_t promise = jerry_create_promise (); - task_p->promise = jerry_acquire_value (promise); + jerry_value_t promise = jerry_promise (); + task_p->promise = jerry_value_copy (promise); return promise; } @@ -5796,7 +5460,7 @@ main (void) jerry_init (JERRY_INIT_EMPTY); resolve_module_task_t task; - jerry_module_set_import_callback (resolve_dynamic, &task); + jerry_module_on_import (resolve_dynamic, &task); const jerry_char_t script[] = "import('modules/my_module.mjs').then(\n" " function (namespace) { /* use namespace */},\n" @@ -5804,47 +5468,47 @@ main (void) ")"; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_HAS_RESOURCE | JERRY_PARSE_HAS_USER_VALUE; + parse_options.options = JERRY_PARSE_HAS_SOURCE_NAME | JERRY_PARSE_HAS_USER_VALUE; /* Resource is usually used for debugging purposes, e.g. for generating backtrace. */ - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "dir/my_script.js"); + parse_options.source_name = jerry_string_sz ("dir/my_script.js"); /* User value should provide information for resolving dynamic imports. * In this case it contains the full path excluding the filename. */ - parse_options.user_value = jerry_create_string ((const jerry_char_t *) "/home/user/dir"); + parse_options.user_value = jerry_string_sz ("/home/user/dir"); jerry_value_t script_value = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); - jerry_release_value (parse_options.user_value); - jerry_release_value (jerry_run (script_value)); - jerry_release_value (script_value); + jerry_value_free (parse_options.source_name); + jerry_value_free (parse_options.user_value); + jerry_value_free (jerry_run (script_value)); + jerry_value_free (script_value); /* The application resolves both the module and the promise using the specifier * and the user_value. In this example the specifier is modules/my_module.mjs. */ const jerry_char_t module_script[] = "export var a = 5"; - parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE | JERRY_PARSE_HAS_USER_VALUE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "modules/my_module.mjs"); - parse_options.user_value = jerry_create_string ((const jerry_char_t *) "/home/user/dir/modules"); + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_SOURCE_NAME | JERRY_PARSE_HAS_USER_VALUE; + parse_options.source_name = jerry_string_sz ("modules/my_module.mjs"); + parse_options.user_value = jerry_string_sz ("/home/user/dir/modules"); jerry_value_t module_value = jerry_parse (module_script, sizeof (module_script) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); - jerry_release_value (parse_options.user_value); - jerry_release_value (jerry_module_link (module_value, NULL, NULL)); - jerry_release_value (jerry_module_evaluate (module_value)); + jerry_value_free (parse_options.source_name); + jerry_value_free (parse_options.user_value); + jerry_value_free (jerry_module_link (module_value, NULL, NULL)); + jerry_value_free (jerry_module_evaluate (module_value)); /* The promise must be resolved with the namespace object, not the module. */ - jerry_value_t namespace_value = jerry_module_get_namespace (module_value); - jerry_release_value (jerry_resolve_or_reject_promise (task.promise, namespace_value, true)); + jerry_value_t namespace_value = jerry_module_namespace (module_value); + jerry_value_free (jerry_promise_resolve (task.promise, namespace_value)); - jerry_release_value (namespace_value); - jerry_release_value (module_value); - jerry_release_value (task.specifier); - jerry_release_value (task.user_value); - jerry_release_value (task.promise); + jerry_value_free (namespace_value); + jerry_value_free (module_value); + jerry_value_free (task.specifier); + jerry_value_free (task.user_value); + jerry_value_free (task.promise); /* Process promise handlers. */ - jerry_release_value (jerry_run_all_enqueued_jobs ()); + jerry_value_free (jerry_run_jobs ()); jerry_cleanup (); return 0; @@ -5852,39 +5516,39 @@ main (void) ``` **See also** -- [jerry_module_import_callback_t](#jerry_module_import_callback_t) +- [jerry_module_import_cb_t](#jerry_module_import_cb_t) -## jerry_native_module_create +## jerry_native_module Creates a native module with a list of exports. The initial state of the module is linked. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. - Native pointers can be used to assign private data to a native module, - see [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) + see [jerry_object_set_native_ptr](#jerry_object_set_native_ptr) - When `callback` is `NULL`, no function is called when the module is evaluated, only its state is changed to evaluated. - This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c jerry_value_t -jerry_native_module_create (jerry_native_module_evaluate_callback_t callback, - const jerry_value_t * const exports_p, - size_t number_of_exports); +jerry_native_module (jerry_native_module_evaluate_cb_t callback, + const jerry_value_t * const exports_p, + size_t number_of_exports); ``` -- `callback` - a [jerry_native_module_evaluate_callback_t](#jerry_native_module_evaluate_callback_t) callback +- `callback` - a [jerry_native_module_evaluate_cb_t](#jerry_native_module_evaluate_cb_t) callback which is called by [jerry_module_evaluate](#jerry_module_evaluate) to evaluate the native module. - `exports_p` - list of the exported bindings of the module, must be valid string identifiers. - `number_of_exports` - number of exports in the `exports_p` list. - return - a native module, if the module is successfully created - - error, otherwise + - exception, otherwise *New in version [[NEXT_RELEASE]]*. @@ -5902,15 +5566,15 @@ main (void) jerry_value_t exports[2] = { - jerry_create_string ((const jerry_char_t *) "first_export"), - jerry_create_string ((const jerry_char_t *) "second_export") + jerry_string_sz ("first_export"), + jerry_string_sz ("second_export") }; - jerry_value_t native_module = jerry_native_module_create (NULL, exports, 2); + jerry_value_t native_module = jerry_native_module (NULL, exports, 2); - jerry_release_value (exports[0]); - jerry_release_value (exports[1]); - jerry_release_value (native_module); + jerry_value_free (exports[0]); + jerry_value_free (exports[1]); + jerry_value_free (native_module); jerry_cleanup (); return 0; @@ -5921,33 +5585,33 @@ main (void) - [jerry_module_link](#jerry_module_link) - [jerry_module_evaluate](#jerry_module_evaluate) -- [jerry_native_module_get_export](#jerry_native_module_get_export) -- [jerry_native_module_set_export](#jerry_native_module_set_export) +- [jerry_native_module_get](#jerry_native_module_get) +- [jerry_native_module_set](#jerry_native_module_set) -## jerry_native_module_get_export +## jerry_native_module_get Gets the value of an export binding which belongs to a native module. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- 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_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c jerry_value_t -jerry_native_module_get_export (const jerry_value_t native_module_val, - const jerry_value_t export_name_val); +jerry_native_module_get (const jerry_value_t native_module_val, + const jerry_value_t export_name_val); ``` - `native_module_val` - a native module object. - `export_name_val` - string identifier of the export. - return - value of the export, if success - - error, otherwise + - exception, otherwise *New in version [[NEXT_RELEASE]]*. @@ -5963,15 +5627,15 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t export = jerry_create_string ((const jerry_char_t *) "an_export"); + jerry_value_t export = jerry_string_sz ("an_export"); - jerry_value_t native_module = jerry_native_module_create (NULL, &export, 1); + jerry_value_t native_module = jerry_native_module (NULL, &export, 1); - jerry_value_t value = jerry_native_module_get_export (native_module, export); - jerry_release_value (value); + jerry_value_t value = jerry_native_module_get (native_module, export); + jerry_value_free (value); - jerry_release_value (export); - jerry_release_value (native_module); + jerry_value_free (export); + jerry_value_free (native_module); jerry_cleanup (); return 0; @@ -5980,27 +5644,27 @@ main (void) **See also** -- [jerry_native_module_create](#jerry_native_module_create) -- [jerry_native_module_set_export](#jerry_native_module_set_export) +- [jerry_native_module](#jerry_native_module) +- [jerry_native_module_set](#jerry_native_module_set) -## jerry_native_module_set_export +## jerry_native_module_set Sets the value of an export binding which belongs to a native module. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- 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_MODULE_SYSTEM`) and can be checked in runtime with the `JERRY_FEATURE_MODULE` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c jerry_value_t -jerry_value_t jerry_native_module_set_export (const jerry_value_t native_module_val, - const jerry_value_t export_name_val, - const jerry_value_t value_to_set) +jerry_value_t jerry_native_module_set (const jerry_value_t native_module_val, + const jerry_value_t export_name_val, + const jerry_value_t value_to_set) ``` - `native_module_val` - a native module object. @@ -6008,7 +5672,7 @@ jerry_value_t jerry_native_module_set_export (const jerry_value_t native_module_ - `value_to_set` - new value of the export. - return - true, if success - - error, otherwise + - exception, otherwise *New in version [[NEXT_RELEASE]]*. @@ -6024,17 +5688,17 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t export = jerry_create_string ((const jerry_char_t *) "an_export"); + jerry_value_t export = jerry_string_sz ("an_export"); - jerry_value_t native_module = jerry_native_module_create (NULL, &export, 1); + jerry_value_t native_module = jerry_native_module (NULL, &export, 1); - jerry_value_t number = jerry_create_number (3.5); - jerry_value_t value = jerry_native_module_set_export (native_module, export, number); - jerry_release_value (value); - jerry_release_value (number); + jerry_value_t number = jerry_number (3.5); + jerry_value_t value = jerry_native_module_set (native_module, export, number); + jerry_value_free (value); + jerry_value_free (number); - jerry_release_value (export); - jerry_release_value (native_module); + jerry_value_free (export); + jerry_value_free (native_module); jerry_cleanup (); return 0; @@ -6043,33 +5707,28 @@ main (void) **See also** -- [jerry_native_module_create](#jerry_native_module_create) -- [jerry_native_module_get_export](#jerry_native_module_get_export) +- [jerry_native_module](#jerry_native_module) +- [jerry_native_module_get](#jerry_native_module_get) # Functions for promise objects -These APIs all depend on the es.next profile (or on some build options). +These APIs are always enabled. -## jerry_get_promise_result +## jerry_promise_result **Summary** The function returns the result of a Promise object. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- 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_is_feature_enabled](#jerry_is_feature_enabled). -- The es.next profile enables this by default. - **Prototype** ```c jerry_value_t -jerry_get_promise_result (const jerry_value_t promise); +jerry_promise_result (const jerry_value_t promise); ``` - `promise` - the input Promise object. @@ -6081,8 +5740,6 @@ jerry_get_promise_result (const jerry_value_t promise); *New in version 2.2*. -*Changed in version [[NEXT_RELEASE]]*: Build option dependency changed from `JERRY_BUILTIN_PROMISE` to `JERRY_ESNEXT`. - **Example** [doctest]: # (test="compile") @@ -6093,52 +5750,46 @@ jerry_get_promise_result (const jerry_value_t promise); static void example (void) { - // acquire/create a promise object. - jerry_value_t promise = jerry_create_promise (); + // create a promise object. + jerry_value_t promise = jerry_promise (); { // prepare the argument for the resolve or reject. - jerry_value_t argument = jerry_create_number (33); + jerry_value_t argument = jerry_number (33); - jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise, - argument, - true); - // 'is_ok' should be checked if it is an error or not. + jerry_value_t is_ok = jerry_promise_resolve (promise, argument); + + // 'is_ok' should be checked if it is an exception or not. // skipped in this example - jerry_release_value (is_ok); - jerry_release_value (argument); + jerry_value_free (is_ok); + jerry_value_free (argument); } - jerry_value_t promise_result = jerry_get_promise_result (promise); + jerry_value_t promise_result = jerry_promise_result (promise); // 'promise_result' is now the number 33. - jerry_release_value (promise_result); - jerry_release_value (promise); + jerry_value_free (promise_result); + jerry_value_free (promise); } ``` **See also** -- [jerry_create_promise](#jerry_create_promise) +- [jerry_promise](#jerry_promise) - [jerry_promise_state_t](#jerry_promise_state_t) -## jerry_get_promise_state +## jerry_promise_state **Summary** *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- 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_is_feature_enabled](#jerry_is_feature_enabled). -- The es.next profile enables this by default. - **Prototype** ```c jerry_promise_state_t -jerry_get_promise_state (const jerry_value_t promise); +jerry_promise_state (const jerry_value_t promise); ``` - `promise` - the input promise object. @@ -6149,8 +5800,6 @@ jerry_get_promise_state (const jerry_value_t promise); *New in version 2.2*. -*Changed in version [[NEXT_RELEASE]]*: Build option dependency changed from `JERRY_BUILTIN_PROMISE` to `JERRY_ESNEXT`. - **Example** [doctest]: # (test="compile") @@ -6161,38 +5810,37 @@ jerry_get_promise_state (const jerry_value_t promise); static void example (void) { - // acquire/create a promise object. - jerry_value_t promise = jerry_create_promise (); + // create a promise object. + jerry_value_t promise = jerry_promise (); - jerry_promise_state_t start_state = jerry_get_promise_state (promise); + jerry_promise_state_t start_state = jerry_promise_state (promise); // a Promise have a default state of JERRY_PROMISE_STATE_PENDING { // prepare the argument for the resolve or reject. - jerry_value_t argument = jerry_create_number (33); + jerry_value_t argument = jerry_number (33); + + jerry_value_t is_ok = jerry_promise_resolve (promise, argument); - jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise, - argument, - true); - // 'is_ok' should be checked if it is an error or not. + // 'is_ok' should be checked if it is an exception or not. // skipped in this example - jerry_release_value (is_ok); - jerry_release_value (argument); + jerry_value_free (is_ok); + jerry_value_free (argument); } - jerry_promise_state_t current_state = jerry_get_promise_state (promise); + jerry_promise_state_t current_state = jerry_promise_state (promise); // at this point the Promise should be in the JERRY_PROMISE_STATE_FULFILLED state. - jerry_release_value (promise); + jerry_value_free (promise); } ``` **See also** -- [jerry_create_promise](#jerry_create_promise) +- [jerry_promise](#jerry_promise) - [jerry_promise_state_t](#jerry_promise_state_t) -## jerry_promise_set_callback +## jerry_promise_on_event **Summary** @@ -6201,14 +5849,14 @@ Sets a callback for tracking Promise and async operations. *Notes*: - This API depends on a build option (`JERRY_PROMISE_CALLBACK`) and can be checked in runtime with the `JERRY_FEATURE_PROMISE_CALLBACK` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -void jerry_promise_set_callback (jerry_promise_event_filter_t filters, jerry_promise_callback_t callback, - void *user_p); +void jerry_promise_on_event (jerry_promise_event_filter_t filters, jerry_promise_event_cb_t callback, + void *user_p); ``` - `filters` - combination of [jerry_promise_event_filter_t](#jerry_promise_event_filter_t) options @@ -6249,13 +5897,13 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_promise_set_callback (JERRY_PROMISE_EVENT_FILTER_CREATE, promise_callback, NULL); + jerry_promise_on_event (JERRY_PROMISE_EVENT_FILTER_CREATE, promise_callback, NULL); const char *source_p = "var p = Promise.resolve(0)\n" "p.then(function (v) { return v; })"; - jerry_release_value (jerry_eval ((const jerry_char_t *) source_p, - strlen (source_p), - JERRY_PARSE_NO_OPTS)); + jerry_value_free (jerry_eval ((const jerry_char_t *) source_p, + strlen (source_p), + JERRY_PARSE_NO_OPTS)); jerry_cleanup (); return 0; @@ -6264,10 +5912,10 @@ main (void) **See also** -- [jerry_create_promise](#jerry_create_promise) +- [jerry_promise](#jerry_promise) - [jerry_promise_state_t](#jerry_promise_state_t) -## jerry_from_property_descriptor +## jerry_property_descriptor_to_object **Summary** @@ -6275,21 +5923,21 @@ This API function is equivalent to FromPropertyDescriptor operation defined in E It returns with an ECMAScript Object which represents the property attributes. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_from_property_descriptor (const jerry_property_descriptor_t *src_prop_desc_p) +jerry_property_descriptor_to_object (const jerry_property_descriptor_t *src_prop_desc_p) ``` - `src_prop_desc_p` - the input property descriptor. - return - [jerry_value_t](#jerry_value_t) - - jerry value - if success - - value marked with error flag - otherwise + - object value - if success + - exception - otherwise *New in version 2.4*. @@ -6303,22 +5951,22 @@ jerry_from_property_descriptor (const jerry_property_descriptor_t *src_prop_desc static void example (void) { - jerry_value_t prop_name = jerry_create_string_from_utf8 ((jerry_char_t *) "value"); + jerry_value_t prop_name = jerry_string_sz ("value"); - jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor (); prop_desc.value = prop_name; prop_desc.flags |= JERRY_PROP_IS_VALUE_DEFINED; - jerry_value_t from_object = jerry_from_property_descriptor (&prop_desc); + jerry_value_t from_object = jerry_property_descriptor_to_object (&prop_desc); - jerry_release_value (prop_name); - jerry_release_value (from_object); + jerry_value_free (prop_name); + jerry_value_free (from_object); jerry_property_descriptor_free (&prop_desc); } ``` -## jerry_to_property_descriptor +## jerry_property_descriptor_from_object **Summary** @@ -6326,14 +5974,14 @@ This API function is equivalent to ToPropertyDescriptor operation defined in ECM It decodes the ECMAScript object and fills the fields of a JerryScript property descriptor. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_to_property_descriptor (jerry_value_t obj_value, jerry_property_descriptor_t *out_prop_desc_p); +jerry_property_descriptor_from_object (jerry_value_t obj_value, jerry_property_descriptor_t *out_prop_desc_p); ``` - `obj_value` - the input object @@ -6341,7 +5989,7 @@ jerry_to_property_descriptor (jerry_value_t obj_value, jerry_property_descriptor - return - [jerry_value_t](#jerry_value_t) - true, if success - - thrown error, otherwise + - thrown exception, otherwise *New in version 2.4*. @@ -6355,34 +6003,34 @@ jerry_to_property_descriptor (jerry_value_t obj_value, jerry_property_descriptor static void example (void) { - jerry_value_t object = jerry_create_object (); - jerry_value_t prop_name = jerry_create_string_from_utf8 ((jerry_char_t *) "value"); - jerry_value_t value = jerry_create_boolean (true); + jerry_value_t object = jerry_object (); + jerry_value_t prop_name = jerry_string_sz ("value"); + jerry_value_t value = jerry_boolean (true); jerry_property_descriptor_t prop_desc; - jerry_release_value (jerry_set_property (object, prop_name, prop_name)); + jerry_value_free (jerry_object_set (object, prop_name, prop_name)); - jerry_release_value (jerry_to_property_descriptor (object, &prop_desc)); + jerry_value_free (jerry_property_descriptor_from_object (object, &prop_desc)); - jerry_release_value (object); - jerry_release_value (prop_name); - jerry_release_value (value); + jerry_value_free (object); + jerry_value_free (prop_name); + jerry_value_free (value); jerry_property_descriptor_free (&prop_desc); } ``` -## jerry_resolve_or_reject_promise +## jerry_promise_resolve **Summary** -Resolve or reject the promise with an argument. +Resolve the promise with an argument. *Note*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. @@ -6390,17 +6038,14 @@ Resolve or reject the promise with an argument. ```c jerry_value_t -jerry_resolve_or_reject_promise (jerry_value_t promise, - jerry_value_t argument, - bool is_resolve) +jerry_promise_resolve (jerry_value_t promise, jerry_value_t argument); ``` - `promise` - the promise value -- `argument` - the argument for resolve or reject -- `is_resolve` - whether the promise should be resolved or rejected +- `argument` - the argument value - return value - - undefined jerry value - success of resolve or reject - - jerry value with error flag - otherwise + - undefined - if resolve call was successful + - exception - otherwise *New in version 2.0*. @@ -6410,57 +6055,103 @@ jerry_resolve_or_reject_promise (jerry_value_t promise, ```c { - jerry_value_t promise = ... // acquire/create a promise object. + jerry_value_t promise = ... // create/copy a promise object. ... - bool is_resolve = ... // whether the promise should be resolved or rejected - jerry_value_t argument = ... // prepare the argument for the resolve or reject. + jerry_value_t argument = ... // prepare the argument for resolve. - jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise, - argument, - is_resolve); + jerry_value_t is_ok = jerry_promise_resolve (promise, argument); - if (jerry_value_is_error (is_ok)) + if (jerry_value_is_exception (is_ok)) { - // handle the error. + // handle the exception. } - jerry_release_value (is_ok); - jerry_release_value (argument); - jerry_release_value (promise); + jerry_value_free (is_ok); + jerry_value_free (argument); + jerry_value_free (promise); } ``` **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_value_is_error](#jerry_value_is_error) +- [jerry_value_free](#jerry_value_free) +- [jerry_value_is_exception](#jerry_value_is_exception) + +## jerry_promise_reject + +**Summary** + +Reject the promise with an argument. + +*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_promise_reject (jerry_value_t promise, jerry_value_t argument); +``` + +- `promise` - the promise value +- `argument` - the argument value +- return value + - undefined - if reject call was successful + - exception - otherwise + +*New in version 2.0*. + +**Example** + +```c +{ + jerry_value_t promise = ... // create/copy a promise object. + + ... + + jerry_value_t argument = ... // prepare the argument for reject. + + jerry_value_t is_ok = jerry_promise_reject (promise, argument); + + if (jerry_value_is_exception (is_ok)) + { + // handle the exception. + } + + jerry_value_free (is_ok); + jerry_value_free (argument); + jerry_value_free (promise); +} +``` + +**See also** + +- [jerry_value_free](#jerry_value_free) +- [jerry_value_is_exception](#jerry_value_is_exception) # Functions for symbols -These APIs all depend on the es.next profile (or on build options). +These APIs are always enabled. -## jerry_get_well_known_symbol +## jerry_symbol **Summary** Get the well-known symbol corresponding to the given [well-known symbol id](#jerry_well_known_symbol_t). *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- 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_BUILTIN_SYMBOL`) and can be checked - in runtime with the `JERRY_FEATURE_SYMBOL` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). -- The es.next profile enables this by default. - If the symbol support is not enabled an undefined will be returned. **Prototype** ```c jerry_value_t -jerry_get_well_known_symbol (jerry_well_known_symbol_t symbol); +jerry_symbol (jerry_well_known_symbol_t symbol); ``` - `symbol` - [jerry_well_known_symbol_t](#jerry_well_known_symbol_t) enum value @@ -6482,15 +6173,15 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t array_value = jerry_create_array (5); - jerry_value_t symbol_iterator = jerry_get_well_known_symbol (JERRY_SYMBOL_ITERATOR); - jerry_value_t array_iterator = jerry_get_property (array_value, symbol_iterator); + jerry_value_t array_value = jerry_array (5); + jerry_value_t symbol_iterator = jerry_symbol (JERRY_SYMBOL_ITERATOR); + jerry_value_t array_iterator = jerry_object_get (array_value, symbol_iterator); // usage of array_iterator - jerry_release_value (array_iterator); - jerry_release_value (symbol_iterator); - jerry_release_value (array_value); + jerry_value_free (array_iterator); + jerry_value_free (symbol_iterator); + jerry_value_free (array_value); jerry_cleanup (); return 0; @@ -6501,32 +6192,27 @@ main (void) - [jerry_well_known_symbol_t](#jerry_well_known_symbol_t) -## jerry_get_symbol_description +## jerry_symbol_description **Summary** Returns with the `[[Description]]` internal property of a symbol value. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- 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_BUILTIN_SYMBOL`) and can be checked - in runtime with the `JERRY_FEATURE_SYMBOL` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). -- The es.next profile enables this by default. -- If the symbol support is not enabled an error will be returned. **Prototype** ```c jerry_value_t -jerry_get_symbol_description (const jerry_value_t value); +jerry_symbol_description (const jerry_value_t value); ``` - `value` - symbol value - return value - string or undefined value containing the symbol's description - if success - - thrown error, otherwise + - thrown exception, otherwise *New in version 2.4*. @@ -6542,17 +6228,17 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "foo"); - jerry_value_t symbol_value = jerry_create_symbol (string_value); + jerry_value_t string_value = jerry_string_sz ("foo"); + jerry_value_t symbol_value = jerry_symbol_with_description (string_value); - jerry_release_value (string_value); + jerry_value_free (string_value); - jerry_value_t symbol_description = jerry_get_symbol_description (symbol_value); + jerry_value_t symbol_description = jerry_symbol_description (symbol_value); // usage of symbol_desc_string - jerry_release_value (symbol_description); - jerry_release_value (symbol_value); + jerry_value_free (symbol_description); + jerry_value_free (symbol_value); jerry_cleanup (); return 0; @@ -6561,9 +6247,9 @@ main (void) **See also** -- [jerry_get_symbol_descriptive_string](#jerry_get_symbol_descriptive_string) +- [jerry_symbol_descriptive_string](#jerry_symbol_descriptive_string) -## jerry_get_symbol_descriptive_string +## jerry_symbol_descriptive_string **Summary** @@ -6571,25 +6257,20 @@ Call the SymbolDescriptiveString ecma builtin operation on the API value. Based on ECMA 262 v6 19.4.3.2.1 this is in the form of `Symbol(<description>)`. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- 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_BUILTIN_SYMBOL`) and can be checked - in runtime with the `JERRY_FEATURE_SYMBOL` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). -- The es.next profile enables this by default. -- If the symbol support is not enabled an error will be returned. **Prototype** ```c jerry_value_t -jerry_get_symbol_descriptive_string (const jerry_value_t value); +jerry_symbol_descriptive_string (const jerry_value_t value); ``` - `value` - symbol value - return value - string value containing the symbol's descriptive string - if success - - thrown error, otherwise + - thrown exception, otherwise *New in version 2.0*. @@ -6605,17 +6286,17 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "foo"); - jerry_value_t symbol_value = jerry_create_symbol (string_value); + jerry_value_t string_value = jerry_string_sz ("foo"); + jerry_value_t symbol_value = jerry_symbol_with_description (string_value); - jerry_release_value (string_value); + jerry_value_free (string_value); - jerry_value_t symbol_desc_string = jerry_get_symbol_descriptive_string (symbol_value); + jerry_value_t symbol_desc_string = jerry_symbol_descriptive_string (symbol_value); // usage of symbol_desc_string - jerry_release_value (symbol_desc_string); - jerry_release_value (symbol_value); + jerry_value_free (symbol_desc_string); + jerry_value_free (symbol_value); jerry_cleanup (); return 0; @@ -6624,32 +6305,32 @@ main (void) **See also** -- [jerry_get_symbol_description](#jerry_get_symbol_description) +- [jerry_symbol_description](#jerry_symbol_description) # Functions for BigInts These APIs all depend on build option (`JERRY_BUILTIN_BIGINT`). -## jerry_get_bigint_size_in_digits +## jerry_bigint_digit_count **Summary** Returns the size of uint64 digits of a BigInt value. This value is the minimum size of the buffer which can hold all digits of a BigInt value when -the digits are retrieved by `[jerry_get_bigint_digits](#jerry_get_bigint_digits)`. +the digits are retrieved by `[jerry_bigint_to_digits](#jerry_bigint_to_digits)`. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + see: [jerry_feature_enabled](#jerry_feature_enabled). +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c uint32_t -jerry_get_bigint_size_in_digits (jerry_value_t value) +jerry_bigint_digit_count (jerry_value_t value) ``` - `value` - BigInt value @@ -6664,6 +6345,8 @@ jerry_get_bigint_size_in_digits (jerry_value_t value) [doctest]: # () ```c +#include <stdio.h> + #include "jerryscript.h" int @@ -6672,12 +6355,12 @@ main (void) jerry_init (JERRY_INIT_EMPTY); uint64_t digits[4] = { 0x1, 0x1, 0x0, 0x0 }; - jerry_value_t bigint_value = jerry_create_bigint (digits, 4, true); + jerry_value_t bigint_value = jerry_bigint (digits, 4, true); /* Prints two, because the leading zeroes in digits buffer are discarded. */ - printf("size: %d\n", (int) jerry_get_bigint_size_in_digits (bigint_value)); + printf("size: %d\n", (int) jerry_bigint_digit_count (bigint_value)); - jerry_release_value (bigint_value); + jerry_value_free (bigint_value); jerry_cleanup (); return 0; @@ -6687,31 +6370,31 @@ main (void) **See also** - [jerry_value_is_bigint](#jerry_value_is_bigint) -- [jerry_get_bigint_digits](#jerry_get_bigint_digits) +- [jerry_bigint_to_digits](#jerry_bigint_to_digits) -## jerry_get_bigint_digits +## jerry_bigint_to_digits **Summary** Copies the uint64 digits of a BigInt value into a buffer. This function supports any buffer sizes. If the buffer size is smaller than the size returned by -`[jerry_get_bigint_size_in_digits](#jerry_get_bigint_size_in_digits)`, only the +`[jerry_bigint_digit_count](#jerry_bigint_digit_count)`, only the least significant digits are copied into the buffer. If the buffer size is greater, the unused digits are filled with zero. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + see: [jerry_feature_enabled](#jerry_feature_enabled). +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c void -jerry_get_bigint_digits (jerry_value_t value, uint64_t *digits_p, uint32_t size, bool *sign_p) +jerry_bigint_to_digits (jerry_value_t value, uint64_t *digits_p, uint32_t size, bool *sign_p) ``` - `value` - BigInt value @@ -6735,13 +6418,13 @@ main (void) jerry_init (JERRY_INIT_EMPTY); uint64_t digits[4] = { 0x1, 0x1, 0x0, 0x0 }; - jerry_value_t bigint_value = jerry_create_bigint (digits, 4, true); + jerry_value_t bigint_value = jerry_bigint (digits, 4, true); uint64_t get_digits[4]; bool sign; - jerry_get_bigint_digits (bigint_value, get_digits, 2, &sign); + jerry_bigint_to_digits (bigint_value, get_digits, 2, &sign); - jerry_release_value (bigint_value); + jerry_value_free (bigint_value); jerry_cleanup (); return 0; @@ -6751,14 +6434,14 @@ main (void) **See also** - [jerry_value_is_bigint](#jerry_value_is_bigint) -- [jerry_get_bigint_size_in_digits](#jerry_get_bigint_size_in_digits) +- [jerry_bigint_digit_count](#jerry_bigint_digit_count) # Functions for Proxy objects These APIs all depend on build option (`JERRY_BUILTIN_PROXY`). -## jerry_get_proxy_target +## jerry_proxy_target **Summary** @@ -6767,7 +6450,7 @@ Gets the target object of a Proxy object. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. @@ -6775,12 +6458,12 @@ Gets the target object of a Proxy object. ```c jerry_value_t -jerry_get_proxy_target (jerry_value_t proxy_value); +jerry_proxy_target (jerry_value_t proxy_value); ``` - `proxy_value` - Proxy object value - return value - - type error - if proxy_value is not a Proxy object + - type error exception - if proxy_value is not a Proxy object - target object - otherwise *New in version 2.4*. @@ -6789,29 +6472,29 @@ jerry_get_proxy_target (jerry_value_t proxy_value); ```c { - jerry_value_t target = jerry_create_object (); - jerry_value_t handler = jerry_create_object (); - jerry_value_t proxy = jerry_create_proxy (target, handler); + jerry_value_t target = jerry_object (); + jerry_value_t handler = jerry_object (); + jerry_value_t proxy = jerry_proxy (target, handler); - jerry_release_value (target); - jerry_release_value (handler); + jerry_value_free (target); + jerry_value_free (handler); - target = jerry_get_proxy_target (proxy); + target = jerry_proxy_target (proxy); // ... usage of the target - jerry_release_value (target); - jerry_release_value (proxy); + jerry_value_free (target); + jerry_value_free (proxy); } ``` **See also** -- [jerry_create_proxy](#jerry_create_proxy) -- [jerry_create_special_proxy](#jerry_create_special_proxy) -- [jerry_get_proxy_handler](#jerry_get_proxy_handler) +- [jerry_proxy](#jerry_proxy) +- [jerry_proxy_custom](#jerry_proxy_custom) +- [jerry_proxy_handler](#jerry_proxy_handler) -## jerry_get_proxy_handler +## jerry_proxy_handler **Summary** @@ -6820,7 +6503,7 @@ Gets the handler object of a Proxy object. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. @@ -6828,12 +6511,12 @@ Gets the handler object of a Proxy object. ```c jerry_value_t -jerry_get_proxy_handler (jerry_value_t proxy_value); +jerry_proxy_handler (jerry_value_t proxy_value); ``` - `proxy_value` - Proxy object value - return value - - type error - if proxy_value is not a Proxy object + - type error exception - if proxy_value is not a Proxy object - handler object - otherwise *New in version [[NEXT_RELEASE]]*. @@ -6842,74 +6525,74 @@ jerry_get_proxy_handler (jerry_value_t proxy_value); ```c { - jerry_value_t target = jerry_create_object (); - jerry_value_t handler = jerry_create_object (); - jerry_value_t proxy = jerry_create_proxy (target, handler); + jerry_value_t target = jerry_object (); + jerry_value_t handler = jerry_object (); + jerry_value_t proxy = jerry_proxy (target, handler); - jerry_release_value (target); - jerry_release_value (handler); + jerry_value_free (target); + jerry_value_free (handler); - handler = jerry_get_proxy_handler (proxy); + handler = jerry_proxy_handler (proxy); // ... usage of the handler - jerry_release_value (handler); - jerry_release_value (proxy); + jerry_value_free (handler); + jerry_value_free (proxy); } ``` **See also** -- [jerry_create_proxy](#jerry_create_proxy) -- [jerry_create_special_proxy](#jerry_create_special_proxy) -- [jerry_get_proxy_target](#jerry_get_proxy_target) +- [jerry_proxy](#jerry_proxy) +- [jerry_proxy_custom](#jerry_proxy_custom) +- [jerry_proxy_target](#jerry_proxy_target) -# Acquire and release API values +# Copy and free API values -## jerry_acquire_value +## jerry_value_copy **Summary** -Acquires the specified Jerry API value. +Copies the specified Jerry API value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_acquire_value (jerry_value_t value); +jerry_value_copy (jerry_value_t value); ``` - `value` - api value -- return value - acquired value that may be used outside of the engine +- return value - copied value **Example** ```c { - jerry_value_t object_value = jerry_create_object (); + jerry_value_t object_value = jerry_object (); - jerry_value_t acquired_object = jerry_acquire_value (object_value); + jerry_value_t copied_object = jerry_value_copy (object_value); - jerry_release_value (object_value); + jerry_value_free (object_value); - // acquired_object refers to the created object and makes it + // copied_object refers to the created object and makes it // available after the release of 'object_value' - jerry_release_value (acquired_object); + jerry_value_free (copied_object); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) - [jerry_value_t](#jerry_value_t) -## jerry_release_value +## jerry_value_free **Summary** @@ -6919,7 +6602,7 @@ Release specified Jerry API value. ```c void -jerry_release_value (jerry_value_t value); +jerry_value_free (jerry_value_t value); ``` - `value` - api value @@ -6928,11 +6611,11 @@ jerry_release_value (jerry_value_t value); ```c { - jerry_value_t object_value = jerry_create_object (); + jerry_value_t object_value = jerry_object (); ... - jerry_release_value (object_value); + jerry_value_free (object_value); } ``` @@ -6941,23 +6624,23 @@ jerry_release_value (jerry_value_t value); Function for creating [API values](#jerry_value_t). -*Note*: Every created API value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Every created API value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. -## jerry_create_array +## jerry_array **Summary** Create an array object value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_array (uint32_t size); +jerry_array (uint32_t size); ``` - `size` - size of array; @@ -6967,21 +6650,21 @@ jerry_create_array (uint32_t size); ```c { - jerry_value_t array = jerry_create_array (10); + jerry_value_t array = jerry_array (10); ... - jerry_release_value (array); + jerry_value_free (array); } ``` **See also** -- [jerry_set_property_by_index](#jerry_set_property_by_index) -- [jerry_get_property_by_index](#jerry_get_property_by_index) +- [jerry_object_set_index](#jerry_object_set_index) +- [jerry_object_get_index](#jerry_object_get_index) -## jerry_create_arraybuffer +## jerry_arraybuffer **Summary** @@ -6990,15 +6673,15 @@ Create a jerry_value_t representing an ArrayBuffer object. *Note*: - 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_is_feature_enabled](#jerry_is_feature_enabled). -- Returned value must be freed with [jerry_release_value](#jerry_release_value) + see: [jerry_feature_enabled](#jerry_feature_enabled). +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_arraybuffer (jerry_length_t size); +jerry_arraybuffer (jerry_length_t size); ``` - `size` - size of the backing store allocated for the array buffer **in bytes**. @@ -7010,11 +6693,11 @@ jerry_create_arraybuffer (jerry_length_t size); ```c { - jerry_value_t buffer_value = jerry_create_arraybuffer (15); + jerry_value_t buffer_value = jerry_arraybuffer (15); ... // use the ArrayBuffer - jerry_release_value (buffer_value); + jerry_value_free (buffer_value); } ``` @@ -7023,10 +6706,10 @@ jerry_create_arraybuffer (jerry_length_t size); - [jerry_arraybuffer_read](#jerry_arraybuffer_read) - [jerry_arraybuffer_write](#jerry_arraybuffer_write) - [jerry_value_is_arraybuffer](#jerry_value_is_arraybuffer) -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_create_arraybuffer_external +## jerry_arraybuffer_external **Summary** @@ -7040,18 +6723,19 @@ so the user can release the buffer which was provided. *Note*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - If `buffer_p` is NULL, the buffer is allocated by the allocator callback passed to - [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks) -- Returned value must be freed with [jerry_release_value](#jerry_release_value) + [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_arraybuffer_external (const jerry_length_t size - uint8_t *buffer_p, void *arraybuffer_user_p); +jerry_arraybuffer_external (uint8_t *buffer_p, + const jerry_length_t size + void *arraybuffer_user_p); ``` - `size` - size of the buffer **in bytes**. @@ -7069,25 +6753,25 @@ jerry_create_arraybuffer_external (const jerry_length_t size ```c { uint8_t buffer_p[15]; - jerry_value_t buffer_value = jerry_create_arraybuffer_external (15, buffer_p, NULL); + jerry_value_t buffer_value = jerry_arraybuffer_external (buffer_p, 15, NULL); ... // use the array buffer - jerry_release_value (buffer_value); + jerry_value_free (buffer_value); } ``` **See also** -- [jerry_get_arraybuffer_pointer](#jerry_get_arraybuffer_pointer) +- [jerry_arraybuffer_data](#jerry_arraybuffer_data) - [jerry_arraybuffer_read](#jerry_arraybuffer_read) - [jerry_arraybuffer_write](#jerry_arraybuffer_write) - [jerry_value_is_arraybuffer](#jerry_value_is_arraybuffer) -- [jerry_release_value](#jerry_release_value) -- [jerry_object_native_free_callback_t](#jerry_object_native_free_callback_t) +- [jerry_value_free](#jerry_value_free) +- [jerry_object_native_free_cb_t](#jerry_object_native_free_cb_t) -## jerry_create_shared_arraybuffer +## jerry_shared_arraybuffer **Summary** @@ -7095,14 +6779,14 @@ Create a jerry_value_t representing a SharedArrayBuffer object. *Note*: - This API depends on a build option (`JERRY_BUILTIN_SHAREDARRAYBUFFER`). -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_shared_arraybuffer (jerry_length_t size); +jerry_shared_arraybuffer (jerry_length_t size); ``` - `size` - size of the backing store allocated for the shared array buffer **in bytes**. @@ -7114,11 +6798,11 @@ jerry_create_shared_arraybuffer (jerry_length_t size); ```c { - jerry_value_t buffer_value = jerry_create_shared_arraybuffer (15); + jerry_value_t buffer_value = jerry_shared_arraybuffer (15); ... // use the SharedArrayBuffer - jerry_release_value (buffer_value); + jerry_value_free (buffer_value); } ``` @@ -7127,10 +6811,10 @@ jerry_create_shared_arraybuffer (jerry_length_t size); - [jerry_arraybuffer_read](#jerry_arraybuffer_read) - [jerry_arraybuffer_write](#jerry_arraybuffer_write) - [jerry_value_is_shared_arraybuffer](#jerry_value_is_shared_arraybuffer) -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_create_shared_arraybuffer_external +## jerry_shared_arraybuffer_external **Summary** @@ -7144,21 +6828,21 @@ so the user can release the buffer which was provided. *Note*: - This API depends on a build option (`JERRY_BUILTIN_SHAREDARRAYBUFFER`). - If `buffer_p` is NULL, the buffer is allocated by the allocator callback passed to - [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks) -- Returned value must be freed with [jerry_release_value](#jerry_release_value) + [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_shared_arraybuffer_external (const jerry_length_t size - uint8_t *buffer_p, - jerry_value_free_callback_t free_cb); +jerry_shared_arraybuffer_external (uint8_t *buffer_p, + const jerry_length_t size, + jerry_value_free_callback_t free_cb); ``` -- `size` - size of the buffer **in bytes**. - `buffer_p` - the backing store used by the shared array buffer object. +- `size` - size of the buffer **in bytes**. - `arraybuffer_user_p` - user pointer assigned to the shared array buffer object. - return value - value of the newly constructed shared array buffer object. @@ -7170,25 +6854,25 @@ jerry_create_shared_arraybuffer_external (const jerry_length_t size ```c { uint8_t buffer_p[15]; - jerry_value_t buffer_value = jerry_create_shared_arraybuffer_external (15, buffer_p, NULL); + jerry_value_t buffer_value = jerry_shared_arraybuffer_external (buffer_p, 15, NULL); ... // use the shared array buffer - jerry_release_value (buffer_value); + jerry_value_free (buffer_value); } ``` **See also** -- [jerry_get_arraybuffer_pointer](#jerry_get_arraybuffer_pointer) +- [jerry_arraybuffer_data](#jerry_arraybuffer_data) - [jerry_arraybuffer_read](#jerry_arraybuffer_read) - [jerry_arraybuffer_write](#jerry_arraybuffer_write) - [jerry_value_is_shared_arraybuffer](#jerry_value_is_shared_arraybuffer) -- [jerry_release_value](#jerry_release_value) -- [jerry_object_native_free_callback_t](#jerry_object_native_free_callback_t) +- [jerry_value_free](#jerry_value_free) +- [jerry_object_native_free_cb_t](#jerry_object_native_free_cb_t) -## jerry_create_boolean +## jerry_boolean **Summary** @@ -7196,13 +6880,13 @@ Create a jerry_value_t representing a boolean value from the given boolean param *Notes*: - The boolean values (true/false) are fixed constants. Their values can be copied any number of times without calling - [jerry_acquire_value](#jerry_acquire_value), and freeing it with [jerry_release_value](#jerry_release_value) is optional. + [jerry_value_copy](#jerry_value_copy), and freeing it with [jerry_value_free](#jerry_value_free) is optional. **Prototype** ```c jerry_value_t -jerry_create_boolean (bool value); +jerry_boolean (bool value); ``` - `value` - raw boolean value. @@ -7212,125 +6896,121 @@ jerry_create_boolean (bool value); ```c { - jerry_value_t boolean_value = jerry_create_boolean (true); + jerry_value_t boolean_value = jerry_boolean (true); ... // usage of the value - jerry_release_value (boolean_value); + jerry_value_free (boolean_value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_create_error +## jerry_error **Summary** -Create new JavaScript error object. +Create new JavaScript Error object with the specified error message. Important! The `error_type` argument *must not be* `JERRY_ERROR_NONE`. -Creating an error with no error type is not valid. +Creating an Error object with no error type is not valid. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_error (jerry_error_t error_type, - const jerry_char_t *message_p); +jerry_error (jerry_error_t error_type, jerry_value_t message); ``` - `error_type` - type of error -- `message_p` - value of 'message' property of constructed error object -- return value - value of the constructed error object +- `message` - error message string +- return value - constructed error object **Example** ```c { - jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_TYPE, - (const jerry_char_t *) "error"); + jerry_value_t message = jerry_string_sz ("error"); + jerry_value_t error_obj = jerry_error (JERRY_ERROR_COMMON, message); ... // usage of error_obj - jerry_release_value (error_obj); + jerry_value_free (error_obj); + jerry_value_free (message); } ``` **See also** -- [jerry_value_is_error](#jerry_value_is_error) -- [jerry_get_value_from_error](#jerry_get_value_from_error) -- [jerry_create_error_from_value](#jerry_create_error_from_value) +- [jerry_value_is_exception](#jerry_value_is_exception) +- [jerry_exception_value](#jerry_exception_value) +- [jerry_throw](#jerry_throw) -## jerry_create_error_sz +## jerry_error_sz **Summary** -Create new JavaScript error object. +Create new JavaScript Error object, using the a zero-terminated string as the error message. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_error_sz (jerry_error_t error_type, - const jerry_char_t *message_p, - jerry_size_t message_size); +jerry_error_sz (jerry_error_t error_type, const char *message_p); ``` - `error_type` - type of the error - `message_p` - value of 'message' property of the constructed error object -- `message_size` - size of the message in bytes -- return value - value of the constructed error object +- return value - constructed error object **Example** ```c { - const jerry_char_t message[] = "error"; - jerry_value_t error_obj = jerry_create_error_sz (JERRY_ERROR_COMMON, - message, - sizeof (message) - 1); + jerry_value_t error_obj = jerry_error_sz (JERRY_ERROR_TYPE, "error"); ... // usage of error_obj - jerry_release_value (error_obj); + jerry_value_free (error_obj); } ``` **See also** -- [jerry_create_error](#jerry_create_error) +- [jerry_error](#jerry_error) -## jerry_create_dataview +## jerry_dataview **Summary** Create new JavaScript DataView object. *Note*: - - This API depends on the es.next profile. - - Returned value must be freed with [jerry_release_value](#jerry_release_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). + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_dataview (const jerry_value_t array_buffer, - const jerry_length_t byte_offset, - const jerry_length_t byte_length) +jerry_dataview (const jerry_value_t array_buffer, + const jerry_length_t byte_offset, + const jerry_length_t byte_length) ``` - `array_buffer` - arrayBuffer to create DataView from @@ -7338,7 +7018,7 @@ jerry_create_dataview (const jerry_value_t array_buffer, - `byte_length` - number of elements in the byte array - return value - value of the constructed DataView object - if success - - created error - otherwise + - exception - otherwise *New in version 2.0*. @@ -7354,13 +7034,13 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t arraybuffer = jerry_create_arraybuffer (16); - jerry_value_t dataview = jerry_create_dataview (arraybuffer, 0, 16); + jerry_value_t arraybuffer = jerry_arraybuffer (16); + jerry_value_t dataview = jerry_dataview (arraybuffer, 0, 16); // usage of dataview - jerry_release_value (dataview); - jerry_release_value (arraybuffer); + jerry_value_free (dataview); + jerry_value_free (arraybuffer); jerry_cleanup (); return 0; @@ -7370,23 +7050,23 @@ main (void) **See also** - [jerry_value_is_dataview](#jerry_value_is_dataview) -- [jerry_create_arraybuffer](#jerry_create_arraybuffer) +- [jerry_arraybuffer](#jerry_arraybuffer) -## jerry_create_external_function +## jerry_function_external **Summary** Create an external function object. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_external_function (jerry_external_handler_t handler_p); +jerry_function_external (jerry_external_handler_t handler_p); ``` - `handler_p` - pointer to native handler of the function object @@ -7408,7 +7088,7 @@ handler (const jerry_call_info_t *call_info_p, { printf ("Native handler called!\n"); - return jerry_create_boolean (true); + return jerry_boolean (true); } int @@ -7416,17 +7096,17 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t func_val = jerry_create_external_function (handler); - jerry_value_t glob_obj = jerry_get_global_object (); + jerry_value_t func_val = jerry_function_external (handler); + jerry_value_t glob_obj = jerry_current_realm (); // after this, script can invoke the native handler through "handler_field (1, 2, 3);" - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field"); + jerry_value_t prop_name = jerry_string_sz ("handler_field"); // set property and release the return value without any check - jerry_release_value (jerry_set_property (glob_obj, prop_name, func_val)); - jerry_release_value (prop_name); + jerry_value_free (jerry_object_set (glob_obj, prop_name, func_val)); + jerry_value_free (prop_name); - jerry_release_value (func_val); - jerry_release_value (glob_obj); + jerry_value_free (func_val); + jerry_value_free (glob_obj); // Test the method by calling it const char *test_src = "handler_field ();"; @@ -7434,7 +7114,7 @@ main (void) strlen (test_src), JERRY_PARSE_NO_OPTS); // release the eval result - jerry_release_value (ret_val); + jerry_value_free (ret_val); jerry_cleanup (); return 0; } @@ -7443,24 +7123,24 @@ main (void) **See also** - [jerry_external_handler_t](#jerry_external_handler_t) -- [jerry_set_property](#jerry_set_property) -- [jerry_call_function](#jerry_call_function) +- [jerry_object_set](#jerry_object_set) +- [jerry_call](#jerry_call) -## jerry_create_number +## jerry_number **Summary** Creates a `jerry_value_t` representing a number value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_number (double value); +jerry_number (double value); ``` - `value` - double value from which a `jerry_value_t` will be created @@ -7470,35 +7150,35 @@ jerry_create_number (double value); ```c { - jerry_value_t number_value = jerry_create_number (3.14); + jerry_value_t number_value = jerry_number (3.14); ... // usage of the value - jerry_release_value (number_value); + jerry_value_free (number_value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_create_number_infinity](#jerry_create_number_infinity) -- [jerry_create_number_nan](#jerry_create_number_nan) +- [jerry_value_free](#jerry_value_free) +- [jerry_infinity](#jerry_infinity) +- [jerry_nan](#jerry_nan) -## jerry_create_number_infinity +## jerry_infinity **Summary** Creates a `jerry_value_t` representing a positive or negative infinity value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_number_infinity (bool sign); +jerry_infinity (bool sign); ``` - `sign` - true for negative Infinity and false for positive Infinity @@ -7508,35 +7188,35 @@ jerry_create_number_infinity (bool sign); ```c { - jerry_value_t positive_inf_value = jerry_create_number_infinity (false); + jerry_value_t positive_inf_value = jerry_infinity (false); ... // usage of the positive_inf_value - jerry_release_value (positive_inf_value); + jerry_value_free (positive_inf_value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_create_number](#jerry_create_number) -- [jerry_create_number_nan](#jerry_create_number_nan) +- [jerry_value_free](#jerry_value_free) +- [jerry_number](#jerry_number) +- [jerry_nan](#jerry_nan) -## jerry_create_number_nan +## jerry_nan **Summary** Creates a `jerry_value_t` representing a not-a-number value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_number_nan (void); +jerry_nan (void); ``` - return value - a `jerry_value_t` representing the not-a-number value @@ -7545,22 +7225,22 @@ jerry_create_number_nan (void); ```c { - jerry_value_t nan_value = jerry_create_number_nan (); + jerry_value_t nan_value = jerry_nan (); ... // usage of the nan_value - jerry_release_value (nan_value); + jerry_value_free (nan_value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_create_number](#jerry_create_number) -- [jerry_create_number_infinity](#jerry_create_number_infinity) +- [jerry_value_free](#jerry_value_free) +- [jerry_number](#jerry_number) +- [jerry_infinity](#jerry_infinity) -## jerry_create_null +## jerry_null **Summary** @@ -7568,13 +7248,13 @@ Creates and returns a `jerry_value_t` with type null object. *Notes*: - The null value is a fixed constant. Its value can be copied any number of times without calling - [jerry_acquire_value](#jerry_acquire_value), and freeing it with [jerry_release_value](#jerry_release_value) is optional. + [jerry_value_copy](#jerry_value_copy), and freeing it with [jerry_value_free](#jerry_value_free) is optional. **Prototype** ```c jerry_value_t -jerry_create_null (void); +jerry_null (void); ``` - return value - a `jerry_value_t` representing null. @@ -7583,33 +7263,33 @@ jerry_create_null (void); ```c { - jerry_value_t null_value = jerry_create_null (); + jerry_value_t null_value = jerry_null (); ... // usage of the value - jerry_release_value (null_value); + jerry_value_free (null_value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_create_object +## jerry_object **Summary** Create new JavaScript object, like with new Object(). -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_object (void); +jerry_object (void); ``` - return value - value of the created object @@ -7618,36 +7298,35 @@ jerry_create_object (void); ```c { - jerry_value_t object_value = jerry_create_object (); + jerry_value_t object_value = jerry_object (); ... // usage of object_value - jerry_release_value (object_value); + jerry_value_free (object_value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_create_promise +## jerry_promise **Summary** Create an empty promise object which can be resolved or rejected later -by calling jerry_resolve_or_reject_promise. +by calling jerry_promise_resolve or jerry_promise_reject. *Note*: - - This API depends on the es.next profile. - - Returned value must be freed with [jerry_release_value](#jerry_release_value) + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_promise (void) +jerry_promise (void) ``` - return value - value of the newly created promise @@ -7658,42 +7337,44 @@ jerry_create_promise (void) ```c { - jerry_value_t p = jerry_create_promise (); + jerry_value_t p = jerry_promise (); ...// usage of the promise - jerry_release_value (p); + jerry_value_free (p); } ``` **See also** -- [jerry_resolve_or_reject_promise](#jerry_resolve_or_reject_promise) -- [jerry_release_value](#jerry_release_value) +- [jerry_promise_resolve](#jerry_promise_resolve) +- [jerry_promise_reject](#jerry_promise_reject) +- [jerry_value_free](#jerry_value_free) -## jerry_create_proxy +## jerry_proxy **Summary** Create a new Proxy object with the given target and handler. *Note*: - - This API depends on the es.next profile. - - Returned value must be freed with [jerry_release_value](#jerry_release_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). + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_proxy (const jerry_value_t target, - const jerry_value_t handler); +jerry_proxy (const jerry_value_t target, const jerry_value_t handler); ``` - `target` - proxy target - `handler` - proxy handler -- return thrown error - if the Proxy construction fails +- return exception - if the Proxy construction fails value of the newly created proxy object - otherwise *New in version 2.3*. @@ -7710,16 +7391,16 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t target = jerry_create_object (); - jerry_value_t handler = jerry_create_object (); - jerry_value_t proxy = jerry_create_proxy (target, handler); + jerry_value_t target = jerry_object (); + jerry_value_t handler = jerry_object (); + jerry_value_t proxy = jerry_proxy (target, handler); - jerry_release_value (target); - jerry_release_value (handler); + jerry_value_free (target); + jerry_value_free (handler); // usage of the proxy - jerry_release_value (proxy); + jerry_value_free (proxy); jerry_cleanup (); } @@ -7728,11 +7409,11 @@ main (void) **See also** - [jerry_value_is_proxy](#jerry_value_is_proxy) -- [jerry_create_special_proxy](#jerry_create_special_proxy) -- [jerry_release_value](#jerry_release_value) +- [jerry_proxy_custom](#jerry_proxy_custom) +- [jerry_value_free](#jerry_value_free) -## jerry_create_special_proxy +## jerry_proxy_custom **Summary** @@ -7740,23 +7421,25 @@ Create a new Proxy object with the given target and handler. The behaviour of the Proxy can be specialized with an options argument. *Note*: - - This API depends on the es.next profile. - - Returned value must be freed with [jerry_release_value](#jerry_release_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). + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_special_proxy (const jerry_value_t target, - const jerry_value_t handler, - uint32_t options); +jerry_proxy_custom (const jerry_value_t target, + const jerry_value_t handler, + uint32_t options); ``` - `target` - proxy target - `handler` - proxy handler -- `options` - any combination of [jerry_proxy_object_options_t](#jerry_proxy_object_options_t) options -- return thrown error - if the Proxy construction fails +- `options` - any combination of [jerry_proxy_custom_behavior_t](#jerry_proxy_custom_behavior_t) options +- return thrown exception - if the Proxy construction fails value of the newly created proxy object - otherwise *New in version [[NEXT_RELEASE]]*. @@ -7773,16 +7456,16 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t target = jerry_create_object (); - jerry_value_t handler = jerry_create_object (); - jerry_value_t proxy = jerry_create_special_proxy (target, handler, JERRY_PROXY_SKIP_RESULT_VALIDATION); + jerry_value_t target = jerry_object (); + jerry_value_t handler = jerry_object (); + jerry_value_t proxy = jerry_proxy_custom (target, handler, JERRY_PROXY_SKIP_RESULT_VALIDATION); - jerry_release_value (target); - jerry_release_value (handler); + jerry_value_free (target); + jerry_value_free (handler); // usage of the proxy - jerry_release_value (proxy); + jerry_value_free (proxy); jerry_cleanup (); } @@ -7791,67 +7474,68 @@ main (void) **See also** - [jerry_value_is_proxy](#jerry_value_is_proxy) -- [jerry_create_special_proxy](#jerry_create_special_proxy) -- [jerry_release_value](#jerry_release_value) +- [jerry_proxy_custom](#jerry_proxy_custom) +- [jerry_value_free](#jerry_value_free) -## jerry_create_string +## jerry_string_sz **Summary** -Create string from a valid CESU8 string. +Create string from a zero-terminated ASCII string. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_string (const jerry_char_t *str_p); +jerry_string_sz (const char *str_p); ``` - `str_p` - non-null pointer to string -- return value - value of the created string +- return value - created string **Example** ```c { - const jerry_char_t char_array[] = "a string"; - jerry_value_t string_value = jerry_create_string (char_array); + const char char_array[] = "a string"; + jerry_value_t string_value = jerry_string_sz (char_array); ... // usage of string_value - jerry_release_value (string_value); + jerry_value_free (string_value); } ``` **See also** -- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) -- [jerry_create_string_sz](#jerry_create_string_sz) +- [jerry_string](#jerry_string) -## jerry_create_string_sz +## jerry_string **Summary** -Create string from a valid CESU8 string. +Create a string from a buffer using the specified encoding. The data in the buffer must be valid for the encoding. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_string_sz (const jerry_char_t *str_p, - jerry_size_t str_size) +jerry_string (const jerry_char_t *buffer_p, + jerry_size_t buf_size, + jerry_encoding_t encoding) ``` -- `str_p` - non-null pointer to string -- `str_size` - size of the string +- `buffer_p` - non-null pointer to buffer +- `buf_size` - size of the buffer +- `encoding` - encoding of the string data - return value - value of the created string **Example** @@ -7859,128 +7543,41 @@ jerry_create_string_sz (const jerry_char_t *str_p, ```c { const jerry_char_t char_array[] = "a string"; - jerry_value_t string_value = jerry_create_string_sz (char_array, - sizeof (char_array) - 1); + jerry_value_t string_value = jerry_string (char_array, + sizeof (char_array) - 1, + JERRY_ENCODING_CESU8); ... // usage of string_value - jerry_release_value (string_value); + jerry_value_free (string_value); } ``` **See also** -- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) -- [jerry_create_string](#jerry_create_string) +- [jerry_validate_string](#jerry_validate_string) +- [jerry_string_sz](#jerry_string_sz) -## jerry_create_string_from_utf8 +## jerry_string_external_sz **Summary** -Create string from a valid UTF8 string. - -*Note*: - - The difference from [jerry_create_string](#jerry_create_string) is that it accepts utf-8 string instead of cesu-8 string. - - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. - -**Prototype** - -```c -jerry_value_t -jerry_create_string_from_utf8 (const jerry_char_t *str_p); -``` - -- `str_p` - non-null pointer to string -- return value - value of the created string - -*New in version 2.0*. - -**Example** - -```c -{ - const jerry_char_t char_array[] = "a string"; - jerry_value_t string_value = jerry_create_string_from_utf8 (char_array); - - ... // usage of string_value - - jerry_release_value (string_value); -} -``` - -**See also** - -- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) -- [jerry_create_string_sz_from_utf8](#jerry_create_string_sz_from_utf8) - - -## jerry_create_string_sz_from_utf8 - -**Summary** - -Create string from a valid UTF8 string. - -*Note*: - - The difference from [jerry_create_string_sz](#jerry_create_string_sz) is that it accepts utf-8 string instead of cesu-8 string. - - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. - -**Prototype** - -```c -jerry_value_t -jerry_create_string_sz_from_utf8 (const jerry_char_t *str_p, - jerry_size_t str_size) -``` - -- `str_p` - non-null pointer to string -- `str_size` - size of the string -- return value - value of the created string - -*New in version 2.0*. - -**Example** - -```c -{ - const jerry_char_t char_array[] = "a string"; - jerry_value_t string_value = jerry_create_string_sz_from_utf8 (char_array, - sizeof (char_array) - 1); - - ... // usage of string_value - - jerry_release_value (string_value); -} - -``` - -**See also** - -- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) -- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) - - -## jerry_create_external_string - -**Summary** - -Create an external string from a valid CESU8 string. The string buffer passed to the function +Create an external string from a zero-terminated ASCII string. The string buffer passed to the function should not be modified until the free callback is called. This function can be used to avoid the duplication of large strings. *Note*: - - The free callback can be set by [jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback) - - Returned value must be freed with [jerry_release_value](#jerry_release_value) + - The free callback can be set by [jerry_string_external_on_free](#jerry_string_external_on_free) + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_external_string (const jerry_char_t *str_p, void *user_p); +jerry_string_external_sz (const char *str_p, void *user_p); ``` - `str_p` - non-null pointer to string @@ -7996,23 +7593,21 @@ jerry_create_external_string (const jerry_char_t *str_p, void *user_p); ```c { const char* string_p = "a large and immutable string: this is a story about ...."; - jerry_value_t string_value = jerry_create_external_string ((const jerry_char_t *) string_p, - NULL); + jerry_value_t string_value = jerry_string_external_sz (string_p, NULL); ... // usage of string_value - jerry_release_value (string_value); + jerry_value_free (string_value); } ``` **See also** -- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) -- [jerry_create_external_string_sz](#jerry_create_external_string_sz) -- [jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback) +- [jerry_string_external](#jerry_string_external) +- [jerry_string_external_on_free](#jerry_string_external_on_free) -## jerry_create_external_string_sz +## jerry_string_external **Summary** @@ -8021,17 +7616,17 @@ should not be modified until the free callback is called. This function can be u the duplication of large strings. *Note*: - - The free callback can be set by [jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback) - - Returned value must be freed with [jerry_release_value](#jerry_release_value) + - The free callback can be set by [jerry_string_external_on_free](#jerry_string_external_on_free) + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_external_string_sz (const jerry_char_t *str_p, - jerry_size_t str_size, - void *user_p); +jerry_string_external (const jerry_char_t *str_p, + jerry_size_t str_size, + void *user_p); ``` - `str_p` - non-null pointer to string @@ -8048,47 +7643,46 @@ jerry_create_external_string_sz (const jerry_char_t *str_p, ```c { const char* string_p = "a large and immutable string: this is a story about ...."; - jerry_value_t string_value = jerry_create_external_string_sz ((const jerry_char_t *) string_p, - strlen (string_p), - NULL); + jerry_value_t string_value = jerry_string_external ((const jerry_char_t *) string_p, + strlen (string_p), + NULL); ... // usage of string_value - jerry_release_value (string_value); + jerry_value_free (string_value); } ``` **See also** -- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) -- [jerry_create_external_string](#jerry_create_external_string) -- [jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback) +- [jerry_validate_string](#jerry_validate_string) +- [jerry_string_external_sz](#jerry_string_external_sz) +- [jerry_string_external_on_free](#jerry_string_external_on_free) -## jerry_create_symbol +## jerry_symbol **Summary** Create symbol from an API value. *Note*: - - The given argument is converted to string. This operation can throw an error. - - This API depends on the es.next profile. - - Returned value must be freed with [jerry_release_value](#jerry_release_value) + - The given argument is converted to string. This operation can throw an exception. + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_symbol (const jerry_value_t value) +jerry_symbol_with_description (const jerry_value_t value) ``` - `value` - API value - return value - value of the created symbol, if success - - thrown error, otherwise + - thrown exception, otherwise *New in version 2.0*. @@ -8104,15 +7698,15 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "Symbol description string"); - jerry_value_t symbol_value = jerry_create_symbol (string_value); + jerry_value_t string_value = jerry_string_sz ("Symbol description string"); + jerry_value_t symbol_value = jerry_symbol_with_description (string_value); // The description value is no longer needed - jerry_release_value (string_value); + jerry_value_free (string_value); // usage of symbol_value - jerry_release_value (symbol_value); + jerry_value_free (symbol_value); jerry_cleanup (); } @@ -8121,10 +7715,10 @@ main (void) **See also** - [jerry_value_is_symbol](#jerry_value_is_symbol) -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_create_bigint +## jerry_bigint **Summary** @@ -8133,15 +7727,15 @@ Create BigInt value from uint64 digits *Note*: - 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_is_feature_enabled](#jerry_is_feature_enabled). -- Returned value must be freed with [jerry_release_value](#jerry_release_value) + see: [jerry_feature_enabled](#jerry_feature_enabled). +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_create_bigint (const uint64_t *digits_p, uint32_t size, bool sign) +jerry_bigint (const uint64_t *digits_p, uint32_t size, bool sign) ``` - `digits_p` - array of uint64 digits, least significant digit first @@ -8149,7 +7743,7 @@ jerry_create_bigint (const uint64_t *digits_p, uint32_t size, bool sign) - `sign` - false if the created value should be positive, and true if the created value should be negative - return value - value of the created bigint, if success - - thrown error, otherwise + - thrown exception, otherwise *New in version 2.4*. @@ -8166,11 +7760,11 @@ main (void) jerry_init (JERRY_INIT_EMPTY); uint64_t digits[2] = { 0x1, 0x1 }; - jerry_value_t bigint_value = jerry_create_bigint (digits, 2, true); + jerry_value_t bigint_value = jerry_bigint (digits, 2, true); // usage of bigint_value - jerry_release_value (bigint_value); + jerry_value_free (bigint_value); jerry_cleanup (); } @@ -8178,26 +7772,26 @@ main (void) **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) - [jerry_value_is_bigint](#jerry_value_is_bigint) -- [jerry_get_bigint_digits](#jerry_get_bigint_digits) +- [jerry_bigint_to_digits](#jerry_bigint_to_digits) -## jerry_create_regexp +## jerry_regexp_sz **Summary** -Returns a `jerry_value_t` RegExp object or an error, 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 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. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_create_regexp (const jerry_char_t *pattern_p, uint16_t flags); +jerry_regexp_sz (const jerry_char_t *pattern_p, uint16_t flags); ``` - `pattern_p` - the RegExp pattern as a zero-terminated UTF-8 string @@ -8213,30 +7807,30 @@ jerry_create_regexp (const jerry_char_t *pattern_p, uint16_t flags); jerry_char_t pattern_p = "[cgt]gggtaaa|tttaccc[acg]"; uint16_t pattern_flags = JERRY_REGEXP_FLAG_IGNORE_CASE; - jerry_value_t regexp = jerry_create_regexp (pattern_p, pattern_flags); + jerry_value_t regexp = jerry_regexp_sz (pattern_p, pattern_flags); ... - jerry_release_value (regexp); + jerry_value_free (regexp); } ``` -## jerry_create_regexp_sz +## jerry_regexp **Summary** -Returns a `jerry_value_t` RegExp object or an error, 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 from the argument 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_release_value](#jerry_release_value) when it +*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_create_regexp_sz (const jerry_char_t *pattern_p, jerry_size_t pattern_size, uint16_t flags); +jerry_regexp (const jerry_value_t pattern, uint16_t flags); ``` - `pattern_p` - the RegExp pattern as a zero-terminated UTF-8 string @@ -8252,18 +7846,21 @@ jerry_create_regexp_sz (const jerry_char_t *pattern_p, jerry_size_t pattern_size { jerry_char_t pattern_p = "[cgt]gggtaaa|tttaccc[acg]"; jerry_size_t pattern_size = sizeof (pattern_p) - 1; + jerry_value_t pattern_str = jerry_string (pattern_p, pattern_size, JERRY_ENCODING_UTF8); + uint16_t pattern_flags = JERRY_REGEXP_FLAG_IGNORE_CASE; - jerry_value_t regexp = jerry_create_regexp_sz (pattern_p, pattern_size, pattern_flags); + jerry_value_t regexp = jerry_regexp (pattern_str, pattern_flags); + jerry_value_free (pattern_str); ... - jerry_release_value (regexp); + jerry_value_free (regexp); } ``` -## jerry_create_typedarray +## jerry_typedarray **Summary** @@ -8273,18 +7870,18 @@ For the new object the type of the TypedArray (see: [jerry_typedarray_type_t](#j and element count can be specified. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- 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_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** ```c jerry_value_t -jerry_create_typedarray (jerry_typedarray_type_t type_name, jerry_length_t item_count); +jerry_typedarray (jerry_typedarray_type_t type_name, jerry_length_t item_count); ``` - `type_name` - type of TypedArray to create @@ -8297,11 +7894,11 @@ jerry_create_typedarray (jerry_typedarray_type_t type_name, jerry_length_t item_ ```c { - jerry_value_t array = jerry_create_typedarray (JERRY_TYPEDARRAY_UINT16, 15); + jerry_value_t array = jerry_typedarray (JERRY_TYPEDARRAY_UINT16, 15); ... // use the TypedArray - jerry_release_value (array); + jerry_value_free (array); } ``` @@ -8309,10 +7906,10 @@ jerry_create_typedarray (jerry_typedarray_type_t type_name, jerry_length_t item_ - [jerry_typedarray_type_t](#jerry_typedarray_type_t) - [jerry_value_is_typedarray](#jerry_value_is_typedarray) -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_create_typedarray_for_arraybuffer +## jerry_typedarray_with_buffer **Summary** @@ -8323,32 +7920,32 @@ For the new object the type of the TypedArray (see: [jerry_typedarray_type_t](#j and element count can be specified. The developer must ensure that the ArrayBuffer has the correct length for the given -type of TypedArray otherwise an error is generated. +type of TypedArray otherwise an exception is generated. The JavaScript equivalent of this function is: `new %TypedArray%(arraybuffer)` where `%TypedArray%` is one of the allowed TypedArray functions. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- 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_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** ```c jerry_value_t -jerry_create_typedarray_for_arraybuffer (jerry_typedarray_type_t type_name, - const jerry_value_t arraybuffer); +jerry_typedarray_with_buffer (jerry_typedarray_type_t type_name, + const jerry_value_t arraybuffer); ``` - `type_name` - type of TypedArray to create - `arraybuffer` - the ArrayBuffer to use for the new TypedArray - return value - the new TypedArray as a `jerry_value_t` - - Error if the ArrayBuffer does not have enough space for the given type of TypedArray + - exception if the ArrayBuffer does not have enough space for the given type of TypedArray *New in version 2.0*. @@ -8356,13 +7953,13 @@ jerry_create_typedarray_for_arraybuffer (jerry_typedarray_type_t type_name, ```c { - jerry_value_t buffer = jerry_create_array_buffer (12 * 2); - jerry_value_t array = jerry_create_typedarray_for_arraybuffer (JERRY_TYPEDARRAY_UINT16, buffer); - jerry_release_value (buffer); + jerry_value_t buffer = jerry_array_buffer (12 * 2); + jerry_value_t array = jerry_typedarray_with_buffer (JERRY_TYPEDARRAY_UINT16, buffer); + jerry_value_free (buffer); ... // use the TypedArray - jerry_release_value (array); + jerry_value_free (array); } ``` @@ -8370,10 +7967,10 @@ jerry_create_typedarray_for_arraybuffer (jerry_typedarray_type_t type_name, - [jerry_typedarray_type_t](#jerry_typedarray_type_t) - [jerry_value_is_typedarray](#jerry_value_is_typedarray) -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_create_typedarray_for_arraybuffer_sz +## jerry_typedarray_with_buffer_span **Summary** @@ -8384,27 +7981,27 @@ For the new object the type of the TypedArray (see: [jerry_typedarray_type_t](#j and element count can be specified. The developer must ensure that the ArrayBuffer has the correct length for the given -type of TypedArray otherwise an error is generated. +type of TypedArray otherwise an exception is generated. The JavaScript equivalent of this function is: `new %TypedArray%(arraybuffer, byteOffset, length)` where `%TypedArray%` is one of the allowed TypedArray functions. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- 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_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** ```c jerry_value_t -jerry_create_typedarray_for_arraybuffer_sz (jerry_typedarray_type_t type_name, - const jerry_value_t arraybuffer, - jerry_length_t byte_offset, - jerry_length_t length); +jerry_typedarray_with_buffer_span (jerry_typedarray_type_t type_name, + const jerry_value_t arraybuffer, + jerry_length_t byte_offset, + jerry_length_t length); ``` - `type_name` - type of TypedArray to create @@ -8413,7 +8010,7 @@ jerry_create_typedarray_for_arraybuffer_sz (jerry_typedarray_type_t type_name, - `length` - number of elements to used from the ArrayBuffer (this is not the same as the byteLength) - return value - the new TypedArray as a `jerry_value_t` - - Error if the ArrayBuffer does not have enough space for the given type of TypedArray + - exception if the ArrayBuffer does not have enough space for the given type of TypedArray *New in version 2.0*. @@ -8421,13 +8018,13 @@ jerry_create_typedarray_for_arraybuffer_sz (jerry_typedarray_type_t type_name, ```c { - jerry_value_t buffer = jerry_create_array_buffer (12 * 2); - jerry_value_t array = jerry_create_typedarray_for_arraybuffer_sz (JERRY_TYPEDARRAY_UINT16, buffer, 4, 10); - jerry_release_value (buffer); + jerry_value_t buffer = jerry_array_buffer (12 * 2); + jerry_value_t array = jerry_typedarray_with_buffer_span (JERRY_TYPEDARRAY_UINT16, buffer, 4, 10); + jerry_value_free (buffer); ... // use the TypedArray - jerry_release_value (array); + jerry_value_free (array); } ``` @@ -8435,10 +8032,10 @@ jerry_create_typedarray_for_arraybuffer_sz (jerry_typedarray_type_t type_name, - [jerry_typedarray_type_t](#jerry_typedarray_type_t) - [jerry_value_is_typedarray](#jerry_value_is_typedarray) -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_create_container +## jerry_container **Summary** @@ -8446,21 +8043,21 @@ Create a jerry_value_t representing a given type container object. *Notes*: - This method is expected to work the same way as the JavaScript Map constructor. -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- 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_BUILTIN_CONTAINER`) and can be checked in runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` feature enum values. - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** ```c jerry_value_t -jerry_create_container (jerry_container_type_t container_type, - const jerry_value_t *arguments_list_p, - jerry_length_t arguments_list_len); +jerry_container (jerry_container_type_t container_type, + const jerry_value_t *arguments_list_p, + jerry_length_t arguments_list_len); ``` - `container_type` - Type of the container to be created, see `jerry_container_type_t`. @@ -8484,12 +8081,12 @@ main (void) jerry_char_t src[] = "[1,2,3,4].entries()"; jerry_value_t iterable = jerry_eval (src, sizeof (src) - 1, JERRY_PARSE_NO_OPTS); - jerry_value_t map = jerry_create_container (JERRY_CONTAINER_TYPE_MAP, &iterable, 1); - jerry_release_value (iterable); + jerry_value_t map = jerry_container (JERRY_CONTAINER_TYPE_MAP, &iterable, 1); + jerry_value_free (iterable); // use the Map - jerry_release_value (map); + jerry_value_free (map); jerry_cleanup (); return 0; @@ -8499,24 +8096,24 @@ main (void) **See also** - [jerry_container_type_t](#jerry_container_type_t) -- [jerry_get_container_type](#jerry_get_container_type) +- [jerry_container_type](#jerry_container_type) -## jerry_create_undefined +## jerry_undefined **Summary** Creates a `jerry_value_t` representing an undefined value. *Notes*: -- The undefined value is a fixed constant. Its value can be copied any number of times without calling [jerry_acquire_value](#jerry_acquire_value), and freeing it with [jerry_release_value](#jerry_release_value) is optional. +- The undefined value is a fixed constant. Its value can be copied any number of times without calling [jerry_value_copy](#jerry_value_copy), and freeing it with [jerry_value_free](#jerry_value_free) is optional. **Prototype** ```c jerry_value_t -jerry_create_undefined (void); +jerry_undefined (void); ``` - return value - value of undefined @@ -8525,38 +8122,38 @@ jerry_create_undefined (void); ```c { - jerry_value_t undefined_value = jerry_create_undefined (); + jerry_value_t undefined_value = jerry_undefined (); ... // usage of the value - jerry_release_value (undefined_value); + jerry_value_free (undefined_value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) -## jerry_create_realm +## jerry_realm **Summary** Creates a `jerry_value_t` representing a new global object. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) +- 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_BUILTIN_REALMS`) and can be checked in runtime with the `JERRY_FEATURE_REALM` feature enum value. - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** ```c jerry_value_t -jerry_create_realm (void); +jerry_realm (void); ``` - return value - realm object value @@ -8575,11 +8172,11 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t realm_value = jerry_create_realm (); + jerry_value_t realm_value = jerry_realm (); // usage of the value - jerry_release_value (realm_value); + jerry_value_free (realm_value); jerry_cleanup (); return 0; @@ -8588,37 +8185,37 @@ main (void) **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_free](#jerry_value_free) # General API functions of JS objects -## jerry_has_property +## jerry_object_has **Summary** Checks whether the object or its prototype objects have the given property. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_has_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val); +jerry_object_has (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 - - raised error - if the operation fail - - true/false API value - depend on whether the property exists + - 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 error value. +*Changed in version 2.3*: The return value can be an exception value. **Example** @@ -8632,15 +8229,15 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field"); + 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_has_property (global_object, prop_name); + jerry_value_t has_prop_js = jerry_object_has (global_object, prop_name); bool has_prop = jerry_value_is_true (has_prop_js); - jerry_release_value (has_prop_js); - jerry_release_value (prop_name); - jerry_release_value (global_object); + jerry_value_free (has_prop_js); + jerry_value_free (prop_name); + jerry_value_free (global_object); jerry_cleanup (); @@ -8650,36 +8247,36 @@ main (void) **See also** -- [jerry_has_own_property](#jerry_has_own_property) -- [jerry_delete_property](#jerry_delete_property) +- [jerry_object_has_own](#jerry_object_has_own) +- [jerry_object_delete](#jerry_object_delete) -## jerry_has_own_property +## jerry_object_has_own **Summary** Checks whether the object has the given property. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_has_own_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val); +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 - - raised error - if the operation fails + - exception - if the operation fails - true/false API value - depend on whether the property exists *Changed in version 2.0*: The return value type is now a JavaScript value and not a primitive boolean value. -*Changed in version 2.3*: The return value can be an error value. +*Changed in version 2.3*: The return value can be an exception value. **Example** @@ -8693,15 +8290,15 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field"); + 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_has_own_property (global_object, prop_name); + 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_release_value (has_prop_js); - jerry_release_value (prop_name); - jerry_release_value (global_object); + jerry_value_free (has_prop_js); + jerry_value_free (prop_name); + jerry_value_free (global_object); jerry_cleanup (); @@ -8711,28 +8308,28 @@ main (void) **See also** -- [jerry_has_property](#jerry_has_property) -- [jerry_delete_property](#jerry_delete_property) +- [jerry_object_has](#jerry_object_has) +- [jerry_object_delete](#jerry_object_delete) -## jerry_has_internal_property +## jerry_object_has_internal **Summary** Checks whether the object has the given internal property. *Note*: - - Properties which were not created with [jerry_set_internal_property](#jerry_set_internal_property) are excluded + - 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_release_value](#jerry_release_value) when it + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c bool -jerry_has_internal_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val); +jerry_object_has_internal (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); ``` - `obj_val` - object value @@ -8755,13 +8352,13 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property"); + jerry_value_t global_object = jerry_current_realm (); + jerry_value_t prop_name = jerry_string_sz ("hidden_property"); - bool has_internal_js_prop = jerry_has_internal_property (global_object, prop_name); + bool has_internal_js_prop = jerry_object_has_internal (global_object, prop_name); - jerry_release_value (prop_name); - jerry_release_value (global_object); + jerry_value_free (prop_name); + jerry_value_free (global_object); return 0; } @@ -8769,12 +8366,12 @@ main (void) **See also** -- [jerry_delete_internal_property](#jerry_delete_internal_property) -- [jerry_get_internal_property](#jerry_get_internal_property) -- [jerry_set_internal_property](#jerry_set_internal_property) +- [jerry_object_delete_internal](#jerry_object_delete_internal) +- [jerry_object_get_internal](#jerry_object_get_internal) +- [jerry_object_set_internal](#jerry_object_set_internal) -## jerry_delete_property +## jerry_object_delete **Summary** @@ -8783,41 +8380,42 @@ Delete a property from an object. **Prototype** ```c -bool -jerry_delete_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val); +jerry_value_t +jerry_object_delete (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); ``` - `obj_val` - object value - `prop_name_val` - property name - return value - true, if property was deleted successfully - - false, otherwise + - exception, otherwise **Example** ```c { - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); + jerry_value_t global_object = jerry_current_realm (); + jerry_value_t prop_name = jerry_string_sz ("my_prop"); - bool delete_result = jerry_delete_property (global_object, prop_name); + jerry_value_t delete_result = jerry_object_delete (global_object, prop_name); /* use "delete_result" */ - jerry_release_value (prop_name); - jerry_release_value (global_object); + jerry_value_free (delete_result); + jerry_value_free (prop_name); + jerry_value_free (global_object); } ``` **See also** -- [jerry_has_property](#jerry_has_property) -- [jerry_has_own_property](#jerry_has_own_property) -- [jerry_delete_property_by_index](#jerry_delete_property_by_index) -- [jerry_get_property](#jerry_get_property) +- [jerry_object_has](#jerry_object_has) +- [jerry_object_has_own](#jerry_object_has_own) +- [jerry_object_delete_index](#jerry_object_delete_index) +- [jerry_object_get](#jerry_object_get) -## jerry_delete_property_by_index +## jerry_object_delete_index **Summary** @@ -8826,16 +8424,16 @@ Delete indexed property from the specified object. **Prototype** ```c -bool -jerry_delete_property_by_index (const jerry_value_t obj_val, - uint32_t index); +jerry_value_t +jerry_object_delete_index (const jerry_value_t obj_val, + uint32_t index); ``` - `obj_val` - object value - `index` - index number - return value - - true, if property was deleted successfully - - false, otherwise + - true value, if property was deleted successfully + - exception, otherwise *New in version 2.0*. @@ -8845,39 +8443,40 @@ jerry_delete_property_by_index (const jerry_value_t obj_val, { jerry_value_t object; - ... // create or acquire object + ... // create or copy object - bool delete_result = jerry_delete_property_by_index (object, 5); + jerry_value_t delete_result = jerry_object_delete_index (object, 5); - jerry_release_value (object); + jerry_value_free (delete_result); + jerry_value_free (object); } ``` **See also** -- [jerry_has_property](#jerry_has_property) -- [jerry_has_own_property](#jerry_has_own_property) -- [jerry_delete_property](#jerry_delete_property) -- [jerry_get_property](#jerry_get_property) -- [jerry_set_property](#jerry_set_property) -- [jerry_get_property_by_index](#jerry_get_property_by_index) -- [jerry_set_property_by_index](#jerry_set_property_by_index) +- [jerry_object_has](#jerry_object_has) +- [jerry_object_has_own](#jerry_object_has_own) +- [jerry_object_delete](#jerry_object_delete) +- [jerry_object_get](#jerry_object_get) +- [jerry_object_set](#jerry_object_set) +- [jerry_object_get_index](#jerry_object_get_index) +- [jerry_object_set_index](#jerry_object_set_index) -## jerry_delete_internal_property +## jerry_object_delete_internal **Summary** Delete an internal property from an object. -*Note*: Properties which were not created with [jerry_set_internal_property](#jerry_set_internal_property) are excluded +*Note*: Properties which were not created with [jerry_object_set_internal](#jerry_object_set_internal) are excluded during the operation. **Prototype** ```c bool -jerry_delete_internal_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val); +jerry_object_delete_internal (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); ``` - `obj_val` - object value @@ -8892,46 +8491,46 @@ jerry_delete_internal_property (const jerry_value_t obj_val, ```c { - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property"); + jerry_value_t global_object = jerry_current_realm (); + jerry_value_t prop_name = jerry_string_sz ("hidden_property"); - bool delete_result = jerry_delete_internal_property (global_object, prop_name); + bool delete_result = jerry_object_delete_internal (global_object, prop_name); /* use "delete_result" */ - jerry_release_value (prop_name); - jerry_release_value (global_object); + jerry_value_free (prop_name); + jerry_value_free (global_object); } ``` **See also** -- [jerry_has_internal_property](#jerry_has_internal_property) -- [jerry_get_internal_property](#jerry_get_internal_property) -- [jerry_set_internal_property](#jerry_set_internal_property) +- [jerry_object_has_internal](#jerry_object_has_internal) +- [jerry_object_get_internal](#jerry_object_get_internal) +- [jerry_object_set_internal](#jerry_object_set_internal) -## jerry_get_property +## jerry_object_get **Summary** Get value of a property to the specified object with the given name. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_get_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val); +jerry_object_get (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); ``` - `obj_val` - object value - `prop_name_val` - property name - return value - value of property, if success - - thrown error, otherwise + - thrown exception, otherwise **Example** @@ -8945,16 +8544,16 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "Object"); + jerry_value_t global_object = jerry_current_realm (); + jerry_value_t prop_name = jerry_string_sz ("Object"); - jerry_value_t prop_value = jerry_get_property (global_object, prop_name); + jerry_value_t prop_value = jerry_object_get (global_object, prop_name); /* use "prop_value" then release it. */ - jerry_release_value (prop_value); - jerry_release_value (prop_name); - jerry_release_value (global_object); + jerry_value_free (prop_value); + jerry_value_free (prop_name); + jerry_value_free (global_object); return 0; } @@ -8962,30 +8561,30 @@ main (void) **See also** -- [jerry_has_property](#jerry_has_property) -- [jerry_has_own_property](#jerry_has_own_property) -- [jerry_delete_property](#jerry_delete_property) -- [jerry_delete_property_by_index](#jerry_delete_property_by_index) -- [jerry_set_property](#jerry_set_property) -- [jerry_get_property_by_index](#jerry_get_property_by_index) -- [jerry_set_property_by_index](#jerry_set_property_by_index) +- [jerry_object_has](#jerry_object_has) +- [jerry_object_has_own](#jerry_object_has_own) +- [jerry_object_delete](#jerry_object_delete) +- [jerry_object_delete_index](#jerry_object_delete_index) +- [jerry_object_set](#jerry_object_set) +- [jerry_object_get_index](#jerry_object_get_index) +- [jerry_object_set_index](#jerry_object_set_index) -## jerry_get_property_by_index +## jerry_object_get_index **Summary** Get value by an index from the specified object. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_get_property_by_index (const jerry_value_t obj_val, - uint32_t index); +jerry_object_get_index (const jerry_value_t obj_val, + uint32_t index); ``` - `obj_val` - object value @@ -9000,28 +8599,28 @@ jerry_get_property_by_index (const jerry_value_t obj_val, { jerry_value_t object; - ... // create or acquire object + ... // create or copy object - jerry_value_t value = jerry_get_property_by_index (object, 5); + jerry_value_t value = jerry_object_get_index (object, 5); ... - jerry_release_value (value); - jerry_release_value (object); + jerry_value_free (value); + jerry_value_free (object); } ``` **See also** -- [jerry_has_property](#jerry_has_property) -- [jerry_has_own_property](#jerry_has_own_property) -- [jerry_delete_property](#jerry_delete_property) -- [jerry_delete_property_by_index](#jerry_delete_property_by_index) -- [jerry_get_property](#jerry_get_property) -- [jerry_set_property](#jerry_set_property) -- [jerry_set_property_by_index](#jerry_set_property_by_index) +- [jerry_object_has](#jerry_object_has) +- [jerry_object_has_own](#jerry_object_has_own) +- [jerry_object_delete](#jerry_object_delete) +- [jerry_object_delete_index](#jerry_object_delete_index) +- [jerry_object_get](#jerry_object_get) +- [jerry_object_set](#jerry_object_set) +- [jerry_object_set_index](#jerry_object_set_index) -## jerry_get_own_property +## jerry_object_find_own **Summary** @@ -9031,7 +8630,7 @@ The receiver is passed as the `this` argument for getters, and the receiver argument for Proxy `get` traps. *Notes*: - - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. - The `found_p` argument is ignored if its value is NULL. - The target value of `found_p` argument is set to false when the arguments are invalid, e.g. `obj_val` is not an object. @@ -9039,10 +8638,10 @@ argument for Proxy `get` traps. ```c jerry_value_t -jerry_get_own_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val, - const jerry_value_t receiver_val, - bool *found_p); +jerry_object_find_own (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + const jerry_value_t receiver_val, + bool *found_p); ``` - `obj_val` - object value @@ -9051,7 +8650,7 @@ jerry_get_own_property (const jerry_value_t obj_val, - `found_p` - [out] true, if the property is found or obj_val is a Proxy object, false otherwise - return value - value of property, if success - - thrown error, otherwise + - thrown exception, otherwise **Example** @@ -9066,11 +8665,11 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "Object"); + jerry_value_t global_object = jerry_current_realm (); + jerry_value_t prop_name = jerry_string_sz ("Object"); bool found; - jerry_value_t prop_value = jerry_get_own_property (global_object, prop_name, global_object, &found); + jerry_value_t prop_value = jerry_object_find_own (global_object, prop_name, global_object, &found); if (found) { @@ -9079,9 +8678,9 @@ main (void) /* use "prop_value" then release it. */ - jerry_release_value (prop_value); - jerry_release_value (prop_name); - jerry_release_value (global_object); + jerry_value_free (prop_value); + jerry_value_free (prop_name); + jerry_value_free (global_object); return 0; } @@ -9089,27 +8688,27 @@ main (void) **See also** -- [jerry_get_property](#jerry_get_property) -- [jerry_get_property_by_index](#jerry_get_property_by_index) +- [jerry_object_get](#jerry_object_get) +- [jerry_object_get_index](#jerry_object_get_index) -## jerry_get_internal_property +## jerry_object_get_internal **Summary** Get value of an internal property to the specified object with the given name. *Note*: - - Properties which were not created with [jerry_set_internal_property](#jerry_set_internal_property) are excluded + - 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_release_value](#jerry_release_value) when it + - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_get_internal_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val); +jerry_object_get_internal (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); ``` - `obj_val` - object value @@ -9117,7 +8716,7 @@ jerry_get_internal_property (const jerry_value_t obj_val, - return value - value of property, if the internal property exists - undefined value, if the, if the internal does not property exists - - thrown error, otherwise + - thrown exception, otherwise *New in version 2.2*. @@ -9133,16 +8732,16 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property"); + jerry_value_t global_object = jerry_current_realm (); + jerry_value_t prop_name = jerry_string_sz ("hidden_property"); - jerry_value_t prop_value = jerry_get_internal_property (global_object, prop_name); + jerry_value_t prop_value = jerry_object_get_internal (global_object, prop_name); /* use "prop_value" then release it. */ - jerry_release_value (prop_value); - jerry_release_value (prop_name); - jerry_release_value (global_object); + jerry_value_free (prop_value); + jerry_value_free (prop_name); + jerry_value_free (global_object); return 0; } @@ -9150,27 +8749,27 @@ main (void) **See also** -- [jerry_has_internal_property](#jerry_has_internal_property) -- [jerry_delete_internal_property](#jerry_delete_internal_property) -- [jerry_set_internal_property](#jerry_set_internal_property) +- [jerry_object_has_internal](#jerry_object_has_internal) +- [jerry_object_delete_internal](#jerry_object_delete_internal) +- [jerry_object_set_internal](#jerry_object_set_internal) -## jerry_set_property +## jerry_object_set **Summary** Set a property to the specified object with the given name. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_set_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val, - const jerry_value_t value_to_set) +jerry_object_set (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + const jerry_value_t value_to_set) ``` - `obj_val` - object value @@ -9178,7 +8777,7 @@ jerry_set_property (const jerry_value_t obj_val, - `value_to_set` - value to set - return value - true, if success - - thrown error, otherwise + - thrown exception, otherwise **Example** @@ -9186,52 +8785,52 @@ jerry_set_property (const jerry_value_t obj_val, { jerry_value_t value_to_set; - ... // create or acquire value to set + ... // create or copy value to set - jerry_value_t glob_obj = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); + jerry_value_t glob_obj = jerry_current_realm (); + jerry_value_t prop_name = jerry_string_sz ("my_prop"); - jerry_value_t set_result = jerry_set_property (glob_obj, prop_name, value_to_set); + jerry_value_t set_result = jerry_object_set (glob_obj, prop_name, value_to_set); ... // check result of property set call - jerry_release_value (set_result); - jerry_release_value (prop_name); + jerry_value_free (set_result); + jerry_value_free (prop_name); ... - jerry_release_value (value_to_set); - jerry_release_value (glob_obj); + jerry_value_free (value_to_set); + jerry_value_free (glob_obj); } ``` **See also** -- [jerry_has_property](#jerry_has_property) -- [jerry_has_own_property](#jerry_has_own_property) -- [jerry_delete_property](#jerry_delete_property) -- [jerry_delete_property_by_index](#jerry_delete_property_by_index) -- [jerry_get_property](#jerry_get_property) -- [jerry_get_property_by_index](#jerry_get_property_by_index) -- [jerry_set_property_by_index](#jerry_set_property_by_index) +- [jerry_object_has](#jerry_object_has) +- [jerry_object_has_own](#jerry_object_has_own) +- [jerry_object_delete](#jerry_object_delete) +- [jerry_object_delete_index](#jerry_object_delete_index) +- [jerry_object_get](#jerry_object_get) +- [jerry_object_get_index](#jerry_object_get_index) +- [jerry_object_set_index](#jerry_object_set_index) -## jerry_set_property_by_index +## jerry_object_set_index **Summary** Set indexed value in the specified object -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_set_property_by_index (const jerry_value_t obj_val, - uint32_t index, - const jerry_value_t value_to_set); +jerry_object_set_index (const jerry_value_t obj_val, + uint32_t index, + const jerry_value_t value_to_set); ``` - `obj_val` - object value @@ -9248,30 +8847,30 @@ jerry_set_property_by_index (const jerry_value_t obj_val, jerry_value_t object; jerry_value_t value_to_set; - ... // create or acquire object and value to set + ... // create or copy object and value to set - jerry_value_t ret_val = jerry_set_property_by_index (object, 5, value_to_set); + jerry_value_t ret_val = jerry_object_set_index (object, 5, value_to_set); ... - jerry_release_value (value_to_set); - jerry_release_value (ret_val); - jerry_release_value (object); + jerry_value_free (value_to_set); + jerry_value_free (ret_val); + jerry_value_free (object); } ``` **See also** -- [jerry_has_property](#jerry_has_property) -- [jerry_has_own_property](#jerry_has_own_property) -- [jerry_delete_property](#jerry_delete_property) -- [jerry_delete_property_by_index](#jerry_delete_property_by_index) -- [jerry_get_property](#jerry_get_property) -- [jerry_set_property](#jerry_set_property) -- [jerry_get_property_by_index](#jerry_get_property_by_index) +- [jerry_object_has](#jerry_object_has) +- [jerry_object_has_own](#jerry_object_has_own) +- [jerry_object_delete](#jerry_object_delete) +- [jerry_object_delete_index](#jerry_object_delete_index) +- [jerry_object_get](#jerry_object_get) +- [jerry_object_set](#jerry_object_set) +- [jerry_object_get_index](#jerry_object_get_index) -## jerry_set_internal_property +## jerry_object_set_internal **Summary** @@ -9279,16 +8878,16 @@ Set an internal property to the specified object with the given name. *Note*: - The property cannot be accessed from the JavaScript context, only from the public API. - - It is different from [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) in that any jerry API value + - It is different from [jerry_object_set_native_ptr](#jerry_object_set_native_ptr) in that any jerry API value can be hidden from the JavaScript context, not only native pointers. **Prototype** ```c bool -jerry_set_internal_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val, - const jerry_value_t value_to_set) +jerry_object_set_internal (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + const jerry_value_t value_to_set) ``` - `obj_val` - object value @@ -9296,7 +8895,7 @@ jerry_set_internal_property (const jerry_value_t obj_val, - `value_to_set` - value to set - return value - true, if success - - thrown error, otherwise + - thrown exception, otherwise *New in version 2.2*. @@ -9312,17 +8911,17 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property"); - jerry_value_t value_to_set = jerry_create_number (5); + jerry_value_t global_object = jerry_current_realm (); + jerry_value_t prop_name = jerry_string_sz ("hidden_property"); + jerry_value_t value_to_set = jerry_number (5); - bool set_result = jerry_set_internal_property (global_object, prop_name, value_to_set); + bool set_result = jerry_object_set_internal (global_object, prop_name, value_to_set); /* check the result of internal property set call */ - jerry_release_value (value_to_set); - jerry_release_value (prop_name); - jerry_release_value (global_object); + jerry_value_free (value_to_set); + jerry_value_free (prop_name); + jerry_value_free (global_object); return 0; } @@ -9330,12 +8929,12 @@ main (void) **See also** -- [jerry_has_internal_property](#jerry_has_internal_property) -- [jerry_delete_internal_property](#jerry_delete_internal_property) -- [jerry_get_internal_property](#jerry_get_internal_property) +- [jerry_object_has_internal](#jerry_object_has_internal) +- [jerry_object_delete_internal](#jerry_object_delete_internal) +- [jerry_object_get_internal](#jerry_object_get_internal) -## jerry_property_descriptor_create +## jerry_property_descriptor **Summary** @@ -9346,7 +8945,7 @@ the `jerry_property_descriptor_t` struct will be set to zero or false depending ```c jerry_property_descriptor_t -jerry_property_descriptor_create (void); +jerry_property_descriptor (void); ``` *New in version [[NEXT_RELEASE]]*: Replaces `jerry_init_property_descriptor_fields`. @@ -9355,7 +8954,7 @@ jerry_property_descriptor_create (void); ```c { - jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor (); ... // usage of prop_desc @@ -9363,32 +8962,32 @@ jerry_property_descriptor_create (void); } ``` -For a more complete example see [jerry_define_own_property](#jerry_define_own_property). +For a more complete example see [jerry_object_define_own_prop](#jerry_object_define_own_prop). **See also** - [jerry_property_descriptor_t](#jerry_property_descriptor_t) -- [jerry_define_own_property](#jerry_define_own_property) -- [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) +- [jerry_object_define_own_prop](#jerry_object_define_own_prop) +- [jerry_object_get_own_prop](#jerry_object_get_own_prop) - [jerry_property_descriptor_free](#jerry_property_descriptor_free) -## jerry_define_own_property +## jerry_object_define_own_prop **Summary** Define a property to the specified object with the given name. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_define_own_property (const jerry_value_t obj_val, - const jerry_value_t prop_name_val, - const jerry_property_descriptor_t *prop_desc_p); +jerry_object_define_own_prop (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + const jerry_property_descriptor_t *prop_desc_p); ``` - `obj_val` - target object where the property should be registered @@ -9396,11 +8995,11 @@ jerry_define_own_property (const jerry_value_t obj_val, - `prop_desc_p` - pointer to property descriptor - return value - true, if success - - thrown error, otherwise + - thrown exception, otherwise **Example** -Registering a simple value property via the `jerry_define_own_property` method: +Registering a simple value property via the `jerry_object_define_own_prop` method: [doctest]: # (name="02.API-REFERENCE-define-property.c") @@ -9412,14 +9011,14 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global_obj_val = jerry_get_global_object (); + jerry_value_t global_obj_val = jerry_current_realm (); // configure the property - jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor (); - // create or acquire value to set + // create or copy value to set // For example: - jerry_value_t value_to_set = jerry_create_number (33); + jerry_value_t value_to_set = jerry_number (33); // set the property descriptor fields: // set the "JERRY_PROP_IS_VALUE_DEFINED" flag to indicate the "value" @@ -9437,28 +9036,28 @@ main (void) prop_desc.value = value_to_set; // add the property as "my_prop" for the global object - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); - jerry_value_t return_value = jerry_define_own_property (global_obj_val, prop_name, &prop_desc); - if (jerry_value_is_error (return_value)) + jerry_value_t prop_name = jerry_string_sz ("my_prop"); + jerry_value_t return_value = jerry_object_define_own_prop (global_obj_val, prop_name, &prop_desc); + if (jerry_value_is_exception (return_value)) { // there was an error } // re-define the property with the enumerable flag set to false prop_desc.flags &= (uint16_t) ~JERRY_PROP_IS_ENUMERABLE; - return_value = jerry_define_own_property (global_obj_val, prop_name, &prop_desc); - if (jerry_value_is_error (return_value)) + return_value = jerry_object_define_own_prop (global_obj_val, prop_name, &prop_desc); + if (jerry_value_is_exception (return_value)) { // there was an error } - // if there was no error at this point the global object should have a "my_prop" property + // if there was no exception at this point the global object should have a "my_prop" property - jerry_release_value (return_value); - jerry_release_value (prop_name); + jerry_value_free (return_value); + jerry_value_free (prop_name); jerry_property_descriptor_free (&prop_desc); - jerry_release_value (global_obj_val); + jerry_value_free (global_obj_val); jerry_cleanup (); return 0; @@ -9466,7 +9065,7 @@ main (void) ``` -Registering a getter/setter property via the `jerry_define_own_property` method: +Registering a getter/setter property via the `jerry_object_define_own_prop` method: [doctest]: # (name="02.API-REFERENCE-define-property-getset.c") @@ -9485,7 +9084,7 @@ method_getter (const jerry_call_info_t *call_info_p, counter++; printf("Getter called, returning: %d\n", counter); - return jerry_create_number (counter); + return jerry_number (counter); } static jerry_value_t @@ -9496,12 +9095,12 @@ method_setter (const jerry_call_info_t *call_info_p, // Note: the arguments count and type should be checked // in this example it is omitted! - double new_value = jerry_get_number_value (args[0]); + double new_value = jerry_value_as_number (args[0]); counter = (int) new_value; printf("Setter called, setting: %d\n", counter); - return jerry_create_undefined (); + return jerry_undefined (); } int @@ -9509,32 +9108,32 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global_obj_val = jerry_get_global_object (); + jerry_value_t global_obj_val = jerry_current_realm (); // configure the property - jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor (); // set the property descriptor fields: prop_desc.flags |= JERRY_PROP_IS_GET_DEFINED | JERRY_PROP_IS_SET_DEFINED; - prop_desc.getter = jerry_create_external_function (method_getter); - prop_desc.setter = jerry_create_external_function (method_setter); + prop_desc.getter = jerry_function_external (method_getter); + prop_desc.setter = jerry_function_external (method_setter); // add the property as "my_prop" for the global object - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); - jerry_value_t return_value = jerry_define_own_property (global_obj_val, prop_name, &prop_desc); - if (jerry_value_is_error (return_value)) + jerry_value_t prop_name = jerry_string_sz ("my_prop"); + jerry_value_t return_value = jerry_object_define_own_prop (global_obj_val, prop_name, &prop_desc); + if (jerry_value_is_exception (return_value)) { // there was an error } - // if there was no error at this point the global object should have a "my_prop" property + // if there was no exception at this point the global object should have a "my_prop" property - jerry_release_value (return_value); - jerry_release_value (prop_name); + jerry_value_free (return_value); + jerry_value_free (prop_name); jerry_property_descriptor_free (&prop_desc); - jerry_release_value (global_obj_val); + jerry_value_free (global_obj_val); // run an example js code to use the getter/setters @@ -9542,7 +9141,7 @@ main (void) jerry_value_t eval_result = jerry_eval ((const jerry_char_t *) src_p, strlen (src_p), JERRY_PARSE_NO_OPTS); // "eval_result" is the last result of "this.my_prop" that is "5" currently. - double result_number = jerry_get_number_value (eval_result); + double result_number = jerry_value_as_number (eval_result); printf("output: %lf\n", result_number); jerry_cleanup (); @@ -9554,12 +9153,12 @@ main (void) **See also** - [jerry_property_descriptor_t](#jerry_property_descriptor_t) -- [jerry_property_descriptor_create](#jerry_property_descriptor_create) -- [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) +- [jerry_property_descriptor](#jerry_property_descriptor) +- [jerry_object_get_own_prop](#jerry_object_get_own_prop) - [jerry_property_descriptor_free](#jerry_property_descriptor_free) -## jerry_get_own_property_descriptor +## jerry_object_get_own_prop **Summary** @@ -9569,9 +9168,9 @@ Construct property descriptor from specified property. ```c jerry_value_t -jerry_get_own_property_descriptor (const jerry_value_t obj_val, - const jerry_value_t prop_name_val, - jerry_property_descriptor_t *prop_desc_p); +jerry_object_get_own_prop (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + jerry_property_descriptor_t *prop_desc_p); ``` - `obj_val` - object value @@ -9585,26 +9184,26 @@ jerry_get_own_property_descriptor (const jerry_value_t obj_val, ```c { - jerry_value_t global_obj_val = jerry_get_global_object (); + jerry_value_t global_obj_val = jerry_current_realm (); - jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); - jerry_get_own_property_descriptor (global_obj_val, prop_name, &prop_desc); - jerry_release_value (prop_name); + jerry_value_t prop_name = jerry_string_sz ("my_prop"); + jerry_object_get_own_prop (global_obj_val, prop_name, &prop_desc); + jerry_value_free (prop_name); ... // usage of property descriptor jerry_property_descriptor_free (&prop_desc); - jerry_release_value (global_obj_val); + jerry_value_free (global_obj_val); } ``` **See also** - [jerry_property_descriptor_t](#jerry_property_descriptor_t) -- [jerry_property_descriptor_create](#jerry_property_descriptor_create) -- [jerry_define_own_property](#jerry_define_own_property) +- [jerry_property_descriptor](#jerry_property_descriptor) +- [jerry_object_define_own_prop](#jerry_object_define_own_prop) - [jerry_property_descriptor_free](#jerry_property_descriptor_free) @@ -9629,7 +9228,7 @@ jerry_property_descriptor_free (const jerry_property_descriptor_t *prop_desc_p); ```c { - jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor (); ... // usage of property descriptor @@ -9639,30 +9238,29 @@ jerry_property_descriptor_free (const jerry_property_descriptor_t *prop_desc_p); **See also** -- [jerry_property_descriptor_create](#jerry_property_descriptor_create) -- [jerry_define_own_property](#jerry_define_own_property) -- [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) +- [jerry_property_descriptor](#jerry_property_descriptor) +- [jerry_object_define_own_prop](#jerry_object_define_own_prop) +- [jerry_object_get_own_prop](#jerry_object_get_own_prop) -## jerry_call_function +## jerry_call **Summary** -Call function specified by a function value. Error flag must -not be set for any arguments of this function. Value of `this` -parameter should be set to `undefined` for non-method calls. +Call function specified by a function value. The argument values must not be exceptions. +Value of `this` parameter should be set to `undefined` for non-method calls. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_call_function (const jerry_value_t func_obj_val, - const jerry_value_t this_val, - const jerry_value_t args_p[], - jerry_size_t args_count); +jerry_call (const jerry_value_t func_obj_val, + const jerry_value_t this_val, + const jerry_value_t args_p[], + jerry_size_t args_count); ``` - `func_obj_val` - the function object to call @@ -9681,45 +9279,45 @@ jerry_call_function (const jerry_value_t func_obj_val, if (jerry_value_is_function (target_function)) { - jerry_value_t this_val = jerry_create_undefined (); - jerry_value_t ret_val = jerry_call_function (target_function, this_val, NULL, 0); + jerry_value_t this_val = jerry_undefined (); + jerry_value_t ret_val = jerry_call (target_function, this_val, NULL, 0); - if (!jerry_value_is_error (ret_val)) + if (!jerry_value_is_exception (ret_val)) { ... // handle return value } - jerry_release_value (ret_val); - jerry_release_value (this_val); + jerry_value_free (ret_val); + jerry_value_free (this_val); } - jerry_release_value (target_function); + jerry_value_free (target_function); } ``` **See also** - [jerry_is_function](#jerry_is_function) -- [jerry_create_external_function](#jerry_create_external_function) +- [jerry_function_external](#jerry_function_external) -## jerry_construct_object +## jerry_construct **Summary** Construct object, invoking specified function object as constructor. Error flag must not be set for any arguments of this function. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_construct_object (const jerry_value_t func_obj_val, - const jerry_value_t args_p[], - jerry_size_t args_count); +jerry_construct (const jerry_value_t func_obj_val, + const jerry_value_t args_p[], + jerry_size_t args_count); ``` - `func_obj_val` - function object to call @@ -9737,14 +9335,14 @@ jerry_construct_object (const jerry_value_t func_obj_val, if (jerry_is_constructor (val)) { - jerry_value_t ret_val = jerry_construct_object (val, NULL, 0); + jerry_value_t ret_val = jerry_construct (val, NULL, 0); - if (!jerry_value_is_error (ret_val)) + if (!jerry_value_is_exception (ret_val)) { ... // handle return value } - jerry_release_value (ret_val); + jerry_value_free (ret_val); } } ``` @@ -9754,112 +9352,112 @@ jerry_construct_object (const jerry_value_t func_obj_val, - [jerry_is_constructor](#jerry_is_constructor) -## jerry_get_object_keys +## jerry_object_keys **Summary** Get keys of the specified object value. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_get_object_keys (const jerry_value_t obj_val); +jerry_object_keys (const jerry_value_t obj_val); ``` - `obj_val` - object value - return value - array object value, if success - - thrown error, otherwise + - thrown exception, otherwise **Example** ```c { jerry_value_t object; - ... // create or acquire object + ... // create or copy object - jerry_value_t keys_array = jerry_get_object_keys (object); + jerry_value_t keys_array = jerry_object_keys (object); ... // usage of keys_array - jerry_release_value (keys_array); + jerry_value_free (keys_array); } ``` **See also** -- [jerry_get_property](#jerry_get_property) -- [jerry_set_property](#jerry_set_property) +- [jerry_object_get](#jerry_object_get) +- [jerry_object_set](#jerry_object_set) -## jerry_get_prototype +## jerry_object_proto **Summary** Get the prototype of the specified object. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_get_prototype (const jerry_value_t obj_val); +jerry_object_proto (const jerry_value_t obj_val); ``` - `obj_val` - object value - return value - object value, if success - - null or thrown error, otherwise + - null or thrown exception, otherwise **Example** ```c { jerry_value_t object; - ... // create or acquire object + ... // create or copy object - jerry_value_t prototype = jerry_get_prototype (object); + jerry_value_t prototype = jerry_object_proto (object); ... // usage of prototype object - jerry_release_value (prototype); - jerry_release_value (object); + jerry_value_free (prototype); + jerry_value_free (object); } ``` **See also** -- [jerry_set_prototype](#jerry_set_prototype) +- [jerry_object_set_proto](#jerry_object_set_proto) -## jerry_set_prototype +## jerry_object_set_proto **Summary** Set the prototype of the specified object. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_set_prototype (const jerry_value_t obj_val, - const jerry_value_t proto_obj_val); +jerry_object_set_proto (const jerry_value_t obj_val, + const jerry_value_t proto_obj_val); ``` - `obj_val` - object value - `proto_obj_val` - prototype object value - return value - true, if success - - thrown error, otherwise + - thrown exception, otherwise **Example** @@ -9868,47 +9466,43 @@ jerry_set_prototype (const jerry_value_t obj_val, jerry_value_t object; jerry_value_t prototype; - ... // create or acquire object and prototype + ... // create or copy object and prototype - jerry_value_t ret_val = jerry_set_prototype (object, prototype); + jerry_value_t ret_val = jerry_object_set_proto (object, prototype); - jerry_release_value (ret_val); - jerry_release_value (prototype); - jerry_release_value (object); + jerry_value_free (ret_val); + jerry_value_free (prototype); + jerry_value_free (object); } ``` **See also** -- [jerry_get_prototype](#jerry_get_prototype) +- [jerry_object_proto](#jerry_object_proto) -## jerry_get_object_native_pointer +## jerry_object_get_native_ptr **Summary** Get native pointer by the given type information. The pointer and the type information are previously associated with the object by -[jerry_set_object_native_pointer](#jerry_set_object_native_pointer). +[jerry_object_set_native_ptr](#jerry_object_set_native_ptr). -*Note*: `out_native_pointer_p` can be NULL, and it means the - caller doesn't want to get the native_pointer. +*Note*: `native_info_p` can be NULL **Prototype** ```c -bool -jerry_get_object_native_pointer (const jerry_value_t obj_val, - void **out_native_pointer_p, - const jerry_object_native_info_t *native_info_p) +void * +jerry_object_get_native_ptr (const jerry_value_t object, + const jerry_object_native_info_t *native_info_p) ``` -- `obj_val` - object value to get native pointer from. -- `out_native_pointer_p` - native pointer (output parameter). +- `object` - object value to get native pointer from. - `native_info_p` - native pointer's type information. - return value - - true, if there is native pointer associated of the specified object with the given native type info - - false, otherwise + - 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`. @@ -10006,10 +9600,9 @@ print_buffer (char *data_p, static void do_stuff (jerry_value_t object) { - void *native_p; - bool has_p = jerry_get_object_native_pointer (object, &native_p, &buffer_obj_type_info); + void *native_p = jerry_object_get_native_ptr (object, &buffer_obj_type_info); - if (!has_p) + if (native_p == NULL) { // Process the error return; @@ -10023,9 +9616,9 @@ do_stuff (jerry_value_t object) if (need_shape_info) { - has_p = jerry_get_object_native_pointer (object, &native_p, &shape_obj_type_info); + native_p = jerry_object_get_native_ptr (object, &shape_obj_type_info); - if (!has_p) + if (native_p == NULL) { // Process the error return; @@ -10041,9 +9634,9 @@ do_stuff (jerry_value_t object) if (need_secret_info) { - has_p = jerry_get_object_native_pointer (object, &native_p, NULL); + native_p = jerry_object_get_native_ptr (object, NULL); - if (!has_p) + if (native_p == NULL) { // Process the error return; @@ -10051,7 +9644,7 @@ do_stuff (jerry_value_t object) printf("Secret: %d\n", (int)((uintptr_t) native_p)); // Usage of native_p - bool deleted = jerry_delete_object_native_pointer (object, NULL); + bool deleted = jerry_object_delete_native_ptr (object, NULL); if (deleted) { @@ -10065,29 +9658,29 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t object = jerry_create_object (); + jerry_value_t object = jerry_object (); buffer_native_object_t *buffer_p = (buffer_native_object_t *) malloc (sizeof (buffer_native_object_t)); buffer_p->length = 14; buffer_p->data_p = (char *) malloc (buffer_p->length * sizeof (char)); memcpy (buffer_p->data_p, "My buffer data", buffer_p->length); - jerry_set_object_native_pointer (object, buffer_p, &buffer_obj_type_info); + jerry_object_set_native_ptr (object, &buffer_obj_type_info, buffer_p); shape_native_object_t *shape_p = (shape_native_object_t *) malloc (sizeof (shape_native_object_t)); shape_p->area = 6; shape_p->perimeter = 12; - jerry_set_object_native_pointer (object, shape_p, &shape_obj_type_info); + jerry_object_set_native_ptr (object, &shape_obj_type_info, shape_p); // The native pointer can be NULL. This gives possibly to get notified via the native type info's // free callback when the object has been freed by the GC. - jerry_set_object_native_pointer (object, NULL, &destructor_obj_type_info); + jerry_object_set_native_ptr (object, &destructor_obj_type_info, NULL); // The native type info can be NULL as well. In this case the registered property is simply freed // when the object is freed by the GC. - jerry_set_object_native_pointer (object, SECRET_INFO, NULL); + jerry_object_set_native_ptr (object, NULL, SECRET_INFO); do_stuff (object); - jerry_release_value (object); + jerry_value_free (object); jerry_cleanup (); return 0; @@ -10096,17 +9689,17 @@ main (void) **See also** -- [jerry_create_object](#jerry_create_object) -- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) +- [jerry_object](#jerry_object) +- [jerry_object_set_native_ptr](#jerry_object_set_native_ptr) - [jerry_object_native_info_t](#jerry_object_native_info_t) -## jerry_set_object_native_pointer +## jerry_object_set_native_ptr **Summary** Set native pointer and an optional type information for the specified object. -You can get them by calling [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) later. +You can get them by calling [jerry_object_get_native_ptr](#jerry_object_get_native_ptr) later. *Notes*: - If a native pointer was already set for the object with the same type information, its value is updated. @@ -10117,37 +9710,37 @@ You can get them by calling [jerry_get_object_native_pointer](#jerry_get_object_ - The free callback can invoke API functions. *Note*: If possible do not store API values in native pointers, rather check - [jerry_set_internal_property](#jerry_set_internal_property). + [jerry_object_set_internal](#jerry_object_set_internal). **Prototype** ```c void -jerry_set_object_native_pointer (const jerry_value_t obj_val, - void *native_p, - const jerry_object_native_info_t *info_p) +jerry_object_set_native_ptr (const jerry_value_t obj_val, + const jerry_object_native_info_t *info_p, + void *native_p); ``` - `obj_val` - object to set native pointer in. -- `native_p` - native pointer. - `info_p` - native pointer's type information or NULL. When used, this should be a long-lived pointer, usually a pointer to a `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`. **Example** -See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) for a +See [jerry_object_get_native_ptr](#jerry_object_get_native_ptr) for a best-practice example. **See also** -- [jerry_create_object](#jerry_create_object) -- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) +- [jerry_object](#jerry_object) +- [jerry_object_get_native_ptr](#jerry_object_get_native_ptr) - [jerry_object_native_info_t](#jerry_object_native_info_t) -## jerry_delete_object_native_pointer +## jerry_object_delete_native_ptr **Summary** @@ -10164,8 +9757,8 @@ Delete the native pointer of the specified object associated with the given nati ```c bool -jerry_delete_object_native_pointer (const jerry_value_t obj_val, - const jerry_object_native_info_t *info_p) +jerry_object_delete_native_ptr (const jerry_value_t obj_val, + const jerry_object_native_info_t *info_p) ``` - `obj_val` - object to delete native pointer from. @@ -10175,25 +9768,25 @@ jerry_delete_object_native_pointer (const jerry_value_t obj_val, **Example** -See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) for a +See [jerry_object_get_native_ptr](#jerry_object_get_native_ptr) for a best-practice example. **See also** -- [jerry_create_object](#jerry_create_object) -- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) -- [jerry_get_object_native_pointer](#jerry_set_object_native_pointer) +- [jerry_object](#jerry_object) +- [jerry_object_get_native_ptr](#jerry_object_get_native_ptr) +- [jerry_object_get_native_ptr](#jerry_object_set_native_ptr) - [jerry_object_native_info_t](#jerry_object_native_info_t) -## jerry_native_pointer_init_references +## jerry_native_ptr_init **Summary** Initialize the references stored in a buffer pointed by a native pointer. The references are initialized to undefined. This function must be called before the buffer is attached to an object by -[jerry_set_object_native_pointer](#jerry_set_object_native_pointer). +[jerry_object_set_native_ptr](#jerry_object_set_native_ptr). *Note*: - The description of [jerry_object_native_info_t](#jerry_object_native_info_t) @@ -10203,8 +9796,8 @@ before the buffer is attached to an object by ```c void -jerry_native_pointer_init_references (void *native_pointer_p, - const jerry_object_native_info_t *native_info_p); +jerry_native_ptr_init (void *native_pointer_p, + const jerry_object_native_info_t *native_info_p); ``` - `native_pointer_p` - a valid non-NULL pointer to a native buffer. @@ -10233,7 +9826,7 @@ native_references_free_callback (void *native_p, /**< native pointer */ jerry_object_native_info_t *info_p) /**< native info */ { /* References must be finalized when a buffer is no longer attached. */ - jerry_native_pointer_release_references (native_p, info_p); + jerry_native_ptr_free (native_p, info_p); free (native_p); } /* native_references_free_callback */ @@ -10249,20 +9842,20 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t object_value = jerry_create_object (); + jerry_value_t object_value = jerry_object (); user_buffer_t *buffer_p = (user_buffer_t *) malloc (sizeof (user_buffer_t)); /* References must be initialized before a buffer is attached. */ - jerry_native_pointer_init_references ((void *) buffer_p, &native_info); + jerry_native_ptr_init ((void *) buffer_p, &native_info); - jerry_set_object_native_pointer (object_value, (void *) buffer_p, &native_info); + jerry_object_set_native_ptr (object_value, &native_info, (void *) buffer_p); /* References can be modified after the buffer is attached. * This example sets a self reference. */ - jerry_native_pointer_set_reference (&buffer_p->a, object_value); + jerry_native_ptr_set (&buffer_p->a, object_value); - jerry_release_value (object_value); + jerry_value_free (object_value); jerry_cleanup (); return 0; @@ -10271,11 +9864,11 @@ main (void) **See also** -- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) -- [jerry_native_pointer_release_references](#jerry_native_pointer_release_references) -- [jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference) +- [jerry_object_set_native_ptr](#jerry_object_set_native_ptr) +- [jerry_native_ptr_free](#jerry_native_ptr_free) +- [jerry_native_ptr_set](#jerry_native_ptr_set) -## jerry_native_pointer_release_references +## jerry_native_ptr_free **Summary** @@ -10283,7 +9876,7 @@ Release the value references stored in a buffer pointed by a native pointer. This function must be called after a buffer is no longer attached to any object, even if the buffer is attached to another object again. This function also initializes the values to undefined, so calling -[jerry_native_pointer_init_references](#jerry_native_pointer_init_references) +[jerry_native_ptr_init](#jerry_native_ptr_init) is optional before the buffer is attached again. *Note*: @@ -10294,8 +9887,8 @@ is optional before the buffer is attached again. ```c void -jerry_native_pointer_release_references (void *native_pointer_p, - const jerry_object_native_info_t *native_info_p); +jerry_native_ptr_free (void *native_pointer_p, + const jerry_object_native_info_t *native_info_p); ``` - `native_pointer_p` - a valid non-NULL pointer to a native buffer. @@ -10305,16 +9898,16 @@ jerry_native_pointer_release_references (void *native_pointer_p, **Example** -See the example of [jerry_native_pointer_init_references](#jerry_native_pointer_init_references). +See the example of [jerry_native_ptr_init](#jerry_native_ptr_init). **See also** -- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) -- [jerry_native_pointer_init_references](#jerry_native_pointer_init_references) -- [jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference) +- [jerry_object_set_native_ptr](#jerry_object_set_native_ptr) +- [jerry_native_ptr_init](#jerry_native_ptr_init) +- [jerry_native_ptr_set](#jerry_native_ptr_set) -## jerry_native_pointer_set_reference +## jerry_native_ptr_set **Summary** @@ -10331,8 +9924,8 @@ part of a buffer which is currently assigned to an object. ```c void -jerry_native_pointer_set_reference (jerry_value_t *reference_p, - jerry_value_t value) +jerry_native_ptr_set (jerry_value_t *reference_p, + jerry_value_t value) ``` - `reference_p` - a valid non-NULL pointer to a reference in a native buffer. @@ -10342,16 +9935,16 @@ jerry_native_pointer_set_reference (jerry_value_t *reference_p, **Example** -See the example of [jerry_native_pointer_init_references](#jerry_native_pointer_init_references). +See the example of [jerry_native_ptr_init](#jerry_native_ptr_init). **See also** -- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) -- [jerry_native_pointer_init_references](#jerry_native_pointer_init_references) -- [jerry_native_pointer_release_references](#jerry_native_pointer_release_references) +- [jerry_object_set_native_ptr](#jerry_object_set_native_ptr) +- [jerry_native_ptr_init](#jerry_native_ptr_init) +- [jerry_native_ptr_free](#jerry_native_ptr_free) -## jerry_object_get_property_names +## jerry_object_property_names **Summary** @@ -10361,15 +9954,15 @@ Gets the property keys for the given object using the selected filters. ```c jerry_value_t -jerry_object_get_property_names (jerry_value_t obj_val, - jerry_property_filter_t filter); +jerry_object_property_names (jerry_value_t obj_val, + jerry_property_filter_t filter); ``` - `obj_val` - object value - `filter` - any combination of [jerry_property_filter_t](#jerry_property_filter_t) options - return value - array containing the filtered property keys in successful operation - - error marked with error flag, otherwise + - exception, otherwise *New in version 2.4*. @@ -10377,13 +9970,13 @@ jerry_object_get_property_names (jerry_value_t obj_val, ```c { - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t keys = jerry_object_get_property_names (object, JERRY_PROPERTY_FILTER_ALL); + jerry_value_t global_object = jerry_current_realm (); + jerry_value_t keys = jerry_object_property_names (object, JERRY_PROPERTY_FILTER_ALL); ... // usage of keys - jerry_release_value (keys); - jerry_release_value (global_object); + jerry_value_free (keys); + jerry_value_free (global_object); } ``` @@ -10391,7 +9984,7 @@ jerry_object_get_property_names (jerry_value_t obj_val, - [jerry_property_filter_t](#jerry_property_filter_t) -## jerry_foreach_object_property +## jerry_object_foreach **Summary** @@ -10404,9 +9997,9 @@ If the method returns `false` the iteration will end. ```c bool -jerry_foreach_object_property (jerry_value_t obj_val, - jerry_object_property_foreach_t foreach_p, - void *user_data_p); +jerry_object_foreach (jerry_value_t obj_val, + jerry_object_property_foreach_cb_t foreach_p, + void *user_data_p); ``` - `obj_val` - object value @@ -10442,11 +10035,10 @@ foreach_function (const jerry_value_t prop_name, { if (jerry_value_is_string (prop_name)) { jerry_char_t string_buffer[128]; - jerry_size_t copied_bytes = jerry_substring_to_char_buffer (prop_name, - 0, - 127, - string_buffer, - 127); + jerry_size_t copied_bytes = jerry_string_to_buffer (prop_name, + JERRY_ENCODING_UTF8, + string_buffer, + sizeof (string_buffer) - 1); string_buffer[copied_bytes] = '\0'; printf ("Property: %s\n", string_buffer); @@ -10465,25 +10057,25 @@ main (void) jerry_init (JERRY_INIT_EMPTY); /* Construct an example object with a single property. */ - jerry_value_t object = jerry_create_object (); + jerry_value_t object = jerry_object (); { - jerry_value_t test_property = jerry_create_string ((const jerry_char_t *) "DemoProp"); - jerry_value_t test_value = jerry_create_number (3); + jerry_value_t test_property = jerry_string_sz ("DemoProp"); + jerry_value_t test_value = jerry_number (3); /* By default all properties added to an object are enumerable. */ - jerry_value_t set_result = jerry_set_property (object, test_property, test_value); - /* The `set_result` should be checked if it is an error or not. */ - jerry_release_value (set_result); - jerry_release_value (test_value); - jerry_release_value (test_property); + jerry_value_t set_result = jerry_object_set (object, test_property, test_value); + /* The `set_result` should be checked if it is an exception or not. */ + jerry_value_free (set_result); + jerry_value_free (test_value); + jerry_value_free (test_property); } /* Iterate on the object's properties with the given user data. */ struct iteration_data user_data = { 0 }; - bool iteration_result = jerry_foreach_object_property (object, foreach_function, &user_data); + bool iteration_result = jerry_object_foreach (object, foreach_function, &user_data); /* Check and process the `iteration_result` if required. */ - jerry_release_value (object); + jerry_value_free (object); jerry_cleanup (); @@ -10493,9 +10085,9 @@ main (void) **See also** -- [jerry_object_property_foreach_t](#jerry_object_property_foreach_t) +- [jerry_object_property_foreach_cb_t](#jerry_object_property_foreach_cb_t) -## jerry_objects_foreach +## jerry_foreach_live_object **Summary** @@ -10504,14 +10096,14 @@ Iterate over all objects available in the engine. The "iterator" `foreach_p` method should return `true` value to continue the search. If the method returns `false` the search for the object is finished. -*Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value). +*Note*: Values obtained in `foreach_p` must be retained using [jerry_value_copy](#jerry_value_copy). **Prototype** ```c bool -jerry_objects_foreach (jerry_objects_foreach_t foreach_p, - void *user_data_p); +jerry_foreach_live_object (jerry_foreach_live_object_cb_t foreach_p, + void *user_data_p); ``` - `foreach_p` - function that will be invoked for each object. @@ -10547,16 +10139,16 @@ find_my_object (const jerry_value_t candidate, find_my_object_info_t *info_p = (find_my_object_info_t *) user_data_p; /* Check if the given object has the required property. */ - jerry_value_t has_property = jerry_has_property (candidate, info_p->property_name); + jerry_value_t has_property = jerry_object_has (candidate, info_p->property_name); bool object_found = jerry_value_is_true (has_property); if (object_found) { - /* We found it, so we acquire the value and record it. */ - info_p->result = jerry_acquire_value (candidate); + /* We found it, so we copy the value and record it. */ + info_p->result = jerry_value_copy (candidate); } - jerry_release_value (has_property); + jerry_value_free (has_property); /* If the object was not found continue the search. */ return !object_found; @@ -10572,46 +10164,46 @@ main (void) /* Create the test object. */ { - jerry_value_t test_object = jerry_create_object (); + jerry_value_t test_object = jerry_object (); { - jerry_value_t test_property = jerry_create_string ((const jerry_char_t *) "DemoProp"); - jerry_value_t test_value = jerry_create_number (3); - jerry_value_t set_result = jerry_set_property (test_object, test_property, test_value); - /* The `set_result` should be checked if it is an error or not. */ - jerry_release_value (set_result); - jerry_release_value (test_value); - jerry_release_value (test_property); + jerry_value_t test_property = jerry_string_sz ("DemoProp"); + jerry_value_t test_value = jerry_number (3); + jerry_value_t set_result = jerry_object_set (test_object, test_property, test_value); + /* The `set_result` should be checked if it is an exception or not. */ + jerry_value_free (set_result); + jerry_value_free (test_value); + jerry_value_free (test_property); } { /* Register the test object into the global object. */ - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t demo_property = jerry_create_string ((const jerry_char_t *) "DemoObject"); - jerry_value_t set_result = jerry_set_property (global_object, demo_property, test_object); - /* The `set_result` should be checked if it is an error or not. */ - jerry_release_value (set_result); - jerry_release_value (demo_property); - jerry_release_value (global_object); + jerry_value_t global_object = jerry_current_realm (); + jerry_value_t demo_property = jerry_string_sz ("DemoObject"); + jerry_value_t set_result = jerry_object_set (global_object, demo_property, test_object); + /* The `set_result` should be checked if it is an exception or not. */ + jerry_value_free (set_result); + jerry_value_free (demo_property); + jerry_value_free (global_object); } - jerry_release_value (test_object); + jerry_value_free (test_object); } /* Look up the test object base on a property name. */ find_my_object_info_t search_info = { - .property_name = jerry_create_string ((const jerry_char_t *) "DemoProp") + .property_name = jerry_string_sz ("DemoProp") }; - if (jerry_objects_foreach (find_my_object, &search_info)) + if (jerry_foreach_live_object (find_my_object, &search_info)) { /* The search was successful. Do something useful with search_info.result. */ // ... printf ("Object found\n"); /* Release the found object after we're done using it. */ - jerry_release_value (search_info.result); + jerry_value_free (search_info.result); } else { @@ -10621,7 +10213,7 @@ main (void) return_value = 1; } - jerry_release_value (search_info.property_name); + jerry_value_free (search_info.property_name); /* Engine cleanup */ jerry_cleanup (); @@ -10631,9 +10223,9 @@ main (void) **See also** -- [jerry_objects_foreach_t](#jerry_objects_foreach_t) +- [jerry_foreach_live_object_cb_t](#jerry_foreach_live_object_cb_t) -## jerry_objects_foreach_by_native_info +## jerry_foreach_live_object_with_info **Summary** @@ -10642,15 +10234,15 @@ Iterate over all objects in the engine matching a certain native data type. The "iterator" `foreach_p` method should return `true` value to continue the search. If the method returns `false` the search for the object is finished. -*Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value). +*Note*: Values obtained in `foreach_p` must be retained using [jerry_value_copy](#jerry_value_copy). **Prototype** ```c bool -jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *native_info_p, - jerry_objects_foreach_by_native_info_t foreach_p, - void *user_data_p); +jerry_foreach_live_object_with_info (const jerry_object_native_info_t *native_info_p, + jerry_foreach_live_object_with_info_cb_t foreach_p, + void *user_data_p); ``` - `native_info_p` - native pointer's type information. @@ -10709,23 +10301,23 @@ static void add_object_with_nativeptr (int foo_value) { // construct object and native_set value: - jerry_value_t test_object = jerry_create_object (); + jerry_value_t test_object = jerry_object (); native_obj_t *native_obj_p = malloc (sizeof (*native_obj_p)); native_obj_p->foo = foo_value; native_obj_p->bar = true; - jerry_set_object_native_pointer (test_object, native_obj_p, &native_obj_type_info); + jerry_object_set_native_ptr (test_object, &native_obj_type_info, native_obj_p); /* Register the test object into the global object. */ - jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t demo_property = jerry_create_string ((const jerry_char_t *) "DemoObject"); - jerry_value_t set_result = jerry_set_property (global_object, demo_property, test_object); - /* The `set_result` should be checked if it is an error or not. */ - jerry_release_value (set_result); - jerry_release_value (demo_property); - jerry_release_value (global_object); - - jerry_release_value (test_object); + jerry_value_t global_object = jerry_current_realm (); + jerry_value_t demo_property = jerry_string_sz ("DemoObject"); + jerry_value_t set_result = jerry_object_set (global_object, demo_property, test_object); + /* The `set_result` should be checked if it is an exception or not. */ + jerry_value_free (set_result); + jerry_value_free (demo_property); + jerry_value_free (global_object); + + jerry_value_free (test_object); } /* create_object_with_nativeptr */ /* @@ -10740,8 +10332,8 @@ find_object (const jerry_value_t candidate, void *data_p, void *user_data_p) if (find_data_p->match_foo_value == native_obj_p->foo) { - /* If the object was found, acquire it and store it in the user data. */ - find_data_p->found_object = jerry_acquire_value (candidate); + /* If the object was found, copy it and store it in the user data. */ + find_data_p->found_object = jerry_value_copy (candidate); find_data_p->found_native_data_p = native_obj_p; /* Stop traversing over the objects. */ @@ -10766,12 +10358,12 @@ main (void) .match_foo_value = 3, }; - if (jerry_objects_foreach_by_native_info (&native_obj_type_info, find_object, &find_data)) + if (jerry_foreach_live_object_with_info (&native_obj_type_info, find_object, &find_data)) { /* The object was found and is now stored in `find_data.found_object`. After using it, it must be released. */ printf ("Object found, native foo value: %d\n", find_data.found_native_data_p->foo); - jerry_release_value (find_data.found_object); + jerry_value_free (find_data.found_object); } else { @@ -10786,20 +10378,20 @@ main (void) **See also** -- [jerry_create_object](#jerry_create_object) -- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) -- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) +- [jerry_object](#jerry_object) +- [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_objects_foreach](#jerry_objects_foreach) +- [jerry_foreach_live_object](#jerry_foreach_live_object) # Input validator functions -## jerry_is_valid_utf8_string +## jerry_validate_string **Summary** -Check if a given character buffer is a valid UTF-8 string. +Check if a given character buffer is a valid in the specified encoding string. **Notes**: Calling this method is safe in any time. It can be called even before engine initialization. @@ -10808,12 +10400,14 @@ even before engine initialization. ```c bool -jerry_is_valid_utf8_string (const jerry_char_t *utf8_buf_p, /**< UTF-8 string */ - jerry_size_t buf_size) /**< string size */ +jerry_validate_string (const jerry_char_t *buffer_p, /**< string data */ + jerry_size_t buf_size, /**< string size */ + jerry_encoding_t encoding); /**< encoding */ ``` -- `utf8_buf_p` - UTF-8 input string buffer. +- `buffer_p` - input string buffer. - `buf_size` - input string buffer size in bytes. +- `encoding` - string encoding - return value - true, if the provided string was a valid UTF-8 string. - false, if the string is not valid as an UTF-8 string. @@ -10833,89 +10427,21 @@ main (void) const jerry_char_t script[] = "print ('Hello, World!');"; const jerry_size_t script_size = sizeof (script) - 1; - if (jerry_is_valid_utf8_string (script, script_size)) + if (!jerry_validate_string (script, script_size, JERRY_ENCODING_CESU8)) { - jerry_run_simple (script, script_size, JERRY_INIT_EMPTY); - } - - return 0; -} -``` - -**See also** - -- [jerry_run_simple](#jerry_run_simple) -- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) -- [jerry_create_string_sz_from_utf8](#jerry_create_string_sz_from_utf8) -- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size) -- [jerry_get_utf8_string_length](#jerry_get_utf8_string_length) -- [jerry_string_to_utf8_char_buffer](#jerry_string_to_utf8_char_buffer) -- [jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer) - -## jerry_is_valid_cesu8_string - -**Summary** - -Check if a given character buffer is a valid CESU-8 string. - -**Notes**: Calling this method is safe in any time. It can be called -even before engine initialization. - -**Prototype** - -```c -bool -jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string */ - jerry_size_t buf_size) /**< string size */ -``` - -- `cesu8_buf_p` - CESU-8 input string buffer. -- `buf_size` - input string buffer size in bytes. -- return value - - true, if the provided string was a valid CESU-8 string. - - false, if the string is not valid as a CESU-8 string. - -*New in version 2.0*. - -**Example** - -[doctest]: # () - -```c -#include "jerryscript.h" - -int -main (void) -{ - jerry_init (JERRY_INIT_EMPTY); - - const jerry_char_t script[] = "Hello, World!"; - const jerry_size_t script_size = sizeof (script) - 1; - - if (jerry_is_valid_cesu8_string (script, script_size)) - { - jerry_value_t string_value = jerry_create_string_sz (script, - script_size); - - // usage of string_value - - jerry_release_value (string_value); + return 1; } - jerry_cleanup (); return 0; } ``` **See also** -- [jerry_create_string](#jerry_create_string) -- [jerry_create_string_sz](#jerry_create_string_sz) -- [jerry_get_string_size](#jerry_get_string_size) -- [jerry_get_string_length](#jerry_get_string_length) -- [jerry_string_to_char_buffer](#jerry_string_to_char_buffer) -- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer) - +- [jerry_string](#jerry_string) +- [jerry_string_size](#jerry_string_size) +- [jerry_string_length](#jerry_string_length) +- [jerry_string_to_buffer](#jerry_string_to_buffer) # Dynamic memory management functions @@ -10967,107 +10493,6 @@ void jerry_heap_free (void *mem_p, size_t size); - [jerry_heap_alloc](#jerry_heap_alloc) -# External context functions - -## jerry_create_context - -**Summary** - -Create an external JerryScript engine context. - -**Prototype** - -```c -jerry_context_t * -jerry_create_context (uint32_t heap_size, - jerry_context_alloc_t alloc, - void *cb_data_p); -``` - -- `heap_size` - requested heap size of the JerryScript context -- `alloc` - function for allocation -- `cb_data_p` - user data -- return value - - pointer to the newly created JerryScript context if success - - NULL otherwise. - -*New in version 2.0*. - -**Example** - -[doctest]: # (test="compile", name="02.API-REFERENCE-create-context.c") - -```c -#include <stdlib.h> -#include <pthread.h> - -#include "jerryscript.h" -#include "jerryscript-port.h" - -/* A different Thread Local Storage variable for each jerry context. */ -__thread jerry_context_t *tls_context; - -jerry_context_t * -jerry_port_get_current_context (void) -{ - /* Returns the context assigned to the thread. */ - return tls_context; -} - -/* Allocate JerryScript heap for each thread. */ -static void * -context_alloc_fn (size_t size, void *cb_data) -{ - (void) cb_data; - return malloc (size); -} - -static void * -thread_function (void *param) -{ - tls_context = jerry_create_context (512 * 1024, - context_alloc_fn, - NULL); - jerry_init (JERRY_INIT_EMPTY); - /* Run JerryScript in the context (e.g.: jerry_parse & jerry_run) */ - jerry_cleanup (); - - /* Deallocate JerryScript context */ - free (tls_context); - - return NULL; -} - -#define NUM_OF_THREADS 8 - -int -main (void) -{ - pthread_t threads[NUM_OF_THREADS]; - - /* Create the threads. */ - for (int i = 0; i < NUM_OF_THREADS; i++) - { - pthread_create (&threads[i], NULL, thread_function, (void *) (intptr_t) i); - } - - /* Wait for the threads to complete, and release their resources. */ - for (int i = 0; i < NUM_OF_THREADS; i++) - { - pthread_join (threads[i], NULL); - } - - return 0; -} -``` - -**See also** - -- [jerry_context_t](#jerry_context_t) -- [jerry_context_alloc_t](#jerry_context_alloc_t) -- [jerry_port_get_current_context](05.PORT-API.md#jerry_port_get_current_context) - - # Snapshot functions ## jerry_generate_snapshot @@ -11077,11 +10502,11 @@ main (void) Generate snapshot from the specified source code. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- 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_SNAPSHOT_SAVE`) and can be checked in runtime with - the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). - If the feature is not enabled the function will return an error. + the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_feature_enabled](#jerry_feature_enabled). + If the feature is not enabled the function will return an exception. **Prototype** @@ -11101,12 +10526,12 @@ jerry_generate_snapshot (jerry_value_t compiled_code, - the size of the generated snapshot in bytes as number value, if it was generated successfully (i.e. there are no syntax errors in source code, buffer size is sufficient, and snapshot support is enabled in current configuration through JERRY_SNAPSHOT_SAVE) - - thrown error, otherwise. + - thrown exception, otherwise. *New in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: The `source_p`, `source_size`, `resource_name_p`, - and `resource_name_length` arguments are replaced by `compiled_code` +*Changed in version [[NEXT_RELEASE]]*: 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 by calling `jerry_parse` with function arguments and using this method @@ -11135,14 +10560,14 @@ main (void) 0, global_mode_snapshot_buffer, buffer_size); - jerry_release_value (parse_result); + jerry_value_free (parse_result); - if (!jerry_value_is_error (generate_result)) + if (!jerry_value_is_exception (generate_result)) { - size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + size_t snapshot_size = (size_t) jerry_value_as_number (generate_result); } - jerry_release_value (generate_result); + jerry_value_free (generate_result); jerry_cleanup (); return 0; @@ -11164,11 +10589,11 @@ main (void) Execute/load snapshot from the specified buffer. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- 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_SNAPSHOT_EXEC`) and can be checked in runtime with - the `JERRY_FEATURE_SNAPSHOT_EXEC` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). - If the feature is not enabled the function will return an error. + the `JERRY_FEATURE_SNAPSHOT_EXEC` feature enum value, see [jerry_feature_enabled](#jerry_feature_enabled). + If the feature is not enabled the function will return an exception. **Prototype** @@ -11189,7 +10614,7 @@ jerry_exec_snapshot (const uint32_t *snapshot_p, [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t). - return value - result of bytecode, if run was successful. - - thrown error, otherwise (an error is reported if the snapshot execution feature is not enabled). + - 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. @@ -11221,12 +10646,12 @@ main (void) 0, snapshot_buffer, buffer_size); - jerry_release_value (parse_result); + jerry_value_free (parse_result); - /* 'generate_result' variable should be checked whether it contains an error. */ + /* 'generate_result' variable should be checked whether it contains an exception. */ - size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); - jerry_release_value (generate_result); + size_t snapshot_size = (size_t) jerry_value_as_number (generate_result); + jerry_value_free (generate_result); jerry_cleanup (); jerry_init (JERRY_INIT_EMPTY); @@ -11238,7 +10663,7 @@ main (void) NULL); /* 'res' now contains 'string from snapshot' */ - jerry_release_value (res); + jerry_value_free (res); jerry_cleanup (); return 0; @@ -11264,7 +10689,7 @@ main (void) jerry_parse_options_t parse_options; parse_options.options = JERRY_PARSE_HAS_ARGUMENT_LIST; - parse_options.argument_list = jerry_create_string ((const jerry_char_t *) "a, b"); + parse_options.argument_list = jerry_string_sz ("a, b"); jerry_value_t parse_result = jerry_parse (function_to_snapshot, sizeof (function_to_snapshot) - 1, @@ -11275,13 +10700,13 @@ main (void) 0, snapshot_buffer, buffer_size); - jerry_release_value (parse_result); - jerry_release_value (parse_options.argument_list); + jerry_value_free (parse_result); + jerry_value_free (parse_options.argument_list); - /* 'generate_result' variable should be checked whether it contains an error. */ + /* 'generate_result' variable should be checked whether it contains an exception. */ - size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); - jerry_release_value (generate_result); + size_t snapshot_size = (size_t) jerry_value_as_number (generate_result); + jerry_value_free (generate_result); jerry_cleanup (); jerry_init (JERRY_INIT_EMPTY); @@ -11293,19 +10718,19 @@ main (void) NULL); /* 'func' can be used now as a function object. */ - jerry_value_t this_value = jerry_create_undefined (); + jerry_value_t this_value = jerry_undefined (); jerry_value_t args[2]; - args[0] = jerry_create_number (1.0); - args[1] = jerry_create_number (2.0); + args[0] = jerry_number (1.0); + args[1] = jerry_number (2.0); - jerry_value_t res = jerry_call_function (func, this_value, args, 2); + jerry_value_t res = jerry_call (func, this_value, args, 2); /* 'res' now contains the value 3 as a jerry_value_t. */ - jerry_release_value (res); - jerry_release_value (args[0]); - jerry_release_value (args[1]); - jerry_release_value (this_value); - jerry_release_value (func); + jerry_value_free (res); + jerry_value_free (args[0]); + jerry_value_free (args[1]); + jerry_value_free (this_value); + jerry_value_free (func); jerry_cleanup (); return 0; @@ -11328,7 +10753,7 @@ None of these literals are magic strings. In C format only valid identifiers are *Note*: - This API depends on a build option (`JERRY_SNAPSHOT_SAVE`) and can be checked in runtime with - the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_feature_enabled](#jerry_feature_enabled). If the feature is not enabled the function will return zero. **Prototype** @@ -11380,10 +10805,10 @@ main (void) 0, snapshot_buffer, buffer_size); - jerry_release_value (parse_result); + jerry_value_free (parse_result); - size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); - jerry_release_value (generate_result); + size_t snapshot_size = (size_t) jerry_value_as_number (generate_result); + jerry_value_free (generate_result); const size_t literal_size = jerry_get_literals_from_snapshot (snapshot_buffer, snapshot_size, @@ -11412,7 +10837,7 @@ main (void) # Backtrace functions -## jerry_get_backtrace +## jerry_backtrace **Summary** @@ -11423,17 +10848,17 @@ The array length is zero if the backtrace is not available. This function is typically called from native callbacks. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. - This feature depends on build option (`JERRY_LINE_INFO`) and can be checked in runtime with the `JERRY_FEATURE_LINE_INFO` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c jerry_value_t -jerry_get_backtrace (uint32_t max_depth); +jerry_backtrace (uint32_t max_depth); ``` - `max_depth` - backtrace collection stops after reaching this value, 0 = unlimited @@ -11456,35 +10881,34 @@ backtrace_handler (const jerry_call_info_t *call_info_p, const jerry_value_t args_p[], const jerry_length_t args_count) { - if (!jerry_is_feature_enabled (JERRY_FEATURE_LINE_INFO)) + if (!jerry_feature_enabled (JERRY_FEATURE_LINE_INFO)) { printf ("Line info disabled, no backtrace will be printed\n"); - return jerry_create_undefined (); + return jerry_undefined (); } /* If the line info feature is disabled an empty array will be returned. */ - jerry_value_t backtrace_array = jerry_get_backtrace (5); - uint32_t array_length = jerry_get_array_length (backtrace_array); + jerry_value_t backtrace_array = jerry_backtrace (5); + uint32_t array_length = jerry_array_length (backtrace_array); for (uint32_t idx = 0; idx < array_length; idx++) { - jerry_value_t property = jerry_get_property_by_index (backtrace_array, idx); + jerry_value_t property = jerry_object_get_index (backtrace_array, idx); jerry_char_t string_buffer[64]; - jerry_size_t copied_bytes = jerry_substring_to_char_buffer (property, - 0, - 63, - string_buffer, - 63); + jerry_size_t copied_bytes = jerry_string_to_buffer (property, + JERRY_ENCODING_UTF8, + string_buffer, + sizeof (string_buffer) - 1); string_buffer[copied_bytes] = '\0'; printf(" %d: %s\n", idx, string_buffer); - jerry_release_value (property); + jerry_value_free (property); } - jerry_release_value (backtrace_array); + jerry_value_free (backtrace_array); - return jerry_create_undefined (); + return jerry_undefined (); } /* backtrace_handler */ int @@ -11492,19 +10916,19 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global = jerry_get_global_object (); + jerry_value_t global = jerry_current_realm (); /* Register the "capture_backtrace" method. */ { - jerry_value_t func = jerry_create_external_function (backtrace_handler); - jerry_value_t name = jerry_create_string ((const jerry_char_t *) "backtrace"); - jerry_value_t result = jerry_set_property (global, name, func); - jerry_release_value (result); - jerry_release_value (name); - jerry_release_value (func); + jerry_value_t func = jerry_function_external (backtrace_handler); + jerry_value_t name = jerry_string_sz ("backtrace"); + jerry_value_t result = jerry_object_set (global, name, func); + jerry_value_free (result); + jerry_value_free (name); + jerry_value_free (func); } - jerry_release_value (global); + jerry_value_free (global); const char *source = ("function f() { g (); }\n" "function g() { h (); }\n" @@ -11512,21 +10936,21 @@ main (void) "f ();\n"); jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "demo_memory.js"); + parse_options.options = JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("demo_memory.js"); jerry_value_t program = jerry_parse ((const jerry_char_t *) source, strlen (source), &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); - if (!jerry_value_is_error (program)) + if (!jerry_value_is_exception (program)) { jerry_value_t run_result = jerry_run (program); - jerry_release_value (run_result); + jerry_value_free (run_result); } - jerry_release_value (program); + jerry_value_free (program); jerry_cleanup (); return 0; @@ -11535,8 +10959,7 @@ main (void) **See also** -- [jerry_get_backtrace_from](#jerry_get_backtrace_from) -- [jerry_create_external_function](#jerry_create_external_function) +- [jerry_function_external](#jerry_function_external) ## jerry_backtrace_capture @@ -11547,16 +10970,16 @@ Low-level function to capture each backtrace frame. The captured frame data is passed to a callback function. To improve performance, the majority of the frame data is not initialized when the callback function is called. The initialization of these fields can be done later by helper functions such -as [jerry_backtrace_get_location](#jerry_backtrace_get_location). +as [jerry_frame_location](#jerry_frame_location). **Prototype** ```c void -jerry_backtrace_capture (jerry_backtrace_callback_t callback, void *user_p); +jerry_backtrace_capture (jerry_backtrace_cb_t callback, void *user_p); ``` -- `callback` - a [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- `callback` - a [jerry_backtrace_cb_t](#jerry_backtrace_cb_t) callback which is called for each captured frame - `user_p` - pointer passed to the `callback` function, can be NULL @@ -11572,7 +10995,7 @@ jerry_backtrace_capture (jerry_backtrace_callback_t callback, void *user_p); #include "jerryscript.h" static bool -backtrace_callback (jerry_backtrace_frame_t *frame_p, +backtrace_callback (jerry_frame_t *frame_p, void *user_p) { printf (" A stack frame is captured\n"); @@ -11590,7 +11013,7 @@ backtrace_handler (const jerry_call_info_t *call_info_p, jerry_backtrace_capture (&backtrace_callback, NULL); - return jerry_create_undefined (); + return jerry_undefined (); } /* backtrace_handler */ int @@ -11598,19 +11021,19 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global = jerry_get_global_object (); + jerry_value_t global = jerry_current_realm (); /* Register the "dump_backtrace" method. */ { - jerry_value_t func = jerry_create_external_function (backtrace_handler); - jerry_value_t name = jerry_create_string ((const jerry_char_t *) "backtrace"); - jerry_value_t result = jerry_set_property (global, name, func); - jerry_release_value (result); - jerry_release_value (name); - jerry_release_value (func); + jerry_value_t func = jerry_function_external (backtrace_handler); + jerry_value_t name = jerry_string_sz ("backtrace"); + jerry_value_t result = jerry_object_set (global, name, func); + jerry_value_free (result); + jerry_value_free (name); + jerry_value_free (func); } - jerry_release_value (global); + jerry_value_free (global); const char *source = ("function f() { g (); }\n" "function g() { h (); }\n" @@ -11618,21 +11041,21 @@ main (void) "f ();\n"); jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "demo_backtrace.js"); + parse_options.options = JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("demo_backtrace.js"); jerry_value_t program = jerry_parse ((const jerry_char_t *) source, strlen (source), &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); - if (!jerry_value_is_error (program)) + if (!jerry_value_is_exception (program)) { jerry_value_t run_result = jerry_run (program); - jerry_release_value (run_result); + jerry_value_free (run_result); } - jerry_release_value (program); + jerry_value_free (program); jerry_cleanup (); return 0; @@ -11641,15 +11064,15 @@ main (void) **See also** -- [jerry_get_backtrace](#jerry_get_backtrace) -- [jerry_backtrace_get_frame_type](#jerry_backtrace_get_frame_type) -- [jerry_backtrace_get_location](#jerry_backtrace_get_location) -- [jerry_backtrace_get_function](#jerry_backtrace_get_function) -- [jerry_backtrace_get_this](#jerry_backtrace_get_this) -- [jerry_backtrace_is_strict](#jerry_backtrace_is_strict) +- [jerry_backtrace_capture](#jerry_backtrace_capture) +- [jerry_frame_type](#jerry_frame_type) +- [jerry_frame_location](#jerry_frame_location) +- [jerry_frame_callee](#jerry_frame_callee) +- [jerry_frame_this](#jerry_frame_this) +- [jerry_frame_is_strict](#jerry_frame_is_strict) -## jerry_backtrace_get_frame_type +## jerry_frame_type **Summary** @@ -11660,13 +11083,13 @@ and the value becomes invalid after the callback returns. **Prototype** ```c -jerry_backtrace_frame_types_t -jerry_backtrace_get_frame_type (jerry_backtrace_frame_t *frame_p); +jerry_frame_type_t +jerry_frame_type (jerry_frame_t *frame_p); ``` -- `frame_p` - a frame passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- `frame_p` - a frame passed to the [jerry_backtrace_cb_t](#jerry_backtrace_cb_t) callback - return value - - frame type listed in [jerry_backtrace_frame_types_t](#jerry_backtrace_frame_types_t) + - frame type listed in [jerry_frame_type_t](#jerry_frame_type_t) *New in version [[NEXT_RELEASE]]*. @@ -11677,10 +11100,10 @@ with the following callback function: ```c static bool -backtrace_callback (jerry_backtrace_frame_t *frame_p, +backtrace_callback (jerry_frame_t *frame_p, void *user_p) { - switch (jerry_backtrace_get_frame_type (frame_p)) + switch (jerry_frame_type (frame_p)) { case JERRY_BACKTRACE_FRAME_JS: { @@ -11703,7 +11126,7 @@ backtrace_callback (jerry_backtrace_frame_t *frame_p, - [jerry_backtrace_capture](#jerry_backtrace_capture) -## jerry_backtrace_get_location +## jerry_frame_location **Summary** @@ -11722,11 +11145,11 @@ becomes invalid after the callback returns. **Prototype** ```c -const jerry_backtrace_location_t * -jerry_backtrace_get_location (jerry_backtrace_frame_t *frame_p); +const jerry_frame_location_t * +jerry_frame_location (jerry_frame_t *frame_p); ``` -- `frame_p` - a frame passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- `frame_p` - a frame passed to the [jerry_backtrace_cb_t](#jerry_backtrace_cb_t) callback - return value - pointer to the location private field if the location is available, - NULL otherwise @@ -11740,11 +11163,11 @@ with the following callback function: ```c static bool -backtrace_callback (jerry_backtrace_frame_t *frame_p, +backtrace_callback (jerry_frame_t *frame_p, void *user_p) { - const jerry_backtrace_location_t *location_p; - location_p = jerry_backtrace_get_location (frame_p); + const jerry_frame_location_t *location_p; + location_p = jerry_frame_location (frame_p); if (location_p == NULL) { @@ -11753,11 +11176,10 @@ backtrace_callback (jerry_backtrace_frame_t *frame_p, } jerry_char_t string_buffer[64]; - jerry_size_t copied_bytes = jerry_substring_to_char_buffer (location_p->resource_name, - 0, - 63, - string_buffer, - 63); + jerry_size_t copied_bytes = jerry_string_to_buffer (location_p->source_name, + JERRY_ENCODING_UTF8 + string_buffer, + sizeof (string_buffer) - 1); string_buffer[copied_bytes] = '\0'; printf(" %s:%d:%d\n", string_buffer, (int) location_p->line, (int) location_p->column); return true; @@ -11769,7 +11191,7 @@ backtrace_callback (jerry_backtrace_frame_t *frame_p, - [jerry_backtrace_capture](#jerry_backtrace_capture) -## jerry_backtrace_get_function +## jerry_frame_callee **Summary** @@ -11787,10 +11209,10 @@ after the callback returns. ```c const jerry_value_t * -jerry_backtrace_get_function (jerry_backtrace_frame_t *frame_p); +jerry_frame_callee (jerry_frame_t *frame_p); ``` -- `frame_p` - a frame passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- `frame_p` - a frame passed to the [jerry_backtrace_cb_t](#jerry_backtrace_cb_t) callback - return value - pointer to the called function if the function is available, - NULL otherwise @@ -11804,10 +11226,10 @@ with the following callback function: ```c static bool -backtrace_callback (jerry_backtrace_frame_t *frame_p, +backtrace_callback (jerry_frame_t *frame_p, void *user_p) { - jerry_value_t *function_p = jerry_backtrace_get_function (frame_p); + jerry_value_t *function_p = jerry_frame_callee (frame_p); if (function_p != NULL) { @@ -11825,7 +11247,7 @@ backtrace_callback (jerry_backtrace_frame_t *frame_p, - [jerry_backtrace_capture](#jerry_backtrace_capture) -## jerry_backtrace_get_this +## jerry_frame_this **Summary** @@ -11844,10 +11266,10 @@ after the callback returns. ```c const jerry_value_t * -jerry_backtrace_get_this (jerry_backtrace_frame_t *frame_p); +jerry_frame_this (jerry_frame_t *frame_p); ``` -- `frame_p` - a frame passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- `frame_p` - a frame passed to the [jerry_backtrace_cb_t](#jerry_backtrace_cb_t) callback - return value - pointer to the 'this' binding if the binding is available, - NULL otherwise @@ -11861,10 +11283,10 @@ with the following callback function: ```c static bool -backtrace_callback (jerry_backtrace_frame_t *frame_p, +backtrace_callback (jerry_frame_t *frame_p, void *user_p) { - jerry_value_t *this_p = jerry_backtrace_get_this (frame_p); + jerry_value_t *this_p = jerry_frame_this (frame_p); if (this_p != NULL) { @@ -11882,7 +11304,7 @@ backtrace_callback (jerry_backtrace_frame_t *frame_p, - [jerry_backtrace_capture](#jerry_backtrace_capture) -## jerry_backtrace_is_strict +## jerry_frame_is_strict **Summary** @@ -11895,10 +11317,10 @@ becomes invalid after the callback returns. ```c bool -jerry_backtrace_is_strict (jerry_backtrace_frame_t *frame_p); +jerry_frame_is_strict (jerry_frame_t *frame_p); ``` -- `frame_p` - a frame passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- `frame_p` - a frame passed to the [jerry_backtrace_cb_t](#jerry_backtrace_cb_t) callback - return value - true, if strict mode code is bound to the frame - false, otherwise @@ -11912,10 +11334,10 @@ with the following callback function: ```c static bool -backtrace_callback (jerry_backtrace_frame_t *frame_p, +backtrace_callback (jerry_frame_t *frame_p, void *user_p) { - if (jerry_backtrace_is_strict (frame_p)) + if (jerry_frame_is_strict (frame_p)) { printf ("Strict mode code is running"); return true; @@ -11933,42 +11355,41 @@ backtrace_callback (jerry_backtrace_frame_t *frame_p, # Miscellaneous functions -## jerry_set_vm_exec_stop_callback +## jerry_halt_handler **Summary** The callback passed to this function is periodically called when JerryScript executes an ECMAScript program. -If the callback returns with undefined value the ECMAScript execution -continues. Otherwise the result is thrown by the engine (if the error -flag is not set for the returned value the engine automatically sets -it). The callback function might be called again even if it threw -an error. In this case the function must throw the same error again. +If the callback returns with undefined value the ECMAScript execution continues. +Otherwise the result is thrown by the engine. The callback function might be +called again even if it threw an exception. In this case the function must throw the +same exception again. To reduce the CPU overhead of constantly checking the termination condition the callback is called when a backward jump is executed -or an exception is caught. Setting the `frequency` to a greater +or an exception is caught. Setting the `interval` to a greater than `1` value reduces this overhead further. If its value is N only every Nth event (backward jump, etc.) trigger the next check. *Notes*: -- This API depends on a build option (`JERRY_VM_EXEC_STOP`) and can be checked +- This API depends on a build option (`JERRY_VM_HALT`) and can be checked in runtime with the `JERRY_FEATURE_VM_EXEC_STOP` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c void -jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb, - void *user_p, - uint32_t frequency); +jerry_halt_handler (uint32_t interval, + jerry_halt_cb_t callback + void *user_p); ``` -- `stop_cb` - periodically called callback (passing NULL disables this feature) -- `user_p` - user pointer passed to the `stop_cb` function -- `frequency` - frequency of calling the `stop_cb` function +- `interval` - interval of calling the `callback` function +- `callback` - periodically called callback (passing NULL disables this feature) +- `user_p` - user pointer passed to the `callback` function *New in version 2.0*. @@ -11987,11 +11408,11 @@ vm_exec_stop_callback (void *user_p) while (*countdown_p > 0) { (*countdown_p)--; - return jerry_create_undefined (); + return jerry_undefined (); } - // The error flag is added automatically. - return jerry_create_string ((const jerry_char_t *) "Abort script"); + // The value will be automatically wrapped into an exception. + return jerry_string_sz ("Abort script"); } int @@ -12000,54 +11421,54 @@ main (void) jerry_init (JERRY_INIT_EMPTY); int countdown = 10; - jerry_set_vm_exec_stop_callback (vm_exec_stop_callback, &countdown, 16); + jerry_halt_handler (16, vm_exec_stop_callback, &countdown); // Infinite loop. const jerry_char_t script[] = "while(true) {}"; jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL); - jerry_release_value (jerry_run (parsed_code)); - jerry_release_value (parsed_code); + jerry_value_free (jerry_run (parsed_code)); + jerry_value_free (parsed_code); jerry_cleanup (); } ``` **See also** -- [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t) +- [jerry_halt_cb_t](#jerry_halt_cb_t) -## jerry_get_resource_name +## jerry_source_name **Summary** -Get the resource name (usually a file name) of the currently executed script or the given function object. +Get the source name (usually a file name) of the currently executed script or the given function object. This function is typically called from native callbacks. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. - This feature depends on build option (`JERRY_LINE_INFO`) and can be checked in runtime with the `JERRY_FEATURE_LINE_INFO` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c jerry_value_t -jerry_get_resource_name (jerry_value_t value); +jerry_source_name (jerry_value_t value); ``` -- `value` - api value to obtain the resource name from +- `value` - api value to obtain the source name from - return string value constructed from - - the currently executed function object's resource name, if the given value is undefined - - resource name of the function object, if the given value is a function object + - the currently executed function object's source name, if the given value is undefined + - source name of the function object, if the given value is a function object - "<anonymous>", otherwise *New in version 2.2*. **Example** -[doctest]: # (name="02.API-REFERENCE-jsresourcename.c") +[doctest]: # (name="02.API-REFERENCE-jssourcename.c") ```c #include <stdio.h> @@ -12055,58 +11476,58 @@ jerry_get_resource_name (jerry_value_t value); #include "jerryscript.h" static jerry_value_t -resource_name_handler (const jerry_call_info_t *call_info_p, - const jerry_value_t args_p[], - const jerry_length_t args_count) +source_name_handler (const jerry_call_info_t *call_info_p, + const jerry_value_t args_p[], + const jerry_length_t args_count) { - jerry_value_t undefined_value = jerry_create_undefined (); - jerry_value_t resource_name = jerry_get_resource_name (args_count > 0 ? args_p[0] : undefined_value); - jerry_release_value (undefined_value); + jerry_value_t undefined_value = jerry_undefined (); + jerry_value_t source_name = jerry_source_name (args_count > 0 ? args_p[0] : undefined_value); + jerry_value_free (undefined_value); - return resource_name; -} /* resource_name_handler */ + return source_name; +} /* source_name_handler */ int main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t global = jerry_get_global_object (); + jerry_value_t global = jerry_current_realm (); - /* Register the "resourceName" method. */ + /* Register the sourceName" method. */ { - jerry_value_t func = jerry_create_external_function (resource_name_handler); - jerry_value_t name = jerry_create_string ((const jerry_char_t *) "resourceName"); - jerry_value_t result = jerry_set_property (global, name, func); - jerry_release_value (result); - jerry_release_value (name); - jerry_release_value (func); + jerry_value_t func = jerry_function_external (source_name_handler); + jerry_value_t name = jerry_string_sz ("sourceName"); + jerry_value_t result = jerry_object_set (global, name, func); + jerry_value_free (result); + jerry_value_free (name); + jerry_value_free (func); } - jerry_release_value (global); + jerry_value_free (global); - const jerry_char_t source[] = "function myFunction() { return resourceName() }; myFunction()"; + const jerry_char_t source[] = "function myFunction() { return sourceName() }; myFunction()"; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "demo.js"); + parse_options.options = JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string_sz ("demo.js"); jerry_value_t program = jerry_parse (source, sizeof (source) - 1, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); - if (!jerry_value_is_error (program)) + if (!jerry_value_is_exception (program)) { /* `run_result` contains "demo.js" */ jerry_value_t run_result = jerry_run (program); /* usage of `run_result` */ - jerry_release_value (run_result); + jerry_value_free (run_result); } - jerry_release_value (program); + jerry_value_free (program); jerry_cleanup (); return 0; @@ -12115,9 +11536,9 @@ main (void) **See also** -- [jerry_create_external_function](#jerry_create_external_function) +- [jerry_function_external](#jerry_function_external) -## jerry_get_user_value +## jerry_source_user_value **Summary** @@ -12126,14 +11547,14 @@ set by the parser when the JERRY_PARSE_HAS_USER_VALUE flag is set in the `option member of the [jerry_parse_options_t](#jerry_parse_options_t) structure. *Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_get_user_value (const jerry_value_t value); +jerry_source_user_value (const jerry_value_t value); ``` - `value` - script / module / function value which executes ECMAScript code (native modules / functions do not have user value). @@ -12157,22 +11578,22 @@ main (void) const jerry_char_t script[] = "function abc() {} abc"; - jerry_value_t user_value = jerry_create_object (); + jerry_value_t user_value = jerry_object (); jerry_parse_options_t parse_options; parse_options.options = JERRY_PARSE_HAS_USER_VALUE; parse_options.user_value = user_value; jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, &parse_options); - jerry_release_value (user_value); + jerry_value_free (user_value); - /* The jerry_get_user_value returns the object which - * was created by jerry_create_object before. */ + /* The jerry_source_user_value returns the object which + * was created by jerry_object before. */ - user_value = jerry_get_user_value (parsed_code); - jerry_release_value (parsed_code); + user_value = jerry_source_user_value (parsed_code); + jerry_value_free (parsed_code); - jerry_release_value (user_value); + jerry_value_free (user_value); jerry_cleanup (); return 0; } @@ -12184,7 +11605,7 @@ main (void) - [jerry_generate_snapshot](#jerry_generate_snapshot) - [jerry_exec_snapshot](#jerry_exec_snapshot) -## jerry_is_eval_code +## jerry_function_is_dynamic **Summary** @@ -12194,7 +11615,7 @@ Checks whether an ECMAScript code is compiled by eval like (eval, new Function, **Prototype** ```c -bool jerry_is_eval_code (const jerry_value_t value); +bool jerry_function_is_dynamic (const jerry_value_t value); ``` - `value` - script / module / function value which executes ECMAScript code - return @@ -12219,14 +11640,14 @@ main (void) jerry_value_t script_value = jerry_parse (script, sizeof (script) - 1, NULL); jerry_value_t function_value = jerry_run (script_value); - jerry_release_value (script_value); + jerry_value_free (script_value); - if (jerry_is_eval_code (function_value)) + if (jerry_function_is_dynamic (function_value)) { /* Code enters here. */ } - jerry_release_value (function_value); + jerry_value_free (function_value); jerry_cleanup (); return 0; } @@ -12238,7 +11659,7 @@ main (void) - [jerry_generate_snapshot](#jerry_generate_snapshot) - [jerry_exec_snapshot](#jerry_exec_snapshot) -## jerry_get_source_info +## jerry_source_info **Summary** @@ -12246,16 +11667,16 @@ Returns a newly created source info structure corresponding to the passed script The function is lower level than `toString()` operation, but provides more contextual information. *Notes*: -- Returned value must be freed with [jerry_free_source_info](#jerry_free_source_info) when it +- Returned value must be freed with [jerry_source_info_free](#jerry_source_info_free) when it is no longer needed. - This API depends on a build option (`JERRY_FUNCTION_TO_STRING`) and can be checked in runtime with the `JERRY_FEATURE_FUNCTION_TO_STRING` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -jerry_source_info_t *jerry_get_source_info (const jerry_value_t value); +jerry_source_info_t *jerry_source_info (const jerry_value_t value); ``` - `value` - script / module / function value which executes JavaScript code (native modules / functions do not have source info). @@ -12281,15 +11702,15 @@ main (void) jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL); - jerry_source_info_t *source_info_p = jerry_get_source_info (parsed_code); - jerry_release_value (parsed_code); + jerry_source_info_t *source_info_p = jerry_source_info (parsed_code); + jerry_value_free (parsed_code); if (source_info_p != NULL) { - /* Check the information provided by jerry_get_source_info. */ + /* Check the information provided by jerry_source_info. */ } - jerry_free_source_info (source_info_p); + jerry_source_info_free (source_info_p); jerry_cleanup (); return 0; @@ -12298,36 +11719,36 @@ main (void) **See also** -- [jerry_free_source_info](#jerry_free_source_info) +- [jerry_source_info_free](#jerry_source_info_free) - [jerry_source_info_t](#jerry_source_info_t) -## jerry_free_source_info +## jerry_source_info_free **Summary** -Frees the the source info structure returned by [jerry_get_source_info](#jerry_get_source_info). +Frees the the source info structure returned by [jerry_source_info](#jerry_source_info). *Notes*: - This API depends on a build option (`JERRY_FUNCTION_TO_STRING`) and can be checked in runtime with the `JERRY_FEATURE_FUNCTION_TO_STRING` feature enum value, - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** ```c -void jerry_free_source_info (jerry_source_info_t *source_info_p) +void jerry_source_info_free (jerry_source_info_t *source_info_p) ``` -- `source_info_p` - source info structure returned by [jerry_get_source_info](#jerry_get_source_info) +- `source_info_p` - source info structure returned by [jerry_source_info](#jerry_source_info) *New in version [[NEXT_RELEASE]]*. **Example** -See [jerry_get_source_info](#jerry_get_source_info) +See [jerry_source_info](#jerry_source_info) **See also** -- [jerry_get_source_info](#jerry_get_source_info) +- [jerry_source_info](#jerry_source_info) - [jerry_source_info_t](#jerry_source_info_t) @@ -12346,7 +11767,7 @@ by the application (i.e. the gc must not reclaim it). This is also true to the returned previously active realm, so there is no need to free the value after the restoration. The function can only fail if realms are not supported or the passed argument is not a realm. In this case the returned exception must -be freed by [jerry_release_value](#jerry_release_value). +be freed by [jerry_value_free](#jerry_value_free). This function is useful to parse a script, create a native function, load a snapshot or create an exception in another realm. Each ECMAScript code runs in the realm @@ -12355,7 +11776,7 @@ which was active when the code was parsed or loaded regardless of the current re *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** @@ -12375,7 +11796,7 @@ jerry_set_realm (jerry_value_t realm_value); ```c { - jerry_value_t realm_value = jerry_create_realm (); + jerry_value_t realm_value = jerry_realm (); jerry_value_t old_realm = jerry_set_realm (realm_value); @@ -12387,9 +11808,9 @@ jerry_set_realm (jerry_value_t realm_value); **See also** -- [jerry_create_realm](#jerry_create_realm) +- [jerry_realm](#jerry_realm) -## jerry_realm_get_this +## jerry_realm_this **Summary** @@ -12400,18 +11821,18 @@ changed by [jerry_realm_set_this](#jerry_realm_set_this). *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** ```c jerry_value_t -jerry_realm_get_this (jerry_value_t realm_value) +jerry_realm_this (jerry_value_t realm_value) ``` - `realm_value` - realm value - return - - type error - if realm_value is not a realm + - type error exception- if realm_value is not a realm - 'this' binding object - otherwise *New in version 2.4*. @@ -12420,20 +11841,20 @@ jerry_realm_get_this (jerry_value_t realm_value) ```c { - jerry_value_t realm_value = jerry_create_realm (); + jerry_value_t realm_value = jerry_realm (); - jerry_value_t this_value = jerry_realm_get_this (realm_value); + jerry_value_t this_value = jerry_realm_this (realm_value); ... // usage of the this_value - jerry_release_value (this_value); - jerry_release_value (realm_value); + jerry_value_free (this_value); + jerry_value_free (realm_value); } ``` **See also** -- [jerry_create_realm](#jerry_create_realm) +- [jerry_realm](#jerry_realm) - [jerry_realm_set_this](#jerry_realm_set_this) ## jerry_realm_set_this @@ -12446,7 +11867,7 @@ any script on the realm. Otherwise the operation is undefined. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** @@ -12458,7 +11879,7 @@ jerry_realm_set_this (jerry_value_t realm_value, jerry_value_t this_value) - `realm_value` - realm value - `this_value` - new this value - return - - type error - if realm_value is not a realm or this_value is not object + - type error exception- if realm_value is not a realm or this_value is not object - true - otherwise *New in version 2.4*. @@ -12467,11 +11888,11 @@ jerry_realm_set_this (jerry_value_t realm_value, jerry_value_t this_value) ```c { - jerry_value_t realm_value = jerry_create_realm (); + jerry_value_t realm_value = jerry_realm (); jerry_value_t old_realm = jerry_set_realm (realm_value); /* The prototype of the object comes from the new realm. */ - jerry_value_t this_value = jerry_create_object (); + jerry_value_t this_value = jerry_object (); jerry_set_realm (old_realm); jerry_value_t result = jerry_realm_set_this (realm_value, this_value); @@ -12482,15 +11903,17 @@ jerry_realm_set_this (jerry_value_t realm_value, jerry_value_t this_value) **See also** -- [jerry_create_realm](#jerry_create_realm) +- [jerry_realm](#jerry_realm) - [jerry_set_realm](#jerry_set_realm) -- [jerry_realm_get_this](#jerry_realm_get_this) +- [jerry_realm_this](#jerry_realm_this) # ArrayBuffer and TypedArray functions -These APIs all depend on the es.next profile. +These APIs all depend 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). -## jerry_get_arraybuffer_byte_length +## jerry_arraybuffer_size **Summary** @@ -12501,7 +11924,7 @@ same value which was passed to the ArrayBuffer constructor call. ```c jerry_length_t -jerry_get_arraybuffer_byte_length (const jerry_value_t value); +jerry_arraybuffer_size (const jerry_value_t value); ``` - `value` - ArrayBuffer object @@ -12515,16 +11938,16 @@ jerry_get_arraybuffer_byte_length (const jerry_value_t value); ```c { - jerry_value_t buffer = jerry_create_arraybuffer (15); - jerry_length_t length = jerry_get_arraybuffer_byte_length (buffer); + jerry_value_t buffer = jerry_arraybuffer (15); + jerry_length_t length = jerry_arraybuffer_size (buffer); // length should be 15 - jerry_release_value (buffer); + jerry_value_free (buffer); } ``` **See also** -- [jerry_create_arraybuffer](#jerry_create_arraybuffer) +- [jerry_arraybuffer](#jerry_arraybuffer) ## jerry_arraybuffer_read @@ -12569,7 +11992,7 @@ jerry_arraybuffer_read (const jerry_value_t value, { uint8_t data[20]; jerry_value_t buffer; - // ... create the ArrayBuffer or acquire it from somewhere. + // ... create the ArrayBuffer or copy it from somewhere. jerry_value_t bytes_read; @@ -12580,15 +12003,15 @@ jerry_arraybuffer_read (const jerry_value_t value, // process the data variable - jerry_release_value (buffer); + jerry_value_free (buffer); } ``` **See also** -- [jerry_create_arraybuffer](#jerry_create_arraybuffer) +- [jerry_arraybuffer](#jerry_arraybuffer) - [jerry_arraybuffer_write](#jerry_arraybuffer_write) -- [jerry_get_arraybuffer_byte_length](#jerry_get_arraybuffer_byte_length) +- [jerry_arraybuffer_size](#jerry_arraybuffer_size) ## jerry_arraybuffer_write @@ -12640,7 +12063,7 @@ jerry_arraybuffer_write (const jerry_value_t value, } jerry_value_t buffer; - // ... create the ArrayBuffer or acquire it from somewhere. + // ... create the ArrayBuffer or copy it from somewhere. jerry_value_t bytes_written; @@ -12651,18 +12074,18 @@ jerry_arraybuffer_write (const jerry_value_t value, // use the ArrayBuffer - jerry_release_value (buffer); + jerry_value_free (buffer); } ``` **See also** -- [jerry_create_arraybuffer](#jerry_create_arraybuffer) +- [jerry_arraybuffer](#jerry_arraybuffer) - [jerry_arraybuffer_write](#jerry_arraybuffer_write) -- [jerry_get_arraybuffer_byte_length](#jerry_get_arraybuffer_byte_length) +- [jerry_arraybuffer_size](#jerry_arraybuffer_size) -## jerry_get_arraybuffer_pointer +## jerry_arraybuffer_data **Summary** @@ -12671,15 +12094,15 @@ The function allows access to the contents of the Array Buffer directly. **WARNING!** This operation is for expert use only! The programmer must ensure that the returned memory area is used correctly. That is there is no out of bounds reads or writes. The lifetime of the underlying -data buffer is managed by the ArrayBuffer value. Make sure to acquire the -value with [`jerry_acquire_value`](#jerry_acquire_value) if the data +data buffer is managed by the ArrayBuffer value. Make sure to copy the +value with [`jerry_value_copy`](#jerry_value_copy) if the data buffer is needed later. **Prototype** ```c uint8_t * -jerry_get_arraybuffer_pointer (const jerry_value_t value); +jerry_arraybuffer_data (const jerry_value_t value); ``` - `value` - Array Buffer object. @@ -12696,9 +12119,9 @@ jerry_get_arraybuffer_pointer (const jerry_value_t value); ```c { // create the ArrayBuffer - jerry_value_t buffer = jerry_create_arraybuffer (16); + jerry_value_t buffer = jerry_arraybuffer (16); - uint8_t *const data = jerry_get_arraybuffer_pointer (buffer); + uint8_t *const data = jerry_arraybuffer_data (buffer); for (int i = 0; i < 16; i++) { @@ -12708,15 +12131,15 @@ jerry_get_arraybuffer_pointer (const jerry_value_t value); // use the Array Buffer // release buffer as it is not needed after this point - jerry_release_value (buffer); + jerry_value_free (buffer); } ``` **See also** -- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) +- [jerry_arraybuffer_external](#jerry_arraybuffer_external) -## jerry_is_arraybuffer_detachable +## jerry_arraybuffer_is_detachable **Summary** @@ -12725,14 +12148,14 @@ Get if the ArrayBuffer is detachable. **Prototype** ```c -jerry_value_t -jerry_is_arraybuffer_detachable (const jerry_value_t value); +bool +jerry_arraybuffer_is_detachable (const jerry_value_t value); ``` - `value` - ArrayBuffer to be detached - return - - boolean value if success - - Error otherwise + - true if the arraybuffer is detachable + - false otherwise *New in version 2.2*. @@ -12741,43 +12164,41 @@ jerry_is_arraybuffer_detachable (const jerry_value_t value); ```c { // create the ArrayBuffer - jerry_value_t buffer = jerry_create_arraybuffer (16); + jerry_value_t buffer = jerry_arraybuffer (16); - jerry_value_t res = jerry_is_arraybuffer_detachable (buffer); - bool is_detachable = jerry_value_is_true (res); + bool is_detachable = jerry_arraybuffer_is_detachable (buffer); // release buffer as it is not needed after this point - jerry_release_value (res); - jerry_release_value (buffer); + jerry_value_free (buffer); } ``` **See also** -- [jerry_detach_arraybuffer](#jerry_detach_arraybuffer) +- [jerry_arraybuffer_detach](#jerry_arraybuffer_detach) -## jerry_detach_arraybuffer +## jerry_arraybuffer_detach **Summary** Detach the underlying data block from ArrayBuffer and set its bytelength to 0. -This operation requires the ArrayBuffer to be external that created by -`jerry_create_arraybuffer_external`. +This operation requires the ArrayBuffer to be an external buffer created by +`jerry_arraybuffer_external`. **Prototype** ```c jerry_value_t -jerry_detach_arraybuffer (const jerry_value_t value); +jerry_arraybuffer_detach (const jerry_value_t value); ``` -*Note*: If the ArrayBuffer has been created with `jerry_create_arraybuffer_external` the optional free callback is called on a successful detach operation +*Note*: If the ArrayBuffer has been created with `jerry_arraybuffer_external` the optional free callback is called on a successful detach operation - `value` - ArrayBuffer to be detached - return - null value if success - - Error otherwise + - exception otherwise *New in version 2.2*. @@ -12788,19 +12209,19 @@ jerry_detach_arraybuffer (const jerry_value_t value); uint8_t buf[1]; jerry_size_t length = 1; // create the ArrayBuffer - jerry_value_t buffer = jerry_create_arraybuffer (length, buf, NULL); + jerry_value_t buffer = jerry_arraybuffer (length, buf, NULL); - jerry_value_t res = jerry_detach_arraybuffer (buffer); + jerry_value_t res = jerry_arraybuffer_detach (buffer); // release buffer as it is not needed after this point - jerry_release_value (res); - jerry_release_value (buffer); + jerry_value_free (res); + jerry_value_free (buffer); } ``` **See also** -- [jerry_is_arraybuffer_detachable](#jerry_is_arraybuffer_detachable) +- [jerry_arraybuffer_is_detachable](#jerry_arraybuffer_is_detachable) ## jerry_arraybuffer_has_buffer @@ -12811,7 +12232,7 @@ Checks whether a buffer is currently allocated for an array buffer or typed arra *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). **Prototype** @@ -12839,7 +12260,7 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t array_buffer_value = jerry_create_arraybuffer (1024 * 1024); + jerry_value_t array_buffer_value = jerry_arraybuffer (1024 * 1024); /* By default, the backing store of large array buffers * is allocated when it is used the first time. */ @@ -12849,7 +12270,7 @@ main (void) /* Code enters here in this case. */ } - jerry_release_value (array_buffer_value); + jerry_value_free (array_buffer_value); jerry_cleanup (); return 0; @@ -12858,12 +12279,12 @@ main (void) **See also** -- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) -- [jerry_create_shared_arraybuffer_external](#jerry_create_shared_arraybuffer_external) -- [jerry_arraybuffer_set_compact_allocation_limit](#jerry_arraybuffer_set_compact_allocation_limit) -- [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks) +- [jerry_arraybuffer_external](#jerry_arraybuffer_external) +- [jerry_shared_arraybuffer_external](#jerry_shared_arraybuffer_external) +- [jerry_arraybuffer_heap_allocation_limit](#jerry_arraybuffer_heap_allocation_limit) +- [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) -## jerry_arraybuffer_set_compact_allocation_limit +## jerry_arraybuffer_heap_allocation_limit **Summary** @@ -12875,7 +12296,7 @@ are not called for these array buffers. *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The default limit is 256 bytes. - When an array buffer is allocated in a single memory block, its backing store is not freed when the array buffer is detached. @@ -12886,7 +12307,7 @@ are not called for these array buffers. ```c void -jerry_arraybuffer_set_compact_allocation_limit (const jerry_length_t allocation_limit); +jerry_arraybuffer_heap_allocation_limit (const jerry_length_t allocation_limit); ``` - `allocation_limit` - maximum size of compact allocation. @@ -12905,9 +12326,9 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_arraybuffer_set_compact_allocation_limit (1); + jerry_arraybuffer_heap_allocation_limit (1); - jerry_value_t array_buffer_value = jerry_create_arraybuffer (1); + jerry_value_t array_buffer_value = jerry_arraybuffer (1); if (jerry_arraybuffer_has_buffer (array_buffer_value)) { @@ -12915,9 +12336,9 @@ main (void) * is allocated during buffer creation. */ } - jerry_release_value (array_buffer_value); + jerry_value_free (array_buffer_value); - array_buffer_value = jerry_create_arraybuffer (2); + array_buffer_value = jerry_arraybuffer (2); if (jerry_arraybuffer_has_buffer (array_buffer_value)) { @@ -12925,7 +12346,7 @@ main (void) * is allocated when it is used the first time. */ } - jerry_release_value (array_buffer_value); + jerry_value_free (array_buffer_value); jerry_cleanup (); return 0; @@ -12935,9 +12356,9 @@ main (void) **See also** - [jerry_arraybuffer_has_buffer](#jerry_arraybuffer_has_buffer) -- [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks) +- [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) -## jerry_arraybuffer_set_allocator_callbacks +## jerry_arraybuffer_allocator **Summary** @@ -12946,7 +12367,7 @@ Set callbacks for allocating and freeing backing stores for array buffer objects *Notes*: - 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_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - This function is recommended to be called after [jerry_init](#jerry_init) before any array buffer is allocated. - The callbacks can be NULL to use the default callbacks. The default `allocate_callback` @@ -12958,9 +12379,9 @@ Set callbacks for allocating and freeing backing stores for array buffer objects ```c void -jerry_arraybuffer_set_allocator_callbacks (jerry_arraybuffer_allocate_t allocate_callback, - jerry_arraybuffer_free_t free_callback, - void *user_p) +jerry_arraybuffer_allocator (jerry_arraybuffer_allocate_cb_t allocate_callback, + jerry_arraybuffer_free_cb_t free_callback, + void *user_p) ``` - `allocate_callback` - callback for allocating array buffer memory. @@ -13002,20 +12423,20 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_arraybuffer_set_allocator_callbacks (NULL, array_buffer_free_cb, NULL); + jerry_arraybuffer_allocator (NULL, array_buffer_free_cb, NULL); /* The buffer of the array buffer object is allocated by the default * allocator using jerry_heap_alloc and freed by array_buffer_free_cb. */ const jerry_char_t script[] = "var result = new uint32Array(1024); result[0] = 1; result"; jerry_value_t array_buffer_value = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); - jerry_release_value (array_buffer_value); + jerry_value_free (array_buffer_value); /* The buffer of the array buffer object has a non-NULL * arraybuffer_user_p value, so it is not freed by array_buffer_free_cb. */ - array_buffer_value = jerry_create_arraybuffer_external (sizeof (global_buffer), global_buffer, global_buffer); - jerry_release_value (array_buffer_value); + array_buffer_value = jerry_arraybuffer_external (global_buffer, sizeof (global_buffer), global_buffer); + jerry_value_free (array_buffer_value); jerry_cleanup (); return 0; @@ -13025,9 +12446,9 @@ main (void) **See also** - [jerry_arraybuffer_has_buffer](#jerry_arraybuffer_has_buffer) -- [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks) +- [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) -## jerry_get_dataview_buffer +## jerry_dataview_buffer **Summary** @@ -13035,16 +12456,16 @@ Get the ArrayBuffer object used by a DataView object. Additionally returns the byteLength and byteOffset properties of the DataView object. -For the returned ArrayBuffer the [jerry_release_value](#jerry_release_value) +For the returned ArrayBuffer the [jerry_value_free](#jerry_value_free) must be called when it is no longer needed. **Prototype** ```c jerry_value_t -jerry_get_dataview_buffer (const jerry_value_t value, - jerry_length_t *byteOffset, - jerry_length_t *byteLength); +jerry_dataview_buffer (const jerry_value_t value, + jerry_length_t *byteOffset, + jerry_length_t *byteLength); ``` - `value` - DataView to get the ArrayBuffer from @@ -13068,11 +12489,11 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t arraybuffer = jerry_create_arraybuffer (16); - jerry_value_t dataview = jerry_create_dataview (arraybuffer, 0, 16); + jerry_value_t arraybuffer = jerry_arraybuffer (16); + jerry_value_t dataview = jerry_dataview (arraybuffer, 0, 16); jerry_length_t byteOffset = 0; jerry_length_t byteLength = 0; - jerry_value_t buffer = jerry_get_dataview_buffer (dataview, &byteOffset, &byteLength); + jerry_value_t buffer = jerry_dataview_buffer (dataview, &byteOffset, &byteLength); // buffer is an ArrayBuffer object and ArrayBuffer operations can be performed on it // byteOffset is 0 @@ -13080,9 +12501,9 @@ main (void) // usage of buffer - jerry_release_value (buffer); - jerry_release_value (dataview); - jerry_release_value (arraybuffer); + jerry_value_free (buffer); + jerry_value_free (dataview); + jerry_value_free (arraybuffer); jerry_cleanup (); } @@ -13090,10 +12511,10 @@ main (void) **See also** -- [jerry_create_dataview](#jerry_create_dataview) +- [jerry_dataview](#jerry_dataview) -## jerry_get_typedarray_type +## jerry_typedarray_type **Summary** @@ -13106,7 +12527,7 @@ enum value. ```c jerry_typedarray_type_t -jerry_get_typedarray_type (jerry_value_t value); +jerry_typedarray_type (jerry_value_t value); ``` - `value` - TypedArray object to query for type. @@ -13121,23 +12542,23 @@ jerry_get_typedarray_type (jerry_value_t value); ```c { jerry_typedarray_type_t expected_type = JERRY_TYPEDARRAY_UINT32; - jerry_value_t typedarray = jerry_create_typedarray (expected_class, 25); + jerry_value_t typedarray = jerry_typedarray (expected_class, 25); - jerry_typedarray_type_t type = jerry_get_typedarray_type (typedarray); + jerry_typedarray_type_t type = jerry_typedarray_type (typedarray); // 'type' is now JERRY_TYPEDARRAY_UINT32 - jerry_release_value (typedarray); + jerry_value_free (typedarray); } ``` **See also** -- [jerry_create_typedarray](#jerry_create_typedarray) +- [jerry_typedarray](#jerry_typedarray) - [jerry_typedarray_type_t](#jerry_typedarray_type_t) -## jerry_get_typedarray_length +## jerry_typedarray_length **Summary** @@ -13149,7 +12570,7 @@ This is not the same as the byteLength property of a TypedArray object. ``` jerry_length_t -jerry_get_typedarray_length (jerry_value_t value); +jerry_typedarray_length (jerry_value_t value); ``` - `value` - TypedArray object to query @@ -13163,22 +12584,22 @@ jerry_get_typedarray_length (jerry_value_t value); ```c { - jerry_value_t array = jerry_create_typedarray (JERRY_TYPEDARRAY_INT32, 21); + jerry_value_t array = jerry_typedarray (JERRY_TYPEDARRAY_INT32, 21); - jerry_length_t element_count = jerry_get_typedarray_length (array); + jerry_length_t element_count = jerry_typedarray_length (array); // element_count is now 21. - jerry_release_value (array); + jerry_value_free (array); } ``` **See also** -- [jerry_create_typedarray](#jerry_create_typedarray) +- [jerry_typedarray](#jerry_typedarray) -## jerry_get_typedarray_buffer +## jerry_typedarray_buffer **Summary** @@ -13186,19 +12607,19 @@ Get the ArrayBuffer object used by a TypedArray object. Additionally returns the byteLength and byteOffset properties of the TypedArray object. -For the returned ArrayBuffer the [jerry_release_value](#jerry_release_value) +For the returned ArrayBuffer the [jerry_value_free](#jerry_value_free) must be called. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*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_get_typedarray_buffer (jerry_value_t value, - jerry_length_t *byteOffset, - jerry_length_t *byteLength); +jerry_typedarray_buffer (jerry_value_t value, + jerry_length_t *byteOffset, + jerry_length_t *byteLength); ``` - `value` - TypedArray to get the ArrayBuffer from @@ -13214,24 +12635,24 @@ jerry_get_typedarray_buffer (jerry_value_t value, ```c { - jerry_value_t array = jerry_create_typedarray (JERRY_TYPEDARRAY_INT16, 11); + jerry_value_t array = jerry_typedarray (JERRY_TYPEDARRAY_INT16, 11); jerry_length_t byteLength = 0; jerry_length_t byteOffset = 0; - jerry_value_t buffer = jerry_get_typedarray_buffer (array, &byteOffset, &byteLength); + jerry_value_t buffer = jerry_typedarray_buffer (array, &byteOffset, &byteLength); // buffer is an ArrayBuffer object and ArrayBuffer operations can be performed on it - // byteLength is 11 * 2 (2 as the TypedArray stores Int16 that is 2 byte elements) + // byteLength is 11 * 2 (2 as the TypedArray stores Int16 that is 2 byte elements) // byteOffset is 0 - jerry_release_value (buffer); - jerry_release_value (array); + jerry_value_free (buffer); + jerry_value_free (array); } ``` **See also** -- [jerry_create_typedarray](#jerry_create_typedarray) +- [jerry_typedarray](#jerry_typedarray) # JSON functions @@ -13239,10 +12660,10 @@ jerry_get_typedarray_buffer (jerry_value_t value, **Summary** -Parses a JSON string creating a JavaScript value. The behaviour is equivalent with +Parses a CESU-8 or UTF-8 encoded string as a JSON string, creating a JavaScript value. The behaviour is equivalent with the "JSON.parse(string)" JS call. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -13257,7 +12678,7 @@ jerry_json_parse (const jerry_char_t *string_p, - `string_size` - size of the string. - return - `jerry_value_t` containing a JavaScript value. - - Error value in case of any parse error. + - exception value in case of any parse error. *New in version 2.0*. @@ -13279,7 +12700,7 @@ main (void) /* "obj" now contains and object created from the "data" JSON string. */ - jerry_release_value (obj); + jerry_value_free (obj); /* Cleanup engine */ jerry_cleanup (); @@ -13295,7 +12716,7 @@ main (void) Create a JSON string value from a JavaScript value. The behaviour is equivalent with the "JSON.stringify(input_value)" JS call. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -13308,7 +12729,7 @@ jerry_json_stringify (const jerry_value_t input_value); - `input_value` - a `jerry_value_t` to stringify. - return - `jerry_value_t` containing a JSON string. - - Error value in case of any stringification error. + - exception value in case of any stringification error. *New in version 2.0*. @@ -13325,21 +12746,21 @@ main (void) /* Initialize engine */ jerry_init (JERRY_INIT_EMPTY); - jerry_value_t obj = jerry_create_object (); + jerry_value_t obj = jerry_object (); { - jerry_value_t key = jerry_create_string ((const jerry_char_t *) "name"); - jerry_value_t value = jerry_create_string ((const jerry_char_t *) "John"); - jerry_release_value (jerry_set_property (obj, key, value)); - jerry_release_value (key); - jerry_release_value (value); + jerry_value_t key = jerry_string_sz ("name"); + jerry_value_t value = jerry_string_sz ("John"); + jerry_value_free (jerry_object_set (obj, key, value)); + jerry_value_free (key); + jerry_value_free (value); } jerry_value_t stringified = jerry_json_stringify (obj); /* "stringified" now contains a JSON string */ - jerry_release_value (stringified); - jerry_release_value (obj); + jerry_value_free (stringified); + jerry_value_free (obj); /* Cleanup engine */ jerry_cleanup (); @@ -13350,7 +12771,7 @@ main (void) # Container Functions -## jerry_get_array_from_container +## jerry_container_to_array **Summary** @@ -13362,7 +12783,7 @@ if the container object contains key-value structure and false if not. - This API function depends on a build option (`JERRY_BUILTIN_CONTAINER`) and can be checked runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` feature enum values. - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. *New in version [[NEXT_RELEASE]]*. @@ -13371,15 +12792,15 @@ if the container object contains key-value structure and false if not. ```c jerry_value_t -jerry_get_array_from_container(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 - `is_key_value` - Will be set to `true` if the given container has key-value pairs, `false` otherwise. - return value - jerry_value_t containing an array of values from the Map/Set or iterator object - - Error if the `value` is nor a Container or a Container Iterator. + - exception if the `value` is nor a Container or a Container Iterator. - `undefined` if the `value` is undefined/null. **Example** @@ -13396,15 +12817,15 @@ main (void) jerry_value_t iterable = jerry_eval (src, sizeof (src) - 1, JERRY_PARSE_NO_OPTS); bool is_key_value_container = false; - jerry_value_t buffer_from_map = jerry_get_array_from_container (iterable, &is_key_value_container); + jerry_value_t buffer_from_map = jerry_container_to_array (iterable, &is_key_value_container); /* The buffer_from_map contains two elements: 1 and 2, which is the key/value pair of the only item in the set. is_key_value set to true, as the original is a key-value structure (a Map Iterator) */ - jerry_release_value (iterable); - jerry_release_value (buffer_from_map); + jerry_value_free (iterable); + jerry_value_free (buffer_from_map); jerry_cleanup (); @@ -13414,33 +12835,33 @@ main (void) **See also** -- [jerry_create_container](#jerry_create_container) +- [jerry_container](#jerry_container) - [jerry_container_type_t](#jerry_container_type_t) -## jerry_container_operation +## jerry_container_op **Summary** Perform container operation on the given operands (add, delete, set, etc.). *Note*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. - This API function depends on a build option (`JERRY_BUILTIN_CONTAINER`) and can be checked runtime with the `JERRY_FEATURE_MAP` , `JERRY_FEATURE_SET` , `JERRY_FEATURE_WEAKMAP` , `JERRY_FEATURE_WEAKSET` feature enum values. - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + see: [jerry_feature_enabled](#jerry_feature_enabled). - The es.next profile enables this by default. **Prototype** ```c jerry_value_t -jerry_container_operation (jerry_container_operation_t operation, - jerry_value_t container, - jerry_value_t *arguments, - uint32_t arguments_number) +jerry_container_op (jerry_container_op_t operation, + jerry_value_t container, + jerry_value_t *arguments, + uint32_t arguments_number) ``` - `operation` - container operation @@ -13448,7 +12869,7 @@ jerry_container_operation (jerry_container_operation_t operation, - `arguments` - array of arguments - `arguments_number` - number of arguments - result if the operation is successful - - error, otherwise + - exception, otherwise *New in version [[NEXT_RELEASE]]*. @@ -13464,23 +12885,23 @@ main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_value_t map = jerry_create_container (JERRY_CONTAINER_TYPE_MAP, NULL, 0); - jerry_value_t key_str = jerry_create_string ((jerry_char_t *) "number"); - jerry_value_t number = jerry_create_number (10); + jerry_value_t map = jerry_container (JERRY_CONTAINER_TYPE_MAP, NULL, 0); + jerry_value_t key_str = jerry_string_sz ("number"); + jerry_value_t number = jerry_number (10); jerry_value_t args[2] = {key_str, number}; - jerry_value_t result = jerry_container_operation (JERRY_CONTAINER_OP_SET, map, args, 2); - jerry_release_value (result); + jerry_value_t result = jerry_container_op (JERRY_CONTAINER_OP_SET, map, args, 2); + jerry_value_free (result); - result = jerry_container_operation (JERRY_CONTAINER_OP_SIZE, map, NULL, 0); - jerry_release_value (result); + result = jerry_container_op (JERRY_CONTAINER_OP_SIZE, map, NULL, 0); + jerry_value_free (result); - result = jerry_container_operation (JERRY_CONTAINER_OP_CLEAR, map, NULL, 0); - jerry_release_value (result); + result = jerry_container_op (JERRY_CONTAINER_OP_CLEAR, map, NULL, 0); + jerry_value_free (result); - jerry_release_value (map); - jerry_release_value (key_str); - jerry_release_value (number); + jerry_value_free (map); + jerry_value_free (key_str); + jerry_value_free (number); jerry_cleanup (); return 0; @@ -13489,5 +12910,5 @@ main (void) **See also** -- [jerry_create_container](#jerry_create_container) +- [jerry_container](#jerry_container) - [jerry_container_type_t](#jerry_container_type_t) diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index ec180fcc..d8cf46ed 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -42,40 +42,7 @@ $ export PKG_CONFIG_PATH=$(pwd)/example_install/lib/pkgconfig/ Test if the `pkg-config` works for JerryScript: ```sh -$ pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-ext libjerry-math -``` - -## Example 1. Execute JavaScript from your application - -The most basic example to test the engine is to create an `api-example-1.c` file containing the following code: - -[doctest]: # () - -```c -#include "jerryscript.h" - -int -main (void) -{ - const jerry_char_t script[] = "var str = 'Hello, World!';"; - - bool ret_value = jerry_run_simple (script, sizeof (script) - 1, JERRY_INIT_EMPTY); - - return (ret_value ? 0 : 1); -} -``` - -To compile it one can use the following command: - -```sh -$ gcc api-example-1.c -o api-example-1 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math) -``` - -If everything is correct the application returns with a zero exit code: - -``` -$ ./api-example-1 -$ echo $? +$ pkg-config --cflags --libs libjerry-core libjerry-port libjerry-ext libjerry-math ``` ## Example 2. Split engine initialization and script execution. @@ -83,9 +50,9 @@ $ echo $? In this example the engine is initialized directly with the `jerry_init` method and cleaned up with the `jerry_cleanup` method. The example JavaScript code is directly parsed and executed via the `jerry_eval` method. Each `jerry_value_t` -returned by the API methods is freed with the `jerry_release_value` method. +returned by the API methods is freed with the `jerry_value_free` method. -To make sure that the code parsing and execution was ok, the `jerry_value_is_error` +To make sure that the code parsing and execution was ok, the `jerry_value_is_exception` method is used to check for any errors. Use the following code for the `api-example-2.c` file: @@ -113,10 +80,10 @@ main (void) JERRY_PARSE_NO_OPTS); /* Check if there was any error (syntax or runtime) */ - bool run_ok = !jerry_value_is_error (eval_ret); + bool run_ok = !jerry_value_is_exception (eval_ret); /* Parsed source code must be freed */ - jerry_release_value (eval_ret); + jerry_value_free (eval_ret); /* Cleanup engine */ jerry_cleanup (); @@ -128,7 +95,7 @@ main (void) To compile it one can use the following command: ```sh -$ gcc api-example-2.c -o api-example-2 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math) +$ gcc api-example-2.c -o api-example-2 $(pkg-config --cflags --libs libjerry-core libjerry-port libjerry-math) ``` If everything is correct the application returns with a zero exit code: @@ -166,20 +133,20 @@ main (void) jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL); /* Check if there is any JS code parse error */ - if (!jerry_value_is_error (parsed_code)) + if (!jerry_value_is_exception (parsed_code)) { /* Execute the parsed source code in the Global scope */ jerry_value_t ret_value = jerry_run (parsed_code); /* Check the execution return value if there is any error */ - run_ok = !jerry_value_is_error (ret_value); + run_ok = !jerry_value_is_exception (ret_value); /* Returned value must be freed */ - jerry_release_value (ret_value); + jerry_value_free (ret_value); } /* Parsed source code must be freed */ - jerry_release_value (parsed_code); + jerry_value_free (parsed_code); /* Cleanup engine */ jerry_cleanup (); @@ -191,7 +158,7 @@ main (void) To compile it one can use the following command: ```sh -$ gcc api-example-3.c -o api-example-3 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math) +$ gcc api-example-3.c -o api-example-3 $(pkg-config --cflags --libs libjerry-core libjerry-port libjerry-math) ``` If everything is correct the application returns with a zero exit code: @@ -210,10 +177,10 @@ In this example a very simple "print" method is added which prints out a static This method will be implemented in C and will be called from the JavaScript code. For this a few extra API methods are required: -- `jerry_get_global_object` -- `jerry_create_string` -- `jerry_set_property` -- `jerry_create_external_function` +- `jerry_current_realm` +- `jerry_string_sz` +- `jerry_object_set` +- `jerry_function_external` The `api-example-4.c` file should contain the following code: @@ -233,7 +200,7 @@ print_handler (const jerry_call_info_t *call_info_p, printf ("Print handler was called\n"); /* Return an "undefined" value to the JavaScript engine */ - return jerry_create_undefined (); + return jerry_undefined (); } int @@ -248,40 +215,40 @@ main (void) /* Add the "print" method for the JavaScript global object */ { /* Get the "global" object */ - jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t global_object = jerry_current_realm (); /* Create a "print" JS string */ - jerry_value_t property_name_print = jerry_create_string ((const jerry_char_t *) "print"); + jerry_value_t property_name_print = jerry_string_sz ("print"); /* Create a function from a native C method (this function will be called from JS) */ - jerry_value_t property_value_func = jerry_create_external_function (print_handler); + jerry_value_t property_value_func = jerry_function_external (print_handler); /* Add the "print" property with the function value to the "global" object */ - jerry_value_t set_result = jerry_set_property (global_object, property_name_print, property_value_func); + jerry_value_t set_result = jerry_object_set (global_object, property_name_print, property_value_func); /* Check if there was no error when adding the property (in this case it should never happen) */ - if (jerry_value_is_error (set_result)) { + if (jerry_value_is_exception (set_result)) { printf ("Failed to add the 'print' property\n"); } /* Release all jerry_value_t-s */ - jerry_release_value (set_result); - jerry_release_value (property_value_func); - jerry_release_value (property_name_print); - jerry_release_value (global_object); + jerry_value_free (set_result); + jerry_value_free (property_value_func); + jerry_value_free (property_name_print); + jerry_value_free (global_object); } /* Setup Global scope code */ jerry_value_t parsed_code = jerry_parse (script, script_size, NULL); - if (!jerry_value_is_error (parsed_code)) + if (!jerry_value_is_exception (parsed_code)) { /* Execute the parsed source code in the Global scope */ jerry_value_t ret_value = jerry_run (parsed_code); /* Returned value must be freed */ - jerry_release_value (ret_value); + jerry_value_free (ret_value); } /* Parsed source code must be freed */ - jerry_release_value (parsed_code); + jerry_value_free (parsed_code); /* Cleanup engine */ jerry_cleanup (); @@ -294,7 +261,7 @@ main (void) To compile it one can use the following command: ```sh -$ gcc api-example-4.c -o api-example-4 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math) +$ gcc api-example-4.c -o api-example-4 $(pkg-config --cflags --libs libjerry-core libjerry-port libjerry-math) ``` If everything is correct the application should print out the message present in the `print_handler` method: @@ -314,7 +281,7 @@ argument (which probably comes from a JavaScript source) to a JS string and prin New API methods used: - `jerry_value_to_string` -- `jerry_string_to_utf8_char_buffer` +- `jerry_string_to_buffer` The `api-example-5.c` file should contain the following code: @@ -342,17 +309,17 @@ print_handler (const jerry_call_info_t *call_info_p, * Please note that if the string does not fit into the buffer nothing will be copied. * More details on the API reference page */ - jerry_size_t copied_bytes = jerry_string_to_utf8_char_buffer (string_value, buffer, sizeof (buffer) - 1); + jerry_size_t copied_bytes = jerry_string_to_buffer (string_value, JERRY_ENCODING_UTF8, buffer, sizeof (buffer) - 1); buffer[copied_bytes] = '\0'; /* Release the "toString" result */ - jerry_release_value (string_value); + jerry_value_free (string_value); printf ("%s\n", (const char *)buffer); } /* Return an "undefined" value to the JavaScript engine */ - return jerry_create_undefined (); + return jerry_undefined (); } int @@ -367,40 +334,40 @@ main (void) /* Add the "print" method for the JavaScript global object */ { /* Get the "global" object */ - jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t global_object = jerry_current_realm (); /* Create a "print" JS string */ - jerry_value_t property_name_print = jerry_create_string ((const jerry_char_t *) "print"); + jerry_value_t property_name_print = jerry_string_sz ("print"); /* Create a function from a native C method (this function will be called from JS) */ - jerry_value_t property_value_func = jerry_create_external_function (print_handler); + jerry_value_t property_value_func = jerry_function_external (print_handler); /* Add the "print" property with the function value to the "global" object */ - jerry_value_t set_result = jerry_set_property (global_object, property_name_print, property_value_func); + jerry_value_t set_result = jerry_object_set (global_object, property_name_print, property_value_func); /* Check if there was no error when adding the property (in this case it should never happen) */ - if (jerry_value_is_error (set_result)) { + if (jerry_value_is_exception (set_result)) { printf ("Failed to add the 'print' property\n"); } /* Release all jerry_value_t-s */ - jerry_release_value (set_result); - jerry_release_value (property_value_func); - jerry_release_value (property_name_print); - jerry_release_value (global_object); + jerry_value_free (set_result); + jerry_value_free (property_value_func); + jerry_value_free (property_name_print); + jerry_value_free (global_object); } /* Setup Global scope code */ jerry_value_t parsed_code = jerry_parse (script, script_size, NULL); - if (!jerry_value_is_error (parsed_code)) + if (!jerry_value_is_exception (parsed_code)) { /* Execute the parsed source code in the Global scope */ jerry_value_t ret_value = jerry_run (parsed_code); /* Returned value must be freed */ - jerry_release_value (ret_value); + jerry_value_free (ret_value); } /* Parsed source code must be freed */ - jerry_release_value (parsed_code); + jerry_value_free (parsed_code); /* Cleanup engine */ jerry_cleanup (); @@ -413,7 +380,7 @@ main (void) To compile it one can use the following command: ```sh -$ gcc api-example-5.c -o api-example-5 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math) +$ gcc api-example-5.c -o api-example-5 $(pkg-config --cflags --libs libjerry-core libjerry-port libjerry-math) ``` If everything is correct the application should print out the string passed for the `print` method in the JS code: @@ -431,14 +398,14 @@ can be used by other applications. In this example the following extension methods are used: -- `jerryx_handler_register_global` +- `jerryx_register_global` - `jerryx_handler_print` In further examples this "print" handler will be used. ```c #include "jerryscript.h" -#include "jerryscript-ext/handler.h" +#include "jerryscript-ext/handlers.h" int main (void) @@ -450,23 +417,22 @@ main (void) jerry_init (JERRY_INIT_EMPTY); /* Register 'print' function from the extensions to the global object */ - jerryx_handler_register_global ((const jerry_char_t *) "print", - jerryx_handler_print); + jerryx_register_global ("print", jerryx_handler_print); /* Setup Global scope code */ jerry_value_t parsed_code = jerry_parse (script, script_size, NULL); - if (!jerry_value_is_error (parsed_code)) + if (!jerry_value_is_exception (parsed_code)) { /* Execute the parsed source code in the Global scope */ jerry_value_t ret_value = jerry_run (parsed_code); /* Returned value must be freed */ - jerry_release_value (ret_value); + jerry_value_free (ret_value); } /* Parsed source code must be freed */ - jerry_release_value (parsed_code); + jerry_value_free (parsed_code); /* Cleanup engine */ jerry_cleanup (); @@ -478,10 +444,10 @@ main (void) To compile it one can use the following command: -(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call. +(**Note** that the `libjerry-ext` was added **before** the `libjerry-port` entry for the `pkg-config` call. ```sh -$ gcc api-example-6.c -o api-example-6 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math) +$ gcc api-example-6.c -o api-example-6 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port libjerry-math) ``` If everything is correct the application should print out the string passed for the `print` method in the JS code: @@ -500,8 +466,10 @@ Use the following code as the `api-example-7.c` file: [doctest]: # () ```c +#include <stdio.h> #include "jerryscript.h" -#include "jerryscript-ext/handler.h" +#include "jerryscript-ext/handlers.h" +#include "jerryscript-ext/properties.h" int main (void) @@ -512,30 +480,29 @@ main (void) jerry_init (JERRY_INIT_EMPTY); /* Register 'print' function from the extensions */ - jerryx_handler_register_global ((const jerry_char_t *) "print", - jerryx_handler_print); + jerryx_register_global ("print", jerryx_handler_print); /* Getting pointer to the Global object */ - jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t global_object = jerry_current_realm (); /* Constructing strings */ - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_var"); - jerry_value_t prop_value = jerry_create_string ((const jerry_char_t *) "Hello from C!"); + jerry_value_t prop_name = jerry_string_sz ("my_var"); + jerry_value_t prop_value = jerry_string_sz ("Hello from C!"); /* Setting the string value as a property of the Global object */ - jerry_value_t set_result = jerry_set_property (global_object, prop_name, prop_value); + jerry_value_t set_result = jerry_object_set (global_object, prop_name, prop_value); /* The 'set_result' should be checked if there was any error */ - if (jerry_value_is_error (set_result)) { + if (jerry_value_is_exception (set_result)) { printf ("Failed to add the 'my_var' property\n"); } - jerry_release_value (set_result); + jerry_value_free (set_result); /* Releasing string values, as it is no longer necessary outside of engine */ - jerry_release_value (prop_name); - jerry_release_value (prop_value); + jerry_value_free (prop_name); + jerry_value_free (prop_value); /* Releasing the Global object */ - jerry_release_value (global_object); + jerry_value_free (global_object); /* Now starting script that would output value of just initialized field */ jerry_value_t eval_ret = jerry_eval (script, @@ -543,7 +510,7 @@ main (void) JERRY_PARSE_NO_OPTS); /* Free JavaScript value, returned by eval */ - jerry_release_value (eval_ret); + jerry_value_free (eval_ret); /* Freeing engine */ jerry_cleanup (); @@ -554,10 +521,10 @@ main (void) To compile it one can use the following command: -(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call. +(**Note** that the `libjerry-ext` was added **before** the `libjerry-port` entry for the `pkg-config` call. ```sh -$ gcc api-example-7.c -o api-example-7 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math) +$ gcc api-example-7.c -o api-example-7 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port libjerry-math) ``` The sample will output 'Hello from C!'. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine: @@ -571,9 +538,9 @@ $ ./api-example-7 JerryScript value can be a boolean, number, null, object, string, undefined or some special type of objects (arraybuffer, symbols, etc). There is a special "error" value which wraps another value. This "error" can be created by throwing a JavaScript value from JS code -or via API method(s). It is advised to check for this error with the `jerry_value_is_error` method as not all API methods -can process error values. To extract the value from the "error" the API method `jerry_get_value_from_error` should be used. -If an error object is created via API method (for example with `jerry_create_error`) the "error" value is automatically created. +or via API method(s). It is advised to check for this error with the `jerry_value_is_exception` method as not all API methods +can process error values. To extract the value from the "error" the API method `jerry_exception_value` should be used. +If an error object is created via API method (for example with `jerry_error`) the "error" value is automatically created. Notice the difference between error value and error object: - The error object is a object which was constructed via one of the `Error` objects (available from the global object or from API). @@ -590,7 +557,7 @@ var error_object = new Error ("error message"); throw "message"; ``` -To check what type a given `jerry_value_t` is the `jerry_value_is_*` methods or the `jerry_value_get_type` could be used. +To check what type a given `jerry_value_t` is the `jerry_value_is_*` methods or the `jerry_value_type` could be used. For example the following code snippet could print out a few types (not all types are checked): [doctest]: # (test="compile") @@ -605,14 +572,14 @@ print_value (const jerry_value_t jsvalue) { jerry_value_t value; /* If there is an error extract the object from it */ - if (jerry_value_is_error (jsvalue)) + if (jerry_value_is_exception (jsvalue)) { printf ("Error value detected: "); - value = jerry_get_value_from_error (jsvalue, false); + value = jerry_exception_value (jsvalue, false); } else { - value = jerry_acquire_value (jsvalue); + value = jerry_value_copy (jsvalue); } if (jerry_value_is_undefined (value)) @@ -637,7 +604,7 @@ print_value (const jerry_value_t jsvalue) /* Float value */ else if (jerry_value_is_number (value)) { - printf ("number: %lf", jerry_get_number_value (value)); + printf ("number: %lf", jerry_value_as_number (value)); } /* String value */ else if (jerry_value_is_string (value)) @@ -645,11 +612,11 @@ print_value (const jerry_value_t jsvalue) jerry_char_t str_buf_p[256]; /* Determining required buffer size */ - jerry_size_t req_sz = jerry_get_string_size (value); + jerry_size_t req_sz = jerry_string_size (value, JERRY_ENCODING_CESU8); if (req_sz <= 255) { - jerry_string_to_char_buffer (value, str_buf_p, req_sz); + jerry_string_to_buffer (value, JERRY_ENCODING_CESU8, str_buf_p, req_sz); str_buf_p[req_sz] = '\0'; printf ("%s", (const char *) str_buf_p); } @@ -665,7 +632,7 @@ print_value (const jerry_value_t jsvalue) } printf ("\n"); - jerry_release_value (value); + jerry_value_free (value); } ``` @@ -692,21 +659,22 @@ See the following `api-example-8-shell.c` file: #include <stdlib.h> #include <string.h> #include "jerryscript.h" -#include "jerryscript-ext/handler.h" +#include "jerryscript-ext/handlers.h" +#include "jerryscript-ext/properties.h" static void print_value (const jerry_value_t jsvalue) { jerry_value_t value; /* If there is an error extract the object from it */ - if (jerry_value_is_error (jsvalue)) + if (jerry_value_is_exception (jsvalue)) { printf ("Error value detected: "); - value = jerry_get_value_from_error (jsvalue, false); + value = jerry_exception_value (jsvalue, false); } else { - value = jerry_acquire_value (jsvalue); + value = jerry_value_copy (jsvalue); } if (jerry_value_is_undefined (value)) @@ -731,7 +699,7 @@ print_value (const jerry_value_t jsvalue) /* Float value */ else if (jerry_value_is_number (value)) { - printf ("number: %lf", jerry_get_number_value (value)); + printf ("number: %lf", jerry_value_as_number (value)); } /* String value */ else if (jerry_value_is_string (value)) @@ -739,11 +707,11 @@ print_value (const jerry_value_t jsvalue) jerry_char_t str_buf_p[256]; /* Determining required buffer size */ - jerry_size_t req_sz = jerry_get_string_size (value); + jerry_size_t req_sz = jerry_string_size (value, JERRY_ENCODING_CESU8); if (req_sz <= 255) { - jerry_string_to_char_buffer (value, str_buf_p, req_sz); + jerry_string_to_buffer (value, JERRY_ENCODING_CESU8, str_buf_p, req_sz); str_buf_p[req_sz] = '\0'; printf ("%s", (const char *) str_buf_p); } @@ -759,7 +727,7 @@ print_value (const jerry_value_t jsvalue) } printf ("\n"); - jerry_release_value (value); + jerry_value_free (value); } int @@ -771,8 +739,7 @@ main (void) jerry_init (JERRY_INIT_EMPTY); /* Register 'print' function from the extensions */ - jerryx_handler_register_global ((const jerry_char_t *) "print", - jerryx_handler_print); + jerryx_register_global ("print", jerryx_handler_print); while (!is_done) { @@ -815,7 +782,7 @@ main (void) /* Print out the value */ print_value (ret_val); - jerry_release_value (ret_val); + jerry_value_free (ret_val); } /* Cleanup engine */ @@ -827,10 +794,10 @@ main (void) To compile it one can use the following command: -(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call. +(**Note** that the `libjerry-ext` was added **before** the `libjerry-port` entry for the `pkg-config` call. ```sh -$ gcc api-example-8-shell.c -o api-example-8-shell $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math) +$ gcc api-example-8-shell.c -o api-example-8-shell $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port libjerry-math) ``` The application reads lines from standard input and evaluates them, one after another. To try out run: @@ -848,7 +815,8 @@ In this example (`api-example-9.c`) an object with a native function is added to ```c #include "jerryscript.h" -#include "jerryscript-ext/handler.h" +#include "jerryscript-ext/handlers.h" +#include "jerryscript-ext/properties.h" struct my_struct { @@ -863,7 +831,7 @@ get_msg_handler (const jerry_call_info_t *call_info_p, /**< call information */ const jerry_value_t *args_p, /**< function arguments */ const jerry_length_t args_cnt) /**< number of function arguments */ { - return jerry_create_string ((const jerry_char_t *) my_struct.msg); + return jerry_string_sz (my_struct.msg); } /* get_msg_handler */ int @@ -873,33 +841,32 @@ main (void) jerry_init (JERRY_INIT_EMPTY); /* Register 'print' function from the extensions */ - jerryx_handler_register_global ((const jerry_char_t *) "print", - jerryx_handler_print); + jerryx_register_global ("print", jerryx_handler_print); /* Do something with the native object */ my_struct.msg = "Hello, World!"; /* Create an empty JS object */ - jerry_value_t object = jerry_create_object (); + jerry_value_t object = jerry_object (); /* Create a JS function object and wrap into a jerry value */ - jerry_value_t func_obj = jerry_create_external_function (get_msg_handler); + jerry_value_t func_obj = jerry_function_external (get_msg_handler); /* Set the native function as a property of the empty JS object */ - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "myFunc"); - jerry_release_value (jerry_set_property (object, prop_name, func_obj)); - jerry_release_value (prop_name); - jerry_release_value (func_obj); + jerry_value_t prop_name = jerry_string_sz ("myFunc"); + jerry_value_free (jerry_object_set (object, prop_name, func_obj)); + jerry_value_free (prop_name); + jerry_value_free (func_obj); /* Wrap the JS object (not empty anymore) into a jerry api value */ - jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t global_object = jerry_current_realm (); /* Add the JS object to the global context */ - prop_name = jerry_create_string ((const jerry_char_t *) "MyObject"); - jerry_release_value (jerry_set_property (global_object, prop_name, object)); - jerry_release_value (prop_name); - jerry_release_value (object); - jerry_release_value (global_object); + prop_name = jerry_string_sz ("MyObject"); + jerry_value_free (jerry_object_set (global_object, prop_name, object)); + jerry_value_free (prop_name); + jerry_value_free (object); + jerry_value_free (global_object); /* Now we have a "builtin" object called MyObject with a function called myFunc() * @@ -915,7 +882,7 @@ main (void) jerry_value_t eval_ret = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); /* Free JavaScript value, returned by eval */ - jerry_release_value (eval_ret); + jerry_value_free (eval_ret); /* Cleanup engine */ jerry_cleanup (); @@ -926,10 +893,10 @@ main (void) To compile it one can use the following command: -(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call. +(**Note** that the `libjerry-ext` was added **before** the `libjerry-port` entry for the `pkg-config` call. ```sh -$ gcc api-example-9.c -o api-example-9 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math) +$ gcc api-example-9.c -o api-example-9 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port libjerry-math) ``` Execute the example with: @@ -956,7 +923,8 @@ Use the following code for `api-example-10.c`: ```c #include "jerryscript.h" -#include "jerryscript-ext/handler.h" +#include "jerryscript-ext/handlers.h" +#include "jerryscript-ext/properties.h" /** * Add param to 'this.x' @@ -970,27 +938,27 @@ add_handler (const jerry_call_info_t *call_info_p, /**< call information */ /* Note: that the argument count check is ignored for the example's case */ /* Get 'this.x' */ - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "x"); - jerry_value_t x_val = jerry_get_property (call_info_p->this_value, prop_name); + jerry_value_t prop_name = jerry_string_sz ("x"); + jerry_value_t x_val = jerry_object_get (call_info_p->this_value, prop_name); - if (!jerry_value_is_error (x_val)) + if (!jerry_value_is_exception (x_val)) { /* Convert Jerry API values to double */ - double x = jerry_get_number_value (x_val); - double d = jerry_get_number_value (args_p[0]); + double x = jerry_value_as_number (x_val); + double d = jerry_value_as_number (args_p[0]); /* Add the parameter to 'x' */ - jerry_value_t res_val = jerry_create_number (x + d); + jerry_value_t res_val = jerry_number (x + d); /* Set the new value of 'this.x' */ - jerry_release_value (jerry_set_property (call_info_p->this_value, prop_name, res_val)); - jerry_release_value (res_val); + jerry_value_free (jerry_object_set (call_info_p->this_value, prop_name, res_val)); + jerry_value_free (res_val); } - jerry_release_value (x_val); - jerry_release_value (prop_name); + jerry_value_free (x_val); + jerry_value_free (prop_name); - return jerry_create_undefined (); + return jerry_undefined (); } /* add_handler */ int @@ -1000,8 +968,7 @@ main (void) jerry_init (JERRY_INIT_EMPTY); /* Register 'print' function from the extensions */ - jerryx_handler_register_global ((const jerry_char_t *) "print", - jerryx_handler_print); + jerryx_register_global ("print", jerryx_handler_print); /* Create a JS object */ const jerry_char_t my_js_object[] = " \ @@ -1023,16 +990,16 @@ main (void) JERRY_PARSE_NO_OPTS); /* Create a JS function object and wrap into a jerry value */ - jerry_value_t add_func_obj = jerry_create_external_function (add_handler); + jerry_value_t add_func_obj = jerry_function_external (add_handler); /* Set the native function as a property of previously created MyObject */ - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "add2x"); - jerry_release_value (jerry_set_property (my_js_obj_val, prop_name, add_func_obj)); - jerry_release_value (add_func_obj); - jerry_release_value (prop_name); + jerry_value_t prop_name = jerry_string_sz ("add2x"); + jerry_value_free (jerry_object_set (my_js_obj_val, prop_name, add_func_obj)); + jerry_value_free (add_func_obj); + jerry_value_free (prop_name); /* Free JavaScript value, returned by eval (my_js_object) */ - jerry_release_value (my_js_obj_val); + jerry_value_free (my_js_obj_val); const jerry_char_t script[] = " \ var str = MyObject.foo (); \ @@ -1045,7 +1012,7 @@ main (void) jerry_value_t eval_ret = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); /* Free JavaScript value, returned by eval */ - jerry_release_value (eval_ret); + jerry_value_free (eval_ret); /* Cleanup engine */ jerry_cleanup (); @@ -1056,10 +1023,10 @@ main (void) To compile it one can use the following command: -(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call. +(**Note** that the `libjerry-ext` was added **before** the `libjerry-port` entry for the `pkg-config` call. ```sh -$ gcc api-example-10.c -o api-example-10 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math) +$ gcc api-example-10.c -o api-example-10 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port libjerry-math) ``` Execute the example with: @@ -1076,7 +1043,7 @@ Value of x is 17 ## Example 11. Changing the seed of pseudorandom generated numbers If you want to change the seed of `Math.random()` generated numbers, you have to initialize the seed value with `srand`. -A recommended method is using `jerry_port_get_current_time()` or something based on a constantly changing value, therefore every run produces truly random numbers. +A recommended method is using `jerry_port_current_time()` or something based on a constantly changing value, therefore every run produces truly random numbers. [doctest]: # () @@ -1084,13 +1051,14 @@ A recommended method is using `jerry_port_get_current_time()` or something based #include <stdlib.h> #include "jerryscript.h" #include "jerryscript-port.h" -#include "jerryscript-ext/handler.h" +#include "jerryscript-ext/handlers.h" +#include "jerryscript-ext/properties.h" int main (void) { /* Initialize srand value */ - union { double d; unsigned u; } now = { .d = jerry_port_get_current_time () }; + union { double d; unsigned u; } now = { .d = jerry_port_current_time () }; srand (now.u); /* Generate a random number, and print it */ @@ -1100,14 +1068,13 @@ main (void) jerry_init (JERRY_INIT_EMPTY); /* Register the print function */ - jerryx_handler_register_global ((const jerry_char_t *) "print", - jerryx_handler_print); + jerryx_register_global ("print", jerryx_handler_print); /* Evaluate the script */ jerry_value_t eval_ret = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); /* Free the JavaScript value returned by eval */ - jerry_release_value (eval_ret); + jerry_value_free (eval_ret); /* Cleanup the engine */ jerry_cleanup (); diff --git a/05.PORT-API.md b/05.PORT-API.md index 6a58f5f4..14ffc48d 100644 --- a/05.PORT-API.md +++ b/05.PORT-API.md @@ -10,7 +10,7 @@ permalink: /port-api/ # Reference -## Termination +## Process management 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. @@ -34,367 +34,258 @@ Error codes ```c typedef enum { - ERR_OUT_OF_MEMORY = 10, - ERR_REF_COUNT_LIMIT = 12, - ERR_DISABLED_BYTE_CODE = 13, - ERR_FAILED_INTERNAL_ASSERTION = 120 + JERRY_FATAL_OUT_OF_MEMORY = 10, + JERRY_FATAL_REF_COUNT_LIMIT = 12, + JERRY_FATAL_DISABLED_BYTE_CODE = 13, + JERRY_FATAL_UNTERMINATED_GC_LOOPS = 14, + JERRY_FATAL_FAILED_ASSERTION = 120 } jerry_fatal_code_t; ``` -## I/O - -These are the only I/O functions jerry calls. - ```c /** - * Jerry log levels. The levels are in severity order - * where the most serious levels come first. + * Makes the process sleep for a given time. + * + * Note: + * This port function is called by jerry-core when JERRY_DEBUGGER is set to 1. + * Otherwise this function is not used. + * + * @param sleep_time milliseconds to sleep. */ -typedef enum -{ - 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 */ -} jerry_log_level_t; +void jerry_port_sleep (uint32_t sleep_time); +``` + +## External context + +Allows the user to provide external buffer for isolated engine contexts, so that user +can configure the heap size at runtime and run multiple JS applications +simultaneously. +```c /** - * Display or log a debug/error message, and sends it to the debugger client as well. - * The function should implement a printf-like interface, where the first argument - * specifies the log level and the second argument specifies a format string on how - * to stringify the rest of the parameter list. + * Allocate a new context for the engine. * - * This function is only called with messages coming from the jerry engine as - * the result of some abnormal operation or describing its internal operations - * (e.g., data structure dumps or tracing info). + * This port function is called by jerry_init when JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not + * used. The engine will pass the size required for the context structure. An implementation must make sure to + * allocate at least this amount. * - * It should be the port that decides whether error and debug messages are logged to - * the console, or saved to a database or to a file. + * Excess allocated space will be used as the engine heap when jerryscript is configured to use it's internal allocator, + * this can be used to control the internal heap size. * - * Example: a libc-based port may implement this with vfprintf(stderr) or - * vfprintf(logfile), or both, depending on log level. + * NOTE: The allocated memory must be pointer-aligned, otherwise the behavior is + * undefined. * - * Note: - * This port function is called by jerry-core when JERRY_LOGGING is - * enabled. It is also common practice though to use this function in - * application code. + * @param context_size: the size of the internal context structure + * + * @return total size of the allocated buffer */ -void jerry_port_log (jerry_log_level_t level, const char *fmt, ...); +size_t jerry_port_context_alloc (size_t context_size); ``` -The `jerry_port_print_char` is currently not used by the jerry-core directly. -However, it provides a port specific way for `jerry-ext` components to print -information. - ```c /** - * Print a character to stdout. + * Get the currently active context of the engine. + * + * This port function is called by jerry-core when JERRY_EXTERNAL_CONTEXT is enabled. + * Otherwise this function is not used. + * + * @return the pointer to the currently used engine context. */ -void jerry_port_print_char (char c); +struct jerry_context_t *jerry_port_context_get (void); ``` -### Jerry Module system - -The port API provides optional functions that can be used by the -user application to resolve modules. If no callback is provided -to `jerry_module_link`, the `jerry_port_module_resolve` function -is used for resolving modules. - ```c /** - * Opens file with the given path and reads its source. - * @return the source of the file - */ -uint8_t * -jerry_port_read_source (const char *file_name_p, /**< file name */ - size_t *out_size_p) /**< [out] read bytes */ -{ - // open file from given path - // return its source -} /* jerry_port_read_source */ - -/** - * Release the previously opened file's content. - */ -void -jerry_port_release_source (uint8_t *buffer_p) /**< buffer to free */ -{ - free (buffer_p); -} /* jerry_port_release_source */ - -/** - * Default module resolver. + * Free the currently used context. * - * @return a module object if resolving is successful, an error otherwise - */ -jerry_value_t -jerry_port_module_resolve (const jerry_value_t specifier, /**< module specifier string */ - const jerry_value_t referrer, /**< parent module */ - void *user_p) /**< user data */ -{ - // Resolves a module using the specifier string. If a referrer is a module, - // and specifier is a relative path, the base path should be the directory - // part extracted from the path of the referrer module. - - // The callback function of jerry_module_link may call this function - // if it cannot resolve a module. Furthermore if the callback is NULL, - // this function is used for resolving modules. - - // The default implementation only resolves ECMAScript modules, and does - // not (currently) use the user data. -} /* jerry_port_module_resolve */ - -/** - * Release known modules. + * This port function is called by jerry_cleanup when JERRY_EXTERNAL_CONTEXT is enabled. + * Otherwise this function is not used. + * + * @return the pointer to the engine context. */ -void -jerry_port_module_release (const jerry_value_t realm) /**< if this argument is object, release only those modules, - * which realm value is equal to this argument. */ -{ - // This function releases the known modules, forcing their reload - // when resolved again later. The released modules can be filtered - // by realms. This function is only called by user applications. -} /* jerry_port_module_release */ +void jerry_port_context_free (void); ``` -## Date +## I/O ```c /** - * Get local time zone adjustment, in milliseconds, for the given timestamp. - * The timestamp can be specified in either UTC or local time, depending on - * the value of is_utc. Adding the value returned from this function to - * a timestamp in UTC time should result in local time for the current time - * zone, and subtracting it from a timestamp in local time should result in - * UTC time. + * Display or log a debug/error message. * - * Ideally, this function should satisfy the stipulations applied to LocalTZA - * in section 20.3.1.7 of the ECMAScript version 9.0 spec. + * The message is passed as a zero-terminated string. Messages may be logged in parts, which + * will result in multiple calls to this functions. The implementation should consider + * this before appending or prepending strings to the argument. * - * See Also: - * ECMA-262 v9, 20.3.1.7 + * This function is called with messages coming from the jerry engine as + * the result of some abnormal operation or describing its internal operations + * (e.g., data structure dumps or tracing info). * - * Note: - * This port function is called by jerry-core when - * JERRY_BUILTIN_DATE is set to 1. Otherwise this function is - * not used. - * - * @param unix_ms The unix timestamp we want an offset for, given in - * millisecond precision (could be now, in the future, - * or in the past). As with all unix timestamps, 0 refers to - * 1970-01-01, a day is exactly 86 400 000 milliseconds, and - * leap seconds cause the same second to occur twice. - * @param is_utc Is the given timestamp in UTC time? If false, it is in local - * time. - * - * @return milliseconds between local time and UTC for the given timestamp, - * if available - *. 0 if not available / we are in UTC. + * The implementation can decide whether error and debug messages are logged to + * the console, or saved to a database or to a file. */ -double jerry_port_get_local_time_zone_adjustment (double unix_ms, bool is_utc); +void jerry_port_log (const char *message_p); +``` +```c /** - * Get system time + * Print a single character to standard output. * - * Note: - * This port function is called by jerry-core when - * JERRY_BUILTIN_DATE is set to 1. It is also common practice - * in application code to use this function for the initialization of the - * random number generator. + * This port function is never called from jerry-core directly, it is only used by jerry-ext components to print + * information. * - * @return milliseconds since Unix epoch + * @param byte: the byte to print. */ -double jerry_port_get_current_time (void); +void jerry_port_print_byte (jerry_char_t byte); ``` -## External context - -Allow user to provide external buffer for isolated engine contexts, so that user -can configure the heap size at runtime and run multiple JS applications -simultaneously. - ```c /** - * Get the current context of the engine. Each port should provide its own - * implementation of this interface. + * Print a buffer to standard output * - * Note: - * This port function is called by jerry-core when - * JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not - * used. + * This port function is never called from jerry-core directly, it is only used by jerry-ext components to print + * information. * - * @return the pointer to the engine context. + * @param buffer_p: input buffer + * @param buffer_size: data size */ -struct jerry_context_t *jerry_port_get_current_context (void); +void jerry_port_print_buffer (const jerry_char_t *buffer_p, jerry_size_t buffer_size); ``` -## Sleep - ```c /** - * Makes the process sleep for a given time. + * Read a line from standard input. * - * Note: - * This port function is called by jerry-core when JERRY_DEBUGGER is set to 1. - * Otherwise this function is not used. + * The implementation should allocate storage necessary for the string. The result string should include the ending line + * terminator character(s) and should be zero terminated. * - * @param sleep_time milliseconds to sleep. + * An implementation may return NULL to signal that the end of input is reached, or an error occured. + * + * When a non-NULL value is returned, the caller will pass the returned value to `jerry_port_line_free` when the line is + * no longer needed. This can be used to finalize dynamically allocated buffers if necessary. + * + * This port function is never called from jerry-core directly, it is only used by some jerry-ext components that + * require user input. + * + * @param out_size_p: size of the input string in bytes, excluding terminating zero byte + * + * @return pointer to the buffer storing the string, + * or NULL if end of input */ -void jerry_port_sleep (uint32_t sleep_time); +jerry_char_t *jerry_port_line_read (jerry_size_t *out_size_p); ``` -# How to port JerryScript - -This section describes a basic port implementation which was created for Unix based systems. - -## Termination - ```c -#include <stdlib.h> -#include "jerryscript-port.h" - /** - * Default implementation of jerry_port_fatal. + * Free a line buffer allocated by jerry_port_line_read + * + * @param buffer_p: buffer returned by jerry_port_line_read */ -void jerry_port_fatal (jerry_fatal_code_t code) -{ - exit (code); -} /* jerry_port_fatal */ +void jerry_port_line_free (jerry_char_t *buffer_p); ``` -## I/O - -```c -#include <stdarg.h> -#include "jerryscript-port.h" +## Filesystem +``` /** - * Provide log message implementation for the engine. + * Canonicalize a file path. * - * Note: - * This example ignores the log level. + * If possible, the implementation should resolve symbolic links and other directory references found in the input path, + * and create a fully canonicalized file path as the result. + * + * The function may return with NULL in case an error is encountered, in which case the calling operation will not + * proceed. + * + * The implementation should allocate storage for the result path as necessary. Non-NULL return values will be passed + * to `jerry_port_path_free` when the result is no longer needed by the caller, which can be used to finalize + * dynamically allocated buffers. + * + * NOTE: The implementation must not return directly with the input, as the input buffer is released after the call. + * + * @param path_p: zero-terminated string containing the input path + * @param path_size: size of the input path string in bytes, excluding terminating zero + * + * @return buffer with the normalized path if the operation is successful, + * NULL otherwise */ -void -jerry_port_log (jerry_log_level_t level, /**< log level */ - const char *format, /**< format string */ - ...) /**< parameters */ -{ - va_list args; - va_start (args, format); - vfprintf (stderr, format, args); - va_end (args); -} /* jerry_port_log */ +jerry_char_t *jerry_port_path_normalize (const jerry_char_t *path_p, jerry_size_t path_size); ``` ```c /** - * Print a character to stdout with putchar. + * Free a path buffer returned by jerry_port_path_normalize. + * + * @param path_p: the path buffer to free */ -void -jerry_port_print_char (char c) -{ - putchar (c); -} /* jerry_port_print_char */ +void jerry_port_path_free (jerry_char_t *path_p); ``` -## Date - ```c -#include <time.h> -#include <sys/time.h> -#include "jerryscript-port.h" - /** - * Default implementation of jerry_port_get_local_time_zone_adjustment. + * Get the offset of the basename component in the input path. + * + * The implementation should return the offset of the first character after the last path separator found in the path. + * This is used by the caller to split the path into a directory name and a file name. + * + * @param path_p: input zero-terminated path string + * + * @return offset of the basename component in the input path */ -double jerry_port_get_local_time_zone_adjustment (double unix_ms, /**< ms since unix epoch */ - bool is_utc) /**< is the time above in UTC? */ -{ - struct tm tm; - time_t now = (time_t) (unix_ms / 1000); - localtime_r (&now, &tm); - if (!is_utc) - { - now -= tm.tm_gmtoff; - localtime_r (&now, &tm); - } - return ((double) tm.tm_gmtoff) * 1000; -} /* jerry_port_get_local_time_zone_adjustment */ +jerry_size_t jerry_port_path_base (const jerry_char_t *path_p); +``` +```c /** - * Default implementation of jerry_port_get_current_time. + * Open a source file and read its contents into a buffer. + * + * When the source file is no longer needed by the caller, the returned pointer will be passed to + * `jerry_port_source_free`, which can be used to finalize the buffer. + * + * @param file_name_p: Path that points to the source file in the filesystem. + * @param out_size_p: The opened file's size in bytes. + * + * @return pointer to the buffer which contains the content of the file. */ -double jerry_port_get_current_time (void) -{ - struct timeval tv; - - if (gettimeofday (&tv, NULL) != 0) - { - return 0; - } - - return ((double) tv.tv_sec) * 1000.0 + ((double) tv.tv_usec) / 1000.0; -} /* jerry_port_get_current_time */ +jerry_char_t *jerry_port_source_read (const char *file_name_p, jerry_size_t *out_size_p); ``` -## External context - ```c -#include "jerryscript-port.h" -#include "jerryscript-port-default.h" - /** - * Pointer to the current context. - * Note that it is a global variable, and is not a thread safe implementation. + * Free a source file buffer. + * + * @param buffer_p: buffer returned by jerry_port_source_read */ -static jerry_context_t *current_context_p = NULL; +void jerry_port_source_free (jerry_char_t *buffer_p); +``` -/** - * Set the current_context_p as the passed pointer. - */ -void -jerry_port_default_set_current_context (jerry_context_t *context_p) /**< points to the created context */ -{ - current_context_p = context_p; -} /* jerry_port_default_set_current_context */ +## Date +```c /** - * Get the current context. + * Get local time zone adjustment in milliseconds for the given input time. + * + * The argument is a time value representing milliseconds since unix epoch. + * + * Ideally, this function should satisfy the stipulations applied to LocalTZA + * in section 21.4.1.7 of the ECMAScript version 12.0, as if called with isUTC true. * - * @return the pointer to the current context + * This port function can be called by jerry-core when JERRY_BUILTIN_DATE is enabled. + * Otherwise this function is not used. + * + * @param unix_ms: time value in milliseconds since unix epoch + * + * @return local time offset in milliseconds applied to UTC for the given time value */ -jerry_context_t * -jerry_port_get_current_context (void) -{ - return current_context_p; -} /* jerry_port_get_current_context */ +int32_t jerry_port_local_tza (double unix_ms); ``` -## Sleep - ```c -#include "jerryscript-port.h" -#include "jerryscript-port-default.h" - -#ifdef HAVE_TIME_H -#include <time.h> -#elif defined (HAVE_UNISTD_H) -#include <unistd.h> -#endif /* HAVE_TIME_H */ - -#if defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1) -void jerry_port_sleep (uint32_t sleep_time) -{ -#ifdef HAVE_TIME_H - nanosleep (&(const struct timespec) - { - (time_t) sleep_time / 1000, ((long int) sleep_time % 1000) * 1000000L /* Seconds, nanoseconds */ - } - , NULL); -#elif defined (HAVE_UNISTD_H) - usleep ((useconds_t) sleep_time * 1000); -#endif /* HAVE_TIME_H */ - (void) sleep_time; -} /* jerry_port_sleep */ -#endif /* defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1) */ +/** + * Get the current system time in UTC. + * + * This port function is called by jerry-core when JERRY_BUILTIN_DATE is enabled. + * It can also be used in the implementing application to initialize the random number generator. + * + * @return milliseconds since Unix epoch + */ +double jerry_port_current_time (void); ``` diff --git a/06.REFERENCE-COUNTING.md b/06.REFERENCE-COUNTING.md index fc9eb788..9baf1db5 100644 --- a/06.REFERENCE-COUNTING.md +++ b/06.REFERENCE-COUNTING.md @@ -13,10 +13,10 @@ permalink: /reference-counting/ In JerryScript all `jerry_value_t` values are independent references to internal objects. Values returned by JerryScript API functions are always live references and must be released -by `jerry_release_value`. +by `jerry_value_free`. ```c - jerry_value_t global = jerry_get_global_object (); + jerry_value_t global = jerry_current_realm (); /* The value stored in the 'global' variable contains a live * reference to the global object. The system also keeps its @@ -24,9 +24,9 @@ by `jerry_release_value`. * are independent, and both must be destroyed before the global * object can be freed. */ - jerry_release_value (global); + jerry_value_free (global); - /* Without jerry_release_value() the global object will not + /* Without jerry_value_free() the global object will not * be freed even by jerry_cleanup(). After the reference * is released it becomes a dead reference and cannot be * used anymore. */ @@ -36,15 +36,15 @@ Multiple references might refer to the same internal object even though their `jerry_value_t` representation might be different. ```c - jerry_value_t pi_ref1 = jerry_create_number (3.14); - jerry_value_t pi_ref2 = jerry_acquire_value (pi_ref1); + jerry_value_t pi_ref1 = jerry_number (3.14); + jerry_value_t pi_ref2 = jerry_value_copy (pi_ref1); /* Both pi_ref1 and pi_ref2 refer to the same 3.14 value * although they might not be equal in C (pi_ref1 != pi_ref2). */ /* Both references must be released. */ - jerry_release_value (pi_ref1); - jerry_release_value (pi_ref2); + jerry_value_free (pi_ref1); + jerry_value_free (pi_ref2); ``` Releasing the same `jerry_value_t` twice to release two live @@ -52,8 +52,8 @@ references is not allowed and it might cause crashes. Hence the following code is an **INCORRECT WAY** of releasing the 3.14 value. ```c - jerry_release_value (pi_ref1); - jerry_release_value (pi_ref1); + jerry_value_free (pi_ref1); + jerry_value_free (pi_ref1); ``` JerryScript API functions returning with a `jerry_value_t` always @@ -63,7 +63,7 @@ stated in the documentation). The next example shows this behaviour through property getting and setting. ```c - jerry_value_t prop_value = jerry_get_property (...); + jerry_value_t prop_value = jerry_object_get (...); /* The prop_value must be released later because both the base * object and the prop_value have an independent reference to @@ -71,7 +71,7 @@ behaviour through property getting and setting. * prop_value contains a live reference to an error object. * This reference must be released as well. */ - if (jerry_value_is_error (prop_value)) + if (jerry_value_is_exception (prop_value)) { /* Errors can be handled here. */ } @@ -83,12 +83,12 @@ behaviour through property getting and setting. } /* The prop_value must be released. */ - jerry_release_value (prop_value); + jerry_value_free (prop_value); /* Property setting is the same. */ - jerry_value_t new_prop_value = jerry_create_number (2.718); - jerry_value_t result = jerry_set_property (..., new_prop_value); + jerry_value_t new_prop_value = jerry_number (2.718); + jerry_value_t result = jerry_object_set (..., new_prop_value); /* If the property set is successful, a new reference is created * for the value referenced by new_prop_value. The new_prop_value @@ -96,14 +96,14 @@ behaviour through property getting and setting. * is successful. */ /* The new_prop_value can be passed to other JerryScript API - * functions before the jerry_release_value () call. */ + * functions before the jerry_value_free () call. */ - jerry_release_value (new_prop_value); + jerry_value_free (new_prop_value); /* The reference stored in the 'result' variable is live whether * the operation is successful or not, and must also be freed. */ - if (jerry_value_is_error (result)) + if (jerry_value_is_exception (result)) { /* Errors can be handled here. */ } @@ -112,7 +112,7 @@ behaviour through property getting and setting. /* A reference to a true primitive value is returned. */ } - jerry_release_value (result); + jerry_value_free (result); ``` The simplest form of setting a property without error checking @@ -120,8 +120,8 @@ is the following: ```c /* There are no 'ifs' in this snippet. */ - jerry_release_value (jerry_set_property (..., new_prop_value)); - jerry_release_value (new_prop_value); + jerry_value_free (jerry_object_set (..., new_prop_value)); + jerry_value_free (new_prop_value); ``` The reference returned by a `jerry_external_handler_t` callback @@ -138,48 +138,48 @@ jerry_value_t my_external_handler (const jerry_value_t function_obj, * these references are automatically released after the handler * is returned. This approach reduces code size which is useful * on embedded systems. However you can create other references - * to them by calling jerry_acquire_value () if needed. */ + * to them by calling jerry_value_copy () if needed. */ /* Since the ownership of the reference is transferred to the * caller the following snippet is valid. */ /* If the value to be returned is needed for other purposes the - * jerry_acquire_value () can be used to create new references. */ - return jerry_create_string (...); + * jerry_value_copy () can be used to create new references. */ + return jerry_string (...); } ``` Duplicating a `jerry_value_t` in C does not create another live reference. ```c - jerry_value_t undef = jerry_create_undefined (); + jerry_value_t undef = jerry_undefined (); jerry_value_t undef2 = undef; /* Releasing either undef or undef2 is valid but not both. * After the release both references become dead (invalid). */ - jerry_release_value (undef2); + jerry_value_free (undef2); /* Dead references can be reassigned again. */ - undef = jerry_create_boolean (true); + undef = jerry_boolean (true); ``` References can be duplicated in C as long as only one of them is freed. ```c - jerry_value_t a = jerry_create_boolean (true); + jerry_value_t a = jerry_boolean (true); jerry_value_t b = a; jerry_value_t c = a; /* A new reference is assigned to 'a'. */ - a = jerry_create_boolean (false); + a = jerry_boolean (false); [...] - jerry_release_value (a); + jerry_value_free (a); /* The 'a' (boolean false) reference becomes dead (invalid). */ - jerry_release_value (c); + jerry_value_free (c); /* Both 'b' and 'c' (boolean true) references become dead. */ /* Since all references are released, no memory leak occurs. */ diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md index 09b6bd70..515c2a1c 100644 --- a/07.DEBUGGER.md +++ b/07.DEBUGGER.md @@ -84,8 +84,8 @@ Currently, `jerryx_debugger_rp_create ()` for raw packet transport layer and `jerryx_debugger_serial_create (const char* config)` for serial protocol are also available.) -The resource name provided to `jerry_parse ()` is used by the client -to identify the resource name of the source code. This resource name +The source name provided to `jerry_parse ()` is used by the client +to identify the source name of the source code. This source name is usually a file name. ## JerryScript debugger C-API interface @@ -107,14 +107,14 @@ when a source code is received successfully. ```c typedef jerry_value_t -(*jerry_debugger_wait_for_source_callback_t) (const jerry_char_t *resource_name_p, - size_t resource_name_size, +(*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); ``` -- `resource_name_p` - resource (usually a file) name of the source code -- `resource_name_size` - size of resource name +- `source_name_p` - source (usually a file) name of the source code +- `source_name_size` - size of source name - `source_p` - source code character data - `source_size` - size of source code - `user_p` - custom pointer passed to [jerry_debugger_wait_for_client_source](#jerry_debugger_wait_for_client_source) @@ -140,6 +140,8 @@ jerry_debugger_is_connected (void); [doctest]: # (test="link") ```c +#include <stdio.h> + #include "jerryscript.h" #include "jerryscript-ext/debugger.h" @@ -316,8 +318,8 @@ jerry_debugger_wait_for_client_source (jerry_debugger_wait_for_source_callback_t * Runs the source code received by jerry_debugger_wait_for_client_source. */ static jerry_value_t -wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource name */ - size_t resource_name_size, /**< size of resource name */ +wait_for_source_callback (const jerry_char_t *source_name_p, /**< source name */ + size_t source_name_size, /**< size of source name */ const jerry_char_t *source_p, /**< source code */ size_t source_size, /**< source code size */ void *user_p /**< user pointer */) @@ -325,19 +327,21 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam (void) user_p; jerry_parse_options_t parse_options; - parse_options.options = JERRY_PARSE_HAS_RESOURCE; - parse_options.resource_name = jerry_create_string ((const jerry_char_t *) resource_name_p); + parse_options.options = JERRY_PARSE_HAS_SOURCE_NAME; + parse_options.source_name = jerry_string ((const jerry_char_t *) source_name_p, + (jerry_size_t) source_name_size, + JERRY_ENCODING_UTF8); jerry_value_t ret_val = jerry_parse (source_p, source_size, &parse_options); - jerry_release_value (parse_options.resource_name); + jerry_value_free (parse_options.source_name); - if (!jerry_value_is_error (ret_val)) + if (!jerry_value_is_exception (ret_val)) { jerry_value_t func_val = ret_val; ret_val = jerry_run (func_val); - jerry_release_value (func_val); + jerry_value_free (func_val); } return ret_val; @@ -365,7 +369,7 @@ main (void) NULL, &run_result); - jerry_release_value (run_result); + jerry_value_free (run_result); } while (receive_status == JERRY_DEBUGGER_SOURCE_RECEIVED); @@ -417,40 +421,3 @@ main (void) jerry_cleanup (); } ``` - -### jerry_debugger_send_log - -**Summary** - -Sends the program's log to the debugger client. - -**Prototype** - -```c -void -jerry_debugger_send_log (jerry_log_level_t level, const jerry_char_t *buffer, jerry_size_t string_size) -``` - -**Example** - -[doctest]: # (test="link") - -```c -#include "jerryscript.h" -#include "jerryscript-ext/debugger.h" - -int -main (void) -{ - jerry_init (JERRY_INIT_EMPTY); - jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001) - && jerryx_debugger_ws_create ()); - - jerry_char_t my_log[] = "Custom diagnostics"; - jerry_size_t my_log_size = sizeof (my_log); - - jerry_debugger_send_log (JERRY_LOG_LEVEL_DEBUG, my_log, my_log_size); - - jerry_cleanup (); -} -``` diff --git a/08.CODING-STANDARDS.md b/08.CODING-STANDARDS.md index 444220f3..7b2dc01c 100644 --- a/08.CODING-STANDARDS.md +++ b/08.CODING-STANDARDS.md @@ -22,7 +22,7 @@ review. * Tab characters are not allowed. * Maximum line length is 120 characters (excluding newline). * No trailing white space is allowed. -* Run `tools/run-tests.py --check-vera` to check several +* Run `tools/run-tests.py --check-format` to check several of the coding conventions automatically. ## Comments diff --git a/09.EXT-REFERENCE-ARG.md b/09.EXT-REFERENCE-ARG.md index 1c030c63..942197b7 100644 --- a/09.EXT-REFERENCE-ARG.md +++ b/09.EXT-REFERENCE-ARG.md @@ -254,7 +254,7 @@ my_external_handler (const jerry_value_t function_obj, mapping, 4); - if (jerry_value_is_error (rv)) + if (jerry_value_is_exception (rv)) { /* Handle error. */ return rv; @@ -265,7 +265,7 @@ my_external_handler (const jerry_value_t function_obj, * required_bool, required_str and optional_num can now be used. */ - return jerry_create_undefined (); /* Or return something more meaningful. */ + return jerry_undefined (); /* Or return something more meaningful. */ } ``` @@ -650,7 +650,7 @@ my_external_handler (const jerry_value_t function_obj, mapping, 1); - if (jerry_value_is_error (rv)) + if (jerry_value_is_exception (rv)) { /* Handle error. */ return rv; @@ -661,7 +661,7 @@ my_external_handler (const jerry_value_t function_obj, * required_bool, required_num and optional_num can now be used. */ - return jerry_create_undefined (); /* Or return something more meaningful. */ + return jerry_undefined (); /* Or return something more meaningful. */ } ``` @@ -741,7 +741,7 @@ my_external_handler (const jerry_value_t function_obj, mapping, 1); - if (jerry_value_is_error (rv)) + if (jerry_value_is_exception (rv)) { /* Handle error. */ return rv; @@ -752,7 +752,7 @@ my_external_handler (const jerry_value_t function_obj, * required_bool, required_num and optional_num can now be used. */ - return jerry_create_undefined (); /* Or return something more meaningful. */ + return jerry_undefined (); /* Or return something more meaningful. */ } ``` diff --git a/10.EXT-REFERENCE-HANDLER.md b/10.EXT-REFERENCE-HANDLER.md index e9128e2b..c5d10191 100644 --- a/10.EXT-REFERENCE-HANDLER.md +++ b/10.EXT-REFERENCE-HANDLER.md @@ -10,174 +10,9 @@ permalink: /ext-reference-handler/ # Common methods to handle properties -The `jerryscript-ext/handler.h` header defines a set of convenience methods +The `jerryscript-ext/properties.h` header defines a set of convenience methods which makes the property access a bit straightforward. -## jerryx_set_property_str - -**Summary** - -Set a property on a target object with a given name. - -*Note*: -- The property name must be a zero terminated UTF-8 string. -- There should be no '\0' (NULL) character in the name excluding the string terminator. -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it - is no longer needed. - - -**Prototype** - -```c -jerry_value_t -jerryx_set_property_str (const jerry_value_t target_object, - const char *name, - const jerry_value_t value); -``` - -- `target_object` - the object where the property should be set -- `name` - name of the property -- `value` - property value to be set -- return value - - JS true value, if success - - thrown error, if there was a problem setting the property - -**Example** - -[doctest]: # () - -```c -#include "jerryscript.h" -#include "jerryscript-ext/handler.h" - -int -main (int argc, char **argv) -{ - jerry_init (JERRY_INIT_EMPTY); - - jerry_value_t global = jerry_get_global_object (); - - jerry_value_t value = jerry_create_number (3.3); - jerry_value_t result = jerryx_set_property_str (global, "value", value); - if (jerry_value_is_error (result)) - { - /* The error type/reason can be extracted via the `jerry_get_value_from_error` method */ - printf ("Error during property configuration\r\n"); - } - - jerry_release_value (result); - jerry_release_value (value); - jerry_release_value (global); - jerry_cleanup(); - - return 0; -} -``` - -## jerryx_get_property_str - -**Summary** - -Get the value of a property from the specified object with the given name. - -*Notes*: -- The property name must be a zero terminated UTF-8 string. -- There should be no '\0' (NULL) character in the name excluding the string terminator. -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it - is no longer needed. - - -**Prototype** - -``` -jerry_value_t -jerryx_get_property_str (const jerry_value_t target_object, - const char *name); -``` - -- `target_object` - object on which the property name is accessed -- `name` - property name as an UTF-8 `char*` -- return value - - value of property, if success - - thrown error, if there was a problem accessing the property - -**Example** - -[doctest]: # () - -```c -#include "jerryscript.h" -#include "jerryscript-ext/handler.h" - -int -main (int argc, char **argv) -{ - jerry_init (JERRY_INIT_EMPTY); - - jerry_value_t global = jerry_get_global_object (); - - jerry_value_t math_object = jerryx_get_property_str (global, "Math"); - - /* use math_object */ - - jerry_release_value (math_object); - jerry_release_value (global); - jerry_cleanup(); - - return 0; -} -``` - -## jerryx_has_property_str - -**Summary** - -Check if a property exists on an object. - -*Notes*: -- The operation performed is the same as what the `jerry_has_property` method. -- The property name must be a zero terminated UTF-8 string. -- There should be no '\0' (NULL) character in the name excluding the string terminator. - - -**Prototype** - -``` -bool -jerryx_has_property_str (const jerry_value_t target_object, - const char *name); -``` - -- `target_object` - object on which the property name is accessed -- `name` - property name as an UTF-8 `char*` -- return value - - true, if the given property name exists on the object - - false, if there is no such property name or there was an error accessing the property - -**Example** - -[doctest]: # () - -```c -#include "jerryscript.h" -#include "jerryscript-ext/handler.h" - -int -main (int argc, char **argv) -{ - jerry_init (JERRY_INIT_EMPTY); - - jerry_value_t global = jerry_get_global_object (); - - bool have_math = jerryx_has_property_str (global, "Math"); - - jerry_release_value (global); - jerry_cleanup(); - - return have_math ? 0 : 1; -} -``` - # Utility to register multiple properties in bulk In some cases it is useful to register multiple properties for a given object @@ -273,8 +108,10 @@ jerryx_set_properties (const jerry_value_t target_object, [doctest]: # () ```c +#include <stdio.h> #include "jerryscript.h" -#include "jerryscript-ext/handler.h" +#include "jerryscript-ext/handlers.h" +#include "jerryscript-ext/properties.h" static jerry_value_t handler (const jerry_call_info_t *call_info_p, @@ -283,7 +120,7 @@ handler (const jerry_call_info_t *call_info_p, { printf ("native handler called!\n"); - return jerry_create_boolean (true); + return jerry_boolean (true); } int @@ -293,24 +130,24 @@ main (int argc, char **argv) jerryx_property_entry methods[] = { - { "demo", jerry_create_external_function (handler) }, + { "demo", jerry_function_external (handler) }, { NULL, 0 }, }; - jerry_value_t global = jerry_get_global_object (); + jerry_value_t global = jerry_current_realm (); jerryx_register_result reg = jerryx_set_properties (global, methods); /* if `reg.result` is undefined all methods are registered */ - if (jerry_value_is_error (reg.result)) + if (jerry_value_is_exception (reg.result)) { printf ("Only registered %d properties\r\n", reg.registered); /* clean up not registered property values */ jerryx_release_property_entry (methods, reg); /* clean up the error */ - jerry_release_value (reg.result); + jerry_value_free (reg.result); } - jerry_release_value (global); + jerry_value_free (global); jerry_cleanup(); @@ -324,8 +161,8 @@ To make property registration convenient, there are a set of macros to use when setting a property entry: * `JERRYX_PROPERTY_NUMBER(NAME, NUMBER)` - creates a number entry. -* `JERRYX_PROPERTY_STRING(NAME, STR)` - creates an UTF-8 string entry. This string must be zero terminated. -* `JERRYX_PROPERTY_STRING_SZ(NAME, STR, SIZE)` - creates an UTF-8 string entry using only `SIZE` bytes from the string. +* `JERRYX_PROPERTY_STRING(NAME, STR, SIZE)` - creates an UTF-8 string entry using `SIZE` bytes from the string. +* `JERRYX_PROPERTY_STRING_SZ(NAME, STR)` - creates an ASCII string entry. This string must be zero terminated. * `JERRYX_PROPERTY_BOOLEAN(NAME, VALUE)` - creates a boolean entry. * `JERRYX_PROPERTY_FUNCTION(NAME, NATIVE)` - creates a native C function entry. * `JERRYX_PROPERTY_UNDEFINED(NAME)` - creates an undefined property entry. @@ -336,8 +173,10 @@ when setting a property entry: [doctest]: # () ```c +#include <stdio.h> #include "jerryscript.h" -#include "jerryscript-ext/handler.h" +#include "jerryscript-ext/handlers.h" +#include "jerryscript-ext/properties.h" static jerry_value_t handler (const jerry_call_info_t *call_info_p, @@ -346,7 +185,7 @@ handler (const jerry_call_info_t *call_info_p, { printf ("native handler called!\n"); - return jerry_create_boolean (true); + return jerry_boolean (true); } int @@ -367,20 +206,20 @@ main (int argc, char **argv) JERRYX_PROPERTY_LIST_END(), }; - jerry_value_t global = jerry_get_global_object (); + jerry_value_t global = jerry_current_realm (); jerryx_register_result reg = jerryx_set_properties (global, methods); /* if `reg.result` is undefined all methods are registered */ - if (jerry_value_is_error (reg.result)) + if (jerry_value_is_exception (reg.result)) { printf ("Only registered %d properties\r\n", reg.registered); /* clean up not registered property values */ jerryx_release_property_entry (methods, reg); /* clean up the error */ - jerry_release_value (reg.result); + jerry_value_free (reg.result); } - jerry_release_value (global); + jerry_value_free (global); jerry_cleanup(); @@ -450,7 +289,7 @@ jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, const jerry_value **See also** -- [jerryx_handler_register_global](#jerryx_handler_register_global) +- [jerryx_register_global](#jerryx_register_global) ## jerryx_handler_assert_throw @@ -476,7 +315,7 @@ jerryx_handler_assert_throw (const jerry_value_t func_obj_val, const jerry_value **See also** -- [jerryx_handler_register_global](#jerryx_handler_register_global) +- [jerryx_register_global](#jerryx_register_global) ## jerryx_handler_assert @@ -514,7 +353,7 @@ jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p, **See also** -- [jerryx_handler_register_global](#jerryx_handler_register_global) +- [jerryx_register_global](#jerryx_register_global) ## jerryx_handler_print @@ -523,14 +362,14 @@ jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p, 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_char`. The NULL character is output as "\u0000", +`jerry_port_print_byte`. 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_char`. +`jerry_port_print_byte`. **Prototype** @@ -549,26 +388,26 @@ jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this **See also** -- [jerryx_handler_register_global](#jerryx_handler_register_global) -- [jerry_port_print_char](05.PORT-API.md#jerry_port_print_char) +- [jerryx_register_global](#jerryx_register_global) +- [jerry_port_print_byte](05.PORT-API.md#jerry_port_print_char) # Handler registration helper -## jerryx_handler_register_global +## jerryx_register_global **Summary** Register a JavaScript function in the global object. -*Note*: Returned value must be freed with `jerry_release_value`, when it is no +*Note*: Returned value must be freed with `jerry_value_free`, when it is no longer needed. **Prototype** ```c jerry_value_t -jerryx_handler_register_global (const jerry_char_t *name_p, +jerryx_register_global (const char *name_p, jerry_external_handler_t handler_p); ``` @@ -583,7 +422,8 @@ jerryx_handler_register_global (const jerry_char_t *name_p, ```c #include "jerryscript.h" -#include "jerryscript-ext/handler.h" +#include "jerryscript-ext/handlers.h" +#include "jerryscript-ext/properties.h" static const struct { const char *name_p; @@ -599,14 +439,14 @@ static const struct { static void register_common_functions (void) { - jerry_value_t ret = jerry_create_undefined (); + jerry_value_t ret = jerry_undefined (); - for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_is_error (ret); i++) + for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_is_exception (ret); i++) { - ret = jerryx_handler_register_global ((const jerry_char_t *) common_functions[i].name_p, - common_functions[i].handler_p); + ret = jerryx_register_global (common_functions[i].name_p, + common_functions[i].handler_p); } - jerry_release_value (ret); + jerry_value_free (ret); } ``` diff --git a/11.EXT-REFERENCE-AUTORELEASE.md b/11.EXT-REFERENCE-AUTORELEASE.md index b0392e0e..c2cffa72 100644 --- a/11.EXT-REFERENCE-AUTORELEASE.md +++ b/11.EXT-REFERENCE-AUTORELEASE.md @@ -14,7 +14,7 @@ permalink: /ext-reference-autorelease/ **Summary** -Macro for `const jerry_value_t` for which jerry_release_value() is +Macro for `const jerry_value_t` for which jerry_value_free() is automatically called when the variable goes out of scope. *Note*: The macro depends on compiler support. For GCC and LLVM/clang, the macro is implemented @@ -31,23 +31,23 @@ using the `__cleanup__` variable attribute. For other compilers, no support has static void foo (bool enable) { - JERRYX_AR_VALUE_T bar = jerry_create_string ((const jerry_char_t *) "..."); + JERRYX_AR_VALUE_T bar = jerry_string_sz ("..."); if (enable) { - JERRYX_AR_VALUE_T baz = jerry_get_global_object (); + JERRYX_AR_VALUE_T baz = jerry_current_realm (); /* bar and baz can now be used. */ /* - * jerry_release_value (baz) and jerry_release_value (bar) is called automatically before + * jerry_value_free (baz) and jerry_value_free (bar) is called automatically before * returning, because `baz` and `bar` go out of scope. */ return; } /* - * jerry_release_value (bar) is called automatically when the function returns, + * jerry_value_free (bar) is called automatically when the function returns, * because `bar` goes out of scope. */ } @@ -56,5 +56,5 @@ foo (bool enable) **See also** - [jerry_value_t](../api-reference#jerry_value_t) -- [jerry_acquire_value](../api-reference#jerry_acquire_value) -- [jerry_release_value](../api-reference#jerry_release_value) +- [jerry_value_copy](../api-reference#jerry_value_copy) +- [jerry_value_free](../api-reference#jerry_value_free) diff --git a/12.EXT-REFERENCE-MODULE.md b/12.EXT-REFERENCE-MODULE.md index 981a0017..6d54c59d 100644 --- a/12.EXT-REFERENCE-MODULE.md +++ b/12.EXT-REFERENCE-MODULE.md @@ -47,8 +47,8 @@ resolved using the native JerryScript module resolver `jerryx_module_native_reso `jerryx_module_resolve()`. Native modules are registered during application startup and by calling `dlopen()` by means of library constructors, support for which can be turned on using the `FEATURE_INIT_FINI` build flag. In the absence of such a flag, the module registration and unregistration functions are exposed as global symbols which can be called -explicitly. Note: `FEATURE_INIT_FINI` build flag isn't supported on Windows, because Microsoft Visual C/C++ Compiler -doesn't support library constructors and destructors. +explicitly. Note: On windows, `FEATURE_INIT_FINI` build flag only supported with GNU toolchain or Microsoft Visual C/C++ Compiler +2008 and upper. ## jerryx_module_resolve @@ -174,9 +174,9 @@ load_and_evaluate_js_file (const jerry_value_t name, jerry_value_t *result) char *js_file_contents = NULL; int file_size = 0; - jerry_size_t name_size = jerry_get_utf8_string_size (name); + jerry_size_t name_size = jerry_string_size (name, JERRY_ENCODING_UTF8); jerry_char_t name_string[name_size + 1]; - jerry_string_to_utf8_char_buffer (name, name_string, name_size); + jerry_string_to_buffer (name, JERRY_ENCODING_UTF8, name_string, name_size); name_string[name_size] = 0; FILE *js_file = fopen (name_string, "r"); @@ -215,7 +215,7 @@ canonicalize_file_path (const jerry_value_t name) /** * Since a file on the file system can be referred to by multiple relative paths, but only by one absolute path, the * absolute path becomes the canonical name for the module. Thus, to establish this canonical name, we must search - * name for "./" and "../", follow symlinks, etc., then create absolute_path via jerry_create_string () and return + * name for "./" and "../", follow symlinks, etc., then create absolute_path via jerry_string () and return * it, because it is the canonical name for this module. Thus, we avoid loading the same JavaScript file twice. */ @@ -281,7 +281,7 @@ loaded. static jerry_value_t my_module_on_resolve (void) { - return jerry_create_external_function (very_useful_function); + return jerry_function_external (very_useful_function); } /* my_module_on_resolve */ /* Note that there is no semicolon at the end of the next line. This is how it must be. */ diff --git a/14.EXT-REFERENCE-HANDLE-SCOPE.md b/14.EXT-REFERENCE-HANDLE-SCOPE.md index 6ebfc8be..6ffb6002 100644 --- a/14.EXT-REFERENCE-HANDLE-SCOPE.md +++ b/14.EXT-REFERENCE-HANDLE-SCOPE.md @@ -30,7 +30,7 @@ JerryScript only supports a single nested hierarchy of scopes. There is only one static jerry_value_t create_object (void) { - jerry_value_t obj = jerry_create_object (); + jerry_value_t obj = jerry_object (); return obj; } /* create_object */ @@ -51,7 +51,7 @@ main (void) jerry_init (JERRY_INIT_EMPTY); test_handle_scope_val (); - jerry_gc (JERRY_GC_PRESSURE_LOW); + jerry_heap_gc (JERRY_GC_PRESSURE_LOW); jerry_cleanup (); } /* main */ @@ -76,7 +76,7 @@ create_object (void) { jerryx_escapable_handle_scope scope; jerryx_open_escapable_handle_scope (&scope); - jerry_value_t obj = jerryx_create_handle (jerry_create_object ()); + jerry_value_t obj = jerryx_create_handle (jerry_object ()); jerry_value_t escaped_obj; jerryx_escape_handle(scope, obj, &escaped_obj); @@ -103,7 +103,7 @@ main (void) jerry_init (JERRY_INIT_EMPTY); test_handle_scope_val (); - jerry_gc (JERRY_GC_PRESSURE_LOW); + jerry_heap_gc (JERRY_GC_PRESSURE_LOW); jerry_cleanup (); } /* main */ @@ -112,8 +112,8 @@ main (void) **See also** - [jerry_value_t](../api-reference#jerry_value_t) -- [jerry_acquire_value](../api-reference#jerry_acquire_value) -- [jerry_release_value](../api-reference#jerry_release_value) +- [jerry_value_copy](../api-reference#jerry_value_copy) +- [jerry_value_free](../api-reference#jerry_value_free) ## Pre-allocated list of handle scopes and handles diff --git a/_includes/header.html b/_includes/header.html index 9ab699c0..a2153f4a 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -44,4 +44,4 @@ </div><!--/.nav-collapse --> </div> </nav> -<a href="https://github.com/jerryscript-project/jerryscript"><img style="position: absolute; top: 50; right: 0; border: 0;" src="https://camo.githubusercontent.com/652c5b9acfaddf3a9c326fa6bde407b87f7be0f4/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f6f72616e67655f6666373630302e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png"></a> +<a href="https://github.com/jerryscript-project/jerryscript"><img style="position: absolute; top: 50; right: 0; border: 0;" src="https://github.blog/wp-content/uploads/2008/12/forkme_right_orange_ff7600.png" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png"></a> |