diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index d647cfabb..52affee62 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -294,12 +294,22 @@ Enum that contains the supported binary operation types - JERRY_BIN_OP_GREATER_EQUAL - greater or equal relation (>=) - JERRY_BIN_OP_INSTANCEOF - instanceof operation +**See also** + +- [jerry_binary_operation](#jerry_binary_operation) ## jerry_property_descriptor_t **Summary** -Description of ECMA property descriptor +Description of ECMA property descriptor. This struct can be used +for the [jerry_define_own_property](#jerry_define_own_property) method to +configure how the property should be registered. + +The naming scheme is similar to the JavaScript `Object.defineProperty` method. + +Fields should be used in pairs. That is if the `is_value_defined` is set to `true` +the `value` field should contain the value for the property. **Prototype** @@ -344,9 +354,13 @@ typedef struct } jerry_property_descriptor_t; ``` +**See also** + +- [jerry_define_own_property](#jerry_define_own_property) + ## jerry_heap_stats_t -**summary** +**Summary** Description of JerryScript heap memory stats. It is for memory profiling. @@ -364,6 +378,10 @@ typedef struct } jerry_heap_stats_t; ``` +**See also** + +- [jerry_get_memory_stats](#jerry_get_memory_stats) + ## jerry_external_handler_t **Summary** @@ -379,11 +397,22 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_ const jerry_length_t args_count); ``` +- `function_object` - the JavaScript function object which was invoked. +- `this_val` - the `this` value provided for the function call. +- `args_p` - the function arguments, array of JavaScript values. +- `args_count` - the number of arguments. +- return value + - The function's return value. If there is no return value, use [jerry_create_undefined()](#jerry_create_undefined). + +**See also** + +- [jerry_create_external_function](#jerry_create_external_function) + ## jerry_object_native_free_callback_t **Summary** -Native free callback of an object. It is used in jerry_object_native_info_t. +Native free callback of an object. It is used in `jerry_object_native_info_t` and for external Array buffers. **Prototype** @@ -391,6 +420,11 @@ Native free callback of an object. It is used in jerry_object_native_info_t. typedef void (*jerry_object_native_free_callback_t) (void *native_p); ``` +**See also** + +- [jerry_object_native_info_t](#jerry_object_native_info_t) +- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) + ## jerry_object_native_info_t **Summary** @@ -425,7 +459,9 @@ typedef struct **Summary** -Function type applied for each data property of an object +Function type used as a callback for the [jerry_foreach_object_property](#jerry_foreach_object_property) +method. A function with this type must return "true" to continue the iteration or "false" to finish the +iteration on the object's properties. **Prototype** @@ -435,11 +471,24 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na void *user_data_p); ``` +- `property_name` - a property name, this is not always a string. +- `property_value` - the value for the given property. +- `user_data_p` - optional user data pointer supplied via the (jerry_foreach_object_property)[#jerry_foreach_object_property] method. +- return value + - true, to continue the iteration + - false, to stop the iteration + +**See also** + +- [jerry_foreach_object_property](#jerry_foreach_object_property) + ## jerry_objects_foreach_t **Summary** -Function type applied for each object in the engine +Function type used as a callback for the (jerry_objects_foreach)[#jerry_objects_foreach] method. +A function with this type must return "true" to continue the iteration or "false" to finish the +iteration on the object's properties. **Prototype** @@ -448,11 +497,23 @@ typedef bool (*jerry_objects_foreach_t) (const jerry_value_t object, void *user_data_p); ``` +- `object` - the current JavaScript object in the for-each iteration. +- `user_data_p` - optional user data pointer supplied via the (jerry_objects_foreach)[#jerry_objects_foreach] method. +- return value + - true, to continue the iteration + - false, to stop the iteration + +**See also** + +- [jerry_objects_foreach](#jerry_objects_foreach) + ## jerry_objects_foreach_by_native_info_t **Summary** -Function type applied for each matching object in the engine +Function type used as a callback for the (jerry_objects_foreach_by_native_info)[#jerry_objects_foreach_by_native_info] +method. A function with this type must return "true" to continue the iteration or "false" to finish the +iteration on the object's properties. **Prototype** @@ -462,6 +523,17 @@ typedef bool (*jerry_objects_foreach_by_native_info_t) (const jerry_value_t obje void *user_data_p); ``` +- `object` - the current JavaScript object in the for-each iteration. +- `object_data_p` - the current object's native data pointer. +- `user_data_p` - optional user data pointer supplied via the (jerry_objects_foreach_by_native_info)[#jerry_objects_foreach_by_native_info] method. +- return value + - true, to continue the iteration + - false, to stop the iteration + +**See also** + +- [jerry_objects_foreach_by_native_info](#jerry_objects_foreach_by_native_info) + ## jerry_vm_exec_stop_callback_t **Summary** @@ -503,6 +575,10 @@ Possible values: API functions can return the `JERRY_TYPEDARRAY_INVALID` value if the TypedArray support is not in the engine. +**See also** + +- [jerry_get_typedarray_type](#jerry_get_typedarray_type) + # General engine functions @@ -511,7 +587,7 @@ TypedArray support is not in the engine. **Summary** Initializes the JerryScript engine, making it possible to run JavaScript code and perform operations -on JavaScript values. +on JavaScript values. This is required for almost all API functions. **Prototype** @@ -520,14 +596,7 @@ void jerry_init (jerry_init_flag_t flags) ``` -`flags` - combination of various engine configuration flags: - -- `JERRY_INIT_EMPTY` - no flags, just initialize in default configuration. -- `JERRY_INIT_SHOW_OPCODES` - print compiled byte-code. -- `JERRY_INIT_SHOW_REGEXP_OPCODES` - print compiled regexp byte-code. -- `JERRY_INIT_MEM_STATS` - dump memory statistics. -- `JERRY_INIT_MEM_STATS_SEPARATE` - dump memory statistics and reset peak values after parse. -- `JERRY_INIT_DEBUGGER` - deprecated, an unused placeholder now +`flags` - combination of various engine configuration flags [jerry_init_flag_t](#jerry_init_flag_t). **Example** @@ -544,11 +613,13 @@ main (void) // ... jerry_cleanup (); + return 0; } ``` **See also** +- [jerry_init_flag_t](#jerry_init_flag_t) - [jerry_cleanup](#jerry_cleanup) @@ -657,9 +728,10 @@ someplace_in_the_code (void) Registers an external magic string array. -*Note*: The strings in the array must be sorted by size at first, then lexicographically. -*Note*: 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. +*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. **Prototype** @@ -671,8 +743,8 @@ jerry_register_magic_strings (const jerry_char_t * const *ex_str_items_p, ``` - `ex_str_items_p` - character arrays, representing external magic strings' contents -- `count` - number of the strings -- `str_lengths_p` - lengths of the strings +- `count` - number of elements in `ext_str_items_p` array +- `str_lengths_p` - array of lengths for each magic string **Example** @@ -780,6 +852,7 @@ main (void) **See also** +- [jerry_gc_mode_t](#jerry_gc_mode_t) - [jerry_init](#jerry_init) - [jerry_cleanup](#jerry_cleanup) @@ -822,6 +895,7 @@ main (void) const jerry_char_t script[] = "print ('Hello, World!');"; jerry_run_simple (script, sizeof (script) - 1, JERRY_INIT_EMPTY); + return 0; } ``` @@ -882,12 +956,14 @@ main (void) jerry_release_value (parsed_code); jerry_cleanup (); + return 0; } ``` **See also** - [jerry_run](#jerry_run) +- [jerry_parse_function](#jerry_parse_function) ## jerry_parse_function @@ -927,13 +1003,88 @@ jerry_parse_function (const jerry_char_t *resource_name_p, /**< resource name (u - function object value, if script was parsed successfully, - thrown error, otherwise + +**Example** + +[doctest]: # (name="02.API-REFERENCE-parse-func.c") + +```c +#include +#include +#include "jerryscript.h" + +int +main (void) +{ + int return_value = 1; + + /* Initialize engine */ + jerry_init (JERRY_INIT_EMPTY); + + /* Parse the 'function (a,b) { return a + b; }' function */ + const char function_args[] = "a, b"; + const char function_source[] = "return a + b"; + + jerry_value_t parsed_function = jerry_parse_function (NULL, + 0, + (const jerry_char_t *) function_args, + strlen (function_args), + (const jerry_char_t *) function_source, + strlen (function_source), + JERRY_PARSE_NO_OPTS); + + if (!jerry_value_is_error (parsed_function)) + { + /* Run the parsed function */ + jerry_value_t args[] = { + jerry_create_number (3), + jerry_create_number (55), + }; + jerry_size_t argc = sizeof (args) / sizeof (args[0]); + jerry_value_t ret_value = jerry_call_function (parsed_function, + jerry_create_undefined(), + args, + argc); + + /* Process result value */ + if (jerry_value_is_number (ret_value)) { + double value = jerry_get_number_value (ret_value); + printf ("Function result: %lf\n", value); + + return_value = !(value == (3 + 55)); + } + + /* Release the function arguments */ + for (jerry_size_t idx = 0; idx < argc; idx++) { + jerry_release_value (args[idx]); + } + + /* Returned value must be freed */ + jerry_release_value (ret_value); + } + + /* Parsed function must be freed */ + jerry_release_value (parsed_function); + + /* Cleanup engine */ + jerry_cleanup (); + + return return_value; +} +``` + +**See also** + +- [jerry_call_function](#jerry_call_function) + + ## jerry_run **Summary** Run an EcmaScript function created by `jerry_parse`. -*Note*: +*Notes*: - The code should be previously parsed with `jerry_parse`. - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. @@ -1011,7 +1162,7 @@ jerry_eval (const jerry_char_t *source_p, - `source_p` - source code to evaluate, it must be a valid utf8 string. - `source_size` - length of the source code - `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags. -- return value - result of eval, may be error value. +- return value - result of eval, may be an error value. **Example** @@ -1069,6 +1220,7 @@ main (void) jerry_release_value (parsed_code); jerry_cleanup (); + return 0; } ``` @@ -1198,7 +1350,11 @@ jerry_value_is_array (const jerry_value_t value) Returns whether the given `jerry_value_t` is an ArrayBuffer object. -*Note*: This API depends on the ES2015-subset profile. +*Notes*: +- This API depends on a build option (`JERRY_ES2015_BUILTIN_TYPEDARRAY`) and can be checked + in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. **Prototype** @@ -1207,7 +1363,7 @@ bool jerry_value_is_arraybuffer (const jerry_value_t value) ``` -- `value` - api value +- `value` - api value to check. - return value - true, if the given `jerry_value_t` is an ArrayBuffer object. - false, otherwise @@ -1317,7 +1473,11 @@ jerry_value_is_constructor (const jerry_value_t value) Returns whether the given `jerry_value_t` is a DataView object value. -*Note*: This API depends on the ES2015-subset profile. +*Notes*: +- This API depends on a build option (`JERRY_ES2015_BUILTIN_DATAVIEW`) and can be checked + in runtime with the `JERRY_FEATURE_DATAVIEW` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. **Prototype** @@ -1355,12 +1515,14 @@ main (void) jerry_release_value (arraybuffer); jerry_cleanup (); + return 0; } ``` **See also** - [jerry_release_value](#jerry_release_value) +- [jerry_create_dataview](#jerry_create_dataview) ## jerry_value_is_error @@ -1564,7 +1726,12 @@ jerry_value_is_object (const jerry_value_t value) Returns whether the given `jerry_value_t` is a promise value. -*Note*: This API depends on the ES2015-subset profile. +*Notes*: +- This API depends on a build option (`JERRY_ES2015_BUILTIN_PROMISE`) and can be checked + in runtime with the `JERRY_FEATURE_PROMISE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. + **Prototype** @@ -1597,6 +1764,7 @@ jerry_value_is_promise (const jerry_value_t value) **See also** - [jerry_release_value](#jerry_release_value) +- [jerry_create_promise](#jerry_create_promise) ## jerry_value_is_string @@ -1644,7 +1812,11 @@ jerry_value_is_string (const jerry_value_t value) Returns whether the given `jerry_value_t` is a symbol value. -*Note*: This API depends on the ES2015-subset profile. +*Notes*: +- This API depends on a build option (`JERRY_ES2015_BUILTIN_SYMBOL`) and can be checked + in runtime with the `JERRY_FEATURE_SYMBOL` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. **Prototype** @@ -1683,13 +1855,14 @@ main (void) jerry_release_value (symbol_value); jerry_cleanup (); + return 0; } ``` **See also** - [jerry_release_value](#jerry_release_value) - +- [jerry_create_symbol](#jerry_create_symbol) ## jerry_value_is_typedarray @@ -1697,6 +1870,12 @@ main (void) Checks whether the given `jerry_value_t` is a TypedArray object or not. +*Notes*: +- This API depends on a build option (`JERRY_ES2015_BUILTIN_TYPEDARRAY`) and can be checked + in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. + **Prototype** ```c @@ -1711,17 +1890,28 @@ jerry_value_is_typedarray (const jerry_value_t value) **Example** +[doctest]: # () + ```c +#include "jerryscript.h" + +int +main (void) { - jerry_value_t value; - ... // create or acquire value + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t value = jerry_create_typedarray (JERRY_TYPEDARRAY_UINT16, 15); if (jerry_value_is_typedarray (value)) { - ... + /* "value" is a typedarray. */ } jerry_release_value (value); + + jerry_cleanup (); + + return 0; } ``` @@ -1786,6 +1976,10 @@ jerry_type_t jerry_value_get_type (const jerry_value_t value); ``` +- `value` - JavaScript value to check. +- return value + - One of the [jerry_type_t](#jerry_type_t) value. + **Example** ```c @@ -1796,7 +1990,7 @@ jerry_value_get_type (const jerry_value_t value); if (type_info == JERRY_TYPE_NUMBER) { - ... + /* ... */ } jerry_release_value (number); @@ -1804,6 +1998,7 @@ jerry_value_get_type (const jerry_value_t value); ``` **See also** + - [jerry_type_t](#jerry_type_t) ## jerry_is_feature_enabled @@ -1828,18 +2023,19 @@ jerry_is_feature_enabled (const jerry_feature_t feature); ```c { - ... + /* ... */ jerry_feature_t feature = JERRY_FEATURE_SNAPSHOT_SAVE; if (jerry_is_feature_enabled (feature)) { - ... + /* ... */ } } ``` **See also** + - [jerry_feature_t](#jerry_feature_t) @@ -1955,6 +2151,7 @@ main (void) ``` **See also** + - [jerry_binary_operation_t](#jerry_binary_operation_t) @@ -2077,7 +2274,7 @@ jerry_create_error_from_value (jerry_value_t value, bool release); - [jerry_value_t](#jerry_value_t) - [jerry_get_value_from_error](#jerry_get_value_from_error) -- [jerry_create_abort_from_value](#jerry_create_abort_from_value +- [jerry_create_abort_from_value](#jerry_create_abort_from_value) ## jerry_get_error_type @@ -2239,6 +2436,8 @@ jerry_get_boolean_value (const jerry_value_t value); Gets the number value of the given `jerry_value_t` parameter as a raw double. +If the argument passed is not a number `0.0` will be returned. + **Prototype** ```c @@ -2247,7 +2446,9 @@ jerry_get_number_value (const jerry_value_t value); ``` - `value` - api value -- return value - the number value of the given `jerry_value_t` parameter as a raw double. +- return value + - the number value of the given `jerry_value_t` parameter as a raw double. + - `0.0` if the api value passed is not a number. **Example** @@ -2281,6 +2482,7 @@ jerry_get_number_value (const jerry_value_t value); **Summary** Get the size of a string. Returns zero, if the value parameter is not a string. +This is effectively the number of bytes required to store the string's characters. **Prototype** @@ -2318,6 +2520,7 @@ jerry_get_string_size (const jerry_value_t value); **Summary** Get the size of an utf8-encoded string. Returns zero, if the value parameter is not a string. +This is effectively the number of bytes required to store the utf8 encoded string's characters. *Note*: The difference from [jerry_get_string_size](#jerry_get_string_size) is that it returns with utf-8 string size instead of the cesu-8 string size. @@ -2359,6 +2562,11 @@ jerry_get_utf8_string_size (const jerry_value_t value); Get the length of a string. Returns zero, if the value parameter is not a string. +*Notes:* +- The difference from [jerry_get_string_size](#jerry_get_string_size) is that it + returns the number of bytes used for the string. +- This is **not** the number of bytes required to store the string. + **Prototype** ```c @@ -2397,8 +2605,10 @@ jerry_get_string_length (const jerry_value_t value); Get the length of an UTF-8 encoded string. Returns zero, if the value parameter is not a string. -*Note*: The difference from [jerry_get_string_length](#jerry_get_string_length) is that it -returns with utf-8 string length instead of the cesu-8 string length. +*Notes*: +- The difference from [jerry_get_string_length](#jerry_get_string_length) is that it + returns with utf-8 string length instead of the cesu-8 string length. +- This is **not** the number of bytes required to store the string. **Prototype** @@ -2466,17 +2676,37 @@ jerry_string_to_char_buffer (const jerry_value_t value, **Example** +[doctest]: # () + ```c +#include +#include +#include "jerryscript.h" + +int +main (void) { + jerry_init (JERRY_INIT_EMPTY); + jerry_value_t value; - ... // create or acquire value + // create or acquire value + value = jerry_create_string ((const jerry_char_t *) "Demo string"); - jerry_size_t req_sz = jerry_get_string_size (value); - jerry_char_t str_buf_p[req_sz]; + // Read the string into a byte buffer. + jerry_size_t string_size = jerry_get_string_size (value); + jerry_char_t *string_buffer_p = (jerry_char_t *) malloc (sizeof (jerry_char_t) * string_size); - jerry_string_to_char_buffer (value, str_buf_p, req_sz); + jerry_size_t copied_bytes = jerry_string_to_char_buffer (value, string_buffer_p, string_size); + string_buffer_p[copied_bytes] = '\0'; jerry_release_value (value); + + jerry_cleanup (); + + printf ("Test string: %s\n", string_buffer_p); + free (string_buffer_p); + + return 0; } ``` @@ -2529,7 +2759,7 @@ jerry_string_to_utf8_char_buffer (const jerry_value_t value, jerry_size_t req_sz = jerry_get_utf8_string_size (value); jerry_char_t str_buf_p[req_sz]; - jerry_string_to_utf8_char_buffer (value, str_buf_p, req_sz); + jerry_size_t bytes_copied = jerry_string_to_utf8_char_buffer (value, str_buf_p, req_sz); jerry_release_value (value); } @@ -2893,7 +3123,7 @@ jerry_value_to_string (const jerry_value_t value); # Functions for promise objects -These APIs all depend on the ES2015-subset profile. +These APIs all depend on the ES2015-subset profile (or on some build options). ## jerry_resolve_or_reject_promise @@ -2901,8 +3131,14 @@ These APIs all depend on the ES2015-subset profile. Resolve or reject the promise with an argument. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. +*Note*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. +- This API depends on a build option (`JERRY_ES2015_BUILTIN_PROMISE`) and can be checked + in runtime with the `JERRY_FEATURE_PROMISE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. + **Prototype** @@ -2953,16 +3189,23 @@ jerry_resolve_or_reject_promise (jerry_value_t promise, # Functions for symbols -These APIs all depend on the ES2015-subset profile. +These APIs all depend on the ES2015-subset profile (or on build options). ## jerry_get_symbol_descriptive_string **Summary** 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()`. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. +- This API depends on a build option (`JERRY_ES2015_BUILTIN_SYMBOL`) and can be checked + in runtime with the `JERRY_FEATURE_SYMBOL` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. +- If the symbol support is not enabled an error will be returned. **Prototype** @@ -3001,6 +3244,7 @@ main (void) jerry_release_value (symbol_value); jerry_cleanup (); + return 0; } ``` @@ -3386,6 +3630,7 @@ main (void) jerry_release_value (arraybuffer); jerry_cleanup (); + return 0; } ``` @@ -3416,7 +3661,13 @@ jerry_create_external_function (jerry_external_handler_t handler_p); **Example** +[doctest]: # () + ```c +#include +#include +#include "jerryscript.h" + static jerry_value_t handler (const jerry_value_t function_obj, const jerry_value_t this_val, @@ -3428,7 +3679,11 @@ handler (const jerry_value_t function_obj, return jerry_create_boolean (true); } +int +main (void) { + jerry_init (JERRY_INIT_EMPTY); + jerry_value_t func_val = jerry_create_external_function (handler); jerry_value_t glob_obj = jerry_get_global_object (); @@ -3440,6 +3695,16 @@ handler (const jerry_value_t function_obj, jerry_release_value (func_val); jerry_release_value (glob_obj); + + // Test the method by calling it + const char *test_src = "handler_field ();"; + jerry_value_t ret_val = jerry_eval ((const jerry_char_t *) test_src, + strlen (test_src), + JERRY_PARSE_NO_OPTS); + // release the eval result + jerry_release_value (ret_val); + jerry_cleanup (); + return 0; } ``` @@ -3972,10 +4237,13 @@ 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. -*Note*: - - This API depends on the ES2015-subset profile. - - Returned value must be freed with [jerry_release_value](#jerry_release_value) - when it is no longer needed. +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- This API depends on a build option (`JERRY_ES2015_BUILTIN_TYPEDARRAY`) and can be checked + in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. **Prototype** @@ -4023,10 +4291,13 @@ type of TypedArray otherwise an error is generated. The JavaScript equivalent of this function is: `new %TypedArray%(arraybuffer)` where `%TypedArray%` is one of the allowed TypedArray functions. -*Note*: - - This API depends on the ES2015-subset profile. - - Returned value must be freed with [jerry_release_value](#jerry_release_value) - when it is no longer needed. +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- This API depends on a build option (`JERRY_ES2015_BUILTIN_TYPEDARRAY`) and can be checked + in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. **Prototype** @@ -4079,10 +4350,13 @@ type of TypedArray otherwise an error is generated. The JavaScript equivalent of this function is: `new %TypedArray%(arraybuffer, byteOffset, length)` where `%TypedArray%` is one of the allowed TypedArray functions. -*Note*: - - This API depends on the ES2015-subset profile. - - Returned value must be freed with [jerry_release_value](#jerry_release_value) - when it is no longer needed. +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- This API depends on a build option (`JERRY_ES2015_BUILTIN_TYPEDARRAY`) and can be checked + in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. **Prototype** @@ -4182,8 +4456,16 @@ jerry_has_property (const jerry_value_t obj_val, **Example** +[doctest]: # () + ```c +#include "jerryscript.h" + +int +main (void) { + jerry_init (JERRY_INIT_EMPTY); + jerry_value_t global_object = jerry_get_global_object (); jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field"); @@ -4193,6 +4475,10 @@ jerry_has_property (const jerry_value_t obj_val, jerry_release_value (has_prop_js); jerry_release_value (prop_name); jerry_release_value (global_object); + + jerry_cleanup (); + + return 0; } ``` @@ -4227,17 +4513,29 @@ jerry_has_own_property (const jerry_value_t obj_val, **Example** +[doctest]: # () + ```c +#include "jerryscript.h" + +int +main (void) { + jerry_init (JERRY_INIT_EMPTY); + jerry_value_t global_object = jerry_get_global_object (); jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field"); jerry_value_t has_prop_js = jerry_has_own_property (global_object, prop_name); bool has_prop = jerry_get_boolean_value (has_prop_js); - jerry_release_value (jas_prop_js); + jerry_release_value (has_prop_js); jerry_release_value (prop_name); jerry_release_value (global_object); + + jerry_cleanup (); + + return 0; } ``` @@ -4274,7 +4572,8 @@ jerry_delete_property (const jerry_value_t obj_val, jerry_value_t global_object = jerry_get_global_object (); jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); - jerry_delete_property (global_object, prop_name); + bool delete_result = jerry_delete_property (global_object, prop_name); + /* use "delete_result" */ jerry_release_value (prop_name); jerry_release_value (global_object); @@ -4317,7 +4616,7 @@ jerry_delete_property_by_index (const jerry_value_t obj_val, ... // create or acquire object - jerry_delete_property_by_index (object, 5); + bool delete_result = jerry_delete_property_by_index (object, 5); jerry_release_value (object); } @@ -4359,15 +4658,28 @@ jerry_get_property (const jerry_value_t obj_val, **Example** +[doctest]: # () + ```c +#include "jerryscript.h" + +int +main (void) { + jerry_init (JERRY_INIT_EMPTY); + jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "Object"); jerry_value_t prop_value = jerry_get_property (global_object, prop_name); + /* use "prop_value" then release it. */ + + jerry_release_value (prop_value); jerry_release_value (prop_name); jerry_release_value (global_object); + + return 0; } ``` @@ -4553,7 +4865,8 @@ jerry_set_property_by_index (const jerry_value_t obj_val, **Summary** -Initialize property descriptor. +Initialize property descriptor. This means that all fields in the `jerry_property_descriptor_t` +struct will be set to zero or false depending on the field's type. **Prototype** @@ -4577,8 +4890,11 @@ jerry_init_property_descriptor_fields (jerry_property_descriptor_t *prop_desc_p) } ``` +For a more complete example see [jerry_define_own_property](#jerry_define_own_property). + **See also** +- [jerry_property_descriptor_t](#jerry_property_descriptor_t) - [jerry_define_own_property](#jerry_define_own_property) - [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) - [jerry_free_property_descriptor_fields](#jerry_free_property_descriptor_fields) @@ -4602,7 +4918,7 @@ jerry_define_own_property (const jerry_value_t obj_val, const jerry_property_descriptor_t *prop_desc_p); ``` -- `obj_val` - object value +- `obj_val` - target object where the property should be registered - `prop_name_val` - property name - `prop_desc_p` - pointer to property descriptor - return value @@ -4611,32 +4927,152 @@ jerry_define_own_property (const jerry_value_t obj_val, **Example** +Registering a simple value property via the `jerry_define_own_property` method: + +[doctest]: # (name="02.API-REFERENCE-define-property.c") + ```c +#include "jerryscript.h" + +int +main (void) { + jerry_init (JERRY_INIT_EMPTY); + jerry_value_t global_obj_val = jerry_get_global_object (); + // configure the property jerry_property_descriptor_t prop_desc; jerry_init_property_descriptor_fields (&prop_desc); jerry_value_t value_to_set; - ... // create or acquire value to set + // create or acquire value to set + // For example: + value_to_set = jerry_create_number (33); + // set the property descriptor fields: + // set the "is_value_defined" field to "true" to indicate the "value" + // field should be used during the property registration. prop_desc.is_value_defined = true; + + // set the "value" field to the number 33 prop_desc.value = value_to_set; + // add the property as "my_prop" for the global object jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); jerry_value_t return_value = jerry_define_own_property (global_obj_val, prop_name, &prop_desc); + if (jerry_value_is_error (return_value)) + { + // there was an error + } + + // if there was no error at this point the global object should have a "my_prop" property + jerry_release_value (return_value); jerry_release_value (prop_name); jerry_free_property_descriptor_fields (&prop_desc); jerry_release_value (global_obj_val); + + jerry_cleanup (); + return 0; +} +``` + + +Registering a getter/setter property via the `jerry_define_own_property` method: + +[doctest]: # (name="02.API-REFERENCE-define-property-getset.c") + +```c +#include +#include +#include "jerryscript.h" + +static int counter = 0; + +static jerry_value_t +method_getter (const jerry_value_t this_obj, + const jerry_value_t func_obj, + const jerry_value_t args[], + const jerry_length_t argc) +{ + counter++; + printf("Getter called, returning: %d\n", counter); + + return jerry_create_number (counter); +} + +static jerry_value_t +method_setter (const jerry_value_t this_obj, + const jerry_value_t func_obj, + const jerry_value_t args[], + const jerry_length_t argc) +{ + // Note: the arguments count and type should be checked + // in this example it is ommitted! + + double new_value = jerry_get_number_value (args[0]); + counter = (int) new_value; + + printf("Setter called, setting: %d\n", counter); + + return jerry_create_undefined (); +} + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t global_obj_val = jerry_get_global_object (); + + // configure the property + jerry_property_descriptor_t prop_desc; + jerry_init_property_descriptor_fields (&prop_desc); + + // set the property descriptor fields: + + prop_desc.is_get_defined = true; + prop_desc.getter = jerry_create_external_function (method_getter); + prop_desc.is_set_defined = true; + prop_desc.setter = jerry_create_external_function (method_setter); + + // add the property as "my_prop" for the global object + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); + jerry_value_t return_value = jerry_define_own_property (global_obj_val, prop_name, &prop_desc); + if (jerry_value_is_error (return_value)) + { + // there was an error + } + + // if there was no error at this point the global object should have a "my_prop" property + + jerry_release_value (return_value); + jerry_release_value (prop_name); + + jerry_free_property_descriptor_fields (&prop_desc); + jerry_release_value (global_obj_val); + + // run an example js code to use the getter/setters + + const char *src_p = "this.my_prop; this.my_prop; this.my_prop = 4; this.my_prop"; + jerry_value_t eval_result = jerry_eval ((const jerry_char_t *) src_p, strlen (src_p), JERRY_PARSE_NO_OPTS); + + // "eval_result" is the last result of "this.my_prop" that is "5" currently. + double result_number = jerry_get_number_value (eval_result); + printf("output: %lf\n", result_number); + + jerry_cleanup (); + + return result_number != 5.0; } ``` **See also** +- [jerry_property_descriptor_t](#jerry_property_descriptor_t) - [jerry_init_property_descriptor_fields](#jerry_init_property_descriptor_fields) - [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) - [jerry_free_property_descriptor_fields](#jerry_free_property_descriptor_fields) @@ -4684,6 +5120,7 @@ jerry_get_own_property_descriptor (const jerry_value_t obj_val, **See also** +- [jerry_property_descriptor_t](#jerry_property_descriptor_t) - [jerry_init_property_descriptor_fields](#jerry_init_property_descriptor_fields) - [jerry_define_own_property](#jerry_define_own_property) - [jerry_free_property_descriptor_fields](#jerry_free_property_descriptor_fields) @@ -4755,14 +5192,14 @@ jerry_call_function (const jerry_value_t func_obj_val, ```c { - jerry_value_t val; + jerry_value_t target_function; - ... // receiving val + ... // create or get "target_function" - if (jerry_value_is_function (val)) + if (jerry_value_is_function (target_function)) { jerry_value_t this_val = jerry_create_undefined (); - jerry_value_t ret_val = jerry_call_function (val, this_val, NULL, 0); + jerry_value_t ret_val = jerry_call_function (target_function, this_val, NULL, 0); if (!jerry_value_is_error (ret_val)) { @@ -4773,7 +5210,7 @@ jerry_call_function (const jerry_value_t func_obj_val, jerry_release_value (this_val); } - jerry_release_value (val); + jerry_release_value (target_function); } ``` @@ -5248,7 +5685,10 @@ best-practice example. **Summary** -Applies the given function to every property in the given object. +Applies the given function to every enumerable(!) property in the given object. + +The "iterator" `foreach_p` method should return `true` value to continue the iteration. +If the method returns `false` the iteration will end. **Prototype** @@ -5270,25 +5710,74 @@ jerry_foreach_object_property (jerry_value_t obj_val, **Example** + +[doctest]: # (name="02.API-REFERENCE-foreach-property.c") + ```c -bool +#include +#include "jerryscript.h" + +/* Example structure used as user data for the property iteration. */ +struct iteration_data { + int string_property_count; +}; + +/* + * Example foreach function to print out property names. + */ +static bool foreach_function (const jerry_value_t prop_name, const jerry_value_t prop_value, void *user_data_p) { + if (jerry_value_is_string (prop_name)) { + jerry_char_t string_buffer[128]; + jerry_size_t copied_bytes = jerry_substring_to_char_buffer (prop_name, + 0, + 127, + string_buffer, + 127); + string_buffer[copied_bytes] = '\0'; - ... // implementation of the foreach function + printf ("Property: %s\n", string_buffer); + struct iteration_data *data = (struct iteration_data *) user_data_p; + data->string_property_count++; + } + + /* return true to continue iteration */ + return true; } +int +main (void) { - jerry_value_t object; - ... // receive or construct object + jerry_init (JERRY_INIT_EMPTY); - double data = 3.14; // example data + /* Construct an example object with a single property. */ + jerry_value_t object = jerry_create_object (); + { + jerry_value_t test_property = jerry_create_string ((const jerry_char_t *) "DemoProp"); + jerry_value_t test_value = jerry_create_number (3); + /* By default all properties added to an object are enumerable. */ + jerry_value_t set_result = jerry_set_property (object, test_property, test_value); + /* The `set_result` should be checked if it is an error or not. */ + jerry_release_value (set_result); + jerry_release_value (test_value); + jerry_release_value (test_property); + } - jerry_foreach_object_property (object, foreach_function, &data); + /* Iterate on the object's properties with the given user data. */ + struct iteration_data user_data = { 0 }; + bool iteration_result = jerry_foreach_object_property (object, foreach_function, &user_data); + /* Check and process the `iteration_result` if required. */ + + jerry_release_value (object); + + jerry_cleanup (); + + return user_data.string_property_count == 0; } ``` @@ -5300,7 +5789,10 @@ foreach_function (const jerry_value_t prop_name, **Summary** -Iterate over objects. +Iterate over all objects available in the engine. + +The "iterator" `foreach_p` method should return `true` value to continue the search. +If the method returns `false` the search for the object is finished. *Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value). @@ -5320,7 +5812,13 @@ jerry_objects_foreach (jerry_objects_foreach_t foreach_p, **Example** +[doctest]: # (name="02.API-REFERENCE-objects-foreach.c") + ```c +#include +#include "jerryscript.h" + +/* Create a custom structure to guide the search and store the result. */ typedef struct { jerry_value_t property_name; @@ -5331,31 +5829,74 @@ typedef struct * Find the first object with the given property. */ static bool -find_my_object(const jerry_value_t candidate, - void *user_data_p) +find_my_object (const jerry_value_t candidate, + void *user_data_p) { find_my_object_info_t *info_p = (find_my_object_info_t *) user_data_p; - jerry_value_t has_property = jerry_object_has_property (candidate, info_p->property_name); - bool keep_searching = (jerry_value_is_error (has_property) || !jerry_get_boolean_value ()); - if (!keep_searching) + + /* Check if the given object has the required property. */ + jerry_value_t has_property = jerry_has_property (candidate, info_p->property_name); + bool object_found = jerry_get_boolean_value (has_property); + + if (object_found) { /* We found it, so we acquire the value and record it. */ info_p->result = jerry_acquire_value (candidate); } + jerry_release_value (has_property); - return keep_searching; + + /* If the object was not found continue the search. */ + return !object_found; } /* find_my_object */ +int +main (void) { + int return_value = 0; + + /* Initialize JerryScript engine. */ + jerry_init (JERRY_INIT_EMPTY); + + /* Create the test object. */ + { + jerry_value_t test_object = jerry_create_object (); + + { + jerry_value_t test_property = jerry_create_string ((const jerry_char_t *) "DemoProp"); + jerry_value_t test_value = jerry_create_number (3); + jerry_value_t set_result = jerry_set_property (test_object, test_property, test_value); + /* The `set_result` should be checked if it is an error or not. */ + jerry_release_value (set_result); + jerry_release_value (test_value); + jerry_release_value (test_property); + } + + { + /* Register the test object into the global object. */ + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t demo_property = jerry_create_string ((const jerry_char_t *) "DemoObject"); + jerry_value_t set_result = jerry_set_property (global_object, demo_property, test_object); + /* The `set_result` should be checked if it is an error or not. */ + jerry_release_value (set_result); + jerry_release_value (demo_property); + jerry_release_value (global_object); + } + + jerry_release_value (test_object); + } + + /* Look up the test object base on a property name. */ find_my_object_info_t search_info = { - .property_name = jerry_create_string ("desired_property") + .property_name = jerry_create_string ((const jerry_char_t *) "DemoProp") }; - if (jerry_object_foreach (find_my_object, &search_info)) + if (jerry_objects_foreach (find_my_object, &search_info)) { /* The search was successful. Do something useful with search_info.result. */ - ... + // ... + printf ("Object found\n"); /* Release the found object after we're done using it. */ jerry_release_value (search_info.result); @@ -5363,11 +5904,19 @@ find_my_object(const jerry_value_t candidate, else { /* The search has failed. */ + printf ("Object not found\n"); + + return_value = 1; } - jerry_release_value (search_info.desired_property); + jerry_release_value (search_info.property_name); + + /* Engine cleanup */ + jerry_cleanup (); + return return_value; } ``` + **See also** - [jerry_objects_foreach_t](#jerry_objects_foreach_t) @@ -5376,7 +5925,10 @@ find_my_object(const jerry_value_t candidate, **Summary** -Iterate over objects matching a certain native data type. +Iterate over all objects in the engine matching a certain native data type. + +The "iterator" `foreach_p` method should return `true` value to continue the search. +If the method returns `false` the search for the object is finished. *Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value). @@ -5390,13 +5942,20 @@ jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *native_i ``` - `native_info_p` - native pointer's type information. +- `foreach_p` - function that will be invoked for each object. - return value - `true`, if the search function terminated the traversal by returning `false` - `false`, if the end of the list of objects was reached **Example** +[doctest]: # (name="02.API-REFERENCE-objects-foreach-nativeptr.c") + ```c +#include +#include +#include "jerryscript.h" + typedef struct { int foo; @@ -5406,68 +5965,105 @@ typedef struct typedef struct { jerry_value_t found_object; - void *match_data_p; + native_obj_t *found_native_data_p; + + int match_foo_value; } find_object_data_t; static void native_freecb (void *native_p) { - ... // free the native pointer + /* `native_p` was allocated via malloc. */ + free (native_p); } /* native_freecb */ -// NOTE: The address (!) of type_info acts as a way to uniquely "identify" the -// C type `native_obj_t *`. +/* + * NOTE: The address (!) of type_info acts as a way to uniquely "identify" the + * C type `native_obj_t *`. + */ static const jerry_object_native_info_t native_obj_type_info = { .free_cb = native_freecb }; -// Function creating JS object that is "backed" by a native_obj_t *: +/* + * Function creating JS object that is "backed" by a `native_obj_t`. + */ +static void +add_object_with_nativeptr (int foo_value) { - ... - // construct object and native_set value: - jerry_value_t object = ...; + jerry_value_t test_object = jerry_create_object (); native_obj_t *native_obj_p = malloc (sizeof (*native_obj_p)); - jerry_set_object_native_pointer (object, native_obj_p, &native_obj_type_info); + native_obj_p->foo = foo_value; + native_obj_p->bar = true; - ... -} + jerry_set_object_native_pointer (test_object, native_obj_p, &native_obj_type_info); -// Native method that retrieves the JavaScript object by way of its native data: -static bool find_object (const jerry_value_t candidate, void *data_p, void *user_data_p) + /* Register the test object into the global object. */ + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t demo_property = jerry_create_string ((const jerry_char_t *) "DemoObject"); + jerry_value_t set_result = jerry_set_property (global_object, demo_property, test_object); + /* The `set_result` should be checked if it is an error or not. */ + jerry_release_value (set_result); + jerry_release_value (demo_property); + jerry_release_value (global_object); + + jerry_release_value (test_object); +} /* create_object_with_nativeptr */ + +/* + * Example native method that searches for a JavaScript object + * with a `native_obj_type_info` has the correct value. + */ +static bool +find_object (const jerry_value_t candidate, void *data_p, void *user_data_p) { find_object_data_t *find_data_p = (find_object_data_t *) user_data_p; + native_obj_t *native_obj_p = (native_obj_t *) data_p; - if (find_data_p->match_data_p == data_p) + if (find_data_p->match_foo_value == native_obj_p->foo) { - // If the object was found, acquire it and store it in the user data. + /* If the object was found, acquire it and store it in the user data. */ find_data_p->found_object = jerry_acquire_value (candidate); + find_data_p->found_native_data_p = native_obj_p; - // Stop traversing over the objects. + /* Stop traversing over the objects. */ return false; } - // Indicate that the object was not found, so traversal must continue. + /* Indicate that the object was not found, so traversal must continue. */ return true; } /* find_object */ -... + +int +main (void) { + jerry_init (JERRY_INIT_EMPTY); + + add_object_with_nativeptr (4); + add_object_with_nativeptr (3); + add_object_with_nativeptr (2); + find_object_data_t find_data = { - .match_data = native_obj + .match_foo_value = 3, }; if (jerry_objects_foreach_by_native_info (&native_obj_type_info, find_object, &find_data)) { - // The object was found and is now stored in find_data.found_object. After using it, it must be released. - ... + /* The object was found and is now stored in `find_data.found_object`. After using it, it must be released. */ + printf ("Object found, native foo value: %d\n", find_data.found_native_data_p->foo); + jerry_release_value (find_data.found_object); } else { - // The object was not found. + printf ("Object not found\n"); } - ... + + jerry_cleanup (); + + return 0; } ``` @@ -5486,7 +6082,10 @@ static bool find_object (const jerry_value_t candidate, void *data_p, void *user **Summary** -Validate UTF-8 string. +Check if a given character buffer is a valid UTF-8 string. + +**Notes**: Calling this method is safe in any time. It can be called +even before engine initialization. **Prototype** @@ -5496,8 +6095,11 @@ jerry_is_valid_utf8_string (const jerry_char_t *utf8_buf_p, /**< UTF-8 string */ jerry_size_t buf_size) /**< string size */ ``` -- `utf8_buf_p` - UTF-8 input string -- `buf_size` - input string size +- `utf8_buf_p` - UTF-8 input string buffer. +- `buf_size` - input string buffer size in bytes. +- return value + - true, if the provided string was a valid UTF-8 string. + - false, if the string is not valid as an UTF-8 string. **Example** @@ -5516,6 +6118,8 @@ main (void) { jerry_run_simple (script, script_size, JERRY_INIT_EMPTY); } + + return 0; } ``` @@ -5533,7 +6137,10 @@ main (void) **Summary** -Validate CESU-8 string. +Check if a given character buffer is a valid CESU-8 string. + +**Notes**: Calling this method is safe in any time. It can be called +even before engine initialization. **Prototype** @@ -5543,8 +6150,11 @@ jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string jerry_size_t buf_size) /**< string size */ ``` -- `cesu8_buf_p` - CESU-8 input string -- `buf_size` - input string size +- `cesu8_buf_p` - CESU-8 input string buffer. +- `buf_size` - input string buffer size in bytes. +- return value + - true, if the provided string was a valid CESU-8 string. + - false, if the string is not valid as a CESU-8 string. **Example** @@ -5572,6 +6182,7 @@ main (void) } jerry_cleanup (); + return 0; } ``` @@ -5759,8 +6370,8 @@ jerry_generate_snapshot (const jerry_char_t *resource_name_p, - `source_p` - script source, it must be a valid utf8 string. - `source_size` - script source size, in bytes. - `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags. -- `buffer_p` - buffer (aligned to 4 bytes) to save snapshot to. -- `buffer_size` - the buffer's size. +- `buffer_p` - output buffer (aligned to 4 bytes) to save snapshot to. +- `buffer_size` - the output buffer's size in bytes. - return value - the size of the generated snapshot in bytes as number value, if it was generated succesfully (i.e. there are no syntax errors in source code, buffer size is sufficient, and snapshot support is enabled in @@ -5795,6 +6406,7 @@ main (void) jerry_release_value (generate_result); jerry_cleanup (); + return 0; } ``` @@ -5842,7 +6454,7 @@ jerry_generate_function_snapshot (const jerry_char_t *resource_name_p, - `args_size` - function argument size, in bytes. - `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags. - `buffer_p` - buffer (aligned to 4 bytes) to save snapshot to. -- `buffer_size` - the buffer's size. +- `buffer_size` - the buffer's size in bytes. - return value - the size of the generated snapshot in bytes as number value, if it was generated succesfully (i.e. there are no syntax errors in source code, buffer size is sufficient, and snapshot support is enabled in @@ -5880,6 +6492,7 @@ main (void) jerry_release_value (generate_result); jerry_cleanup (); + return 0; } ``` @@ -5956,6 +6569,7 @@ main (void) jerry_release_value (res); jerry_cleanup (); + return 0; } ``` @@ -5987,13 +6601,13 @@ jerry_load_function_snapshot (const uint32_t *snapshot_p, uint32_t exec_snapshot_opts); ``` -- `snapshot_p` - pointer to snapshot -- `snapshot_size` - size of snapshot in bytes -- `func_index` - index of function to load +- `snapshot_p` - pointer to snapshot. +- `snapshot_size` - size of snapshot in bytes. +- `func_index` - index of function to load from the snapshot. - `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags. - return value - - function object built from the snapshot - - thrown error, otherwise + - function object built from the snapshot. + - thrown error, otherwise. **Example** @@ -6130,6 +6744,7 @@ main (void) } jerry_cleanup (); + return 0; } ``` @@ -6233,8 +6848,12 @@ The array length is zero if the backtrace is not available. This function is typically called from native callbacks. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. +- This feature depends on build option (`JERRY_LINE_INFO`) and can be checked + in runtime with the `JERRY_FEATURE_LINE_INFO` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). **Prototype** @@ -6247,6 +6866,94 @@ jerry_get_backtrace (uint32_t max_depth); - return value - a newly constructed JS array +**Example** + +[doctest]: # (name="02.API-REFERENCE-jsbacktrace.c") + +```c +#include +#include +#include "jerryscript.h" + +static jerry_value_t +backtrace_handler (const jerry_value_t function_obj, + const jerry_value_t this_val, + const jerry_value_t args_p[], + const jerry_length_t args_count) +{ + if (!jerry_is_feature_enabled (JERRY_FEATURE_LINE_INFO)) + { + printf ("Line info disabled, no backtrace will be printed\n"); + } + + /* If the line info feature is disabled an empty array will be returned. */ + jerry_value_t backtrace_array = jerry_get_backtrace (5); + uint32_t array_length = jerry_get_array_length (backtrace_array); + + for (uint32_t idx = 0; idx < array_length; idx++) + { + jerry_value_t property = jerry_get_property_by_index (backtrace_array, idx); + + jerry_char_t string_buffer[64]; + jerry_size_t copied_bytes = jerry_substring_to_char_buffer (property, + 0, + 63, + string_buffer, + 63); + string_buffer[copied_bytes] = '\0'; + printf(" %d: %s\n", idx, string_buffer); + + jerry_release_value (property); + } + + jerry_release_value (backtrace_array); + + return jerry_create_undefined (); +} /* backtrace_handler */ + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t global = jerry_get_global_object (); + + /* Register the "dump_backtrace" method. */ + { + jerry_value_t func = jerry_create_external_function (backtrace_handler); + jerry_value_t name = jerry_create_string ((const jerry_char_t *) "backtrace"); + jerry_value_t result = jerry_set_property (global, name, func); + jerry_release_value (result); + jerry_release_value (name); + jerry_release_value (func); + } + + jerry_release_value (global); + + const char *source = ("function f() { g (); }\n" + "function g() { h (); }\n" + "function h() { backtrace (); }\n" + "f ();\n"); + const char *resource = "demo_memoryjs"; + + jerry_value_t program = jerry_parse ((const jerry_char_t *) resource, + strlen (resource), + (const jerry_char_t *) source, + strlen (source), + JERRY_PARSE_NO_OPTS); + if (!jerry_value_is_error (program)) + { + jerry_value_t run_result = jerry_run (program); + jerry_release_value (run_result); + } + + jerry_release_value (program); + jerry_cleanup (); + + return 0; +} +``` + **See also** - [jerry_create_external_function](#jerry_create_external_function)