diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index af85a4e050..12582d9057 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -34,6 +34,7 @@ Enum that contains JerryScript API value types: - JERRY_TYPE_OBJECT - object type - JERRY_TYPE_FUNCTION - function type - JERRY_TYPE_ERROR - error/abort type + - JERRY_TYPE_SYMBOL - symbol type ## jerry_error_t @@ -71,6 +72,7 @@ Possible compile time enabled feature types: - JERRY_FEATURE_REGEXP - RegExp support - JERRY_FEATURE_LINE_INFO - line info available - JERRY_FEATURE_LOGGING - logging + - JERRY_FEATURE_SYMBOL - symbol support ## jerry_regexp_flags_t @@ -286,6 +288,19 @@ An opaque declaration of the JerryScript context structure. typedef struct jerry_context_t jerry_context_t; ``` + +## jerry_binary_operation_t + +Enum that contains the supported binary operation types + - JERRY_BIN_OP_EQUAL - equal comparison (==) + - JERRY_BIN_OP_STRICT_EQUAL - strict equal comparison (===) + - JERRY_BIN_OP_LESS - less relation (<) + - JERRY_BIN_OP_LESS_EQUAL - less or equal relation (<=) + - JERRY_BIN_OP_GREATER - greater relation (>) + - JERRY_BIN_OP_GREATER_EQUAL - greater or equal relation (>=) + - JERRY_BIN_OP_INSTANCEOF - instanceof operation + + ## jerry_property_descriptor_t **Summary** @@ -1090,6 +1105,7 @@ jerry_get_global_object (void); - [jerry_release_value](#jerry_release_value) - [jerry_define_own_property](#jerry_define_own_property) + # Checker functions Functions to check the type of an API value ([jerry_value_t](#jerry_value_t)). @@ -1563,6 +1579,57 @@ jerry_value_is_string (const jerry_value_t value) - [jerry_release_value](#jerry_release_value) +## jerry_value_is_symbol + +**Summary** + +Returns whether the given `jerry_value_t` is a symbol value. + +**Prototype** + +```c +bool +jerry_value_is_symbol (const jerry_value_t value) +``` + +- `value` - API value +- return value + - true, if the given `jerry_value_t` is a symbol + - false, otherwise + +**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 *) "Symbol description string"); + jerry_value_t symbol_value = jerry_create_symbol (string_value); + + jerry_release_value (string_value); + + if (jerry_value_is_symbol (symbol_value)) + { + // usage of symbol_value + } + + jerry_release_value (symbol_value); + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) + + ## jerry_value_is_typedarray **Summary** @@ -1671,7 +1738,7 @@ jerry_value_get_type (const jerry_value_t value); ... } - jerry_value_release (number); + jerry_release_value (number); } ``` @@ -1711,6 +1778,122 @@ jerry_is_feature_enabled (const jerry_feature_t feature); } ``` +**See also** +- [jerry_feature_t](#jerry_feature_t) + + +# Binary operations + +## jerry_binary_operation + +**Summary** + +Perform binary operation on the given operands (==, ===, <, >, etc.). + +**Prototype** + +```c +jerry_value_t +jerry_binary_operation (jerry_binary_operation_t op, + const jerry_value_t lhs, + const jerry_value_t rhs); +``` + +- `op` - binary operation +- `lhs` - left-hand side operand +- `rhs` - right-hand side operand +- return value + - error, if argument has an error flag or operation is unsuccessful or unsupported + - true/false, the result of the binary operation on the given operands otherwise + +**Example - JERRY_BIN_OP_EQUAL** + +```c +{ + jerry_value_t value1; + jerry_value_t value2; + ... // create or acquire value + jerry_value_t result = jerry_binary_operation (JERRY_BIN_OP_EQUAL, value1, value2) + + if (!jerry_value_is_error (result)) + { + if (jerry_get_boolean_value (result)) + { + // value1 and value2 are equal + } + else + { + // value1 and value2 are NOT equal + } + } + else + { + ... // handle error + } + + jerry_release_value (value1); + jerry_release_value (value2); + jerry_release_value (result); +} +``` + +**Example - JERRY_BIN_OP_INSTANCEOF** + +[doctest]: # () + +```c +#include "jerryscript.h" + +static jerry_value_t +my_constructor (const jerry_value_t func_val, + const jerry_value_t this_val, + const jerry_value_t argv[], + const jerry_length_t argc) +{ + return jerry_create_undefined (); +} + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t base_obj = jerry_create_object (); + jerry_value_t constructor = jerry_create_external_function (my_constructor); + + /* External functions does not have a prototype by default, so we need to create one */ + jerry_value_t prototype_str = jerry_create_string ((const jerry_char_t *) ("prototype")); + jerry_release_value (jerry_set_property (constructor, prototype_str, base_obj)); + jerry_release_value (prototype_str); + + /* Construct the instance. */ + jerry_value_t instance_val = jerry_construct_object (constructor, NULL, 0); + + /* Call the API function of 'instanceof'. */ + jerry_value_t is_instance = jerry_binary_operation (JERRY_BIN_OP_INSTANCEOF, + instance_val, + constructor); + if (!jerry_value_is_error (is_instance) + && jerry_get_boolean_value (is_instance) == true) + { + /* ... */ + } + + /* Free all of the jerry values and cleanup the engine. */ + jerry_release_value (base_obj); + jerry_release_value (constructor); + jerry_release_value (instance_val); + jerry_release_value (is_instance); + + jerry_cleanup (); + return 0; +} +``` + +**See also** +- [jerry_binary_operation_t](#jerry_binary_operation_t) + + # Error manipulation functions ## jerry_create_abort_from_value @@ -2701,6 +2884,59 @@ jerry_resolve_or_reject_promise (jerry_value_t promise, - [jerry_release_value](#jerry_release_value) - [jerry_value_is_error](#jerry_value_is_error) +# Functions for symbols + +These APIs all depend on the ES2015-subset profile. + +## jerry_get_symbol_descriptive_string + +**Summary** + +Call the SymbolDescriptiveString 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_get_symbol_descriptive_string (const jerry_value_t value); +``` + +- `value` - symbol value +- return value + - string value containing the symbol's descriptive string - if success + - thrown error, otherwise + +**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_desc_string = jerry_get_symbol_descriptive_string (symbol_value); + + // usage of symbol_desc_string + + jerry_release_value (symbol_desc_string); + jerry_release_value (symbol_value); + + jerry_cleanup (); +} +``` + # Acquire and release API values @@ -3426,6 +3662,58 @@ jerry_create_string_sz (const jerry_char_t *str_p, - [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) +## jerry_create_symbol + +**Summary** + +Create symbol from an API value. + +*Note*: The given argument is converted to string. This operation can throw an error. + +**Prototype** + +```c +jerry_value_t +jerry_create_symbol (const jerry_value_t value) +``` + +- `value` - API value +- return value + - value of the created symbol, if success + - thrown error, otherwise + +**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 *) "Symbol description string"); + jerry_value_t symbol_value = jerry_create_symbol (string_value); + + // The description value is no longer needed + jerry_release_value (string_value); + + // usage of symbol_value + + jerry_release_value (symbol_value); + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_value_is_symbol](#jerry_value_is_symbol) +- [jerry_release_value](#jerry_release_value) + + ## jerry_create_regexp **Summary** diff --git a/09.EXT-REFERENCE-ARG.md b/09.EXT-REFERENCE-ARG.md index 6235b11a1a..1c030c63ee 100644 --- a/09.EXT-REFERENCE-ARG.md +++ b/09.EXT-REFERENCE-ARG.md @@ -71,7 +71,7 @@ typedef struct **Summary** -The structure is used in `jerryx_arg_array`. It provides the array items' corresponding +The structure is used in `jerryx_arg_array`. It provides the array items' corresponding JS-to-C mappings and count. **Prototype** @@ -823,6 +823,32 @@ jerryx_arg_js_iterator_peek (jerryx_arg_js_iterator_t *js_arg_iter_p) - return value - the current `jerry_value_t` argument. - `js_arg_iter_p` - the JS arg iterator from which to peek. +## jerryx_arg_js_iterator_restore + +**Summary** + +Restore the last item popped from the stack. This can be called as +many times as there are arguments on the stack -- if called when the +first element in the array is the current top of the stack, this +function does nothing. + +*Note:* This function relies on the underlying implementation of the +arg stack as an array, as its function is to simply back up the "top +of stack" pointer to point to the previous element of the array. + +*Note:* Like `jerryx_arg_js_iterator_pop ()`, this function will +change the `js_arg_idx` and `js_arg_p` values in the iterator. + +**Prototype** + +```c +jerry_value_t +jerryx_arg_js_iterator_restore (jerryx_arg_js_iterator_t *js_arg_iter_p) +``` + - return value - the the new top of the stack. + - `js_arg_iter_p` - the JS arg iterator to restore. + + ## jerryx_arg_js_iterator_index **Summary**