From c742f27e2d0200076b2cb54cd7d6e4bef5d62c65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zsolt=20Borb=C3=A9ly?= Date: Thu, 1 Oct 2020 16:27:34 +0200 Subject: [PATCH] Update the webpage (#4253) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com --- 00.GETTING-STARTED.md | 6 - 01.CONFIGURATION.md | 2 +- 02.API-REFERENCE.md | 845 ++++++++++++++++++++++++++++++++++++++++- 08.CODING-STANDARDS.md | 6 + 4 files changed, 831 insertions(+), 28 deletions(-) diff --git a/00.GETTING-STARTED.md b/00.GETTING-STARTED.md index 2986eabab..57bf5e638 100644 --- a/00.GETTING-STARTED.md +++ b/00.GETTING-STARTED.md @@ -171,12 +171,6 @@ python tools/run-tests.py --unittests python tools/run-tests.py --jerry-tests ``` -**To run jerry-test-suite** - -```bash -python tools/run-tests.py --jerry-test-suite -``` - **To run signed-off check** ```bash diff --git a/01.CONFIGURATION.md b/01.CONFIGURATION.md index e9fe3e06d..dbd87a51a 100644 --- a/01.CONFIGURATION.md +++ b/01.CONFIGURATION.md @@ -162,7 +162,7 @@ This feature is disabled by default. ### LCache -This option enables the LCache, allowing faster access to object properties. The LCache usases a statically allocated hash-map, which increases memory consumption. +This option enables the LCache, allowing faster access to object properties. The LCache uses a statically allocated hash-map, which increases memory consumption. See [Internals](04.INTERNALS.md#lcache) for further details. This option is enabled by default. diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 94d3350ae..e7864dcb9 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -21,7 +21,7 @@ Enum that contains the following elements: - JERRY_INIT_MEM_STATS_SEPARATE - **deprecated**, dump memory statistics and reset peak values after parse - JERRY_INIT_DEBUGGER - **deprecated**, an unused placeholder now -*Changed in version 2.0*: JERRY_INIT_MEM_STATS_SEPARATE and JERRY_INIT_DEBUGGER are now deprecated and not used internally. +*Changed in version 2.0*: `JERRY_INIT_MEM_STATS_SEPARATE` and `JERRY_INIT_DEBUGGER` are now deprecated and not used internally. ## jerry_type_t @@ -40,6 +40,56 @@ Enum that contains JerryScript API value types: *New in version 2.0*. +## jerry_object_type_t + +Enum that contains JerryScript **object** value types: + + - JERRY_OBJECT_TYPE_NONE - Non-object type + - JERRY_OBJECT_TYPE_GENERIC - Generic JavaScript object without any internal property + - JERRY_OBJECT_TYPE_ARRAY - Array object + - JERRY_OBJECT_TYPE_PROXY - Proxy object + - JERRY_OBJECT_TYPE_FUNCTION - Function object (see [jerry_function_get_type](#jerry_function_get_type)) + - JERRY_OBJECT_TYPE_TYPEDARRAY - %TypedArray% object (see [jerry_get_typedarray_type](#jerry_get_typedarray_type)) + - JERRY_OBJECT_TYPE_ITERATOR - Iterator object (see [jerry_iterator_get_type](#jerry_get_typedarray_type)) + - JERRY_OBJECT_TYPE_CONTAINER - Container object (see [jerry_get_container_type](#jerry_get_container_type)) + + - JERRY_OBJECT_TYPE_ARGUMENTS - Arguments object + - JERRY_OBJECT_TYPE_BOOLEAN - Boolean object + - JERRY_OBJECT_TYPE_DATE - Date object + - JERRY_OBJECT_TYPE_NUMBER - Number object + - JERRY_OBJECT_TYPE_REGEXP - RegExp object + - JERRY_OBJECT_TYPE_STRING - String object + - JERRY_OBJECT_TYPE_SYMBOL - Symbol object + - JERRY_OBJECT_TYPE_GENERATOR - Generator object + - JERRY_OBJECT_TYPE_BIGINT - BigInt object + +*New in version [[NEXT_RELEASE]]*. + +## jerry_function_type_t + +Enum that contains JerryScript **function** value types: + + - JERRY_FUNCTION_TYPE_NONE - Non-function type + - JERRY_FUNCTION_TYPE_GENERIC - Generic JavaScript function + - JERRY_FUNCTION_TYPE_ACCESSOR - Accessor function + - JERRY_FUNCTION_TYPE_BOUND - Bound function + - JERRY_FUNCTION_TYPE_ARROW - Arrow fuction + - JERRY_FUNCTION_TYPE_GENERATOR - Generator function object + +*New in version [[NEXT_RELEASE]]*. + +## jerry_iterator_type_t + +Enum that contains JerryScript **iterator** value types: + + - JERRY_ITERATOR_TYPE_NONE - Non-iterator type + - JERRY_ITERATOR_TYPE_ARRAY - Array iterator + - JERRY_ITERATOR_TYPE_STRING - String iterator + - JERRY_ITERATOR_TYPE_MAP - Map iterator + - JERRY_ITERATOR_TYPE_SET - Set iterator + +*New in version [[NEXT_RELEASE]]*. + ## jerry_error_t Possible types of an error: @@ -87,6 +137,7 @@ Possible compile time enabled feature types: - 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 @@ -101,6 +152,25 @@ Container object types: *New in version 2.3*. +## jerry_well_known_symbol_t + +Well-known symbols: + + - JERRY_SYMBOL_HAS_INSTANCE - @@hasInstance well-known symbol + - JERRY_SYMBOL_IS_CONCAT_SPREADABLE - @@isConcatSpreadable well-known symbol + - JERRY_SYMBOL_ITERATOR - @@iterator well-known symbol + - JERRY_SYMBOL_ASYNC_ITERATOR - @@asyncIterator well-known symbol + - JERRY_SYMBOL_MATCH - @@match well-known symbol + - JERRY_SYMBOL_REPLACE - @@replace well-known symbol + - JERRY_SYMBOL_SEARCH - @@search well-known symbol + - JERRY_SYMBOL_SPECIES - @@species well-known symbol + - JERRY_SYMBOL_SPLIT - @@split well-known symbol + - JERRY_SYMBOL_TO_PRIMITIVE - @@toPrimitive well-known symbol + - JERRY_SYMBOL_TO_STRING_TAG - @@toStringTag well-known symbol + - JERRY_SYMBOL_UNSCOPABLES - @@unscopables well-known symbol + + *New in version [[NEXT_RELEASE]]*. + ## jerry_regexp_flags_t RegExp object optional flags: @@ -484,6 +554,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** @@ -660,6 +731,8 @@ Possible values: - JERRY_TYPEDARRAY_INT32 - represents the Int32Array TypedArray - JERRY_TYPEDARRAY_FLOAT32 - represents the Float32Array TypedArray - JERRY_TYPEDARRAY_FLOAT64 - represents the Float64Array TypedArray + - JERRY_TYPEDARRAY_BIGINT64 - represents the BigInt64Array TypedArray + - JERRY_TYPEDARRAY_BIGUINT64 - represents the BigUint64Array TypedArray - JERRY_TYPEDARRAY_INVALID - represents an invalid TypedArray API functions can return the `JERRY_TYPEDARRAY_INVALID` value if the @@ -667,6 +740,8 @@ TypedArray support is not in the engine. *New in version 2.0*. +*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_TYPEDARRAY_BIGINT64`, `JERRY_TYPEDARRAY_BIGUINT64` values. + **See also** - [jerry_get_typedarray_type](#jerry_get_typedarray_type) @@ -1727,6 +1802,44 @@ jerry_value_is_function (const jerry_value_t value) - [jerry_release_value](#jerry_release_value) +## jerry_value_is_async_function + +**Summary** + +Returns whether the given `jerry_value_t` is an async function. + +**Prototype** + +```c +bool +jerry_value_is_async_function (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is an async function + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_async_function (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) + ## jerry_value_is_number **Summary** @@ -2041,6 +2154,69 @@ main (void) - [jerry_release_value](#jerry_release_value) - [jerry_create_symbol](#jerry_create_symbol) + +## jerry_value_is_bigint + +**Summary** + +Returns whether the given `jerry_value_t` is a bigint value. + +*Notes*: +- 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_is_feature_enabled](#jerry_is_feature_enabled). +- The es.next profile enables this by default. + +**Prototype** + +```c +bool +jerry_value_is_bigint (const jerry_value_t value) +``` + +- `value` - API value +- return value + - true, if the given `jerry_value_t` is a BigInt + - false, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "12345678"); + jerry_value_t bigint_value = jerry_value_to_bigint (string_value); + + jerry_release_value (string_value); + + if (jerry_value_is_bigint (bigint_value)) + { + // usage of bigint_value + } + + jerry_release_value (bigint_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) +- [jerry_create_bigint](#jerry_create_bigint) +- [jerry_value_to_bigint](#jerry_value_to_bigint) + + ## jerry_value_is_typedarray **Summary** @@ -2240,6 +2416,142 @@ jerry_value_get_type (const jerry_value_t value); - [jerry_type_t](#jerry_type_t) +## jerry_object_get_type + +**Summary** + +Returns the **object** type +for a given value as a [jerry_object_type_t](#jerry_object_type_t) enum value. + +Note: For non-object parameters `JERRY_OBJECT_TYPE_NONE` is returned. +Note: the returned type can be checked for more detailed type information in the following cases: + - `JERRY_OBJECT_TYPE_CONTAINER`, *see also:* [jerry_container_get_type](#jerry_container_get_type) + - `JERRY_OBJECT_TYPE_FUNCTION`, *see also:* [jerry_function_get_type](#jerry_function_get_type) + - `JERRY_OBJECT_TYPE_ITERATOR`, *see also:* [jerry_iterator_get_type](#jerry_iterator_get_type) + - `JERRY_OBJECT_TYPE_TYPEDARRAY`, *see also:* [jerry_get_typedarray_type](#jerry_get_typedarray_type) + +**Prototype** + +```c +jerry_object_type_t +jerry_object_get_type (const jerry_value_t value); +``` + +- `value` - JavaScript value to check. +- return value + - One of the [jerry_object_type_t](#jerry_object_type_t) value. + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +```c +{ + jerry_value_t object = jerry_create_object (); + + jerry_object_type_t object_type_info = jerry_object_get_type (object); + + if (type_info == JERRY_OBJECT_TYPE_GENERIC) + { + /* ... */ + } + + jerry_release_value (object); +} +``` + +**See also** + +- [jerry_object_type_t](#jerry_object_type_t) + +## jerry_function_get_type + +**Summary** + +Returns the **function** type +for a given value as a [jerry_function_type_t](#jerry_function_type_t) enum value. + +**Prototype** + +```c +jerry_function_type_t +jerry_function_get_type (const jerry_value_t value); +``` + +- `value` - JavaScript value to check. +- return value + - One of the [jerry_function_type_t](#jerry_function_type_t) value. + +Note: For non-function parameters `JERRY_FUNCTION_TYPE_NONE` is returned. + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +```c +{ + const jerry_char_t script[] = "function f() {}; f"; + jerry_value_t function_object = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); + + jerry_function_type_t function_type_info = jerry_function_get_type (function_object); + + if (type_info == JERRY_FUNCTION_TYPE_GENERIC) + { + /* ... */ + } + + jerry_release_value (function_object); +} +``` + +**See also** + +- [jerry_function_type_t](#jerry_function_type_t) + +## jerry_iterator_get_type + +**Summary** + +Returns the **iterator** type +for a given value as a [jerry_iterator_type_t](#jerry_iterator_type_t) enum value. + +**Prototype** + +```c +jerry_iterator_type_t +jerry_iterator_get_type (const jerry_value_t value); +``` + +- `value` - JavaScript value to check. +- return value + - One of the [jerry_iterator_type_t](#jerry_iterator_type_t) value. + +Note: For non-iterator parameters `JERRY_ITERATOR_TYPE_NONE` is returned. + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +```c +{ + const jerry_char_t script[] = "[1, 2, 3].values()"; + jerry_value_t iterator = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); + + jerry_iterator_type_t iterator_type_info = jerry_iterator_get_type (iterator); + + if (type_info == JERRY_ITERATOR_TYPE_ARRAY) + { + /* ... */ + } + + jerry_release_value (iterator); +} +``` + +**See also** + +- [jerry_iterator_type_t](#jerry_iterator_type_t) + ## jerry_is_feature_enabled **Summary** @@ -3384,6 +3696,50 @@ jerry_value_to_string (const jerry_value_t value); - [jerry_value_to_primitive](#jerry_value_to_primitive) +## jerry_value_to_bigint + +**Summary** + +Call the BigInt constructor ecma builtin operation on the api value. + +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_value_to_bigint (const jerry_value_t value); +``` + +- `value` - api value +- return value + - converted BigInt value, if success + - thrown error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t bigint_value = jerry_value_to_bigint (value); + + jerry_release_value (bigint_value); + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) +- [jerry_value_is_bigint](#jerry_value_is_bigint) +- [jerry_get_bigint_digits](#jerry_get_bigint_digits) + + # Functions for promise objects These APIs all depend on the es.next profile (or on some build options). @@ -3594,6 +3950,128 @@ jerry_resolve_or_reject_promise (jerry_value_t promise, These APIs all depend on the es.next profile (or on build options). +## jerry_get_well_known_symbol + +**Summary** + +Get the well-known symbol corresponding to the given [well-known symbol id](#jerry_well_known_symbol_t). + +*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_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 es.next profile enables this by default. +- If the symbol support is not enabled an undefined will be returned. + +**Prototype** + +```c +jerry_value_t +jerry_get_well_known_symbol (jerry_well_known_symbol_t symbol); +``` + +- `symbol` - [jerry_well_known_symbol_t](#jerry_well_known_symbol_t) enum value +- return value + - undefined value - if invalid well-known symbol was requested + - well-known symbol value, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t array_value = jerry_create_array (5); + jerry_value_t symbol_iterator = jerry_get_well_known_symbol (JERRY_SYMBOL_ITERATOR); + jerry_value_t array_iterator = jerry_get_property (array_value, symbol_iterator); + + // usage of array_iterator + + jerry_release_value (array_iterator); + jerry_release_value (symbol_iterator); + jerry_release_value (array_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_well_known_symbol_t](#jerry_well_known_symbol_t) + +## jerry_get_symbol_description + +**Summary** + +Returns with the `[[Description]]` internal property of a symbol value. + +*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_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 es.next profile enables this by default. +- If the symbol support is not enabled an error will be returned. + +**Prototype** + +```c +jerry_value_t +jerry_get_symbol_description (const jerry_value_t value); +``` + +- `value` - symbol value +- return value + - string or undefined value containing the symbol's description - if success + - thrown error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "foo"); + jerry_value_t symbol_value = jerry_create_symbol (string_value); + + jerry_release_value (string_value); + + jerry_value_t symbol_description = jerry_get_symbol_description (symbol_value); + + // usage of symbol_desc_string + + jerry_release_value (symbol_description); + jerry_release_value (symbol_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_get_symbol_descriptive_string](#jerry_get_symbol_descriptive_string) + ## jerry_get_symbol_descriptive_string **Summary** @@ -3653,6 +4131,137 @@ main (void) } ``` +**See also** + +- [jerry_get_symbol_description](#jerry_get_symbol_description) + +# Functions for BigInts + +These APIs all depend on build option (`JERRY_BUILTIN_BIGINT`). + +## jerry_get_bigint_size_in_digits + +**Summary** + +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 retreived by `[jerry_get_bigint_digits](#jerry_get_bigint_digits)`. + +*Notes*: +- 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_is_feature_enabled](#jerry_is_feature_enabled). +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. + +**Prototype** + +```c +uint32_t +jerry_get_bigint_size_in_digits (jerry_value_t value) +``` + +- `value` - BigInt value +- return value + - number of digits (can be zero for BigInt zero) + - if value is not a BigInt value, it returns with zero + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + uint64_t digits[4] = { 0x1, 0x1, 0x0, 0x0 }; + jerry_value_t bigint_value = jerry_create_bigint (digits, 4, true); + + /* Prints two, because the leading zeroes in digits buffer are discarded. */ + printf("size: %d\n", (int) jerry_get_bigint_size_in_digits (bigint_value)); + + jerry_release_value (bigint_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_value_is_bigint](#jerry_value_is_bigint) +- [jerry_get_bigint_digits](#jerry_get_bigint_digits) + + +## jerry_get_bigint_digits + +**Summary** + +Copies the uint64 digits of a BigInt value into a buffer. This function supports any +buffer sizes. If the buffer size is smaller than the size returned by +`[jerry_get_bigint_size_in_digits](#jerry_get_bigint_size_in_digits)`, only the +least significant digits are copied into the buffer. If the buffer size is greater, +the unused digits are filled with zero. + +*Notes*: +- 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_is_feature_enabled](#jerry_is_feature_enabled). +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. + +**Prototype** + +```c +void +jerry_get_bigint_digits (jerry_value_t value, uint64_t *digits_p, uint32_t size, bool *sign_p) +``` + +- `value` - BigInt value +- `digits_p` - output buffer for digits +- `size` - size of the output buffer +- `sign_p` - the boolean passed to the function is set to false when the BigInt + is positive, and set to true otherwise (this parameter can be NULL) + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + uint64_t digits[4] = { 0x1, 0x1, 0x0, 0x0 }; + jerry_value_t bigint_value = jerry_create_bigint (digits, 4, true); + + uint64_t get_digits[4]; + bool sign; + jerry_get_bigint_digits (bigint_value, get_digits, 2, &sign); + + jerry_release_value (bigint_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_value_is_bigint](#jerry_value_is_bigint) +- [jerry_get_bigint_size_in_digits](#jerry_get_bigint_size_in_digits) + # Acquire and release API values @@ -4574,6 +5183,100 @@ jerry_create_string_sz_from_utf8 (const jerry_char_t *str_p, - [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) +## jerry_create_external_string + +**Summary** + +Create an external string from a valid CESU8 string. The string buffer passed to the function +should not be modified until the free callback is called. This function can be used to avoid +the duplication of large strings. + +*Note*: 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_external_string (const jerry_char_t *str_p, + jerry_object_native_free_callback_t free_cb) +``` + +- `str_p` - non-null pointer to string +- `free_cb` - optional callback which is called right before the string is freed +- return value - value of the created string + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +```c +{ + const char* string_p = "a large and immutable string: this is a story about ...."; + jerry_value_t string_value = jerry_create_external_string ((const jerry_char_t *) string_p, + NULL); + + ... // usage of string_value + + jerry_release_value (string_value); +} +``` + +**See also** + +- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) +- [jerry_create_external_string_sz](#jerry_create_external_string_sz) + + +## jerry_create_external_string_sz + +**Summary** + +Create an external string from a valid CESU8 string. The string buffer passed to the function +should not be modified until the free callback is called. This function can be used to avoid +the duplication of large strings. + +*Note*: 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_external_string_sz (const jerry_char_t *str_p, + jerry_size_t str_size, + jerry_object_native_free_callback_t free_cb) +``` + +- `str_p` - non-null pointer to string +- `str_size` - size of the string +- `free_cb` - optional callback which is called right before the string is freed +- return value - value of the created string + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +```c +{ + const char* string_p = "a large and immutable string: this is a story about ...."; + jerry_value_t string_value = jerry_create_external_string_sz ((const jerry_char_t *) string_p, + strlen (string_p), + NULL); + + ... // usage of string_value + + jerry_release_value (string_value); +} + +``` + +**See also** + +- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) +- [jerry_create_external_string](#jerry_create_external_string) + + ## jerry_create_symbol **Summary** @@ -4632,6 +5335,65 @@ main (void) - [jerry_release_value](#jerry_release_value) +## jerry_create_bigint + +**Summary** + +Create BigInt value from uint64 digits + +*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_is_feature_enabled](#jerry_is_feature_enabled). +- 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_bigint (const uint64_t *digits_p, uint32_t size, bool sign) +``` + +- `digits_p` - array of uint64 digits, least significant digit first +- `size` - size of the `digits_p` array +- `sign` - false if the created value should be positive, and true if the created value should be negative +- return value + - value of the created bigint, if success + - thrown error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + uint64_t digits[2] = { 0x1, 0x1 }; + jerry_value_t bigint_value = jerry_create_bigint (digits, 2, true); + + // usage of bigint_value + + jerry_release_value (bigint_value); + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) +- [jerry_value_is_bigint](#jerry_value_is_bigint) +- [jerry_get_bigint_digits](#jerry_get_bigint_digits) + + ## jerry_create_regexp **Summary** @@ -5009,6 +5771,7 @@ jerry_has_property (const jerry_value_t obj_val, - 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. + *Changed in version 2.3*: The return value can be an error value. **Example** @@ -5069,6 +5832,7 @@ jerry_has_own_property (const jerry_value_t obj_val, - 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. + *Changed in version 2.3*: The return value can be an error value. **Example** @@ -8582,7 +9346,11 @@ jerry_get_typedarray_buffer (jerry_value_t value, **Summary** -Returns the same result as `JSON.parse` ecmascript function. +Parses 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_release_value](#jerry_release_value) when it +is no longer needed. **Prototype** @@ -8592,24 +9360,38 @@ jerry_json_parse (const jerry_char_t *string_p, jerry_size_t string_size); ``` -- `string_p` - a JSON string -- `string_size` - size of the string +- `string_p` - pointer to a JSON string. +- `string_size` - size of the string. - return - - jerry_value_t containing the same as json.parse() - - jerry_value_t containing error massage + - `jerry_value_t` containing a JavaScript value. + - Error value in case of any parse error. *New in version 2.0*. **Example** +[doctest]: # () + ```c +#include "jerryscript.h" + +int +main (void) { + /* Initialize engine */ + jerry_init (JERRY_INIT_EMPTY); + const jerry_char_t data[] = "{\"name\": \"John\", \"age\": 5}"; - jerry_value_t parsed_json = jerry_json_parse (data, sizeof (data) - 1); + jerry_value_t obj = jerry_json_parse (data, sizeof (data) - 1); - // parsed_json now conatins all data stored in data_in_json + /* "obj" now conatins and object created from the "data" JSON string. */ - jerry_release_value (parsed_json); + jerry_release_value (obj); + + /* Cleanup engine */ + jerry_cleanup (); + + return 0; } ``` @@ -8617,37 +9399,58 @@ jerry_json_parse (const jerry_char_t *string_p, **Summary** -Returns the same value as `JSON.stringify` ecmascript function. +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_release_value](#jerry_release_value) when it +is no longer needed. **Prototype** ```c jerry_value_t -jerry_json_stringify (const jerry_value_t object_to_stringify); +jerry_json_stringify (const jerry_value_t input_value); ``` -- `object_to_stringify` - a jerry_value_t object to stringify +- `input_value` - a `jerry_value_t` to stringify. - return - - jerry_value_t containing the same as json.stringify() - - jerry_value_t containing error massage + - `jerry_value_t` containing a JSON string. + - Error value in case of any stringification error. *New in version 2.0*. **Example** +[doctest]: # () + ```c +#include "jerryscript.h" + +int +main (void) { + /* Initialize engine */ + jerry_init (JERRY_INIT_EMPTY); + jerry_value_t obj = jerry_create_object (); - jerry_value_t key = jerry_create_string ((const jerry_char_t *) "name"); - jerry_value_t value = jerry_create_string ((const jerry_char_t *) "John"); - jerry_release_value (jerry_set_property (obj, key, value)); + { + jerry_value_t key = jerry_create_string ((const jerry_char_t *) "name"); + jerry_value_t value = jerry_create_string ((const jerry_char_t *) "John"); + jerry_release_value (jerry_set_property (obj, key, value)); + jerry_release_value (key); + jerry_release_value (value); + } + jerry_value_t stringified = jerry_json_stringify (obj); - //stringified now contains a json formated string + /* "stringified" now contains a JSON string */ - jerry_release_value (obj); - jerry_release_value (key); - jerry_release_value (value); jerry_release_value (stringified); + jerry_release_value (obj); + + /* Cleanup engine */ + jerry_cleanup (); + + return 0; } ``` diff --git a/08.CODING-STANDARDS.md b/08.CODING-STANDARDS.md index f7bd84883..5c26cccab 100644 --- a/08.CODING-STANDARDS.md +++ b/08.CODING-STANDARDS.md @@ -749,6 +749,12 @@ typedef char wrong_newlines_again_t; ``` +### Type usage conventions + + - Passing the number of arguments for a function call is always `uint32_t` + - String size/length/position related operation should use `lit_utf8_size_t` + - Extended objects internal fields must be `uint32_t` + ## Function declarations Function declarations in JerryScript are verbose but this format