Update the webpage (#3624)

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
2020-03-19 17:25:34 +01:00
parent 5b86cf113e
commit 46809447ae
1 changed files with 407 additions and 12 deletions
@@ -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
  - "<anonymous>", 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 <stdio.h>
+#include <string.h>
+#include <jerryscript.h>
+
+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 <stdio.h>
+#include <string.h>
+#include <jerryscript.h>
+
+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