diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index 3610957414..30826e10ee 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -9,6 +9,20 @@ Enum that contains the following elements: - JERRY_INIT_SHOW_REGEXP_OPCODES - dump regexp byte-code to log after compilation - JERRY_INIT_MEM_STATS - dump memory statistics + *Removed in version 3.0*: `JERRY_INIT_MEM_STATS_SEPARATE` and `JERRY_INIT_DEBUGGER` were depreated since v2.0 and they were removed completely in v3.0. + +## jerry_log_level_t + +Enum that contains represents the configurable logging levels. +The levels are in severity order where the most serious levels come first. + + - JERRY_LOG_LEVEL_ERROR - the engine will terminate after the message is printed + - JERRY_LOG_LEVEL_WARNING - a request is aborted, but the engine continues its operation + - JERRY_LOG_LEVEL_DEBUG - debug messages from the engine, low volume + - JERRY_LOG_LEVEL_TRACE - detailed info about engine internals, potentially high volume + +*New in version 3.0*. + ## jerry_type_t Enum that contains JerryScript API value types: @@ -63,7 +77,7 @@ Enum that contains JerryScript **object** value types: *New in version 2.4*. -*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_OBJECT_TYPE_MODULE_NAMESPACE`, `JERRY_OBJECT_TYPE_PROMISE`, `JERRY_OBJECT_TYPE_DATAVIEW`, +*Changed in version 3.0*: Added `JERRY_OBJECT_TYPE_MODULE_NAMESPACE`, `JERRY_OBJECT_TYPE_PROMISE`, `JERRY_OBJECT_TYPE_DATAVIEW`, `JERRY_OBJECT_TYPE_ERROR`, `JERRY_OBJECT_TYPE_SHARED_ARRAYBUFFER`, `JERRY_OBJECT_TYPE_WEAKREF`, `JERRY_OBJECT_TYPE_SCRIPT`, and `JERRY_OBJECT_TYPE_MODULE` values. @@ -102,7 +116,7 @@ produce correct results. [[PreventExtensions]], [[GetOwnProperty]], [[DefineOwnProperty]], [[HasProperty]], [[Get]], [[Set]], [[Delete]] and [[OwnPropertyKeys]] -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. ## jerry_property_filter_t @@ -120,7 +134,7 @@ Enum that contains JerryScript **property filter** options bits: *New in version 2.4*. -*Changed in version [[NEXT_RELEASE]]*: The following values are modified due to a typo in their names (exlcude/exclude): +*Changed in version 3.0*: The following values are modified due to a typo in their names (exlcude/exclude): `JERRY_PROPERTY_FILTER_EXLCUDE_NON_CONFIGURABLE`, `JERRY_PROPERTY_FILTER_EXLCUDE_NON_ENUMERABLE`, `JERRY_PROPERTY_FILTER_EXLCUDE_NON_WRITABLE`, `JERRY_PROPERTY_FILTER_EXLCUDE_STRINGS`, `JERRY_PROPERTY_FILTER_EXLCUDE_SYMBOLS`, `JERRY_PROPERTY_FILTER_EXLCUDE_INTEGER_INDICES`. @@ -129,13 +143,14 @@ Enum that contains JerryScript **property filter** options bits: Possible types of an Error object: - - JERRY_ERROR_COMMON - common error - - JERRY_ERROR_EVAL - eval error - - JERRY_ERROR_RANGE - range error - - JERRY_ERROR_REFERENCE - reference error - - JERRY_ERROR_SYNTAX - syntax error - - JERRY_ERROR_TYPE - type error - - JERRY_ERROR_URI - URI error + - JERRY_ERROR_COMMON - Error + - JERRY_ERROR_EVAL - EvalError + - JERRY_ERROR_RANGE - RangeError + - JERRY_ERROR_REFERENCE - ReferenceError + - JERRY_ERROR_SYNTAX - SyntaxError + - JERRY_ERROR_TYPE - TypeError + - JERRY_ERROR_URI - URIError + - JERRY_ERROR_AGGREGATE - AggregateError There is also a special value `JERRY_ERROR_NONE` which is not an error type this value can only be returned by the [jerry_error_type](#jerry_error_type). @@ -158,7 +173,6 @@ Possible compile time enabled feature types: - JERRY_FEATURE_VM_EXEC_STOP - stopping ECMAScript execution - JERRY_FEATURE_VM_THROW - capturing ECMAScript throws - JERRY_FEATURE_JSON - JSON support - - JERRY_FEATURE_PROMISE - promise support - JERRY_FEATURE_TYPEDARRAY - Typedarray support - JERRY_FEATURE_DATE - Date support - JERRY_FEATURE_REGEXP - RegExp support @@ -185,9 +199,10 @@ Possible compile time enabled feature types: *Changed in version 2.4*: Added `JERRY_FEATURE_BIGINT`, `JERRY_FEATURE_REALM` values. -*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_FEATURE_VM_THROW`, `JERRY_FEATURE_GLOBAL_THIS`, - `JERRY_FEATURE_PROMISE_CALLBACK`, and `JERRY_FEATURE_MODULE`, - `JERRY_FEATURE_WEAKREF`, and `JERRY_FEATURE_FUNCTION_TO_STRING` values. +*Changed in version 3.0*: Added `JERRY_FEATURE_VM_THROW`, `JERRY_FEATURE_GLOBAL_THIS`, + `JERRY_FEATURE_PROMISE_CALLBACK`, and `JERRY_FEATURE_MODULE`, + `JERRY_FEATURE_WEAKREF`, and `JERRY_FEATURE_FUNCTION_TO_STRING` values. + Removed `JERRY_FEATURE_PROMISE.` ## jerry_container_type_t @@ -255,7 +270,7 @@ Option bits for [jerry_parse_options_t](#jerry_parse_options_t). - JERRY_PARSE_HAS_START - `start_line` and `start_column` fields are valid - JERRY_PARSE_HAS_USER_VALUE - `user_value` field is valid -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. Using both `JERRY_PARSE_MODULE` and `JERRY_PARSE_HAS_ARGUMENT_LIST` is an invalid combination and will result in an exception during parsing. @@ -264,6 +279,7 @@ an exception during parsing. - [jerry_parse_options_t](#jerry_parse_options_t) + ## jerry_gc_mode_t Set garbage collection operational mode @@ -278,6 +294,7 @@ memory blocks but the performance may drop after the garbage collection. *New in version 2.0*. + ## jerry_frame_type_t List of backtrace frame types returned by @@ -285,7 +302,8 @@ List of backtrace frame types returned by - JERRY_BACKTRACE_FRAME_JS - indicates that the frame is created for a JavaScript function/method -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. + ## jerry_generate_snapshot_opts_t @@ -315,7 +333,8 @@ when the snapshot is generated and executed. Furthermore the *New in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: The `JERRY_SNAPSHOT_SAVE_STRICT` value is removed, `JERRY_PARSE_STRICT_MODE` should be used instead. +*Changed in version 3.0*: The `JERRY_SNAPSHOT_SAVE_STRICT` value is removed, `JERRY_PARSE_STRICT_MODE` should be used instead. + ## jerry_exec_snapshot_opts_t @@ -329,7 +348,7 @@ Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) functions: - JERRY_SNAPSHOT_EXEC_HAS_USER_VALUE - `user_value` field is valid in [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t) -*Changed in version [[NEXT_RELEASE]]*: The `JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION` value is added, +*Changed in version 3.0*: The `JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION` value is added, which replaces the `jerry_load_function_snapshot` function. **Copy snapshot data into memory** @@ -346,6 +365,7 @@ The `JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed for static snapshots. *New in version 2.0*. + ## jerry_char_t **Summary** @@ -382,6 +402,15 @@ Jerry's length typedef uint32_t jerry_length_t; ``` +## jerry_encoding_t + +Supported string encodings. + + - JERRY_ENCODING_CESU8 - cesu-8 encoding + - JERRY_ENCODING_UTF8 - utf-8 encoding + +*New in version 3.0*. + ## jerry_value_t **Summary** @@ -399,6 +428,7 @@ Returned and created values by the API functions must be freed with typedef uint32_t jerry_value_t; ``` + ## jerry_context_data_manager_t **Summary** @@ -458,6 +488,7 @@ typedef struct *New in version 2.0*. + ## jerry_context_alloc_t **Summary** @@ -473,7 +504,9 @@ typedef void *(*jerry_context_alloc_t) (size_t size, void *cb_data_p); - `size` - allocation size - `cb_data_p` - pointer to user data -*New in version 2.0*. +**New in version 2.0*.* +*External context allocation has been moved to the port API in version 3.0.* + ## jerry_context_t @@ -500,7 +533,7 @@ Enum that contains the supported container operation types - JERRY_CONTAINER_OP_SIZE - Set/WeakSet/Map/WeakMap size operation - JERRY_CONTAINER_OP_CLEAR - Set/Map clear operation -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. ## jerry_binary_op_t @@ -540,7 +573,7 @@ Enum that contains the flags of property descriptors. - JERRY_PROP_IS_SET_DEFINED - Is [[Set]] defined? - JERRY_PROP_SHOULD_THROW - Should throw in case of an exception, instead of returning with false -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -570,7 +603,7 @@ typedef struct } jerry_parse_options_t; ``` -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -604,10 +637,10 @@ typedef struct } jerry_property_descriptor_t; ``` -*Changed in version [[NEXT_RELEASE]]*: The `is_value_defined`, `is_get_defined`, `is_set_defined`, - `is_writable_defined`, `is_writable`, `is_enumerable_defined`, - `is_enumerable`, `is_configurable_defined`, and `is_configurable` - fields are replaced by the `flags` field. +*Changed in version 3.0*: The `is_value_defined`, `is_get_defined`, `is_set_defined`, + `is_writable_defined`, `is_writable`, `is_enumerable_defined`, + `is_enumerable`, `is_configurable_defined`, and `is_configurable` + fields are replaced by the `flags` field. **See also** @@ -632,7 +665,7 @@ typedef struct } jerry_frame_location_t; ``` -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0. from `jerry_backtrace_location_t` to `jerry_frame_location_t`*. ## jerry_frame_t @@ -656,7 +689,7 @@ struct jerry_frame_internal_t; typedef struct jerry_frame_internal_t jerry_frame_t; ``` -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. ## jerry_heap_stats_t @@ -701,7 +734,7 @@ typedef struct jerry_call_info_t } jerry_call_info_t; ``` -*New in version [[NEXT_RELEASE]]*. Contents of this struct replaces the `jerry_get_new_target` function. +*New in version 3.0*. Contents of this struct replaces the `jerry_get_new_target` function. **See also** @@ -747,7 +780,7 @@ Native free callback of generic value types. typedef void (*jerry_value_free_callback_t) (void *native_p); ``` -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -778,7 +811,7 @@ typedef void (*jerry_object_native_free_cb_t) (void *native_p, struct jerry_obje *Changed in version 2.2*: API calls are once again allowed. (See note) -*Changed in version [[NEXT_RELEASE]]*: `info_p` argument is added +*Changed in version 3.0*: `info_p` argument is added **See also** @@ -804,7 +837,7 @@ typedef void (*jerry_external_string_free_cb_t) (jerry_char_t *string_p, - `string_size` - size of external string - `user_p` - pointer passed when the external string is created -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -851,7 +884,7 @@ An enum representing the current status of a module - JERRY_MODULE_STATE_EVALUATED - Module has been evaluated (its source code has been executed) - JERRY_MODULE_STATE_ERROR - An exception has been encountered before the evaluated state is reached -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. ## jerry_module_resolve_cb_t @@ -878,7 +911,7 @@ typedef jerry_value_t (*jerry_module_resolve_cb_t) (const jerry_value_t specifie - a module object - if it can be resolved successfully - an exception - otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** - [jerry_module_link](#jerry_module_link) @@ -920,7 +953,7 @@ typedef jerry_value_t (*jerry_module_import_cb_t) (const jerry_value_t specifier - promise or resolved module - if the operation is successful - an exception - otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** - [jerry_module_on_import](#jerry_module_on_import) @@ -947,7 +980,7 @@ typedef void (*jerry_module_state_changed_cb_t) (jerry_module_state_t new_state, and exception value for error state. - `user_p` - pointer passed to [jerry_module_on_state_changed](#jerry_module_on_state_changed). -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** - [jerry_module_on_state_changed](#jerry_module_on_state_changed) @@ -972,7 +1005,7 @@ typedef void (*jerry_module_import_meta_cb_t) (const jerry_value_t module, - `meta_object` - import.meta object created for the module. - `user_p` - pointer passed to [jerry_module_on_import_meta](#jerry_module_on_import_meta). -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** - [jerry_module_on_import_meta](#jerry_module_on_import_meta) @@ -998,7 +1031,7 @@ typedef jerry_value_t (*jerry_native_module_evaluate_cb_t) (const jerry_value_t - any non-exception value - if the module is evaluated successfully - an exception - otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** - [jerry_module_evaluate](#jerry_module_evaluate) @@ -1022,7 +1055,7 @@ typedef bool (*jerry_backtrace_cb_t) (jerry_frame_t *frame_p, void *user_p); - true, to continue capturing more frames - false, to end the stack capturing -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -1073,7 +1106,7 @@ typedef struct *New in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: Added `number_of_references`, and `offset_of_references` fields. +*Changed in version 3.0*: Added `number_of_references`, and `offset_of_references` fields. **See also** @@ -1205,15 +1238,38 @@ Note: **Prototype** ```c -typedef void (*jerry_throw_cb_t) (const jerry_value_t error_value, void *user_p); +typedef void (*jerry_throw_cb_t) (const jerry_value_t exception_value, void *user_data_p); ``` + - `exception_value` - the thrown exception + - `user_data_p` - optional user data pointer -*New in [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** - [jerry_on_throw](#jerry_on_throw) + +## jerry_string_iterate_cb_t + +**Summary** + +**Prototype** + +```c +typedef void (*jerry_string_iterate_cb_t) (uint32_t value, void *user_data_p); +``` + +- `value` - encoded byte value +- `user_data_p` - optional user data pointer supplied via the (jerry_string_iterate)[#jerry_string_iterate] method. + +*New in version 3.0*. + +**See also** + +- [jerry_string_iterate](#jerry_string_iterate) + + ## jerry_promise_state_t Enum which describes the state of a Promise. @@ -1282,7 +1338,7 @@ Possible values: - object - internal object representing the execution status - value - value for rejecting -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -1321,7 +1377,7 @@ Possible values: - JERRY_PROMISE_EVENT_ASYNC_AFTER_RESOLVE - JERRY_PROMISE_EVENT_ASYNC_AFTER_REJECT -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -1350,7 +1406,7 @@ typedef void (*jerry_promise_event_cb_t) (jerry_promise_event_type_t event_type, - `value` - optional value argument. - `user_data_p` - optional user data pointer supplied via the (jerry_promise_on_event)[#jerry_promise_on_event] method. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -1407,7 +1463,7 @@ typedef struct } jerry_exec_snapshot_option_values_t; ``` -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -1422,7 +1478,7 @@ Possible values: - JERRY_SOURCE_INFO_HAS_FUNCTION_ARGUMENTS - function_arguments field is valid - JERRY_SOURCE_INFO_HAS_SOURCE_RANGE - both source_range_start and source_range_length fields are valid -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -1448,7 +1504,7 @@ typedef struct } jerry_source_info_t; ``` -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -1464,7 +1520,7 @@ Enum that contains the JerryScript type of an array buffer: - JERRY_ARRAYBUFFER_TYPE_ARRAYBUFFER - the object is an array buffer object - JERRY_ARRAYBUFFER_TYPE_SHARED_ARRAYBUFFER - the object is a shared array buffer object -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -1500,7 +1556,7 @@ typedef uint8_t *(*jerry_arraybuffer_allocate_cb_t) (jerry_arraybuffer_type_t bu - return value - Pointer to the buffer, if the allocation is successful, NULL otherwise. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -1534,7 +1590,7 @@ typedef void (*jerry_arraybuffer_free_cb_t) (jerry_arraybuffer_type_t buffer_typ - `arraybuffer_user_p` - [in/out] user pointer assigned to the array buffer or shared array buffer object. - `user_p` - user pointer passed to [jerry_arraybuffer_allocator](#jerry_arraybuffer_allocator) -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **See also** @@ -1867,7 +1923,7 @@ jerry_parse (const jerry_char_t *source_p, *Changed in version 2.0*: Added `source_name_p`, and `source_name_length` arguments. -*Changed in version [[NEXT_RELEASE]]*: The `source_name_p`, `source_name_length`, and `parse_opts` arguments are replaced by `options_p`. +*Changed in version 3.0*: The `source_name_p`, `source_name_length`, and `parse_opts` arguments are replaced by `options_p`. This function replaces the `jerry_parse_function` method. **Example 1** @@ -1976,7 +2032,7 @@ jerry_parse_value (const jerry_value_t source_value, - function object value, if script was parsed successfully, - thrown exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -2319,7 +2375,6 @@ Returns whether the given `jerry_value_t` is an ArrayBuffer object. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -2366,7 +2421,6 @@ Returns whether the given `jerry_value_t` is a SharedArrayBuffer object. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -2380,7 +2434,7 @@ jerry_value_is_shared_arraybuffer (const jerry_value_t value); - true, if the given `jerry_value_t` is a SharedArrayBuffer object. - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -2460,7 +2514,7 @@ jerry_value_is_true (const jerry_value_t value); - true, if the given `jerry_value_t` is true value - false, otherwise -*New in version [[NEXT_RELEASE]]*. Replaces the `jerry_get_boolean_value` method. +*New in version 3.0*. Replaces the `jerry_get_boolean_value` method. **Example** @@ -2500,7 +2554,7 @@ jerry_value_is_false (const jerry_value_t value); - true, if the given `jerry_value_t` is false value - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -2570,7 +2624,6 @@ Returns whether the given `jerry_value_t` is a DataView object value. - This API depends on a build option (`JERRY_BUILTIN_DATAVIEW`) and can be checked in runtime with the `JERRY_FEATURE_DATAVIEW` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -2638,7 +2691,7 @@ jerry_value_is_exception (const jerry_value_t value); - true, if the given `jerry_value_t` is an exception value. - false, otherwise -*New in version 2.0*. +*Renamed in version 3.0 from `jerry_value_is_error` to `jerry_value_is_exception`*. **Example** @@ -2909,7 +2962,6 @@ Returns whether the given `jerry_value_t` is a proxy value. - This API depends on a build option (`JERRY_BUILTIN_PROXY`) and can be checked in runtime with the `JERRY_FEATURE_PROXY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -3053,7 +3105,6 @@ Returns whether the given `jerry_value_t` is a bigint value. - This API depends on a build option (`JERRY_BUILTIN_BIGINT`) and can be checked in runtime with the `JERRY_FEATURE_BIGINT` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -3115,7 +3166,6 @@ Checks whether the given `jerry_value_t` is a TypedArray object or not. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -3174,7 +3224,6 @@ Checks whether the given `jerry_value_t` is the given `jerry_container_type_t` t runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` feature enum values. see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -3459,7 +3508,7 @@ jerry_feature_enabled (const jerry_feature_t feature); - true, if the given `jerry_feature_t` is enabled - false, otherwise -*New in version 2.0*. +*Renamed in version 3.0 from `jerry_is_feature_enabled` to `jerry_feature_enabled`*. **Example** @@ -3902,7 +3951,7 @@ jerry_on_throw (jerry_throw_cb_t throw_cb, - `throw_cb` - callback which is called on throws (passing NULL disables this feature) - `user_p` - user pointer passed to the `throw_cb` function -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -3947,6 +3996,7 @@ main (void) - [jerry_exception_is_captured](#jerry_exception_is_captured) - [jerry_exception_allow_capture](#jerry_exception_allow_capture) + ## jerry_exception_is_captured **Summary** @@ -3970,7 +4020,7 @@ bool jerry_exception_is_captured (jerry_value_t value); - true, if the vm throw callback captured the exception - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0 from `jerry_error_is_throw_captured` to `jerry_exception_is_captured`*. **Example** @@ -4036,7 +4086,7 @@ void jerry_exception_allow_capture (jerry_value_t value, bool should_capture); - `value` - api value (should be an exception) - `should_capture` - callback should capture this error -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -4232,6 +4282,96 @@ jerry_string_length (const jerry_value_t value); - [jerry_validate_string](#jerry_validate_string) +## jerry_string_substr + +**Summary** + +Create a substring of the input string value. +Return an empty string if input value is not a string. + +**Prototype** + +```c +jerry_size_t jerry_string_substr (const jerry_value_t value, jerry_length_t start, jerry_length_t end); +``` + +- `value` - the input string value +- `start` - start position of the substring +- `end` - end position of the substring +- return value - created string + +*New in version 3.0. There were `jerry_substring_to_char_buffer` and `jerry_substring_to_utf8_char_buffer` in previous versions with a similar functionality. + +**Example** + +```c +{ + jerry_value_t str = jerry_string_sz ("Demo string"); + + // Read the string into a byte buffer. + jerry_value_t sub_str = jerry_string_substr (str, 0, 3); + + // usage of 'sub_str' + + jerry_value_free (sub_str) + jerry_value_free (str); +} +``` + +**See also** + +- [jerry_string_sz](#jerry_string_sz) + + +## jerry_string_iterate + +**Summary** + +Iterate over the input string value in the specified encoding, visiting each unit of the encoded string once. If the input value is not a string, the function will do nothing. + + +**Prototype** + +```c +void jerry_string_iterate (const jerry_value_t value, + jerry_encoding_t encoding, + jerry_string_iterate_cb_t callback, + void *user_p); +``` + +- `value` - the input string value +- `encoding` - the requested [encoding](#jerry_encoding_t) for the string +- `callback` - callback function called for each byte of the encoded string, see [jerry_string_iterate_cb_t](#jerry_string_iterate_cb_t) +- `user_p` - user pointer passed to the callback function + +*New in version 3.0*. + +**Example** + +```c +static void my_str_iterator_cb_func (uint32_t value, void *user_p) +{ + // usage of the encoded byte value and the user pointer (if non-null) +} + +... + +void foo () { + jerry_value_t string = jerry_string_sz ("Demo string"); + + jerry_string_iterate (string, JERRY_ENCODING_UTF8, &jerryx_buffered_print, NULL); + + jerry_value_free (string); +} +``` + +**See also** + +- [jerry_string_sz](#jerry_string_sz) +- [jerry_encoding_t](#jerry_encoding_t) +- [jerry_string_iterate_cb_t](#jerry_string_iterate_cb_t) + + ## jerry_string_to_buffer **Summary** @@ -4301,12 +4441,12 @@ main (void) **See also** +- [jerry_encoding_t](#jerry_encoding_t) - [jerry_string_sz](#jerry_string_sz) - [jerry_string_size](#jerry_string_size) -- [jerry_strig_to_buffer](#jerry_strig_to_buffer) -# jerry_string_external_on_free +## jerry_string_external_on_free **Summary** @@ -4328,7 +4468,7 @@ void jerry_string_external_on_free (jerry_external_string_free_cb_t callback_p); - `callback_p` - callback which is called when an external string is freed. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -4371,7 +4511,7 @@ main (void) - [jerry_string_external](#jerry_string_external) -# jerry_string_user_ptr +## jerry_string_user_ptr **Summary** @@ -4397,7 +4537,7 @@ void *jerry_string_user_ptr (const jerry_value_t value, - user pointer - if `value` argument is an external string - NULL - otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -4843,7 +4983,7 @@ jerry_value_t jerry_module_link (const jerry_value_t module_val, - true - if linking is successful - exception - otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -4922,7 +5062,7 @@ jerry_value_t jerry_module_evaluate (const jerry_value_t module_val); - result of module bytecode execution - if evaluation was successful - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -4960,6 +5100,37 @@ main (void) - [jerry_module_link](#jerry_module_link) + +## jerry_module_cleanup + +**Summary** + +Release known modules in the current context. If realm parameter is supplied, cleans up modules native to that realm only. This function should be called by the user application when the module database in the current context is no longer needed. + +**Prototype** + +```c +void jerry_module_cleanup (const jerry_value_t realm); +``` + +- `realm` - release only those modules which realm value is equal to this argument. + +*New in version 3.0* + +**Example** + +```c +jerry_module_cleanup (jerry_current_realm ()); +``` + +**See also** + +- [jerry_current_realm](#jerry_current_realm) +- [jerry_module_state](#jerry_module_state) +- [jerry_module_evaluate](#jerry_module_evaluate) +- [jerry_module_link](#jerry_module_link) + + ## jerry_module_state **Summary** @@ -4983,7 +5154,7 @@ jerry_module_state_t jerry_module_state (const jerry_value_t module_val); - current status - if module_val is a module - JERRY_MODULE_STATE_INVALID - otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -5044,7 +5215,7 @@ void jerry_module_on_state_changed (jerry_module_state_changed_cb_t callback, - `callback` - callback, which is called after the state change. - `user_p` - pointer passed to the callback function. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -5122,7 +5293,7 @@ void jerry_module_on_import_meta (jerry_module_import_meta_cb_t callback, expression of a module is evaluated the first time - `user_p` - pointer passed to the callback function. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -5200,7 +5371,7 @@ size_t jerry_module_request_count (const jerry_value_t module_val); - number of import/export requests of a module, if `module_val` is module, - 0, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -5272,7 +5443,7 @@ jerry_value_t jerry_module_request (const jerry_value_t module_val, size_t reque - module object, if the request has been resolved successfully - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -5340,7 +5511,7 @@ jerry_value_t jerry_module_namespace (const jerry_value_t module_val); - object, if namespace object is available - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -5408,7 +5579,7 @@ jerry_module_on_import (jerry_module_import_cb_t callback_p, - `callback_p` - a [jerry_module_import_cb_t](#jerry_module_import_cb_t) callback which handles `import()` calls - `user_p` - user pointer passed to the callback -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -5540,7 +5711,7 @@ jerry_native_module (jerry_native_module_evaluate_cb_t callback, - a native module, if the module is successfully created - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -5603,7 +5774,7 @@ jerry_native_module_get (const jerry_value_t native_module_val, - value of the export, if success - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -5664,7 +5835,7 @@ jerry_value_t jerry_native_module_set (const jerry_value_t native_module_val, - true, if success - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -5854,7 +6025,7 @@ void jerry_promise_on_event (jerry_promise_event_filter_t filters, jerry_promise and setting NULL disables the tracking - `user_p` - pointer passed to the callback function, can be NULL -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -6018,10 +6189,6 @@ Resolve the promise with an argument. *Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. -- This API depends on a build option (`JERRY_ESNEXT`) and can be checked - in runtime with the `JERRY_FEATURE_PROMISE` feature enum value, - see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -6039,7 +6206,6 @@ jerry_promise_resolve (jerry_value_t promise, jerry_value_t argument); *New in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: Build option dependency changed from `JERRY_BUILTIN_PROMISE` to `JERRY_ESNEXT`. **Example** @@ -6441,7 +6607,6 @@ Gets the target object of a Proxy object. - This API depends on a build option (`JERRY_BUILTIN_PROXY`) and can be checked in runtime with the `JERRY_FEATURE_PROXY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -6494,7 +6659,6 @@ Gets the handler object of a Proxy object. - This API depends on a build option (`JERRY_BUILTIN_PROXY`) and can be checked in runtime with the `JERRY_FEATURE_PROXY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. **Prototype** @@ -6509,7 +6673,7 @@ jerry_proxy_handler (jerry_value_t proxy_value); - type error exception - if proxy_value is not a Proxy object - handler object - otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -6736,7 +6900,7 @@ jerry_arraybuffer_external (uint8_t *buffer_p, *New in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: `free_cb` has been replaced by `arraybuffer_user_p`. +*Changed in version 3.0*: `free_cb` has been replaced by `arraybuffer_user_p`. **Example** @@ -6782,7 +6946,7 @@ jerry_shared_arraybuffer (jerry_length_t size); - `size` - size of the backing store allocated for the shared array buffer **in bytes**. - return value - the new SharedArrayBuffer as a `jerry_value_t` -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -6837,7 +7001,7 @@ jerry_shared_arraybuffer_external (uint8_t *buffer_p, - return value - value of the newly constructed shared array buffer object. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -7432,7 +7596,7 @@ jerry_proxy_custom (const jerry_value_t target, - return thrown exception - if the Proxy construction fails value of the newly created proxy object - otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -7576,7 +7740,7 @@ jerry_string_external_sz (const char *str_p, void *user_p); *New in version 2.4*. -*Changed in version [[NEXT_RELEASE]]*: `free_cb` is replaced by `user_p`. +*Changed in version 3.0*: `free_cb` is replaced by `user_p`. **Example** @@ -7626,7 +7790,7 @@ jerry_string_external (const jerry_char_t *str_p, *New in version 2.4*. -*Changed in version [[NEXT_RELEASE]]*: `free_cb` is replaced by `user_p`. +*Changed in version 3.0*: `free_cb` is replaced by `user_p`. **Example** @@ -7865,7 +8029,7 @@ and element count can be specified. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -7921,7 +8085,7 @@ one of the allowed TypedArray functions. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -7982,7 +8146,7 @@ one of the allowed TypedArray functions. - This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -8039,7 +8203,7 @@ Create a jerry_value_t representing a given type container object. in runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` feature enum values. see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -8137,7 +8301,7 @@ Creates a `jerry_value_t` representing a new global object. - This API depends on a build option (`JERRY_BUILTIN_REALMS`) and can be checked in runtime with the `JERRY_FEATURE_REALM` feature enum value. see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -8241,6 +8405,59 @@ main (void) - [jerry_object_delete](#jerry_object_delete) +## jerry_object_has_sz + +**Summary** + +Checks whether the object or its prototype objects have the given property. + +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. + +**Prototype** + +```c +jerry_value_t jerry_object_has_sz (const jerry_value_t object, const char *key_p); +``` + +- `object` - object value +- `key_p` - property name (zero-terminated string) +- return value - JavaScript value that evaluates to + - exception - if the operation fail + - true/false API value - depend on whether the property exists + +*New in version 3.0* + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t global_object = jerry_current_realm (); + + jerry_value_t has_prop_js = jerry_object_has_sz (global_object, "handler_field"); + bool has_prop = jerry_value_is_true (has_prop_js); + + jerry_value_free (has_prop_js); + jerry_value_free (global_object); + + jerry_cleanup (); + + return 0; +} +``` + +**See also** + +- [jerry_object_has](#jerry_object_has) + + ## jerry_object_has_own **Summary** @@ -8405,6 +8622,45 @@ jerry_object_delete (const jerry_value_t obj_val, - [jerry_object_get](#jerry_object_get) +## jerry_object_delete_sz + +**Summary** + +Delete a property from an object. + +**Prototype** + +```c +jerry_value_t jerry_object_delete_sz (const jerry_value_t object, const char *key_p); +``` + +- `obj_val` - object value +- `key_p` - property name (zero-terminated string) +- return value + - true, if property was deleted successfully + - exception, otherwise + +*New in version 3.0* + +**Example** + +```c +{ + jerry_value_t global_object = jerry_current_realm (); + + jerry_value_t delete_result = jerry_object_delete_sz (global_object, "my_prop"); + /* use "delete_result" */ + + jerry_value_free (delete_result); + jerry_value_free (global_object); +} +``` + +**See also** + +- [jerry_object_delete](#jerry_object_delete) + + ## jerry_object_delete_index **Summary** @@ -8560,6 +8816,59 @@ main (void) - [jerry_object_set_index](#jerry_object_set_index) +## jerry_object_get_sz + +**Summary** + +Get value of a property to the specified object with the given name. + +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t jerry_object_get_sz (const jerry_value_t object, const char *key_p); +``` + +- `obj_val` - object value +- `key_p` - property name (zero-terminated string) +- return value + - value of property, if success + - thrown exception, otherwise + +*New in version 3.0* + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t global_object = jerry_current_realm (); + + jerry_value_t prop_value = jerry_object_get_sz (global_object, "Object"); + + /* use "prop_value" then release it. */ + + jerry_value_free (prop_value); + jerry_value_free (global_object); + + return 0; +} +``` + +**See also** + +- [jerry_object_get](#jerry_object_get) + + ## jerry_object_get_index **Summary** @@ -8805,6 +9114,58 @@ jerry_object_set (const jerry_value_t obj_val, - [jerry_object_set_index](#jerry_object_set_index) +## jerry_object_set_sz + +**Summary** + +Set a property to the specified object with the given name. + +*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it +is no longer needed. + +*New in version 3.0* + +**Prototype** + +```c +jerry_value_t jerry_object_set_sz (jerry_value_t object, const char *key_p, const jerry_value_t value); +``` + +- `obj_val` - object value +- `key_p` - property name (zero-terminated string) +- `value_to_set` - value to set +- return value + - true, if success + - thrown exception, otherwise + +**Example** + +```c +{ + jerry_value_t value_to_set; + + ... // create or copy value to set + + jerry_value_t glob_obj = jerry_current_realm (); + + jerry_value_t set_result = jerry_object_set_sz (glob_obj, "my_prop", value_to_set); + + ... // check result of property set call + + jerry_value_free (set_result); + + ... + + jerry_value_free (value_to_set); + jerry_value_free (glob_obj); +} +``` + +**See also** + +- [jerry_object_set](#jerry_object_set) + + ## jerry_object_set_index **Summary** @@ -8938,7 +9299,7 @@ jerry_property_descriptor_t jerry_property_descriptor (void); ``` -*New in version [[NEXT_RELEASE]]*: Replaces `jerry_init_property_descriptor_fields`. +*New in version 3.0*: Replaces `jerry_init_property_descriptor_fields`. **Example** @@ -9168,7 +9529,7 @@ jerry_object_get_own_prop (const jerry_value_t obj_val, - `prop_desc_p` - pointer to property descriptor - return value -*Changed in version [[NEXT_RELEASE]]*: Return value type is changed to `jerry_value_t`. +*Changed in version 3.0*: Return value type is changed to `jerry_value_t`. **Example** @@ -9212,7 +9573,7 @@ jerry_property_descriptor_free (const jerry_property_descriptor_t *prop_desc_p); - `prop_desc_p` - pointer to property descriptor -*New in version [[NEXT_RELEASE]]*: Replaces `jerry_free_property_descriptor_fields`. +*New in version 3.0*: Replaces `jerry_free_property_descriptor_fields`. **Example** @@ -9590,14 +9951,14 @@ print_buffer (char *data_p, static void do_stuff (jerry_value_t object) { - void *native_p = jerry_object_get_native_ptr (object, &buffer_obj_type_info); - - if (native_p == NULL) + if (!jerry_object_has_native_ptr (object, &buffer_obj_type_info)) { // Process the error return; } + void *native_p = jerry_object_get_native_ptr (object, &buffer_obj_type_info); + // It is safe to cast to buffer_native_object_t * and dereference the pointer: buffer_native_object_t *buffer_p = (buffer_native_object_t *) native_p; print_buffer (buffer_p->data_p, buffer_p->length); // Usage of buffer_p @@ -9606,14 +9967,14 @@ do_stuff (jerry_value_t object) if (need_shape_info) { - native_p = jerry_object_get_native_ptr (object, &shape_obj_type_info); - - if (native_p == NULL) + if (!jerry_object_has_native_ptr (object, &shape_obj_type_info)) { // Process the error return; } + native_p = jerry_object_get_native_ptr (object, &shape_obj_type_info); + // It is safe to cast to shape_native_object_t * and dereference the pointer: shape_native_object_t *shape_p = (shape_native_object_t *) native_p; @@ -9684,6 +10045,38 @@ main (void) - [jerry_object_native_info_t](#jerry_object_native_info_t) +## jerry_object_has_native_ptr + +**Summary** + +Checks wether the argument object has a native poitner set for the specified native type info. + +**Prototype** + +```c +bool jerry_object_has_native_ptr (const jerry_value_t object, const jerry_object_native_info_t *native_info_p); +``` + +- `object` - object to set native pointer in +- `native_info_p` - object's native type info +- return value + - true if the native pointer has been set, + - false otherwise + +*New in version 3.0* + +**Example** + +See [jerry_object_get_native_ptr](#jerry_object_get_native_ptr) for a +best-practice example. + +**See also** + +- [jerry_object_set_native_ptr](#jerry_object_set_native_ptr) +- [jerry_object_get_native_ptr](#jerry_object_get_native_ptr) +- [jerry_object_native_info_t](#jerry_object_native_info_t) + + ## jerry_object_set_native_ptr **Summary** @@ -9793,7 +10186,7 @@ jerry_native_ptr_init (void *native_pointer_p, - `native_pointer_p` - a valid non-NULL pointer to a native buffer. - `native_info_p` - native pointer's type information. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -9884,7 +10277,7 @@ jerry_native_ptr_free (void *native_pointer_p, - `native_pointer_p` - a valid non-NULL pointer to a native buffer. - `native_info_p` - native pointer's type information. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -9921,7 +10314,7 @@ jerry_native_ptr_set (jerry_value_t *reference_p, - `reference_p` - a valid non-NULL pointer to a reference in a native buffer. - `value` - new value of the reference. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -10520,7 +10913,7 @@ jerry_generate_snapshot (jerry_value_t compiled_code, *New in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: The `source_p`, `source_size`, `source_name_p`, +*Changed in version 3.0*: The `source_p`, `source_size`, `source_name_p`, and `source_name_length` arguments are replaced by `compiled_code` which should contain a compiled ECMAScript script / function. The `jerry_generate_function_snapshot` is now removed and can be reproduced @@ -10608,7 +11001,7 @@ jerry_exec_snapshot (const uint32_t *snapshot_p, *Changed in version 2.0*: Added `func_index` and `exec_snapshot_opts` arguments. Removed the `copy_bytecode` last argument. -*Changed in version [[NEXT_RELEASE]]*: Added `options_p` argument. +*Changed in version 3.0*: Added `options_p` argument. **Example 1** @@ -10733,6 +11126,93 @@ main (void) - [jerry_cleanup](#jerry_cleanup) - [jerry_generate_snapshot](#jerry_generate_snapshot) +## jerry_merge_snapshots + +**Summary** + +Merge multiple snapshots into a single buffer + +- `inp_buffers_p` - array of (pointers to start of) input buffers +- `inp_buffer_sizes_p` - array of input buffer sizes +- `number_of_snapshots` - number of snapshots +- `out_buffer_p` - output buffer +- `out_buffer_size` - output buffer size +- `error_p` - error description + +**Prototype** + +```c +size_t jerry_merge_snapshots (const uint32_t **inp_buffers_p, + size_t *inp_buffer_sizes_p, + size_t number_of_snapshots, + uint32_t *out_buffer_p, + size_t out_buffer_size, + const char **error_p); +``` + +**Example** + +```c + static uint32_t snapshot_buffer_0[SNAPSHOT_BUFFER_SIZE]; + static uint32_t snapshot_buffer_1[SNAPSHOT_BUFFER_SIZE]; + size_t snapshot_sizes[2]; + static uint32_t merged_snapshot_buffer[SNAPSHOT_BUFFER_SIZE]; + + const jerry_char_t code_to_snapshot1[] = "var a = 'hello'; 123"; + + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t parse_result = jerry_parse (code_to_snapshot1, sizeof (code_to_snapshot1) - 1, NULL); + jerry_value_t generate_result = jerry_generate_snapshot (parse_result, 0, snapshot_buffer_0, SNAPSHOT_BUFFER_SIZE); + jerry_value_free (parse_result); + + snapshot_sizes[0] = (size_t) jerry_value_as_number (generate_result); + jerry_value_free (generate_result); + + jerry_cleanup (); + + const jerry_char_t code_to_snapshot2[] = "var b = 'hello'; 456"; + + jerry_init (JERRY_INIT_EMPTY); + + parse_result = jerry_parse (code_to_snapshot2, sizeof (code_to_snapshot2) - 1, NULL); + generate_result = jerry_generate_snapshot (parse_result, 0, snapshot_buffer_1, SNAPSHOT_BUFFER_SIZE); + jerry_value_free (parse_result); + + snapshot_sizes[1] = (size_t) jerry_value_as_number (generate_result); + jerry_value_free (generate_result); + + jerry_cleanup (); + + jerry_init (JERRY_INIT_EMPTY); + + const char *error_p; + const uint32_t *snapshot_buffers[2]; + + snapshot_buffers[0] = snapshot_buffer_0; + snapshot_buffers[1] = snapshot_buffer_1; + + static uint32_t snapshot_buffer_0_bck[SNAPSHOT_BUFFER_SIZE]; + static uint32_t snapshot_buffer_1_bck[SNAPSHOT_BUFFER_SIZE]; + + memcpy (snapshot_buffer_0_bck, snapshot_buffer_0, SNAPSHOT_BUFFER_SIZE); + memcpy (snapshot_buffer_1_bck, snapshot_buffer_1, SNAPSHOT_BUFFER_SIZE); + + size_t merged_size = jerry_merge_snapshots (snapshot_buffers, + snapshot_sizes, + 2, + merged_snapshot_buffer, + SNAPSHOT_BUFFER_SIZE, + &error_p); + + jerry_cleanup (); +``` + +**See also** + +- [jerry_generate_snapshot](#jerry_generate_snapshot) +- [jerry_exec_snapshot](#jerry_exec_snapshot) + ## jerry_get_literals_from_snapshot @@ -10973,7 +11453,7 @@ jerry_backtrace_capture (jerry_backtrace_cb_t callback, void *user_p); which is called for each captured frame - `user_p` - pointer passed to the `callback` function, can be NULL -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -11081,7 +11561,7 @@ jerry_frame_type (jerry_frame_t *frame_p); - return value - frame type listed in [jerry_frame_type_t](#jerry_frame_type_t) -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -11144,7 +11624,7 @@ jerry_frame_location (jerry_frame_t *frame_p); - pointer to the location private field if the location is available, - NULL otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -11207,7 +11687,7 @@ jerry_frame_callee (jerry_frame_t *frame_p); - pointer to the called function if the function is available, - NULL otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -11264,7 +11744,7 @@ jerry_frame_this (jerry_frame_t *frame_p); - pointer to the 'this' binding if the binding is available, - NULL otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -11315,7 +11795,7 @@ jerry_frame_is_strict (jerry_frame_t *frame_p); - true, if strict mode code is bound to the frame - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -11345,6 +11825,73 @@ backtrace_callback (jerry_frame_t *frame_p, # Miscellaneous functions +## jerry_log + +**Summary** + + Log a zero-terminated formatted message with the specified log level. + +**Prototype** + +```c +void jerry_log (jerry_log_level_t level, const char *format_p, ...); +``` + +- `level` - message log level, see [jerry_log_level_t](#jerry_log_level_t) +- `format_p` - format string + Supported format specifiers: + `%s`: zero-terminated string + `%c`: character + `%u`: unsigned integer + `%d`: decimal integer + `%x`: unsigned hexadecimal + Width and padding sub-modifiers are also supported. +- rest - variables to substitue into the format string + +*New in version 3.0*. + +**Example** + +```c +jerry_log (JERRY_LOG_LEVEL_DEBUG, + "My debug message with a number param: %d.\n", 42); +``` + +**See also** + +- [jerry_log_level_t](#jerry_log_level_t) +- [jerry_log_set_level](#jerry_log_set_level) + + +## jerry_log_set_level + +**Summary** + +Set the log level of the engine. +Log messages with lower significance than the current log level will be ignored by `jerry_log`. + +**Prototype** + +```c +void jerry_log_set_level (jerry_log_level_t level); +``` + +- `level` - log level to be set, see [jerry_log_level_t](#jerry_log_level_t) + +*New in version 3.0*. + +**Example** + +```c +jerry_log_set_level (JERRY_LOG_LEVEL_WARNING); +``` + +**See also** + +- [jerry_log_level_t](#jerry_log_level_t) +- [jerry_log](#jerry_log) + + ## jerry_halt_handler **Summary** @@ -11552,7 +12099,7 @@ jerry_source_user_value (const jerry_value_t value); - user value - if available, - undefined - otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -11612,7 +12159,7 @@ bool jerry_function_is_dynamic (const jerry_value_t value); - true - if code is compiled by eval like command - false - otherwise -*New in version [[NEXT_RELEASE]]*. +*Renamed in version 3.0 from `jerry_is_eval_code` to `jerry_function_is_dynamic`*. **Example** @@ -11674,7 +12221,7 @@ jerry_source_info_t *jerry_source_info (const jerry_value_t value); - source info - a newly created source info, if at least one field is available, - NULL - otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -11730,7 +12277,7 @@ void jerry_source_info_free (jerry_source_info_t *source_info_p) ``` - `source_info_p` - source info structure returned by [jerry_source_info](#jerry_source_info) -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -11767,7 +12314,7 @@ which was active when the code was parsed or loaded regardless of the current re - This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked in runtime with the `JERRY_FEATURE_REALM` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -11812,7 +12359,7 @@ changed by [jerry_realm_set_this](#jerry_realm_set_this). - This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked in runtime with the `JERRY_FEATURE_REALM` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -11858,7 +12405,7 @@ any script on the realm. Otherwise the operation is undefined. - This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked in runtime with the `JERRY_FEATURE_REALM` feature enum value, see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -12236,7 +12783,7 @@ jerry_arraybuffer_has_buffer (const jerry_value_t value); - true, if a buffer is allocated for an array buffer or typed array - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -12302,7 +12849,7 @@ jerry_arraybuffer_heap_allocation_limit (const jerry_length_t allocation_limit); - `allocation_limit` - maximum size of compact allocation. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -12378,7 +12925,7 @@ jerry_arraybuffer_allocator (jerry_arraybuffer_allocate_cb_t allocate_callback, - `free_callback` - callback for freeing array buffer memory. - `user_p` - user pointer passed to the callbacks. -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** @@ -12774,9 +13321,9 @@ if the container object contains key-value structure and false if not. runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` feature enum values. see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. -*New in version [[NEXT_RELEASE]]*. + +*New in version 3.0*. **Prototype** @@ -12842,7 +13389,7 @@ Perform container operation on the given operands (add, delete, set, etc.). runtime with the `JERRY_FEATURE_MAP` , `JERRY_FEATURE_SET` , `JERRY_FEATURE_WEAKMAP` , `JERRY_FEATURE_WEAKSET` feature enum values. see: [jerry_feature_enabled](#jerry_feature_enabled). -- The es.next profile enables this by default. + **Prototype** @@ -12861,7 +13408,7 @@ jerry_container_op (jerry_container_op_t operation, - result if the operation is successful - exception, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 3.0*. **Example** diff --git a/jerry-core/include/jerryscript-types.h b/jerry-core/include/jerryscript-types.h index 4f0b98f03f..16d5cd07c2 100644 --- a/jerry-core/include/jerryscript-types.h +++ b/jerry-core/include/jerryscript-types.h @@ -86,7 +86,6 @@ typedef enum JERRY_FEATURE_VM_EXEC_STOP, /**< stopping ECMAScript execution */ JERRY_FEATURE_VM_THROW, /**< capturing ECMAScript throws */ JERRY_FEATURE_JSON, /**< JSON support */ - JERRY_FEATURE_PROMISE, /**< promise support */ JERRY_FEATURE_TYPEDARRAY, /**< Typedarray support */ JERRY_FEATURE_DATE, /**< Date support */ JERRY_FEATURE_REGEXP, /**< Regexp support */ @@ -315,8 +314,10 @@ typedef void (*jerry_error_object_created_cb_t) (const jerry_value_t error_objec * * Note: if the function returns with a non-undefined value it * must return with the same value for future calls. + * + * @param user_data_p: optional user data pointer */ -typedef jerry_value_t (*jerry_halt_cb_t) (void *user_p); +typedef jerry_value_t (*jerry_halt_cb_t) (void *user_data_p); /** * Callback function which is called when an exception is thrown in an ECMAScript code. @@ -324,13 +325,19 @@ typedef jerry_value_t (*jerry_halt_cb_t) (void *user_p); * until the value is caught. * * Note: the engine considers exceptions thrown by external functions as never caught. + * + * @param exception_value: the thrown exception + * @param user_data_p: optional user data pointer */ -typedef void (*jerry_throw_cb_t) (const jerry_value_t exception_value, void *user_p); +typedef void (*jerry_throw_cb_t) (const jerry_value_t exception_value, void *user_data_p); /** * Function type applied to each unit of encoding when iterating over a string. + * + * @param value: encoded byte value + * @param user_data_p: optional user data pointer */ -typedef void (*jerry_string_iterate_cb_t) (uint32_t value, void *user_p); +typedef void (*jerry_string_iterate_cb_t) (uint32_t value, void *user_data_p); /** * Function type applied for each data property of an object. diff --git a/jerry-ext/util/print.c b/jerry-ext/util/print.c index f0f8e6b5f3..d26b460c20 100644 --- a/jerry-ext/util/print.c +++ b/jerry-ext/util/print.c @@ -36,7 +36,7 @@ #define JERRYX_SYNTAX_ERROR_MAX_LINE_LENGTH 256 /** - * Struct for buffering print outpu + * Struct for buffering print output */ typedef struct { diff --git a/tests/unit-core/test-api-objecttype.c b/tests/unit-core/test-api-objecttype.c index 0e35c8fc78..4c0337d1c1 100644 --- a/tests/unit-core/test-api-objecttype.c +++ b/tests/unit-core/test-api-objecttype.c @@ -126,7 +126,7 @@ main (void) ENTRY (JERRY_OBJECT_TYPE_SCRIPT, PARSE (NULL)), ENTRY_IF (JERRY_OBJECT_TYPE_MODULE, PARSE (&module_parse_options), JERRY_FEATURE_MODULE), - ENTRY_IF (JERRY_OBJECT_TYPE_PROMISE, jerry_promise (), JERRY_FEATURE_PROMISE), + ENTRY (JERRY_OBJECT_TYPE_PROMISE, jerry_promise ()), ENTRY_IF (JERRY_OBJECT_TYPE_DATAVIEW, test_dataview (), JERRY_FEATURE_DATAVIEW), ENTRY_IF (JERRY_OBJECT_TYPE_FUNCTION, EVALUATE (arrow_function), JERRY_FEATURE_SYMBOL), ENTRY_IF (JERRY_OBJECT_TYPE_FUNCTION, EVALUATE (async_arrow_function), JERRY_FEATURE_SYMBOL),