diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index 3610957414..e27d762bbd 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -739,7 +739,7 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_call_info_t *call Native free callback of generic value types. *Note*: - - Referred values by this method must have at least 1 reference. (Correct API usage satisfies this condition) +- Referred values by this method must have at least 1 reference. (Correct API usage satisfies this condition) **Prototype** @@ -763,7 +763,7 @@ Native free callback of an object. The callback receives both the memory 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) +- Referred values by this method must have at least 1 reference. (Correct API usage satisfies this condition) **Prototype** @@ -821,8 +821,8 @@ object is created and the decorator can create or update any properties of the n Error object. *Note*: - - The callback function cannot be called recursively, so the Error objects created - when the callback is running are not updated. +- The callback function cannot be called recursively, so the Error objects created + when the callback is running are not updated. **Prototype** @@ -860,8 +860,8 @@ An enum representing the current status of a module Callback which is called by [jerry_module_link](#jerry_module_link) to get the referenced module. *Note*: - - If realms are enabled, the returned module should be created in the current realm - (see: [jerry_current_realm](#jerry_current_realm)) +- If realms are enabled, the returned module should be created in the current + realm (see: [jerry_current_realm](#jerry_current_realm)) **Prototype** @@ -891,19 +891,19 @@ typedef jerry_value_t (*jerry_module_resolve_cb_t) (const jerry_value_t specifie Callback which is called when an import is resolved dynamically to get the referenced module. *Note*: - - 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 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 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_current_realm](#jerry_current_realm)) +- 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 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 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_current_realm](#jerry_current_realm)) **Prototype** @@ -1590,7 +1590,8 @@ main (void) Finish JavaScript engine execution, freeing memory and JavaScript values. -*Note*: JavaScript values, received from engine, will be inaccessible after the cleanup. +*Note*: +- JavaScript values, received from engine, will be inaccessible after the cleanup. **Prototype** @@ -1610,10 +1611,11 @@ jerry_cleanup (void); Retrieve a pointer to the item stored within the current context by the given manager. -*Note*: Since internally the pointer to a manager's context data item is linked to the next such pointer in a linked - list, it is inadvisable to invoke too many different managers, because doing so will increase the time it takes - to retrieve a manager's context data item, degrading performance. For example, try to keep the number of - managers below five. +*Note*: +- Since internally the pointer to a manager's context data item is linked to the next + such pointer in a linked list, it is inadvisable to invoke too many different managers, + because doing so will increase the time it takes to retrieve a manager's context data + item, degrading performance. For example, try to keep the number of managers below five. **Prototype** @@ -1691,10 +1693,10 @@ someplace_in_the_code (void) Registers an external magic string array. -*Notes*: - - The strings in the array must be sorted by size at first, then lexicographically. - - The maximum number of external magic strings is limited to 2147483648 (UINT32_MAX / 2). - If there are more than 2147483648 external magic strings the extra is cropped. +*Note*: +- The strings in the array must be sorted by size at first, then lexicographically. +- The maximum number of external magic strings is limited to 2147483648 (UINT32_MAX / 2). + If there are more than 2147483648 external magic strings the extra is cropped. **Prototype** @@ -1755,7 +1757,7 @@ main (void) Get heap memory stats. -**Notes**: +*Note*: - 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 @@ -1846,8 +1848,8 @@ Functions to parse and run JavaScript source code. Parse a script, module, or function and create a compiled code using a character string. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -1959,8 +1961,8 @@ 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_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -2021,10 +2023,10 @@ main (void) 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_value_free](#jerry_value_free) - when it is no longer needed. +*Note*: +- The code should be previously parsed with `jerry_parse`. +- Returned value must be freed with [jerry_value_free](#jerry_value_free) + when it is no longer needed. **Prototype** @@ -2084,8 +2086,8 @@ main (void) Perform JavaScript `eval` function call (ECMA-262 v5.1 sec-15.1.2.1). -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -2126,8 +2128,8 @@ Run enqueued Promise tasks until the first thrown exception or until all tasks g *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_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -2196,8 +2198,8 @@ main (void) Get the Global object. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -2315,7 +2317,7 @@ jerry_value_is_array (const jerry_value_t value) Returns whether the given `jerry_value_t` is an ArrayBuffer object. -*Notes*: +*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_feature_enabled](#jerry_feature_enabled). @@ -2362,7 +2364,7 @@ jerry_value_is_arraybuffer (const jerry_value_t value) Returns whether the given `jerry_value_t` is a SharedArrayBuffer object. -*Notes*: +*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_feature_enabled](#jerry_feature_enabled). @@ -2566,7 +2568,7 @@ jerry_value_is_constructor (const jerry_value_t value) Returns whether the given `jerry_value_t` is a DataView object value. -*Notes*: +*Note*: - 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). @@ -2905,7 +2907,7 @@ jerry_value_is_promise (const jerry_value_t value) Returns whether the given `jerry_value_t` is a proxy value. -*Notes*: +*Note*: - 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). @@ -3049,7 +3051,7 @@ main (void) Returns whether the given `jerry_value_t` is a bigint value. -*Notes*: +*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_feature_enabled](#jerry_feature_enabled). @@ -3111,7 +3113,7 @@ main (void) Checks whether the given `jerry_value_t` is a TypedArray object or not. -*Notes*: +*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_feature_enabled](#jerry_feature_enabled). @@ -3169,7 +3171,7 @@ main (void) Checks whether the given `jerry_value_t` is the given `jerry_container_type_t` type container object. -*Notes* +*Note*: - 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. @@ -3489,8 +3491,8 @@ jerry_feature_enabled (const jerry_feature_t feature); Perform binary operation on the given operands (==, ===, <, >, etc.). -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -3778,8 +3780,8 @@ for the first argument, so the exception value won't be available after the call `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_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -3886,7 +3888,7 @@ 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_throw_cb_t](#jerry_throw_cb_t). -*Notes*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -3954,7 +3956,7 @@ main (void) Checks whether the callback set by [jerry_on_throw](#jerry_on_throw) captured the exception. -*Notes*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -4022,7 +4024,7 @@ main (void) Sets whether the callback set by [jerry_on_throw](#jerry_on_throw) should capture the exception or not. -*Notes*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -4195,7 +4197,7 @@ jerry_string_size (const jerry_value_t value, JERRY_ENCODING_CESU8); Get the length of a string. Returns zero, if the value parameter is not a string. -*Notes:* +*Note*: - 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. @@ -4240,12 +4242,11 @@ 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 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 is larger than the size of the -target buffer, the string will be cropped. - +*Note*: +- Does not put '\0' to the end of string, the return value identifies + the number of valid bytes in the output buffer. +- If the size of the string is larger than the size of the + target buffer, the string will be cropped. **Prototype** @@ -4315,10 +4316,10 @@ string is no longer used. It is recommended to set this function before the first external string is created. *Note*: - - When the callback is NULL, no function is called when an external string is freed. - - In some cases (e.g. when the string is also a magic string registered by - [jerry_register_magic_strings](#jerry_register_magic_strings)), the callback - is called when the string is created, not when it is released. +- When the callback is NULL, no function is called when an external string is freed. +- In some cases (e.g. when the string is also a magic string registered by + [jerry_register_magic_strings](#jerry_register_magic_strings)), the callback + is called when the string is created, not when it is released. **Prototype** @@ -4378,10 +4379,10 @@ main (void) Returns the user pointer assigned to an external string. *Note*: - - 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_string_external_sz](#jerry_string_external_sz). +- 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_string_external_sz](#jerry_string_external_sz). **Prototype** @@ -4523,8 +4524,8 @@ jerry_value_to_boolean (const jerry_value_t value); Call ToNumber operation on the api value. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -4563,8 +4564,9 @@ jerry_value_to_number (const jerry_value_t value); Call ToObject operation on the api value. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -4602,8 +4604,9 @@ jerry_value_to_object (const jerry_value_t value); Call ToPrimitive operation on the api value. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -4641,8 +4644,9 @@ 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_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -4681,8 +4685,8 @@ 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_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. **Prototype** @@ -4821,7 +4825,7 @@ These APIs all depend on module support. Link modules to their dependencies. The dependencies are resolved by a user callback. -*Notes*: +*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_MODULE_SYSTEM`) and can be checked @@ -4904,7 +4908,7 @@ main (void) Evaluate a module and its dependencies. The module must be in linked state. -*Notes*: +*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_MODULE_SYSTEM`) and can be checked @@ -4967,7 +4971,7 @@ main (void) Returns the current status of a module. The available values are listed in [jerry_module_state_t](#jerry_module_state_t) -*Notes*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -5029,7 +5033,7 @@ main (void) Sets a callback which is called after a module state is changed to linked, evaluated, or error. -*Notes*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -5106,7 +5110,7 @@ main (void) Sets a callback which is called when an import.meta expression of a module is evaluated the first time. -*Notes*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -5184,7 +5188,7 @@ Returns the number of import/export requests of a module. The requests can be queried by [jerry_module_request](#jerry_module_request). -*Notes*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -5253,7 +5257,7 @@ the successfully resolved dependencies are module objects, the rest are strings. The number of requests can be queried by [jerry_module_request_count](#jerry_module_request_count). -*Notes*: +*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_MODULE_SYSTEM`) and can be checked @@ -5322,7 +5326,7 @@ main (void) Returns the namespace object of a module -*Notes*: +*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_MODULE_SYSTEM`) and can be checked @@ -5390,7 +5394,7 @@ Sets the callback which is called when dynamic imports are resolved. The resolve receives the `user_value` assigned to the currently executed script, which should provide all the information that is necessary for the resolve. -*Notes*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -5512,7 +5516,7 @@ main (void) Creates a native module with a list of exports. The initial state of the module is linked. -*Notes*: +*Note*: - 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, @@ -5582,7 +5586,7 @@ main (void) Gets the value of an export binding which belongs to a native module. -*Notes*: +*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_MODULE_SYSTEM`) and can be checked @@ -5641,7 +5645,7 @@ main (void) Sets the value of an export binding which belongs to a native module. -*Notes*: +*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_MODULE_SYSTEM`) and can be checked @@ -5710,7 +5714,7 @@ These APIs are always enabled. The function returns the result of a Promise object. -*Notes*: +*Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. @@ -5771,7 +5775,7 @@ example (void) **Summary** -*Notes*: +*Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. @@ -5836,7 +5840,7 @@ example (void) Sets a callback for tracking Promise and async operations. -*Notes*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -5912,7 +5916,7 @@ main (void) This API function is equivalent to FromPropertyDescriptor operation defined in ECMA 262 v11 6.2.5.4. It returns with an ECMAScript Object which represents the property attributes. -*Notes*: +*Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. @@ -5963,7 +5967,7 @@ example (void) This API function is equivalent to ToPropertyDescriptor operation defined in ECMA 262 v11 6.2.5.5. It decodes the ECMAScript object and fills the fields of a JerryScript property descriptor. -*Notes*: +*Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. @@ -6132,7 +6136,7 @@ These APIs are always enabled. Get the well-known symbol corresponding to the given [well-known symbol id](#jerry_well_known_symbol_t). -*Notes*: +*Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. - If the symbol support is not enabled an undefined will be returned. @@ -6188,7 +6192,7 @@ main (void) Returns with the `[[Description]]` internal property of a symbol value. -*Notes*: +*Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. @@ -6246,7 +6250,7 @@ main (void) 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()`. -*Notes*: +*Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. @@ -6309,7 +6313,7 @@ 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_bigint_to_digits](#jerry_bigint_to_digits)`. -*Notes*: +*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_feature_enabled](#jerry_feature_enabled). @@ -6373,7 +6377,7 @@ buffer sizes. If the buffer size is smaller than the size returned by least significant digits are copied into the buffer. If the buffer size is greater, the unused digits are filled with zero. -*Notes*: +*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_feature_enabled](#jerry_feature_enabled). @@ -6437,7 +6441,7 @@ These APIs all depend on build option (`JERRY_BUILTIN_PROXY`). Gets the target object of a Proxy object. -*Notes*: +*Note*: - 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). @@ -6490,7 +6494,7 @@ jerry_proxy_target (jerry_value_t proxy_value); Gets the handler object of a Proxy object. -*Notes*: +*Note*: - 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). @@ -6546,8 +6550,9 @@ jerry_proxy_handler (jerry_value_t proxy_value); Copies the specified Jerry API value. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -6614,8 +6619,9 @@ jerry_value_free (jerry_value_t value); Function for creating [API values](#jerry_value_t). -*Note*: Every created API value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Every created API value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. ## jerry_array @@ -6623,8 +6629,9 @@ is no longer needed. Create an array object value. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -6868,9 +6875,10 @@ jerry_shared_arraybuffer_external (uint8_t *buffer_p, Create a jerry_value_t representing a boolean value from the given boolean parameter. -*Notes*: -- The boolean values (true/false) are fixed constants. Their values 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. +*Note*: +- The boolean values (true/false) are fixed constants. Their values 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** @@ -6908,8 +6916,9 @@ Create new JavaScript Error object with the specified error message. Important! The `error_type` argument *must not be* `JERRY_ERROR_NONE`. Creating an Error object with no error type is not valid. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -6950,8 +6959,9 @@ jerry_error (jerry_error_t error_type, jerry_value_t message); Create new JavaScript Error object, using the a zero-terminated string as the error message. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -6988,11 +6998,11 @@ jerry_error_sz (jerry_error_t error_type, const char *message_p); Create new JavaScript DataView object. *Note*: - - 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. +- 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** @@ -7049,8 +7059,9 @@ main (void) Create an external function object. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -7123,8 +7134,9 @@ main (void) Creates a `jerry_value_t` representing a number value. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -7161,8 +7173,9 @@ jerry_number (double value); Creates a `jerry_value_t` representing a positive or negative infinity value. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -7199,8 +7212,9 @@ jerry_infinity (bool sign); Creates a `jerry_value_t` representing a not-a-number value. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -7236,9 +7250,10 @@ jerry_nan (void); 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_value_copy](#jerry_value_copy), and freeing it with [jerry_value_free](#jerry_value_free) is optional. +*Note*: +- The null 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** @@ -7272,8 +7287,9 @@ jerry_null (void); Create new JavaScript object, like with new Object(). -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -7309,8 +7325,8 @@ Create an empty promise object which can be resolved or rejected later by calling jerry_promise_resolve or jerry_promise_reject. *Note*: - - Returned value must be freed with [jerry_value_free](#jerry_value_free) - when it is no longer needed. +- Returned value must be freed with [jerry_value_free](#jerry_value_free) + when it is no longer needed. **Prototype** @@ -7349,11 +7365,11 @@ jerry_promise (void) Create a new Proxy object with the given target and handler. *Note*: - - 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. +- 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** @@ -7411,11 +7427,11 @@ 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 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. +- 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** @@ -7474,8 +7490,9 @@ main (void) Create string from a zero-terminated ASCII string. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -7511,8 +7528,9 @@ jerry_string_sz (const char *str_p); 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_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -7559,9 +7577,9 @@ 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_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. +- 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** @@ -7606,9 +7624,9 @@ 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_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. +- 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** @@ -7658,9 +7676,9 @@ jerry_string_external (const jerry_char_t *str_p, Create symbol from an API value. *Note*: - - 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. +- 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** @@ -7775,8 +7793,9 @@ Returns a RegExp object created from the argument ASCII string pattern, or an ex object fails. Optional flags can be set using [jerry_regexp_flags_t](#jerry_regexp_flags_t). These flags can be combined together with the binary OR operator or used on their own as enum values. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** ```c @@ -7814,8 +7833,9 @@ Returns a RegExp object from the argument pattern, or an exception if the constr flags can be set using [jerry_regexp_flags_t](#jerry_regexp_flags_t). These flags can be combined together with the binary OR operator or used on their own as enum values. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** ```c @@ -7859,7 +7879,7 @@ Create a jerry_value_t representing an TypedArray object. For the new object the type of the TypedArray (see: [jerry_typedarray_type_t](#jerry_typedarray_type_t)) and element count can be specified. -*Notes*: +*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_BUILTIN_TYPEDARRAY`) and can be checked @@ -7915,7 +7935,7 @@ 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*: +*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_BUILTIN_TYPEDARRAY`) and can be checked @@ -7976,7 +7996,7 @@ 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*: +*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_BUILTIN_TYPEDARRAY`) and can be checked @@ -8031,7 +8051,7 @@ jerry_typedarray_with_buffer_span (jerry_typedarray_type_t type_name, Create a jerry_value_t representing a given type container object. -*Notes*: +*Note*: - This method is expected to work the same way as the JavaScript Map constructor. - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed. @@ -8095,8 +8115,10 @@ main (void) 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_value_copy](#jerry_value_copy), and freeing it with [jerry_value_free](#jerry_value_free) is optional. +*Note*: +- 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** @@ -8131,7 +8153,7 @@ jerry_undefined (void); Creates a `jerry_value_t` representing a new global object. -*Notes*: +*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_BUILTIN_REALMS`) and can be checked @@ -8186,8 +8208,9 @@ main (void) Checks whether the object or its prototype objects have the given property. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -8247,8 +8270,9 @@ main (void) Checks whether the object has the given property. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -8309,10 +8333,10 @@ main (void) Checks whether the object has the given internal property. *Note*: - - Properties which were not created with [jerry_object_set_internal](#jerry_object_set_internal) are excluded - during the operation. - - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +- Properties which were not created with [jerry_object_set_internal](#jerry_object_set_internal) + are excluded during the operation. +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -8458,8 +8482,9 @@ jerry_object_delete_index (const jerry_value_t obj_val, Delete an internal property from an object. -*Note*: Properties which were not created with [jerry_object_set_internal](#jerry_object_set_internal) are excluded - during the operation. +*Note*: +- Properties which were not created with [jerry_object_set_internal](#jerry_object_set_internal) + are excluded during the operation. **Prototype** @@ -8505,8 +8530,9 @@ jerry_object_delete_internal (const jerry_value_t obj_val, 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. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -8566,8 +8592,9 @@ main (void) Get value by an index from the specified object. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -8619,10 +8646,10 @@ whether the property is found, and the receiver object can be specified as well. 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_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. +*Note*: +- 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. **Prototype** @@ -8688,10 +8715,10 @@ main (void) Get value of an internal property to the specified object with the given name. *Note*: - - Properties which were not created with [jerry_object_set_internal](#jerry_object_set_internal) are excluded - during the operation. - - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it - is no longer needed. +- Properties which were not created with [jerry_object_set_internal](#jerry_object_set_internal) + are excluded during the operation. +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -8750,8 +8777,9 @@ main (void) 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. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -8811,8 +8839,9 @@ jerry_object_set (const jerry_value_t obj_val, Set indexed value in the specified object -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -8867,9 +8896,9 @@ jerry_object_set_index (const jerry_value_t obj_val, 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_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. +- The property cannot be accessed from the JavaScript context, only from the public API. +- 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** @@ -8968,8 +8997,9 @@ For a more complete example see [jerry_object_define_own_prop](#jerry_object_def Define 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. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -9240,8 +9270,9 @@ jerry_property_descriptor_free (const jerry_property_descriptor_t *prop_desc_p); 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_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -9298,8 +9329,9 @@ jerry_call (const jerry_value_t func_obj_val, 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_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -9348,8 +9380,9 @@ jerry_construct (const jerry_value_t func_obj_val, Get keys of the specified object value. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -9390,8 +9423,9 @@ jerry_object_keys (const jerry_value_t obj_val); Get the prototype of the specified object. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -9432,8 +9466,9 @@ jerry_object_proto (const jerry_value_t obj_val); Set the prototype of the specified object. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -9479,7 +9514,8 @@ Get native pointer by the given type information. The pointer and the type information are previously associated with the object by [jerry_object_set_native_ptr](#jerry_object_set_native_ptr). -*Note*: `native_info_p` can be NULL +*Note*: +- `native_info_p` can be NULL **Prototype** @@ -9691,16 +9727,15 @@ main (void) Set native pointer and an optional type information for the specified object. 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. - - If a non-NULL free callback is specified in the native type information, - it will be called by the garbage collector when the object is freed. - - If the object is only referenced via the "global" object (or one of it's "child"), - the free callback will be invoked during the execution of `jerry_cleanup`. - - The free callback can invoke API functions. - -*Note*: If possible do not store API values in native pointers, rather check - [jerry_object_set_internal](#jerry_object_set_internal). +*Note*: +- If a native pointer was already set for the object with the same type information, its value is updated. +- If a non-NULL free callback is specified in the native type information, + it will be called by the garbage collector when the object is freed. +- If the object is only referenced via the "global" object (or one of it's "child"), + the free callback will be invoked during the execution of `jerry_cleanup`. +- The free callback can invoke API functions. +- If possible do not store API values in native pointers, rather check + [jerry_object_set_internal](#jerry_object_set_internal). **Prototype** @@ -9736,12 +9771,12 @@ best-practice example. Delete the native pointer of the specified object associated with the given native type info. -*Notes*: - - If the specified object has no matching native pointer for the given native type info the operation has no effect. - - The method does not invoke the free callback specified in the type info. - If the native pointer should be freed then one must get the native pointer first and invoke the free callback manually - before calling this method. - - This operation cannot throw an exception. +*Note*: +- If the specified object has no matching native pointer for the given native type info the operation has no effect. +- The method does not invoke the free callback specified in the type info. + If the native pointer should be freed then one must get the native pointer first and invoke the free callback manually + before calling this method. +- This operation cannot throw an exception. **Prototype** @@ -9779,8 +9814,8 @@ before the buffer is attached to an object by [jerry_object_set_native_ptr](#jerry_object_set_native_ptr). *Note*: - - The description of [jerry_object_native_info_t](#jerry_object_native_info_t) - provides detailed information about these references. +- The description of [jerry_object_native_info_t](#jerry_object_native_info_t) + provides detailed information about these references. **Prototype** @@ -9870,8 +9905,8 @@ function also initializes the values to undefined, so calling is optional before the buffer is attached again. *Note*: - - The description of [jerry_object_native_info_t](#jerry_object_native_info_t) - provides detailed information about these references. +- The description of [jerry_object_native_info_t](#jerry_object_native_info_t) + provides detailed information about these references. **Prototype** @@ -9907,8 +9942,8 @@ Updates a value reference inside the area specified by the `number_of_references part of a buffer which is currently assigned to an object. *Note*: - - The description of [jerry_object_native_info_t](#jerry_object_native_info_t) - provides detailed information about these references. +- The description of [jerry_object_native_info_t](#jerry_object_native_info_t) + provides detailed information about these references. **Prototype** @@ -10086,7 +10121,8 @@ 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_value_copy](#jerry_value_copy). +*Note*: +- Values obtained in `foreach_p` must be retained using [jerry_value_copy](#jerry_value_copy). **Prototype** @@ -10224,7 +10260,8 @@ 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_value_copy](#jerry_value_copy). +*Note*: +- Values obtained in `foreach_p` must be retained using [jerry_value_copy](#jerry_value_copy). **Prototype** @@ -10383,8 +10420,9 @@ main (void) 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. +*Note*: +- Calling this method is safe in any time. It can be called + even before engine initialization. **Prototype** @@ -10441,9 +10479,10 @@ main (void) Allocate memory on the engine's heap. -*Note*: This function may take away memory from the executed JavaScript code. -If any other dynamic memory allocation API is available (e.g., libc malloc), it -should be used instead. +*Note*: +- This function may take away memory from the executed JavaScript code. + If any other dynamic memory allocation API is available (e.g., libc malloc), it + should be used instead. **Prototype** @@ -10491,7 +10530,7 @@ void jerry_heap_free (void *mem_p, size_t size); Generate snapshot from the specified source code. -*Notes*: +*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_SNAPSHOT_SAVE`) and can be checked in runtime with @@ -10578,7 +10617,7 @@ main (void) Execute/load snapshot from the specified buffer. -*Notes*: +*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_SNAPSHOT_EXEC`) and can be checked in runtime with @@ -10837,9 +10876,9 @@ The array length is zero if the backtrace is not available. This function is typically called from native callbacks. -*Notes*: +*Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. + 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_feature_enabled](#jerry_feature_enabled). @@ -11126,7 +11165,7 @@ This function can only be called from the callback function of [jerry_backtrace_capture](#jerry_backtrace_capture), and the value becomes invalid after the callback returns. -*Notes*: +*Note*: - Location information can only be retrieved if JERRY_FEATURE_LINE_INFO feature is enabled. Otherwise the function always returns with NULL. - The returned data must not be modified, and does not need to be freed. @@ -11191,7 +11230,7 @@ function can only be called from the callback function of [jerry_backtrace_capture](#jerry_backtrace_capture), and the value becomes invalid after the callback returns. -*Notes*: +*Note*: - The returned data must not be modified, and does not need to be freed. Any cleanup is done automatically after the callback is returned. @@ -11248,7 +11287,7 @@ function can only be called from the callback function of [jerry_backtrace_capture](#jerry_backtrace_capture), and the value becomes invalid after the callback returns. -*Notes*: +*Note*: - The returned data must not be modified, and does not need to be freed. Any cleanup is done automatically after the callback is returned. @@ -11363,7 +11402,7 @@ 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*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -11435,9 +11474,9 @@ Get the source name (usually a file name) of the currently executed script or th This function is typically called from native callbacks. -*Notes*: +*Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. + 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_feature_enabled](#jerry_feature_enabled). @@ -11536,9 +11575,9 @@ Returns the user value assigned to a script / module / function. This value is set by the parser when the JERRY_PARSE_HAS_USER_VALUE flag is set in the `options` member of the [jerry_parse_options_t](#jerry_parse_options_t) structure. -*Notes*: +*Note*: - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. + is no longer needed. **Prototype** @@ -11656,9 +11695,9 @@ main (void) Returns a newly created source info structure corresponding to the passed script/module/function. The function is lower level than `toString()` operation, but provides more contextual information. -*Notes*: +*Note*: - Returned value must be freed with [jerry_source_info_free](#jerry_source_info_free) when it -is no longer needed. + 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_feature_enabled](#jerry_feature_enabled). @@ -11718,7 +11757,7 @@ main (void) Frees the the source info structure returned by [jerry_source_info](#jerry_source_info). -*Notes*: +*Note*: - 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_feature_enabled](#jerry_feature_enabled). @@ -11763,7 +11802,7 @@ This function is useful to parse a script, create a native function, load a snap or create an exception in another realm. Each ECMAScript code runs in the realm which was active when the code was parsed or loaded regardless of the current realm. -*Notes*: +*Note*: - 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). @@ -11808,7 +11847,7 @@ Gets the 'this' binding of a realm. The 'this' binding is always an object. By default the 'this' binding is the same as the realm object and can be changed by [jerry_realm_set_this](#jerry_realm_set_this). -*Notes*: +*Note*: - 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). @@ -11854,7 +11893,7 @@ jerry_realm_this (jerry_value_t realm_value) Sets the 'this' binding of a realm. This function must be called before executing any script on the realm. Otherwise the operation is undefined. -*Notes*: +*Note*: - 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). @@ -12176,6 +12215,10 @@ Detach the underlying data block from ArrayBuffer and set its bytelength to 0. This operation requires the ArrayBuffer to be an external buffer created by `jerry_arraybuffer_external`. +*Note*: +- If the ArrayBuffer has been created with `jerry_arraybuffer_external` the optional free callback is + called on a successful detach operation + **Prototype** ```c @@ -12183,8 +12226,6 @@ jerry_value_t jerry_arraybuffer_detach (const jerry_value_t value); ``` -*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 @@ -12219,7 +12260,7 @@ jerry_arraybuffer_detach (const jerry_value_t value); Checks whether a buffer is currently allocated for an array buffer or typed array. -*Notes*: +*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_feature_enabled](#jerry_feature_enabled). @@ -12283,7 +12324,7 @@ function are allocated in a single memory block. The allocator callbacks set by [jerry_arraybuffer_set_allocation_callbacks](#jerry_arraybuffer_set_allocation_callbacks) are not called for these array buffers. -*Notes*: +*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_feature_enabled](#jerry_feature_enabled). @@ -12354,7 +12395,7 @@ main (void) Set callbacks for allocating and freeing backing stores for array buffer objects. -*Notes*: +*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_feature_enabled](#jerry_feature_enabled). @@ -12600,8 +12641,9 @@ of the TypedArray object. For the returned ArrayBuffer the [jerry_value_free](#jerry_value_free) must be called. -*Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -12653,8 +12695,9 @@ jerry_typedarray_buffer (jerry_value_t value, 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_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -12706,8 +12749,9 @@ 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_value_free](#jerry_value_free) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_value_free](#jerry_value_free) when it + is no longer needed. **Prototype** @@ -12768,7 +12812,7 @@ main (void) Return a new array containing elements from a Container, or a Container Iterator. Sets the is_key_value_p to true. if the container object contains key-value structure and false if not. -*Notes* +*Note*: - The return value will be an empty array if the Map/Set or Iterator object was empty or finished. - 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`