diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index b46483262..bd753e0c7 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -80,8 +80,26 @@ Possible compile time enabled feature types: - JERRY_FEATURE_LOGGING - logging - JERRY_FEATURE_SYMBOL - symbol support - JERRY_FEATURE_DATAVIEW - DataView support + - JERRY_FEATURE_PROXY - Proxy support + - JERRY_FEATURE_MAP - Map support + - JERRY_FEATURE_SET - Set support + - JERRY_FEATURE_WEAKMAP - WeakMap support + - JERRY_FEATURE_WEAKSET - WeakSet support *New in version 2.0*. +*Changed in version 2.3* : Added `JERRY_FEATURE_WEAKMAP`, `JERRY_FEATURE_WEAKSET` values. + +## jerry_container_type_t + +Container object types: + + - JERRY_CONTAINER_TYPE_INVALID - Invalid container + - JERRY_CONTAINER_TYPE_MAP - Map type + - JERRY_CONTAINER_TYPE_SET - Set type + - JERRY_CONTAINER_TYPE_WEAKMAP - WeakMap type + - JERRY_CONTAINER_TYPE_WEAKSET - WeakSet type + + *New in version 2.3*. ## jerry_regexp_flags_t @@ -457,7 +475,7 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_ Native free callback of an object. It is used in `jerry_object_native_info_t` and for external Array buffers. *Note*: - - This callback method **must not** call any JerryScript API methods. + - Referred values by this method must have at least 1 reference. (Correct API usage satisfies this condition) **Prototype** @@ -466,6 +484,7 @@ typedef void (*jerry_object_native_free_callback_t) (void *native_p); ``` *New in version 2.0*: Renamed from `jerry_object_free_callback_t`. +*Changed in version 2.2*: API calls are once again allowed. (See note) **See also** @@ -621,7 +640,7 @@ Possible values: - JERRY_PROMISE_STATE_FULFILLED - Promise is in "Fulfilled" state. - JERRY_PROMISE_STATE_REJECTED - Promise is in "Rejected" state. -*New in version [NEXT VERSION]*. +*New in version 2.2*. **See also** @@ -1874,6 +1893,55 @@ jerry_value_is_promise (const jerry_value_t value) - [jerry_create_promise](#jerry_create_promise) +## jerry_value_is_proxy + +**Summary** + +Returns whether the given `jerry_value_t` is a proxy value. + +*Notes*: +- This API depends on a build option (`JERRY_ES2015_BUILTIN_PROXY`) and can be checked + in runtime with the `JERRY_FEATURE_PROXY` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. + + +**Prototype** + +```c +bool +jerry_value_is_proxy (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a proxy object + - false, otherwise + +**Example** + +*New in version [next_version]*. + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_proxy (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) +- [jerry_create_proxy](#jerry_create_proxy) + + ## jerry_value_is_string **Summary** @@ -2031,6 +2099,64 @@ main (void) - [jerry_create_typedarray](#jerry_create_typedarray) +## jerry_get_container_type + +**Summary** + +Checks whether the given `jerry_value_t` is the given `jerry_container_type_t` type container object. + +*Notes* +- This API function depends on a build option (`JERRY_ES2015_BUILTIN_CONTAINER`) and can be checked + runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` + feature enum values. + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. + +*New in version 2.3*. + +**Prototype** + +```c +jerry_container_type_t +jerry_get_container_type (const jerry_value_t value) +``` + +- `value` - Container object +- return value + - The corresponding enum value of `jerry_container_type_t`, or `JERRY_CONTAINER_TYPE_INVALID` if the container + was not a valid container object. +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t value = jerry_create_container (JERRY_CONTAINER_TYPE_MAP, NULL, 0); + + if (jerry_get_container_type (value) == JERRY_CONTAINER_TYPE_MAP) + { + /* "value" is a map. */ + } + + jerry_release_value (value); + + jerry_cleanup (); + + return 0; +} +``` + +**See also** + +- [jerry_create_container](#jerry_create_container) +- [jerry_container_type_t](#jerry_container_type_t) + + ## jerry_value_is_undefined **Summary** @@ -3291,7 +3417,7 @@ jerry_get_promise_result (const jerry_value_t promise); - A TypeError is returned if the input argument was not a Promise object or the Promise support was not built into the library. -*New in version [NEXT VERSION]*. +*New in version 2.2*. **Example** @@ -3357,7 +3483,7 @@ jerry_get_promise_state (const jerry_value_t promise); - `JERRY_PROMISE_STATE_NONE` is returned if the input argument was not a promise object or the Promise support was not built into the library. -*New in version [NEXT VERSION]*. +*New in version 2.2*. **Example** @@ -3717,7 +3843,7 @@ jerry_create_arraybuffer_external (const jerry_length_t size - `free_cb` - the callback function called when the object is released - return value - the new ArrayBuffer as a `jerry_value_t` - - if the `size` is zero or `buffer_p` is a null pointer will return RangeError + - if the `size` is zero or `buffer_p` is a null pointer this will return an empty ArrayBuffer. *New in version 2.0*. @@ -4221,6 +4347,65 @@ jerry_create_promise (void) - [jerry_release_value](#jerry_release_value) +## jerry_create_proxy + +**Summary** + +Create a new Proxy object with the given target and handler. + +*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. + +**Prototype** + +```c +jerry_value_t +jerry_create_proxy (const jerry_value_t target, + const jerry_value_t handler) +``` + +- `target` - proxy target +- `handler` - proxy handler +- return thrown error - if the Proxy construction fails + value of the newly created proxy object - otherwise + +**Example** + +*New in version [next_version]*. + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t target = jerry_create_object (); + jerry_value_t handler = jerry_create_object (); + jerry_value_t proxy = jerry_create_proxy (target, handler); + + jerry_release_value (target); + jerry_release_value (handler); + + // usage of the proxy + + jerry_release_value (proxy); + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_value_is_proxy](#jerry_value_is_proxy) +- [jerry_release_value](#jerry_release_value) + + ## jerry_create_string **Summary** @@ -4702,6 +4887,70 @@ jerry_create_typedarray_for_arraybuffer_sz (jerry_typedarray_type_t type_name, - [jerry_release_value](#jerry_release_value) +## jerry_create_container + +**Summary** + +Create a jerry_value_t representing a given type container object. + +*Notes*: +- This method is expected to work the same way as the JavaScript Map constructor. +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- This API depends on a build option (`JERRY_ES2015_BUILTIN_CONTAINER`) and can be checked + in runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` + feature enum values. + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The ES2015-subset profile enables this by default. + +*New in version 2.3*. + +**Prototype** + +```c +jerry_value_t +jerry_create_container (jerry_container_type_t container_type, + const jerry_value_t *arguments_list_p, + jerry_length_t arguments_list_len); +``` + +- `container_type` - Type of the container to be created, see `jerry_container_type_t`. +- `arguments_list_p` - The arguments passed to the container constructor to be inserted to the container. +- `arguments_list_len` - The length of the above arguments. +- return value - the new container object as a `jerry_value_t` + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + jerry_char_t src[] = "[1,2,3,4].entries()"; + jerry_value_t iterable = jerry_eval (src, sizeof (src) - 1, JERRY_PARSE_NO_OPTS); + + jerry_value_t map = jerry_create_container (JERRY_CONTAINER_TYPE_MAP, &iterable, 1); + jerry_release_value (iterable); + + // use the Map + + jerry_release_value (map); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_container_type_t](#jerry_container_type_t) +- [jerry_get_container_type](#jerry_get_container_type) + + ## jerry_create_undefined **Summary** @@ -4755,9 +5004,9 @@ jerry_has_property (const jerry_value_t obj_val, - `obj_val` - object value - `prop_name_val` - property name -- return value - JavaScript boolean value that evaluates to - - true, if the property exists - - false, otherwise +- return value - JavaScript value that evaluates to + - raised error - if the operation fail + - true/false API value - depend on whether the property exists *Changed in version 2.0*: The return value type is now a JavaScript value and not a primitive boolean value. @@ -4814,9 +5063,9 @@ jerry_has_own_property (const jerry_value_t obj_val, - `obj_val` - object value - `prop_name_val` - property name -- return value - JavaScript boolean value that evaluates to - - true, if the property exists - - false, otherwise +- return value - JavaScript value that evaluates to + - raised error - if the operation fails + - true/false API value - depend on whether the property exists *Changed in version 2.0*: The return value type is now a JavaScript value and not a primitive boolean value. @@ -4880,6 +5129,8 @@ jerry_has_internal_property (const jerry_value_t obj_val, - true, if the property exists - false, otherwise +*New in version 2.2*. + **Example** [doctest]: # () @@ -5023,6 +5274,8 @@ jerry_delete_internal_property (const jerry_value_t obj_val, - true, if property was deleted successfully - false, otherwise +*New in version 2.2*. + **Example** ```c @@ -5183,6 +5436,8 @@ jerry_get_internal_property (const jerry_value_t obj_val, - undefined value, if the, if the internal does not property exists - thrown error, otherwise +*New in version 2.2*. + **Example** [doctest]: # () @@ -5360,6 +5615,8 @@ jerry_set_internal_property (const jerry_value_t obj_val, - true, if success - thrown error, otherwise +*New in version 2.2*. + **Example** [doctest]: # () @@ -6155,7 +6412,7 @@ You can get them by calling [jerry_get_object_native_pointer](#jerry_get_object_ 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 **must not** invoke API functions. + - The free callback can invoke API functions. *Note*: If possible do not store API values in native pointers, rather check [jerry_set_internal_property](#jerry_set_internal_property). @@ -7593,6 +7850,8 @@ jerry_get_resource_name (jerry_value_t value); - resource name of the function object, if the given value is a function object - "", otherwise +*New in version 2.2*. + **Example** [doctest]: # (name="02.API-REFERENCE-jsresourcename.c") @@ -7664,6 +7923,138 @@ main (void) - [jerry_create_external_function](#jerry_create_external_function) +## jerry_get_new_target + +**Summary** + +Returns the current "new.target" JavaScript function at the call site. + +If used outside of a native C function it will return "undefined" value. + +*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_ES2015`) and can be checked + in runtime with the `JERRY_FEATURE_SYMBOL` feature enum value (as symbols are enabled in case of ES2015), + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- If the ES2015 mode is not enabled this method will always return the "undefined" value. + +**Prototype** + +```c +jerry_value_t +jerry_get_new_target (void); +``` +- return + - "undefined" - if at the call site it was not a constructor call. + - function object - if the current call site is in a constructor call. + +*New in version 2.2*. + +**Example 1** + +[doctest]: # (name="02.API-REFERENCE-jsnewtarget-01.c") + +```c +#include +#include +#include + +static jerry_value_t +demo_handler (const jerry_value_t func_obj_val, + const jerry_value_t this_val, + const jerry_value_t args_p[], + const jerry_length_t args_cnt) +{ + jerry_value_t new_target = jerry_get_new_target (); + + /* new_target is the "demo" JS function object */ + if (jerry_value_get_type (new_target) == JERRY_TYPE_FUNCTION) + { + printf ("This is a construct call\r\n"); + } + + jerry_release_value (new_target); + + return jerry_create_undefined (); +} + +int +main (int argc, char** argv) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t function_val = jerry_create_external_function (demo_handler); + + jerry_value_t ret_val = jerry_construct_object (function_val, NULL, 0); + + jerry_release_value (ret_val); + jerry_release_value (function_val); + + jerry_cleanup (); + return 0; +} +``` + +**Example 2** + +[doctest]: # (name="02.API-REFERENCE-jsnewtarget-02.c") + +```c +#include +#include +#include + +static jerry_value_t +demo_handler (const jerry_value_t func_obj_val, + const jerry_value_t this_val, + const jerry_value_t args_p[], + const jerry_length_t args_cnt) +{ + jerry_value_t new_target = jerry_get_new_target (); + + /* new_target is a JS function object */ + if (jerry_value_get_type (new_target) == JERRY_TYPE_FUNCTION) + { + printf ("This is a construct call\r\n"); + } + + jerry_release_value (new_target); + + return jerry_create_undefined (); +} + +int +main (int argc, char** argv) +{ + jerry_init (JERRY_INIT_EMPTY); + + /* register C method */ + jerry_value_t global_obj_val = jerry_get_global_object (); + jerry_value_t function_val = jerry_create_external_function (demo_handler); + jerry_value_t function_name_val = jerry_create_string ((const jerry_char_t *) "demo"); + jerry_value_t result_val = jerry_set_property (global_obj_val, function_name_val, function_val); + jerry_release_value (result_val); + jerry_release_value (function_name_val); + jerry_release_value (function_val); + jerry_release_value (global_obj_val); + + /* Invoke C method via JS */ + const char *src = "new demo ()"; + jerry_value_t ret_val = jerry_eval ((const jerry_char_t *) src, + strlen (src), + JERRY_PARSE_NO_OPTS); + + jerry_release_value (ret_val); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_construct_object](#jerry_construct_object) # ArrayBuffer and TypedArray functions @@ -7911,6 +8302,8 @@ jerry_is_arraybuffer_detachable (const jerry_value_t value); - boolean value if success - Error otherwise +*New in version 2.2*. + **Example** ```c @@ -7952,6 +8345,8 @@ jerry_detach_arraybuffer (const jerry_value_t value); - null value if success - Error otherwise +*New in version 2.2*. + **Example** ```c