diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index 8935563a49..b117629eea 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -1,43 +1,170 @@ -# jerry_run_simple +# JerryScript types + +## jerry_init_flag_t + +Enum that contains the following elements: + + - JERRY_INIT_EMPTY - empty flag set + - JERRY_INIT_ENABLE_LOG - enable logging + - JERRY_INIT_SHOW_OPCODES - dump byte-code to stdout after parse + - JERRY_INIT_MEM_STATS - dump memory statistics + - JERRY_INIT_MEM_STATS_SEPARATE - dump memory statistics and reset peak values after parse + +## jerry_error_t + +Possible types of an error: + - JERRY_ERROR_COMMON - common error + - JERRY_ERROR_EVAL - eval error + - JERRY_ERROR_RANGE - range error + - JERRY_ERROR_REFERENCE - reference error + - JERRY_ERROR_SYNTAX - syntax error + - JERRY_ERROR_TYPE - type error + - JERRY_ERROR_URI - URI error + +## jerry_char_t **Summary** -The simplest way to run JavaScript. +Jerry's char value **Prototype** ```c -jerry_completion_code_t -jerry_run_simple (const jerry_char_t *script_source, - size_t script_source_size, - jerry_flag_t flags); +typedef uint8_t jerry_char_t; ``` -- `script_source` - source code, it must be a valid utf8 string. -- `script_source_size` - size of source code buffer, in bytes. -- return value - completion code, indicating whether execution was successful - (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred - (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`). +## jerry_size_t -**Example** +**Summary** + +Jerry's size + +**Prototype** + +```c +typedef uint32_t jerry_size_t; +``` + +## jerry_length_t + +**Summary** + +Jerry's length + +**Prototype** ```c +typedef uint32_t jerry_length_t; +``` + +## jerry_value_t + +**Summary** + +JerryScript value can be a boolean, number, null, object, string or undefined. The value has an error flag, +that indicates whether is an error or not. Every type has an error flag not only objects. The error flag should +be cleared before the value is passed as an argument, otherwise it can lead to a type error. The error objects +created by API functions has the error flag set. + +**Prototype** + +```c +typedef uint32_t jerry_value_t; +``` + +## jerry_property_descriptor_t + +**Summary** + +Description of ECMA property descriptor + +**Prototype** + +```c +typedef struct { - const jerry_char_t *script = "print ('Hello, World!');"; + /** Is [[Value]] defined? */ + bool is_value_defined; - jerry_run_simple (script, strlen ((const char *) script), JERRY_FLAG_EMPTY); -} + /** Is [[Get]] defined? */ + bool is_get_defined; + + /** Is [[Set]] defined? */ + bool is_set_defined; + + /** Is [[Writable]] defined? */ + bool is_writable_defined; + + /** [[Writable]] */ + bool is_writable; + + /** Is [[Enumerable]] defined? */ + bool is_enumerable_defined; + + /** [[Enumerable]] */ + bool is_enumerable; + + /** Is [[Configurable]] defined? */ + bool is_configurable_defined; + + /** [[Configurable]] */ + bool is_configurable; + + /** [[Value]] */ + jerry_value_t value; + + /** [[Get]] */ + jerry_value_t getter; + + /** [[Set]] */ + jerry_value_t setter; +} jerry_property_descriptor_t; ``` -**See also** +## jerry_external_handler_t -- [jerry_init](#jerry_init) -- [jerry_cleanup](#jerry_cleanup) -- [jerry_parse](#jerry_parse) -- [jerry_run](#jerry_run) +**Summary** + +Type of an external function handler + +**Prototype** + +```c +typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj_p, + const jerry_value_t this_val, + const jerry_value_t args_p[], + const jerry_length_t args_count); +``` + +## jerry_object_free_callback_t + +**Summary** + +Native free callback of an object + +**Prototype** + +```c +typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p); +``` + +## jerry_object_property_foreach_t + +**Summary** + +Function type applied for each data property of an object + +**Prototype** + +```c +typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name_p, + const jerry_value_t property_value, + void *user_data_p); +``` +# General engine functions -# jerry_init +## jerry_init **Summary** @@ -48,22 +175,22 @@ JavaScript values. ```c void -jerry_init (jerry_flag_t flags); +jerry_init (jerry_init_flag_t flags) ``` `flags` - combination of various engine configuration flags: -- `JERRY_FLAG_EMPTY` - no flags, just initialize in default configuration. -- `JERRY_FLAG_SHOW_OPCODES` - print compiled byte-code. -- `JERRY_FLAG_MEM_STATS` - dump memory statistics. -- `JERRY_FLAG_MEM_STATS_SEPARATE` - dump memory statistics and reset peak values after parse. -- `JERRY_FLAG_ENABLE_LOG` - enable logging. +- `JERRY_INIT_EMPTY` - no flags, just initialize in default configuration. +- `JERRY_INIT_ENABLE_LOG` - enable logging. +- `JERRY_INIT_SHOW_OPCODES` - print compiled byte-code. +- `JERRY_INIT_MEM_STATS` - dump memory statistics. +- `JERRY_INIT_MEM_STATS_SEPARATE` - dump memory statistics and reset peak values after parse. **Example** ```c { - jerry_init (JERRY_FLAG_SHOW_OPCODES | JERRY_FLAG_ENABLE_LOG); + jerry_init (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_ENABLE_LOG); // ... @@ -75,7 +202,8 @@ jerry_init (jerry_flag_t flags); - [jerry_cleanup](#jerry_cleanup) -# jerry_cleanup + +## jerry_cleanup **Summary** @@ -95,125 +223,223 @@ jerry_cleanup (void); - [jerry_init](#jerry_init) -# jerry_parse +## jerry_register_magic_strings **Summary** -Parse specified script to execute in Global scope. +Registers an external magic string array. -*Note*: Current API doesn't permit replacement or modification of Global scope's code without engine -restart, which means 'jerry_parse' can be invoked only once between `jerry_init` and `jerry_cleanup`. +**Prototype** + +```c +void +jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items, + uint32_t count, + const jerry_length_t *str_lengths); +``` + +- `ex_str_items` - character arrays, representing external magic strings' contents +- `count` - number of the strings +- `str_lengths` - lengths of the strings + +**Example** + +```c +{ + jerry_init (JERRY_INIT_EMPTY); + + // must be static, because 'jerry_register_magic_strings' does not copy + static const jerry_char_ptr_t magic_string_items[] = { + (const jerry_char_ptr_t) "magicstring1", + (const jerry_char_ptr_t) "magicstring2", + (const jerry_char_ptr_t) "magicstring3" + }; + uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t)); + + // must be static, because 'jerry_register_magic_strings' does not copy + static const jerry_length_t magic_string_lengths[] = { + (jerry_length_t)strlen (magic_string_items[0]), + (jerry_length_t)strlen (magic_string_items[1]), + (jerry_length_t)strlen (magic_string_items[2]) + }; + jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths); +} +``` + +**See also** + +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) + + +## jerry_get_memory_limits + +**Summary** + +Gets configured memory limits of JerryScript. **Prototype** ```c -bool -jerry_parse (const jerry_char_t *source_p, - size_t source_size, - jerry_object_t **error_obj_p); +void +jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p, + size_t *out_stack_limit_p); ``` -- `source_p` - string, containing source code to parse. It must be a valid utf8 string. -- `source_size` - size of the string, in bytes. -- `error_obj_p` - error object (output parameter). +- `out_data_bss_brk_limit_p` - out parameter, that gives the maximum size of data + bss + brk sections. +- `out_stack_limit_p` - out parameter, that gives the maximum size of the stack. **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); + jerry_init (JERRY_INIT_EMPTY); - char script [] = "print ('Hello, World!');"; - size_t script_size = strlen ((const char *) script); + size_t stack_limit; + size_t data_dss_brk_limit; + jerry_get_memory_limits (&stack_limit, &data_dss_brk_limit); +} +``` - jerry_object_t *error_object_p = NULL; - if (!jerry_parse (script, script_size, &error_object_p)) - { - /* Error object must be freed, if parsing failed */ - jerry_release_object (error_object_p); - } +**See also** - jerry_cleanup (); +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) + + +## jerry_gc + +**Summary** + +Performs garbage collection. + +**Prototype** + +```c +void +jerry_gc (void); +``` + +**Example** + +```c +jerry_gc (); +``` + +**See also** + +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) + +# Parser and executor functions + +Functions to parse and run JavaScript source code. + +## jerry_run_simple + +**Summary** + +The simplest way to run JavaScript. + +**Prototype** + +```c +bool +jerry_run_simple (const jerry_char_t *script_source, + size_t script_source_size, + jerry_init_flag_t flags); +``` + +- `script_source` - source code, it must be a valid utf8 string. +- `script_source_size` - size of source code buffer, in bytes. +- `jerry_init_flag_t` - combination of various engine configuration flags +- return value + - true, if run was successful + - false, otherwise + +**Example** + +```c +{ + const jerry_char_t *script = "print ('Hello, World!');"; + + jerry_run_simple (script, strlen ((const char *) script), JERRY_INIT_EMPTY); } ``` **See also** +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_parse](#jerry_parse) - [jerry_run](#jerry_run) -# jerry_parse_and_save_snapshot +## jerry_parse **Summary** -Generate snapshot from the specified source code. +Parse specified script to execute in Global scope. + +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +is no longer needed. **Prototype** ```c -size_t -jerry_parse_and_save_snapshot (const jerry_char_t *source_p, - size_t source_size, - bool is_for_global, - uint8_t *buffer_p, - size_t buffer_size); +jerry_value_t +jerry_parse (const jerry_char_t *source_p, + size_t source_size, + bool is_strict); ``` -- `source_p` - script source, it must be a valid utf8 string. -- `source_size` - script source size, in bytes. -- `is_for_global` - snapshot would be executed as global (true) or eval (false). -- `buffer_p` - buffer to save snapshot to. -- `buffer_size` - the buffer's size. +- `source_p` - string, containing source code to parse. It must be a valid utf8 string. +- `source_size` - size of the string, in bytes. +- `is_strict` - defines strict mode. - return value - - the size of snapshot, 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 current configuration through - JERRY_ENABLE_SNAPSHOT) - - 0 otherwise. + - function object value, if script was parsed successfully, + - thrown error, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); + jerry_init (JERRY_INIT_EMPTY); - static uint8_t global_mode_snapshot_buffer[1024]; - const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();"; + char script [] = "print ('Hello, World!');"; + size_t script_size = strlen ((const char *) script); - size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p, - strlen (code_to_snapshot_p), - true, - global_mode_snapshot_buffer, - sizeof (global_mode_snapshot_buffer)); + jerry_value_t parsed_code = jerry_parse (script, script_size, false); + jerry_release_value (parsed_code); + + jerry_cleanup (); } ``` **See also** -- [jerry_init](#jerry_init) -- [jerry_exec_snapshot](#jerry_exec_snapshot) +- [jerry_run](#jerry_run) -# jerry_run +## jerry_run **Summary** -Run code of Global scope. +Run code in Global scope. -*Note*: The code should be previously registered through `jerry_parse`. +*Note*: The code should be previously parsed with `jerry_parse`. **Prototype** ```c -jerry_completion_code_t -jerry_run (jerry_value_t *error_value_p); +jerry_value_t +jerry_run (jerry_value_t func_val); ``` -- `error_value_p` - error value (output parameter). -- return value - completion code that indicates whether run performed successfully. - - `JERRY_COMPLETION_CODE_OK` - successful completion - - `JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION` - an unhandled JavaScript exception occurred - - `JERRY_COMPLETION_CODE_INVALID_SNAPSHOT_VERSION` - snapshot version mismatch - - `JERRY_COMPLETION_CODE_INVALID_SNAPSHOT_FORMAT` - snapshot format is not valid +- `func_val` - function to run +- return value + - result of bytecode, if run was successful + - thrown error, otherwise **Example** @@ -223,32 +449,24 @@ jerry_run (jerry_value_t *error_value_p); size_t script_size = strlen ((const char *) script); /* Initialize engine */ - jerry_init (JERRY_FLAG_EMPTY); + jerry_init (JERRY_INIT_EMPTY); /* Setup Global scope code */ - jerry_object_t *error_object_p = NULL; - if (!jerry_parse (script, script_size, &error_object_p)) - { - /* Error object must be freed, if parsing failed */ - jerry_release_object (error_object_p); - } - else + jerry_value_t parsed_code = jerry_parse (script, script_size, false); + + if (!jerry_value_has_error_flag (parsed_code)) { - /* Execute Global scope code - * - * Note: - * Initialization of 'error_value' is not mandatory here. - */ - jerry_value_t error_value = jerry_create_undefined_value (); - jerry_completion_code_t return_code = jerry_run (&error_value); - - if (return_code == JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION) - { - /* Error value must be freed, if 'jerry_run' returns with an unhandled exception */ - jerry_release_value (error_value); - } + /* Execute the parsed source code in the Global scope */ + jerry_value_t ret_value = jerry_run (parsed_code); + + /* Returned value must be freed */ + jerry_release_value (ret_value); } + /* Parsed source code must be freed */ + jerry_release_value (parsed_code); + + /* Cleanup engine */ jerry_cleanup (); } ``` @@ -258,189 +476,268 @@ jerry_run (jerry_value_t *error_value_p); - [jerry_parse](#jerry_parse) -# jerry_exec_snapshot +## jerry_eval **Summary** -Execute snapshot from the specified buffer. +Perform JavaScript `eval`. **Prototype** ```c -jerry_completion_code_t -jerry_exec_snapshot (const void *snapshot_p, - size_t snapshot_size, - bool copy_bytecode, - jerry_value_t *retval_p); +jerry_value_t +jerry_eval (const jerry_char_t *source_p, + size_t source_size, + bool is_strict); ``` -- `snapshot_p` - pointer to snapshot -- `snapshot_size` - size of snapshot -- `copy_bytecode` - flag, indicating whether the passed snapshot buffer should be copied to the - engine's memory. If set the engine should not reference the buffer after the function returns - (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not - set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup). -- `retval_p` - return value, ECMA-262 'undefined' if code is executed as global scope code. -- return value - completion code that indicates whether run performed successfully. Same as before. +- `source_p` - source code to evaluate, it must be a valid utf8 string. +- `source_size` - length of the source code +- `is_strict` - perform `eval` as it is called from "strict mode" code. +- return value - result of eval, may be error value. **Example** ```c { - bool is_ok; - jerry_value_t res; - static uint8_t global_mode_snapshot_buffer[1024]; - const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();"; + jerry_value_t ret_val = jerry_eval (str_to_eval, + strlen (str_to_eval), + false); +} +``` - jerry_init (JERRY_FLAG_EMPTY); - size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p, - strlen (code_to_snapshot_p), - true, - global_mode_snapshot_buffer, - sizeof (global_mode_snapshot_buffer)); - jerry_cleanup (); +**See also** + +- [jerry_create_external_function](#jerry_create_external_function) +- [jerry_external_handler_t](#jerry_external_handler_t) + + +# Get the global context + +## jerry_get_global_object + +**Summary** + +Get the Global object. + +*Note*: Returned value must be freed with [jerry_release_object](#jerry_release_object) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_get_global_object (void); +``` + +- return value - api value of global object + +**Example** + +```c +{ + jerry_value_t glob_obj_val = jerry_get_global_object (); - jerry_init (JERRY_FLAG_EMPTY); + ... // Do something with global object, ex: add properties - is_ok = (jerry_exec_snapshot (global_mode_snapshot_buffer, - global_mode_snapshot_size, - false, - &res) == JERRY_COMPLETION_CODE_OK); + jerry_release_value (glob_obj_val); } ``` **See also** -- [jerry_init](#jerry_init) -- [jerry_cleanup](#jerry_cleanup) -- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot) +- [jerry_release_object](#jerry_release_object) +- [jerry_define_own_property](#jerry_define_own_property) +# Checker functions -# jerry_get_memory_limits +Functions to check the type of an API value ([jerry_value_t](#jerry_value_t)). + +## jerry_value_is_array **Summary** -Gets configured memory limits of JerryScript. +**Prototype** + +```c +bool +jerry_value_is_array (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is an array + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_array (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) + + +## jerry_value_is_boolean + +**Summary** + +Returns whether the given `jerry_value_t` is a boolean value. **Prototype** ```c -void -jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p, - size_t *out_stack_limit_p); +bool +jerry_value_is_boolean (const jerry_value_t value) ``` -- `out_data_bss_brk_limit_p` - out parameter, that gives the maximum size of data + bss + brk sections. -- `out_stack_limit_p` - out parameter, that gives the maximum size of the stack. +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a boolean value + - false, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); + jerry_value_t value; + ... // create or acquire value - size_t stack_limit; - size_t data_dss_brk_limit; - jerry_get_memory_limits (&stack_limit, &data_dss_brk_limit); + if (jerry_value_is_boolean (value)) + { + ... + } + + jerry_release_value (value); } ``` **See also** -- [jerry_init](#jerry_init) +- [jerry_release_value](#jerry_release_value) -# jerry_gc +## jerry_value_is_constructor **Summary** -Performs garbage collection. +Returns whether the given `jerry_value_t` is a constructor function. **Prototype** ```c -void -jerry_gc (void); +bool +jerry_value_is_constructor (const jerry_value_t value) ``` +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a constructor + - false, otherwise + **Example** ```c -jerry_gc (); +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_constructor (value)) + { + ... + } + + jerry_release_value (value); +} ``` +**See also** -# jerry_eval +- [jerry_release_value](#jerry_release_value) + + +## jerry_value_is_function **Summary** -Perform JavaScript `eval`. +Returns whether the given `jerry_value_t` is a function. **Prototype** ```c -jerry_completion_code_t -jerry_eval (const jerry_char_t *source_p, - size_t source_size, - bool is_direct, - bool is_strict, - jerry_value_t *retval_p); +bool +jerry_value_is_function (const jerry_value_t value) ``` -- `source_p` - source code to evaluate, it must be a valid utf8 string. -- `source_size` - length of the source code -- `is_direct` - whether to perform `eval` in "direct" mode (which means it is called as "eval" and - not through some alias). -- `is_strict` - perform `eval` as it is called from "strict mode" code. -- `retval_p` - value, returned by `eval` (output parameter). -- return value - completion code that indicates whether run performed successfully. Same as before. +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a function + - false, otherwise **Example** ```c { - jerry_value_t ret_val; + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_function (value)) + { + ... + } - jerry_completion_code_t status = jerry_eval (str_to_eval, - strlen (str_to_eval), - false, - false, - &ret_val); + jerry_release_value (value); } ``` **See also** -- [jerry_create_external_function](#jerry_create_external_function) -- [jerry_external_handler_t](#jerry_external_handler_t) +- [jerry_release_value](#jerry_release_value) -# jerry_create_undefined_value +## jerry_value_is_number **Summary** -Creates a `jerry_value_t` representing an undefined value. The value has to be released by -[jerry_release_value](#jerry_release_value). +Returns whether the given `jerry_value_t` is a number. **Prototype** ```c -jerry_value_t -jerry_create_undefined_value (void); +bool +jerry_value_is_function (const jerry_value_t value) ``` -- return value - a `jerry_value_t` representing undefined. +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a number + - false, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_value_t undefined_value = jerry_create_undefined_value (); + jerry_value_t value; + ... // create or acquire value - ... // usage of the value + if (jerry_value_is_number (value)) + { + ... + } - jerry_release_value (undefined_value); + jerry_release_value (value); } ``` @@ -449,32 +746,37 @@ jerry_create_undefined_value (void); - [jerry_release_value](#jerry_release_value) -# jerry_create_null_value +## jerry_value_is_null **Summary** -Creates a `jerry_value_t` representing a null value. The value has to be released by -[jerry_release_value](#jerry_release_value). +Returns whether the given `jerry_value_t` is a null value. **Prototype** ```c -jerry_value_t -jerry_create_null_value (void); +bool +jerry_value_is_null (const jerry_value_t value) ``` -- return value - a `jerry_value_t` representing null. +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a null + - false, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_value_t null_value = jerry_create_null_value (); + jerry_value_t value; + ... // create or acquire value - ... // usage of the value + if (jerry_value_is_null (value)) + { + ... + } - jerry_release_value (null_value); + jerry_release_value (value); } ``` @@ -483,33 +785,37 @@ jerry_create_null_value (void); - [jerry_release_value](#jerry_release_value) -# jerry_create_boolean_value +## jerry_value_is_object **Summary** -Creates a `jerry_value_t` representing a boolean value from the given boolean parameter. The -value has to be released by [jerry_release_value](#jerry_release_value). +Returns whether the given `jerry_value_t` is an object value. **Prototype** ```c -jerry_value_t -jerry_create_boolean_value (bool value); +bool +jerry_value_is_object (const jerry_value_t value) ``` -- `value` - boolean value. -- return value - a `jerry_value_t` created from the given boolean argument. +- `value` - api value +- return value + - true, if the given `jerry_value_t` is an object + - false, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_value_t boolean_value = jerry_create_boolean_value (true); + jerry_value_t value; + ... // create or acquire value - ... // usage of the value + if (jerry_value_is_object (value)) + { + ... + } - jerry_release_value (boolean_value); + jerry_release_value (value); } ``` @@ -518,33 +824,37 @@ jerry_create_boolean_value (bool value); - [jerry_release_value](#jerry_release_value) -# jerry_create_number_value +## jerry_value_is_string **Summary** -Creates a `jerry_value_t` from the given double parameter. The value has to be released by -[jerry_release_value](#jerry_release_value). +Returns whether the given `jerry_value_t` is a string value. **Prototype** ```c -jerry_value_t -jerry_create_number_value (double value); +bool +jerry_value_is_string (const jerry_value_t value) ``` -- `value` - double value from which a `jerry_value_t` will be created. -- return value - a `jerry_value_t` created from the given double argument. +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a string + - false, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_value_t number_value = jerry_create_number_value (3.14); + jerry_value_t value; + ... // create or acquire value - ... // usage of the value + if (jerry_value_is_string (value)) + { + ... + } - jerry_release_value (number_value); + jerry_release_value (value); } ``` @@ -553,34 +863,37 @@ jerry_create_number_value (double value); - [jerry_release_value](#jerry_release_value) -# jerry_create_object_value +## jerry_value_is_undefined **Summary** -Converts the given `jerry_object_t` parameter to a `jerry_value_t`. The value has to be released -by [jerry_release_value](#jerry_release_value) when it is no longer needed. +Returns whether the given `jerry_value_t` is an undefined value. **Prototype** ```c -jerry_value_t -jerry_create_object_value (jerry_object_t *value); +bool +jerry_value_is_undefined (const jerry_value_t value) ``` -- `value` - `jerry_object_t` from which a `jerry_value_t` will be created. -- return value - a `jerry_value_t` created from the given `jerry_object_t` argument. +- `value` - api value +- return value + - true, if the given `jerry_value_t` is an undefined value + - false, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_object_t *object_p = jerry_create_object (); - jerry_value_t object_value = jerry_create_object_value (object_p); + jerry_value_t value; + ... // create or acquire value - ... // usage of object_value + if (jerry_value_is_undefined (value)) + { + ... + } - jerry_release_value (object_value); + jerry_release_value (value); } ``` @@ -589,131 +902,122 @@ jerry_create_object_value (jerry_object_t *value); - [jerry_release_value](#jerry_release_value) -# jerry_create_string_sz +# Error flag manipulation functions + +## jerry_value_has_error_flag **Summary** -Creates a string. The caller should release the string with [jerry_release_string](#jerry_release_string) -when it is no longer needed. +Returns whether the given `jerry_value_t` has the error flag set. **Prototype** ```c -jerry_string_t * -jerry_create_string_sz (const jerry_char_t *str_p, - jerry_size_t str_size) +bool +jerry_value_has_error_flag (const jerry_value_t value); ``` -- `str_p` - string from which the result `jerry_string_t` will be created. -- `str_size` - size of the string. -- return value - a `jerry_string_t*` created from the given `jerry_char_t*` argument. +- `value` - api value +- return value + - true, if the given `jerry_value_t` has the error flag set + - false, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - const jerry_char_t char_array[] = "a string"; - jerry_string_t *string = jerry_create_string_sz (char_array, - strlen ((char *) char_array)); + jerry_value_t value; + ... // create or acquire value - ... // usage of string + if (jerry_value_has_error_flag (value)) + { + ... + } - jerry_release_string (string); + jerry_release_value (value); } - ``` **See also** -- [jerry_release_string](#jerry_release_string) +- [jerry_value_t](#jerry_value_t) -# jerry_create_string_value +## jerry_value_clear_error_flag **Summary** -Creates a `jerry_value_t` from the given `jerry_string_t` parameter. The value has to be released -by [jerry_release_value](#jerry_release_value) when it is no longer needed. +Clear the error flag. **Prototype** ```c -jerry_value_t -jerry_create_string_value (jerry_string_t *value); +void +jerry_value_clear_error_flag (jerry_value_t *value_p); ``` -- `value` - `jerry_string_t` from which a value will be created. -- return value - a `jerry_value_t` created from the given `jerry_string_t` argument. +- `value_p` - pointer to an api value **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - const jerry_char_t char_array[] = "a string"; - jerry_string_t *string = jerry_create_string_sz (char_array, - strlen ((char *) char_array)); - jerry_value_t string_value = jerry_create_string_value (string); + jerry_value_t value; + ... // create or acquire value - ... // usage of string_value + jerry_value_clear_error_flag (&value); - jerry_release_value (string_value); + jerry_release_value (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_t](#jerry_value_t) -# jerry_create_error_sz +## jerry_value_set_error_flag **Summary** -Creates an error object. Caller should release the object with jerry_release_object, when -the value is no longer needed. +Set the error flag. **Prototype** ```c -jerry_object_t * -jerry_create_error_sz (jerry_error_t error_type, - const jerry_char_t *message_p, - jerry_size_t message_size); +void +jerry_value_set_error_flag (jerry_value_t *value_p); ``` -- `error_type` - type of the error. -- `message_p` - value of 'message' property of the constructed error object. -- `message_size` - size of the message in bytes. -- return value - pointer to the created error object. +- `value_p` - pointer to an api value **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_char_t message[] = "error"; - jerry_object_t *error_obj = jerry_create_error_sz (JERRY_ERROR_COMMON, - message, - strlen ((char *) message)); + jerry_value_t value; + ... // create or acquire value - ... // usage of error_obj + jerry_value_set_error_flag (&value); - jerry_release_object (error_obj); + jerry_release_value (value); } ``` **See also** -- [jerry_create_error](#jerry_create_error) +- [jerry_value_t](#jerry_value_t) + + +# Getter functions of 'jerry_value_t' +Get raw data from API values. -# jerry_get_boolean_value +## jerry_get_boolean_value **Summary** -Gets the raw bool value form a `jerry_value_t` value. +Gets the raw bool value form a `jerry_value_t`. **Prototype** @@ -729,7 +1033,6 @@ jerry_get_boolean_value (const jerry_value_t value); ```c { - jerry_init (JERRY_FLAG_EMPTY); jerry_value_t value; ... // create or acquire value @@ -752,7 +1055,7 @@ jerry_get_boolean_value (const jerry_value_t value); - [jerry_release_value](#jerry_release_value) -# jerry_get_number_value +## jerry_get_number_value **Summary** @@ -772,7 +1075,6 @@ jerry_get_number_value (const jerry_value_t value); ```c { - jerry_init (JERRY_FLAG_EMPTY); jerry_value_t value; ... // create or acquire value @@ -794,439 +1096,498 @@ jerry_get_number_value (const jerry_value_t value); - [jerry_release_value](#jerry_release_value) -# jerry_get_object_value +# Functions for string values + +## jerry_get_string_size **Summary** -Gets the object value of the given `jerry_value_t` parameter. +Get the size of a string. Returns zero, if the specified string is not a value. **Prototype** ```c -jerry_object_t * -jerry_get_object_value (const jerry_value_t value); +jerry_size_t +jerry_get_string_size (const jerry_value_t value); ``` - - `value` - api value -- return value - the object contained in the given `jerry_value_t` parameter. +- return value - number of bytes in the buffer needed to represent the string. **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_value_t value; - ... // create or acquire value - - if (jerry_value_is_object (value)) - { - jerry_object_t *raw_value = jerry_get_object_value (value); + jerry_char_t char_array[] = "a string"; + jerry_value_t string = jerry_create_string (char_array); - ... // usage of raw value + jerry_size_t string_size = jerry_get_string_size (string); - } + ... // usage of string_size - jerry_release_value (value); + jerry_release_value (string); } ``` **See also** -- [jerry_value_is_object](#jerry_value_is_object) -- [jerry_release_value](#jerry_release_value) +- [jerry_create_string](#jerry_create_string) +- [jerry_get_string_length](#jerry_get_string_length) -# jerry_get_string_value +## jerry_get_string_length **Summary** -Gets the string value of the given `jerry_value_t` parameter. +Get the length of a string. Returns zero, if the specified string is not a value. **Prototype** ```c -jerry_string_t * -jerry_get_string_value (const jerry_value_t value); +jerry_length_t +jerry_get_string_length (const jerry_value_t value); ``` - `value` - api value -- return value - the string contained in the given `jerry_value_t` parameter. +- return value - number of characters in the string **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_value_t value; - ... // create or acquire value - - if (jerry_value_is_string (value)) - { - jerry_string_t *raw_value = jerry_get_string_value (value); + jerry_char_t char_array[] = "a string"; + jerry_value_t string = jerry_create_string (char_array); - ... // usage of raw value + jerry_length_t string_length = jerry_get_string_length (string); - } + ... // usage of string_length - jerry_release_value (value); + jerry_release_value (string); } - ``` **See also** -- [jerry_value_is_string](#jerry_value_is_string) -- [jerry_release_value](#jerry_release_value) +- [jerry_create_string](#jerry_create_string) +- [jerry_get_string_size](#jerry_get_string_size) -# jerry_get_string_size +## jerry_string_to_char_buffer **Summary** -Gets the length of a jerry_string_t. +Copy string characters to specified buffer. It is the caller's responsibility to make sure that +the string fits in the buffer. + +*Note*: '\0' could occur in characters. **Prototype** ```c jerry_size_t -jerry_get_string_size (const jerry_string_t *str_p); +jerry_string_to_char_buffer (const jerry_value_t value, + jerry_char_t *buffer_p, + jerry_size_t buffer_size); ``` -- `str_p` - input string. -- return value - number of bytes in the buffer needed to represent the string. + +- `value` - input string value +- `buffer_p` - pointer to output buffer +- `buffer_size` - size of the buffer +- return value - number of bytes, actually copied to the buffer **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_char_t char_array[] = "a string"; - jerry_string_t *string = jerry_create_string (char_array); + jerry_value_t value; + ... // create or acquire value - jerry_size_t string_size = jerry_get_string_size (); + jerry_size_t req_sz = jerry_get_string_size (value); + jerry_char_t str_buf_p[req_sz]; - ... // usage of string_size + jerry_string_to_char_buffer (value, str_buf_p, req_sz); - jerry_release_string (string); -} + jerry_release_value (value); +} ``` **See also** - [jerry_create_string](#jerry_create_string) -- [jerry_release_string](#jerry_release_string) -- [jerry_get_string_length](#jerry_get_string_length) +- [jerry_get_string_size](#jerry_get_string_size) + +# Functions for array object values -# jerry_get_string_length +## jerry_get_array_length **Summary** -Gets the length of a `jerry_string_t`. +Get length of an array object. Returns zero, if the given parameter is not an array object. **Prototype** ```c -jerry_length_t -jerry_get_string_length (const jerry_string_t *str_p); +uint32_t +jerry_get_array_length (const jerry_value_t value); ``` -- `str_p` - input string -- return value - number of characters in the string +- `value` - input array value +- return value - length of the given array **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_char_t char_array[] = "a string"; - jerry_string_t *string = jerry_create_string (char_array); - - jerry_length_t string_length = jerry_get_string_length (string); + jerry_value_t value; + ... // create or acquire value - ... // usage of string_length + uint32_t len = jerry_get_array_length (value); - jerry_release_string (string); + jerry_release_value (value); } ``` **See also** -- [jerry_create_string](#jerry_create_string) -- [jerry_release_string](#jerry_release_string) -- [jerry_get_string_size](#jerry_get_string_size) +- [jerry_create_array](#jerry_create_array) + + +# Converters of 'jerry_value_t' +Functions for convering API values to another value type. -# jerry_value_is_undefined +## jerry_value_to_boolean **Summary** -Returns whether the given `jerry_value_t` is an undefined value. +Call ToBoolean operation on the api value. **Prototype** ```c bool -jerry_value_is_undefined (const jerry_value_t value); +jerry_value_to_boolean (const jerry_value_t value); ``` - `value` - api value - return value - - true, if the given `jerry_value_t` is an undefined value + - true, if the logical value is true - false, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); jerry_value_t value; ... // create or acquire value - if (jerry_value_is_undefined (value)) - { - ... - } + bool b = jerry_value_to_boolean (value); jerry_release_value (value); } + ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_to_primitive](#jerry_value_to_primitive) + +## jerry_value_to_number + +**Summary** + +Call ToNumber 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_number (const jerry_value_t value); +``` + +- `value` - api value +- return value + - converted number value, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t number_value = jerry_value_to_number (value); + + jerry_release_value (number_value); + jerry_release_value (value); +} + +``` + +**See also** +- [jerry_value_to_primitive](#jerry_value_to_primitive) -# jerry_value_is_boolean +## jerry_value_to_object **Summary** -Returns whether the given `jerry_value_t` is a boolean value. +Call ToObject 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 -bool -jerry_value_is_boolean (const jerry_value_t value) +jerry_value_t +jerry_value_to_object (const jerry_value_t value); ``` - `value` - api value - return value - - true, if the given `jerry_value_t` is a boolean value - - false, otherwise + - converted object value, if success + - thrown error, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); jerry_value_t value; ... // create or acquire value - if (jerry_value_is_boolean (value)) - { - ... - } + jerry_value_t object_value = jerry_value_to_object (value); + jerry_release_value (object_value); jerry_release_value (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_to_primitive](#jerry_value_to_primitive) + +## jerry_value_to_primitive + +**Summary** + +Call ToPrimitive 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_primitive (const jerry_value_t value); +``` + +- `value` - api value +- return value + - converted primitive value, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t prim_value = jerry_value_to_primitive (value); + + jerry_release_value (prim_value); + jerry_release_value (value); +} +``` +**See also** + +- [jerry_value_t](#jerry_value_t) -# jerry_value_is_number +## jerry_value_to_string **Summary** -Returns whether the given `jerry_value_t` is a number value. +Call the ToString 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 -bool -jerry_value_is_number (const jerry_value_t value); +jerry_value_t +jerry_value_to_string (const jerry_value_t value); ``` - `value` - api value - return value - - true, if the given `jerry_value_t` is a number value - - false, otherwise + - converted srting value, if success + - thrown error, otherwise **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); jerry_value_t value; ... // create or acquire value - if (jerry_value_is_number (value)) - { - ... - } + jerry_value_t string_value = jerry_value_to_string (value); + jerry_release_value (string_value); jerry_release_value (value); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_value_to_primitive](#jerry_value_to_primitive) -# jerry_value_is_function +# Aquire and release API values + +## jerry_acquire_value **Summary** -Returns whether the given `jerry_value_t` is a function object. +Acquires the specified Jerry API value. + +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +is no longer needed. **Prototype** ```c -bool -jerry_value_is_function (const jerry_value_t value); +jerry_value_t +jerry_acquire_value (jerry_value_t value); ``` - `value` - api value -- return value - - true, if the given `jerry_value_t` is a function object - - false, otherwise +- return value - acquired value that may be used outside of the engine **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_value_t value; - ... // create or acquire value + jerry_value_t object_value = jerry_create_object (); - if (jerry_value_is_function (value)) - { - ... - } + jerry_value_t acquired_object = jerry_acquire_value (object_value); - jerry_release_value (value); + jerry_release_value (object_value); + + // acquired_object refers to the created object and makes it + // available after the release of 'object_value' + + jerry_release_value (acquired_object); } ``` **See also** -- [jerry_is_function](#jerry_is_function) - [jerry_release_value](#jerry_release_value) +- [jerry_value_t](#jerry_value_t) -# jerry_value_is_null +## jerry_release_value **Summary** -Returns whether the given jerry_value_t is a null value. +Release specified Jerry API value. **Prototype** ```c -bool -jerry_value_is_null (const jerry_value_t value); +void +jerry_release_value (jerry_value_t value); ``` - `value` - api value -- return value - - true, if the given `jerry_value_t` is a null value - - false, otherwise **Example** ```c - jerry_init (JERRY_FLAG_EMPTY); - jerry_value_t value; - ... // create or acquire value +{ + jerry_value_t object_value = jerry_create_object (); - if (jerry_value_is_null (value)) - { - ... - } + ... - jerry_release_value (value); + jerry_release_value (object_value); +} ``` -**See also** -- [jerry_release_value](#jerry_release_value) +# Create API values +Function for creating [API values](#jerry_value_t). + +*Note*: Every created API value must be freed with [jerry_release_value](#jerry_release_value) when it +is no longer needed. -# jerry_value_is_object +## jerry_create_array **Summary** -Returns whether the given `jerry_value_t` is an object. +Create an array object value. **Prototype** ```c -bool -jerry_value_is_object (const jerry_value_t value); +jerry_value_t +jerry_create_array (uint32_t size); ``` -- `value` - api value -- return value - - true, if the given `jerry_value_t` is an object value - - false, otherwise + - `size` - size of array; + - return value - value of the constructed array object -**Example** + **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_value_t value; - ... // create or acquire value + jerry_value_t array = jerry_create_array (10); - if (jerry_value_is_object (value)) - { ... - } - jerry_release_value (value); + jerry_release_value (array); } ``` **See also** -- [jerry_release_value](#jerry_release_value) +- [jerry_set_property_by_index](#jerry_set_property_by_index) +- [jerry_get_property_by_index](#jerry_get_property_by_index) -# jerry_value_is_string +## jerry_create_boolean **Summary** -Returns whether the given `jerry_value_t` is a string. +Create a jerry_value_t representing a boolean value from the given boolean parameter. **Prototype** ```c -bool -jerry_value_is_string (const jerry_value_t value); +jerry_value_t +jerry_create_boolean (bool value); ``` -- `value` - api value -- return value - - true, if the given `jerry_value_t` is a string - - false, otherwise +- `value` - raw boolean value. +- return value - a `jerry_value_t` created from the given boolean argument. **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_value_t value; - ... // create or acquire value + jerry_value_t boolean_value = jerry_create_boolean (true); - if (jerry_value_is_string (value)) - { - ... - } + ... // usage of the value - jerry_release_value (value); + jerry_release_value (boolean_value); } ``` @@ -1235,893 +1596,866 @@ jerry_value_is_string (const jerry_value_t value); - [jerry_release_value](#jerry_release_value) -# jerry_acquire_value +## jerry_create_error **Summary** -Acquires the specified Jerry API value. - -For values of string, number and object types this acquires the underlying data, for all other types -it is a no-op. The acquired pointer has to be released by [jerry_release_value](#jerry_release_value). +Create new JavaScript error object. **Prototype** ```c jerry_value_t -jerry_acquire_value (jerry_value_t value); +jerry_create_error (jerry_error_t error_type, + const jerry_char_t *message_p); ``` -- `value` - api value -- return value - pointer that may be used outside of the engine +- `error_type` - type of error +- `message_p` - value of 'message' property of constructed error object +- return value - value of the constructed error object **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); - jerry_object_t *object_p = jerry_create_object (); - jerry_value_t object_value = jerry_create_object_value (object_p); + jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_TYPE, + (jerry_char_t * ) "error"); - jerry_value_t acquired_object = jerry_acquire_value (object_value); + ... // usage of error_obj - jerry_release_value (acquired_object); - jerry_release_object (object_p); + + jerry_release_value (error_obj); } ``` **See also** -- [jerry_release_value](#jerry_release_value) -- [jerry_acquire_string](#jerry_acquire_string) -- [jerry_acquire_object](#jerry_acquire_object) +- [jerry_value_has_error_flag](#jerry_value_has_error_flag) +- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag) +- [jerry_value_set_error_flag](#jerry_value_set_error_flag) -# jerry_release_value +## jerry_create_error_sz **Summary** -Release specified pointer to the value. +Create new JavaScript error object. **Prototype** ```c -void -jerry_release_value (jerry_value_t value); +jerry_value_t +jerry_create_error_sz (jerry_error_t error_type, + const jerry_char_t *message_p, + jerry_size_t message_size); ``` -- `value` - api value +- `error_type` - type of the error +- `message_p` - value of 'message' property of the constructed error object +- `message_size` - size of the message in bytes +- return value - value of the constructed error object **Example** ```c { - jerry_value_t val1 = jerry_create_object_value (jerry_create_object ()); - - jerry_string_t *str_p = jerry_create_string ("abc"); - jerry_value_t val2 = jerry_create_string_value (str_p); - - ... // usage of val1 - - jerry_release_value (val1); + jerry_char_t message[] = "error"; + jerry_value_t error_obj = jerry_create_error_sz (JERRY_ERROR_COMMON, + message, + strlen ((char *) message)); - ... // usage of val2 + ... // usage of error_obj - jerry_release_value (val2); + jerry_release_value (error_obj); } ``` +**See also** + +- [jerry_create_error](#jerry_create_error) -# jerry_create_string -**Summary** +## jerry_create_external_function -Create new JavaScript string. +**Summary** -*Note*: Returned value must be freed with [jerry_release_object](#jerry_release_object) when it -is no longer needed. +Create an external function object. **Prototype** ```c -jerry_string_t * -jerry_create_string (const jerry_char_t *v); +jerry_value_t +jerry_create_external_function (jerry_external_handler_t handler_p); ``` -- `v` - value of string to create; -- return value - pointer to the created string. +- `handler_p` - pointer to native handler of the function object +- return value - value of the constructed function object **Example** ```c +static jerry_value_t +handler (const jerry_value_t function_obj_p, + const jerry_value_t this_p, + const jerry_value_t args_p[], + const uint16_t args_cnt) { - jerry_string_t *string_p = jerry_create_string ((jerry_char_t *) "abc"); + printf ("native handler called!\n"); - ... + return jerry_create_boolean (true); +} + +{ + jerry_value_t func_val = jerry_create_external_function (handler); + jerry_value_t glob_obj = jerry_get_global_object (); + + // after this, script can invoke the native handler through "handler_field (1, 2, 3);" + jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field"); + jerry_set_property (glob_obj, prop_name, func_val); + jerry_release_value (prop_name); - jerry_release_string (string_p); + jerry_release_value (func_val); + jerry_release_value (glob_obj); } ``` **See also** -- [jerry_acquire_string](#jerry_acquire_string) -- [jerry_release_string](#jerry_release_string) -- [jerry_string_to_char_buffer](#jerry_string_to_char_buffer) +- [jerry_external_handler_t](#jerry_external_handler_t) +- [jerry_set_property](#jerry_set_property) +- [jerry_call_function](#jerry_call_function) -# jerry_string_to_char_buffer +## jerry_create_number **Summary** -Copy string characters to specified buffer. It is the caller's responsibility to make sure that -the string fits in the buffer. - -*Note*: '\0' could occur in characters. +Creates a `jerry_value_t` representing a number value. **Prototype** ```c -jerry_size_t -jerry_string_to_char_buffer (const jerry_string_t *string_p, - jerry_char_t *buffer_p, - jerry_size_t buffer_size); +jerry_value_t +jerry_create_number (double value); ``` -- `string_p` - pointer to a C string. -- `buffer_p` - pointer to output buffer -- `buffer_size` - size of the buffer -- return value: - - number of bytes, actually copied to the buffer. +- `value` - double value from which a `jerry_value_t` will be created +- return value - a `jerry_value_t` created from the given double argument **Example** ```c { - jerry_object_t *obj_p = jerry_get_global (); - - jerry_value_t val = jerry_get_object_field_value (obj_p, - "field_with_string_value"); - - if (!jerry_value_is_error (val)) - { - if (jerry_value_is_string (val)) - { - char str_buf_p[128]; - jerry_string_t *str_p = jerry_get_string_value (val); - jerry_size_t str_size = jerry_get_string_size (str_p); - jerry_size_t sz = jerry_string_to_char_buffer (str_p, (jerry_char_t *) str_buf_p, str_size); - str_buf_p[sz] = '\0'; - - printf ("%s", str_buf_p); - } + jerry_value_t number_value = jerry_create_number (3.14); - jerry_release_value (val); - } + ... // usage of the value - jerry_release_object (obj_p); + jerry_release_value (number_value); } ``` **See also** -- [jerry_create_string](#jerry_create_string) +- [jerry_release_value](#jerry_release_value) -# jerry_acquire_string +## jerry_create_null **Summary** -Acquire new pointer to the string for usage outside of the engine. The acquired pointer has to be -released with [jerry_release_string](#jerry_release_string). +Creates and returns a `jerry_value_t` with type null object. **Prototype** ```c -jerry_string_t * -jerry_acquire_string (jerry_string_t *string_p); +jerry_value_t +jerry_create_null (void); ``` -- `string_p` - pointer to the string. -- return value - pointer to the string. +- return value - a `jerry_value_t` representing null. **Example** ```c { - jerry_string_t *str_ptr1_p = jerry_create_string ((jerry_char_t *) "abc"); - jerry_string_t *str_ptr2_p = jerry_acquire_string (str_ptr1_p); - - ... // usage of both pointers - - jerry_release_string (str_ptr1_p); + jerry_value_t null_value = jerry_create_null (); - ... // usage of str_ptr2_p pointer + ... // usage of the value - jerry_release_string (str_ptr2_p); + jerry_release_value (null_value); } ``` **See also** -- [jerry_release_string](#jerry_release_string) -- [jerry_create_string](#jerry_create_string) +- [jerry_release_value](#jerry_release_value) + -# jerry_release_string +## jerry_create_object **Summary** -Release specified pointer to the string. +Create new JavaScript object, like with new Object(). **Prototype** ```c -void -jerry_release_string (jerry_string_t *string_p); +jerry_value_t +jerry_create_object (void); ``` -- `string_p` - pointer to the string. +- return value - value of the created object **Example** ```c { - jerry_string_t *str_ptr1_p = jerry_create_string ("abc"); - jerry_string_t *str_ptr2_p = jerry_acquire_string (str_ptr1_p); + jerry_value_t object_value = jerry_create_object (); - ... // usage of both pointers - - jerry_release_string (str_ptr1_p); - - ... // usage of str_ptr2_p pointer + ... // usage of object_value - jerry_release_string (str_ptr2_p); + jerry_release_value (object_value); } ``` **See also** -- [jerry_acquire_string](#jerry_acquire_string) -- [jerry_create_string](#jerry_create_string) +- [jerry_release_value](#jerry_release_value) -# jerry_create_object +## jerry_create_string **Summary** -Create new JavaScript object, like with `new Object()`. - -*Note*: Returned value must be freed with [jerry_release_object](#jerry_release_object) when it -is no longer needed. +Create string from a valid CESU8 string. **Prototype** ```c -jerry_object_t * -jerry_create_object (); +jerry_value_t +jerry_create_string (const jerry_char_t *str_p); ``` -- return value - pointer to the created object. +- `str_p` - pointer to string +- return value - value of the created string **Example** ```c { - jerry_object_t *object_p = jerry_create_object (); + const jerry_char_t char_array[] = "a string"; + jerry_value_t string_value = jerry_create_string (char_array); - ... + ... // usage of string_value - jerry_release_object (object_p); + jerry_release_value (string_value); } ``` **See also** -- [jerry_acquire_object](#jerry_acquire_object) -- [jerry_release_object](#jerry_release_object) -- [jerry_add_object_field](#jerry_add_object_field) -- [jerry_delete_object_field](#jerry_delete_object_field) -- [jerry_get_object_field_value](#jerry_get_object_field_value) -- [jerry_set_object_field_value](#jerry_set_object_field_value) -- [jerry_get_object_native_handle](#jerry_get_object_native_handle) -- [jerry_set_object_native_handle](#jerry_set_object_native_handle) +- [jerry_create_string_sz](#jerry_create_string_sz) -# jerry_acquire_object +## jerry_create_string_sz **Summary** -Acquire new pointer to the object for usage outside of the engine. The acquired pointer has to be -released with [jerry_release_object](#jerry_release_object). +Create string from a valid CESU8 string. **Prototype** ```c -jerry_object_t * -jerry_acquire_object (jerry_object_t *object_p); +jerry_value_t +jerry_create_string_sz (const jerry_char_t *str_p, + jerry_size_t str_size) ``` -- `object_p` - pointer to the object. -- return value - new pointer to the object. +- `str_p` - pointer to string +- `str_size` - size of the string +- return value - value of the created string **Example** ```c { - jerry_object_t *obj_ptr1_p = jerry_create_object (); - jerry_object_t *obj_ptr2_p = jerry_acquire_object (obj_ptr1_p); - - ... // usage of both pointers - - jerry_release_object (obj_ptr1_p); + const jerry_char_t char_array[] = "a string"; + jerry_value_t string_value = jerry_create_string_sz (char_array, + strlen ((char *) char_array)); - ... // usage of obj_ptr2_p pointer + ... // usage of string_value - jerry_release_object (obj_ptr2_p); + jerry_release_value (string_value); } + ``` **See also** -- [jerry_release_object](#jerry_release_object) -- [jerry_create_object](#jerry_create_object) +- [jerry_release_string](#jerry_release_string) -# jerry_release_object +## jerry_create_undefined **Summary** -Release specified pointer to the object. +Creates a jerry_value_t representing an undefined value. **Prototype** ```c -void -jerry_release_object (jerry_object_t *object_p); +jerry_value_t +jerry_create_undefined (void); ``` -- `object_p` - pointer to the object. +- return value - value of undefined **Example** ```c { - jerry_object_t *obj_ptr1_p = jerry_create_object (); - jerry_object_t *obj_ptr2_p = jerry_acquire_object (obj_ptr1_p); - - ... // usage of both pointers + jerry_value_t undefined_value = jerry_create_undefined (); - jerry_release_object (obj_ptr1_p); - - ... // usage of obj_ptr2_p pointer + ... // usage of the value - jerry_release_object (obj_ptr2_p); + jerry_release_value (undefined_value); } ``` **See also** -- [jerry_acquire_object](#jerry_acquire_object) -- [jerry_create_object](#jerry_create_object) +- [jerry_release_value](#jerry_release_value) + +# General API functions of JS objects -# jerry_get_global +## jerry_has_property **Summary** -Get the Global object. +Checks whether the object or it's prototype has the given property. **Prototype** ```c -jerry_object_t * -jerry_get_global (void); +bool +jerry_has_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); ``` -- return value - pointer to the Global object. - -Received pointer should be released with [jerry_release_object](#jerry_release_object), just -when the value is no longer needed. +- `obj_val` - object value +- `prop_name_val` - property name +- return value + - true, if the property exists + - false, otherwise **Example** ```c { - jerry_object_t *glob_obj_p = jerry_get_global (); + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field"); - jerry_value_t val = jerry_get_object_field_value (glob_obj_p, "some_field_name"); - if (!jerry_value_is_error (val)) - { - ... // usage of 'val' - } + bool has_prop = jerry_has_property (global_object, prop_name); - jerry_release_value (val); - jerry_release_object (glob_obj_p); + jerry_release_value (prop_name); + jerry_release_value (global_object); } ``` **See also** -- [jerry_release_object](#jerry_release_object) -- [jerry_add_object_field](#jerry_add_object_field) -- [jerry_delete_object_field](#jerry_delete_object_field) -- [jerry_get_object_field_value](#jerry_get_object_field_value) -- [jerry_set_object_field_value](#jerry_set_object_field_value) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_delete_property](#jerry_delete_property) -# jerry_add_object_field +## jerry_has_own_property **Summary** -Create field (named data property) in an object. +Checks whether the object has the given property. **Prototype** ```c bool -jerry_add_object_field (jerry_object_t *object_p, - const jerry_char_t *field_name_p, - const jerry_value_t field_value, - bool is_writable); +jerry_has_own_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); ``` -- `object_p` - pointer to object to add field at. -- `field_name_p` - name of the field. -- `field_value` - value of the field. -- `is_writable` - flag indicating whether the created field should be writable. +- `obj_val` - object value +- `prop_name_val` - property name - return value - - true, if field was created successfully, i.e. upon the call: - - there is no field with same name in the object; - - the object is extensible. + - true, if the property exists + - false, otherwise **Example** ```c { - jerry_object_t *obj_p = jerry_create_object (); - - jerry_value_t val; + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field"); - ... // initialize val + bool has_prop = jerry_has_own_property (global_object, prop_name); - // Make new constant field - jerry_add_object_field (obj_p, "some_field_name", val, false); + jerry_release_value (prop_name); + jerry_release_value (global_object); } ``` **See also** -- [jerry_create_object](#jerry_create_object) +- [jerry_has_property](#jerry_has_property) +- [jerry_delete_property](#jerry_delete_property) -# jerry_delete_object_field +## jerry_delete_property **Summary** -Delete field (property) in the specified object +Delete a property from an object. **Prototype** ```c bool -jerry_delete_object_field (jerry_object_t *object_p, - const jerry_char_t *field_name_p); +jerry_delete_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); ``` -- `object_p` - pointer to object to delete field at. -- `field_name_p` - name of the field. -- return value - true, if field was deleted successfully, i.e. upon the call: - - there is field with specified name in the object. +- `obj_val` - object value +- `prop_name_val` - property name +- return value + - true, if property was deleted successfully + - false, otherwise **Example** ```c { - jerry_object_t *obj_p; - ... // receive or construct obj_p + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "my_prop"); - jerry_delete_object_field (obj_p, "some_field_name"); + jerry_delete_property (global_object, prop_name); + + jerry_release_value (prop_name); + jerry_release_value (global_object); } ``` **See also** -- [jerry_create_object](#jerry_create_object) +- [jerry_has_property](#jerry_has_property) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_get_property](#jerry_get_property) -# jerry_get_object_field_value +## jerry_get_property **Summary** -Get value of field (property) in the specified object, i.e. perform [[Get]] operation. +Get value of a property to the specified object with the given name. + +*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_object_field_value (jerry_object_t *object_p, - const jerry_char_t *field_name_p); +jerry_get_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); ``` -- `object_p` - pointer to object. -- `field_name_p` - name of the field. -- return value - jerry value of the given field. - -*Note*: Returned value must be freed with [jerry_release_object](#jerry_release_object) when it -is no longer needed. +- `obj_val` - object value +- `prop_name_val` - property name +- return value + - value of property, if success + - thrown error, otherwise **Example** ```c { - jerry_object_t *obj_p; - ... // receive or construct obj_p + 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 val = jerry_get_object_field_value (obj_p, "some_field_name"); + jerry_value_t prop_value = jerry_get_property (obj_val, prop_name); - if (!jerry_value_is_error (val)) - { - ... // usage of 'val' - - } - - jerry_release_value (val); + jerry_release_value (prop_name); + jerry_release_value (global_object); } ``` **See also** -- [jerry_create_object](#jerry_create_object) -- [jerry_set_object_field_value](#jerry_set_object_field_value) -- [jerry_get_object_field_value_sz](#jerry_get_object_field_value_sz) +- [jerry_has_property](#jerry_has_property) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_delete_property](#jerry_delete_property) +- [jerry_set_property](#jerry_set_property) +- [jerry_get_property_by_index](#jerry_get_property_by_index) +- [jerry_set_property_by_index](#jerry_set_property_by_index) -# jerry_get_object_field_value_sz +## jerry_get_property_by_index **Summary** -Gets the value of a field in the specified object. +Get value by an index from the specified object. + +*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_object_field_value_sz (jerry_object_t *object_p, - const jerry_char_t *field_name_p, - jerry_size_t field_name_size); +jerry_get_property_by_index (const jerry_value_t obj_val, + uint32_t index); ``` -- `object_p` - pointer to object. -- `field_name_p` - name of the field. -- `field_name_size` - size of field name in bytes. -- return value - jerry value of the given field. - -*Note*: Returned value must be freed with [jerry_release_object](#jerry_release_object) when it -is no longer needed. +- `obj_val` - object value +- index - index number +- return value + - stored value on the specified index, if success + - thrown exception, otherwise. **Example** ```c { - jerry_init (JERRY_FLAG_EMPTY); + jerry_value_t object; - jerry_char_t field_name[] = "field"; - jerry_value_t field_value = jerry_create_number_value (3.14); + ... // create or acquire object - jerry_object_t* object_p = jerry_create_object (); - jerry_add_object_field (object_p, - field_name, - strlen ((char *) field_name), - field_value, - true); + jerry_value_t value = jerry_get_property_by_index (object, 5); - jerry_value_t retrieved_field_value; - retrieved_field_value = jerry_get_object_field_value_sz (object_p, - field_name, - strlen ((char *) field_name)); - if (!jerry_value_is_error (retrieved_field_value)) - { - ... // usage of the retrieved field - } + ... - jerry_release_value (retrieved_field_value); - jerry_release_object (object_p); + jerry_release_value (value); + jerry_release_value (object); } ``` **See also** -- [jerry_init](#jerry_init) -- [jerry_create_object](#jerry_create_object) -- [jerry_release_object](#jerry_release_object) -- [jerry_add_object_field](#jerry_add_object_field) -- [jerry_get_object_field_value](#jerry_get_object_field_value) -- [jerry_set_object_field_value](#jerry_set_object_field_value) -- [jerry_set_object_field_value_sz](#jerry_set_object_field_value_sz) +- [jerry_has_property](#jerry_has_property) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_delete_property](#jerry_delete_property) +- [jerry_get_property](#jerry_get_property) +- [jerry_set_property](#jerry_set_property) +- [jerry_set_property_by_index](#jerry_set_property_by_index) -# jerry_set_object_field_value +## jerry_set_property **Summary** -Set value of a field (property) in the specified object, i.e. perform [[Put]] operation. +Set a property to the specified object with the given name. + +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +is no longer needed. **Prototype** ```c -bool -jerry_set_object_field_value (jerry_object_t *object_p, - const jerry_char_t *field_name_p, - jerry_value_t field_value); +jerry_value_t +jerry_set_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + const jerry_value_t value_to_set) ``` -- `object_p` - pointer to object. -- `field_name_p` - name of the field. -- `field_value` - field value to set. -- return value - true, if field value was set successfully, i.e. upon the call: - - field value is writable. +- `obj_val` - object value +- `prop_name_val` - property name +- `value_to_set` - value to set +- return value + - true, if success + - thrown error, otherwise **Example** ```c { - jerry_object_t *obj_p; - jerry_value_t val; + jerry_value_t value_to_set; - ... // receive or construct obj_p and val + ... // create or acquire value to set - bool is_ok = jerry_set_object_field_value (obj_p, - (const jerry_char_t *) "some_field_name", - val); + jerry_value_t glob_obj = jerry_get_global_object (); + jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "my_prop"); + + jerry_set_property (glob_obj, prop_name, value_to_set); + + jerry_release_value (prop_name); + + ... + + jerry_release_value (value_to_set); + jerry_release_value (glob_obj); } ``` **See also** -- [jerry_create_object](#jerry_create_object) -- [jerry_get_object_field_value](#jerry_get_object_field_value) -- [jerry_get_object_field_value_sz](#jerry_set_object_field_value_sz) -- [jerry_set_object_field_value_sz](#jerry_set_object_field_value_sz) +- [jerry_has_property](#jerry_has_property) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_delete_property](#jerry_delete_property) +- [jerry_get_property](#jerry_get_property) +- [jerry_get_property_by_index](#jerry_get_property_by_index) +- [jerry_set_property_by_index](#jerry_set_property_by_index) -# jerry_set_object_field_value_sz +## jerry_set_property_by_index **Summary** -Set value of field in the specified object. +Set indexed value in the specified object + +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +is no longer needed. **Prototype** ```c -bool -jerry_set_object_field_value_sz (jerry_object_t *object_p, - const jerry_char_t *field_name_p, - jerry_size_t field_name_size, - const jerry_value_t field_value); +jerry_value_t +jerry_set_property_by_index (const jerry_value_t obj_val, + uint32_t index, + const jerry_value_t value_to_set); ``` -- `object_p` - pointer to object -- `field_name_p` - name of the field -- `field_name_size` - size of field name in bytes -- `field_value` - field value to set +- `obj_val` - object value +- index - index number +- `value_to_set` - value to set - return value - - true, if field value was set successfully - - false, otherwise + - true, if field value was set successfully + - thrown exception, otherwise **Example** ```c { - jerry_object_t *obj_p; - jerry_char_t field_name[] = "some_field_name"; - jerry_value_t val; + jerry_value_t object; + jerry_value_t value_to_set; + + ... // create or acquire object and value to set - ... // receive or construct obj_p and val + jerry_value_t ret_val = jerry_set_property_by_index (object, 5, value_to_set); - bool is_ok = jerry_set_object_field_value_sz (obj_p, - field_name, - strlen ((char *) field_name), - val); + ... + + jerry_release_value (value_to_set); + jerry_release_value (ret_val); + jerry_release_value (object); } ``` **See also** -- [jerry_create_object](#jerry_create_object) -- [jerry_get_object_field_value](#jerry_get_object_field_value) -- [jerry_get_object_field_value_sz](#jerry_set_object_field_value_sz) -- [jerry_set_object_field_value](#jerry_set_object_field_value) +- [jerry_has_property](#jerry_has_property) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_delete_property](#jerry_delete_property) +- [jerry_get_property](#jerry_get_property) +- [jerry_set_property](#jerry_set_property) +- [jerry_get_property_by_index](#jerry_get_property_by_index) -# jerry_get_object_native_handle +## jerry_init_property_descriptor_fields **Summary** -Get native handle, previously associated with specified object. +Initialize property descriptor. **Prototype** ```c -bool -jerry_get_object_native_handle (jerry_object_t *object_p, - uintptr_t *out_handle_p); +void +jerry_init_property_descriptor_fields (jerry_property_descriptor_t *prop_desc_p); ``` -- `object_p` - pointer to object to get handle from. -- `out_handle_p` - handle value (output parameter). -- return value - true, if there is handle associated with the object. +- `prop_desc_p` - pointer to property descriptor **Example** ```c { - jerry_object_t *obj_p; - uintptr_t handle_set; - - ... // receive or construct obj_p and handle_set value + jerry_property_descriptor_t prop_desc; + jerry_init_property_descriptor_fields (&prop_desc); - jerry_set_object_native_handle (obj_p, handle_set, NULL); - - ... + ... // usage of prop_desc - uintptr_t handle_get; - bool is_there_associated_handle = jerry_get_object_native_handle (obj_p, &handle_get); + jerry_free_property_descriptor_fields (&prop_desc); } ``` **See also** -- [jerry_create_object](#jerry_create_object) -- [jerry_set_object_native_handle](#jerry_set_object_native_handle) +- [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) + -# jerry_set_object_native_handle +## jerry_define_own_property **Summary** -Set native handle and, optionally, "free" callback for the specified object. +Define a property to the specified object with the given name. -If native handle or "free" callback were already set for the object, corresponding value is updated. +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +is no longer needed. **Prototype** ```c -void -jerry_set_object_native_handle (jerry_object_t *object_p, - uintptr_t handle, - jerry_object_free_callback_t freecb_p); +jerry_value_t +jerry_define_own_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + const jerry_property_descriptor_t *prop_desc_p); ``` -- `object_p` - pointer to object to set handle in; -- `handle` - handle value; -- `freecb_p` - pointer to "free" callback or NULL (if not NULL the callback would be called upon - GC of the object). +- `obj_val` - object value +- `prop_name_val` - property name +- `prop_desc_p` - pointer to property descriptor +- return value + - true, if success + - thrown error, otherwise **Example** ```c { - jerry_object_t *obj_p; - uintptr_t handle_set; + jerry_value_t global_obj_val = jerry_get_global_object (); - ... // receive or construct obj_p and handle_set value + jerry_property_descriptor_t prop_desc; + jerry_init_property_descriptor_fields (&prop_desc); - jerry_set_object_native_handle (obj_p, handle_set, NULL); + jerry_value_t value_to_set; - ... + ... // create or acquire value to set - uintptr_t handle_get; - bool is_there_associated_handle = jerry_get_object_native_handle (obj_p, &handle_get); + prop_desc.is_value_defined = true; + prop_desc.value = value_to_set; + + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); + jerry_define_own_property (global_obj_val, prop_name, &prop_desc); + jerry_release_value (prop_name); + + jerry_free_property_descriptor_fields (&prop_desc); + jerry_release_value (global_obj_val); } ``` **See also** -- [jerry_create_object](#jerry_create_object) -- [jerry_get_object_native_handle](#jerry_get_object_native_handle) +- [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) + -# jerry_is_function +## jerry_get_own_property_descriptor **Summary** -Check whether the specified object is a function object. +Construct property descriptor from specified property. **Prototype** ```c bool -jerry_is_function (const jerry_object_t *object_p); +jerry_get_own_property_descriptor (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + jerry_property_descriptor_t *prop_desc_p); ``` -- `object_p` - pointer to object to check; -- return value - boolean, indicating whether the specified object can be called as function. +- `obj_val` - object value +- `prop_name_val` - property name +- `prop_desc_p` - pointer to property descriptor +- return value **Example** ```c { - jerry_value_t val; + jerry_value_t global_obj_val = jerry_get_global_object (); - ... // receiving val + jerry_property_descriptor_t prop_desc; + jerry_init_property_descriptor_fields (&prop_desc); - if (jerry_value_is_object (val)) - { - if (jerry_is_function (jerry_get_object_value (val))) - { - // the object is function object - } - } + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); + jerry_get_own_property_descriptor (global_obj_val, prop_name, &prop_desc); + jerry_release_value (prop_name); + + ... // usage of property descriptor + + jerry_free_property_descriptor_fields (&prop_desc); + jerry_release_value (global_obj_val); } ``` **See also** -- [jerry_is_constructor](#jerry_is_constructor) -- [jerry_call_function](#jerry_call_function) +- [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) -# jerry_is_constructor +## jerry_free_property_descriptor_fields **Summary** -Check whether the specified object is a constructor function object. +Free fields of property descriptor (setter, getter and value). **Prototype** ```c -bool -jerry_is_constructor (const jerry_object_t *object_p); +void +jerry_free_property_descriptor_fields (const jerry_property_descriptor_t *prop_desc_p); ``` -- `object_p` - pointer to object to check. -- return value - boolean, indicating whether the specified object can be called as constructor. +- `prop_desc_p` - pointer to property descriptor **Example** ```c { - jerry_value_t val; + jerry_property_descriptor_t prop_desc; + jerry_init_property_descriptor_fields (&prop_desc); - ... // receiving val + ... // usage of property descriptor - if (jerry_value_is_object (val)) - { - if (jerry_is_constructor (jerry_get_object_value (val))) - { - // the object is constructor function object - } - } + jerry_free_property_descriptor_fields (&prop_desc); } ``` **See also** -- [jerry_is_function](#jerry_is_function) -- [jerry_construct_object](#jerry_construct_object) +- [jerry_init_property_descriptor_fields](#jerry_init_property_descriptor_fields) +- [jerry_define_own_property](#jerry_define_own_property) +- [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) -# jerry_call_function +## jerry_call_function **Summary** -Call function object. +Call function specified by a function 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_call_function (jerry_object_t *function_object_p, - jerry_object_t *this_arg_p, +jerry_call_function (const jerry_value_t func_obj_val, + const jerry_value_t this_val, const jerry_value_t args_p[], - uint16_t args_count); + jerry_size_t args_count); ``` -- `function_object_p` - the function object to call; -- `this_arg_p` - object to use as 'this' during the invocation, or NULL - to set the Global object - as 'this'; -- `args_p`, `args_count` - array of arguments and number of them; -- return value - function's return value - -Returned value must be freed with [jerry_release_object](#jerry_release_object) when it is no -longer needed. +- `func_obj_val` - the function object to call +- `this_val` - object for 'this' binding +- `args_p` - function's call arguments +- `args_count` - number of arguments +- return value - returned jerry value of the called function **Example** @@ -2131,21 +2465,18 @@ longer needed. ... // receiving val - if (jerry_value_is_object (val)) + if (jerry_value_is_function (val)) { - if (jerry_is_function (jerry_get_object_value (val))) - { - jerry_value_t ret_val; - - ret_val = jerry_call_function (jerry_get_object_value (val), NULL, NULL, 0); + jerry_value_t this_val = jerry_create_undefined (); + jerry_value_t ret_val = jerry_call_function (val, this_val, NULL, 0); - if (!jerry_value_is_error (ret_val)) - { - ... // handle return value - } - - jerry_release_value (ret_val); + if (!jerry_value_has_error_flag (ret_val)) + { + ... // handle return value } + + jerry_release_value (ret_val); + jerry_release_value (this_val); } } ``` @@ -2156,27 +2487,28 @@ longer needed. - [jerry_create_external_function](#jerry_create_external_function) -# jerry_construct_object +## jerry_construct_object **Summary** Construct object, invoking specified function object as constructor. +*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_construct_object (jerry_object_t *function_object_p, +jerry_construct_object (const jerry_value_t func_obj_val, const jerry_value_t args_p[], uint16_t args_count); ``` -- `function_object_p` - the function object to invoke. -- `args_p`, `args_count` - array of arguments and number of them. -- return value - return value of function invoked as constructor, i.e. like with 'new' operator. - -*Note*: Returned value must be freed with [jerry_release_object](#jerry_release_object) when -it is no longer needed. +- `func_obj_val` - function object to call +- `args_p` - function's call arguments +- `args_count` - number of arguments +- return value - returned value of the invoked constructor **Example** @@ -2186,21 +2518,16 @@ it is no longer needed. ... // receiving val - if (jerry_value_is_object (val)) + if (jerry_is_constructor (val)) { - if (jerry_is_function (jerry_get_object_value (val))) - { - jerry_value_t ret_val; - - ret_val = jerry_construct_object (jerry_get_object_value (val), NULL, 0); + jerry_value_t ret_val = jerry_construct_object (val, NULL, 0); - if (!jerry_value_is_error (ret_val)) - { - ... // handle return value - } - - jerry_release_value (ret_val); + if (!jerry_value_has_error_flag (ret_val)) + { + ... // handle return value } + + jerry_release_value (ret_val); } } ``` @@ -2210,431 +2537,386 @@ it is no longer needed. - [jerry_is_constructor](#jerry_is_constructor) -# jerry_external_handler_t - -**Summary** - -The data type represents pointer to call handler of a native function object. - -**Structure** - -```c -typedef bool (* jerry_external_handler_t) (const jerry_object_t *function_obj_p, - const jerry_value_t this_p, - const jerry_value_t args_p[], - const uint16_t args_count, - jerry_value_t *ret_val_p); -``` - -**See also** - -- [jerry_create_external_function](#jerry_create_external_function) - - -# jerry_create_external_function +## jerry_get_object_keys **Summary** -Create an external function object. +Get keys of the specified object value. **Prototype** ```c -jerry_object_t * -jerry_create_external_function (jerry_external_handler_t handler_p); +jerry_value_t +jerry_get_object_keys (const jerry_value_t obj_val); ``` -- `handler_p` - pointer to native handler of the function object; -- return value - pointer to constructed external function object. - -Received pointer should be released with [jerry_release_object](#jerry_release_object), when -the value is no longer needed. +- `obj_val` - object value +- return value + - array object value, if success + - thrown error, otherwise **Example** ```c -static bool -handler (const jerry_object_t *function_obj_p, - const jerry_value_t this_p, - const jerry_value_t args_p[], - const uint16_t args_cnt, - jerry_value_t *ret_val_p) -{ - printf ("native handler called!\n"); - - *ret_val_p = jerry_create_boolean_value (true); - return true; -} - { - jerry_object_t *obj_p = jerry_create_external_function (handler); - jerry_object_t *glob_obj_p = jerry_get_global (); + jerry_value_t object; + ... // create or acquire object - jerry_value_t val = jerry_create_object_value (obj_p); + jerry_value_t keys_array = jerry_get_object_keys (object); - // after this, script can invoke the native handler through "handler_field (1, 2, 3);" - jerry_set_object_field_value (glob_obj_p, "handler_field", val); + ... // usage of keys_array - jerry_release_object (glob_obj_p); - jerry_release_object (obj_p); + jerry_release_value (keys_array); } ``` **See also** -- [jerry_external_handler_t](#jerry_external_handler_t) -- [jerry_is_function](#jerry_is_function) -- [jerry_call_function](#jerry_call_function) -- [jerry_release_object](#jerry_release_object) +- [jerry_get_property](#jerry_get_property) +- [jerry_set_property](#jerry_set_property) -# jerry_create_array_object +## jerry_get_prototype **Summary** -Create new JavaScript array object. - -*Note*: Returned value must be freed with [jerry_release_object](#jerry_release_object) when it -is no longer needed. +Get the prototype of the specified object. **Prototype** ```c -jerry_object_t * -jerry_create_array_object (jerry_size_t array_size); +jerry_value_t +jerry_get_prototype (const jerry_value_t obj_val); ``` - - `array_size` - size of array; - - return value is pointer to the created array object. +- `obj_val` - object value +- return value + - object value, if success + - null or thrown error, otherwise - **Example** +**Example** ```c { - jerry_object_t *array_object_p = jerry_create_array_object (10); + jerry_value_t object; + ... // create or acquire object - ... + jerry_value_t prototype = jerry_get_prototype (object); + + ... // usage of prototype object - jerry_release_object (array_object_p); + jerry_release_value (prototype); + jerry_release_value (object); } ``` **See also** -- [jerry_acquire_object](#jerry_acquire_object) -- [jerry_release_object](#jerry_release_object) -- [jerry_set_array_index_value](#jerry_set_array_index_value) -- [jerry_get_array_index_value](#jerry_get_array_index_value) -- [jerry_add_object_field](#jerry_add_object_field) -- [jerry_delete_object_field](#jerry_delete_object_field) -- [jerry_get_object_field_value](#jerry_get_object_field_value) -- [jerry_set_object_field_value](#jerry_set_object_field_value) -- [jerry_get_object_native_handle](#jerry_get_object_native_handle) -- [jerry_set_object_native_handle](#jerry_set_object_native_handle) +- [jerry_set_prototype](#jerry_set_prototype) -# jerry_set_array_index_value +## jerry_set_prototype **Summary** -Set value of an indexed element in the specified array object. +Set the prototype of the specified object. **Prototype** ```c -bool -jerry_set_array_index_value (jerry_object_t *array_object_p, - jerry_length_t index, - jerry_value_t value); +jerry_value_t +jerry_get_prototype (const jerry_value_t obj_val, + const jerry_value_t proto_obj_val); ``` -- `array_object_p` - pointer to the array object; -- `index` - index of the array element; -- `value` - value to set; -- return value - true, if value was set successfully. +- `obj_val` - object value +- `proto_obj_val` - prototype object value +- return value + - true, if success + - thrown error, otherwise **Example** ```c { - jerry_object_t *array_object_p = jerry_create_array_object (10); - jerry_value_t val; + jerry_value_t object; + jerry_value_t prototype; - ... // receive or construct val + ... // create or acquire object and prototype - jerry_set_array_index_value (array_object_p, 5, val); + jerry_value_t ret_val = jerry_set_prototype (object, prototype); - jerry_release_object (array_object_p); + jerry_release_value (ret_val); + jerry_release_value (prototype); + jerry_release_value (object); } ``` **See also** -- [jerry_create_array_object](#jerry_create_array_object) +- [jerry_get_prototype](#jerry_get_prototype) -# jerry_get_array_index_value +## jerry_get_object_native_handle **Summary** -Get value of an indexed element in the specified array object. +Get native handle, previously associated with specified object. **Prototype** ```c bool -jerry_get_array_index_value (jerry_object_t *array_object_p, - jerry_length_t index, - jerry_value_t *value_p); +jerry_get_object_native_handle (const jerry_value_t obj_val, + uintptr_t *out_handle_p); ``` -- `array_object_p` - pointer to the array object; -- `index` - index of the array element; -- `value_p` - retrieved indexed value (output parameter); -- return value - true, if value was retrieved successfully. +- `obj_val` - object value +- `out_handle_p` - handle value (output parameter). +- return value + - true, if there is handle associated with the object + - false, otherwise **Example** ```c { - jerry_object_t *array_object_p; - ... // receive or construct array_object_p + jerry_value_t object; + uintptr_t handle_set; - jerry_value_t val; - bool is_ok = jerry_get_array_index_value (array_object_p, 5, &val); - if (is_ok) - { - ... // usage of 'val' - } + ... // receive or construct object and handle_set value + + jerry_set_object_native_handle (object, handle_set, NULL); + + ... + + uintptr_t handle_get; + bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get); } ``` **See also** -- [jerry_create_array_object](#jerry_create_array_object) - +- [jerry_create_object](#jerry_create_object) +- [jerry_set_object_native_handle](#jerry_set_object_native_handle) -# jerry_create_error +## jerry_set_object_native_handle **Summary** -Create new JavaScript error object. It should be throwed from a handle attached to an external -function object. +Set native handle and, optionally, free callback for the specified object + +*Note*: If native handle was already set for the object, its value is updated. + +*Note*: If free callback is specified, it is set to be called upon specified JS-object is freed (by GC). + Otherwise, if NULL is specified for free callback pointer, free callback is not created and, if + a free callback was added earlier for the object, it is removed. **Prototype** ```c -jerry_object_t * -jerry_create_error (jerry_error_t error_type, - const jerry_char_t *message_p); +void +jerry_set_object_native_handle (const jerry_value_t obj_val, + uintptr_t handle, + jerry_object_free_callback_t freecb_p); ``` -- `error_type` - error type of object; -- `message_p` - human-readable description of the error; -- return value is pointer to the created error object. +- `obj_val` - object value to set handle in +- `handle` - handle value +- `freecb_p` - pointer to "free" callback or NULL **Example** ```c -static bool -handler (const jerry_object_t *function_obj_p, - const jerry_value_t this_p, - const jerry_value_t args_p[], - const uint16_t args_cnt, - jerry_value_t *ret_val_p) { - jerry_object_t *error_p = jerry_create_error (JERRY_ERROR_TYPE, - (jerry_char_t * ) "error"); - - jerry_acquire_object (error_p); - *ret_val_p = jerry_create_error_value (error_p); - - jerry_release_object (error_p); - - return false; -} + jerry_value_t object; + uintptr_t handle_set; -{ - jerry_object_t *throw_obj_p = jerry_create_external_function (handler); - jerry_object_t *glob_obj_p = jerry_get_global (); + ... // receive or construct object and handle_set value - jerry_value_t val = jerry_create_object_value (throw_obj_p); + jerry_set_object_native_handle (object, handle_set, NULL); - // after this, script can invoke the native handler through "error_func ();" - // and "error_func" will throw an error when called. - jerry_set_object_field_value (glob_obj_p, "error_func", val); + ... - jerry_release_object (glob_obj_p); - jerry_release_object (throw_obj_p); + uintptr_t handle_get; + bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get); } ``` **See also** -- [jerry_external_handler_t](#jerry_external_handler_t) -- [jerry_is_function](#jerry_is_function) -- [jerry_call_function](#jerry_call_function) -- [jerry_release_object](#jerry_release_object) -- [jerry_create_external_function](#jerry_create_external_function) +- [jerry_create_object](#jerry_create_object) +- [jerry_get_object_native_handle](#jerry_get_object_native_handle) -# jerry_register_external_magic_strings +## jerry_foreach_object_property **Summary** -Registers an external magic string array. +Applies the given function to every property in the given object. **Prototype** ```c -void -jerry_register_external_magic_strings (const jerry_char_ptr_t *ex_str_items, - uint32_t count, - const jerry_length_t *str_lengths); +bool +jerry_foreach_object_property (jerry_value_t obj_val, + jerry_object_property_foreach_t foreach_p, + void *user_data_p); ``` -- `ex_str_items` - character arrays, representing external magic strings' contents -- `count number` - of the strings -- `str_lengths` - lengths of the strings +- `obj_val` - object value +- `foreach_p` - foreach function, that will be apllied for each property +- `user_data_p` - user data for foreach function +- return value + - true, if object fields traversal was performed successfully, i.e.: + - no unhandled exceptions were thrown in object fields traversal + - object fields traversal was stopped on callback that returned false + - false, otherwise, if getter of field threw a exception or unhandled exceptions were thrown + during traversal **Example** ```c +bool foreach_function (const jerry_value_t prop_name, + const jerry_value_t prop_value, + void *user_data_p) { - jerry_init (JERRY_FLAG_EMPTY); - // must be static, because 'jerry_register_external_magic_strings' does not copy - static const jerry_char_ptr_t magic_string_items[] = { - (const jerry_char_ptr_t) "magicstring1", - (const jerry_char_ptr_t) "magicstring2", - (const jerry_char_ptr_t) "magicstring3" - }; - uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t)); + ... // implementation of the foreach function + +} + +{ + jerry_value_t object; + ... // receive or construct object + + double data = 3.14; // example data + + jerry_foreach_object_property (object, foreach_function, &data); - // must be static, because 'jerry_register_external_magic_strings' does not copy - static const jerry_length_t magic_string_lengths[] = { - (jerry_length_t)strlen (magic_string_items[0]), - (jerry_length_t)strlen (magic_string_items[1]), - (jerry_length_t)strlen (magic_string_items[2]) - }; - jerry_register_external_magic_strings (magic_string_items, - num_magic_string_items, - magic_string_lengths); } ``` **See also** -- [jerry_init](#jerry_init) +- [jerry_object_property_foreach_t](#jerry_object_property_foreach_t) -# jerry_value_to_string +# Snapshot functions + +## jerry_parse_and_save_snapshot **Summary** -Creates the textual representation of an API value using the ToString ecma builtin operation. +Generate snapshot from the specified source code. **Prototype** ```c -jerry_value_t -jerry_value_to_string (const jerry_value_t value); +size_t +jerry_parse_and_save_snapshot (const jerry_char_t *source_p, + size_t source_size, + bool is_for_global, + bool is_strict, + uint8_t *buffer_p, + size_t buffer_size); ``` -- `value` - api value. -- return value - textual representation of the given value. +- `source_p` - script source, it must be a valid utf8 string. +- `source_size` - script source size, in bytes. +- `is_for_global` - snapshot would be executed as global (true) or eval (false). +- `is_strict` - stric mode +- `buffer_p` - buffer to save snapshot to. +- `buffer_size` - the buffer's size. +- return value + - the size of snapshot, 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 current configuration through + JERRY_ENABLE_SNAPSHOT) + - 0 otherwise. **Example** ```c { - jerry_value_t value; + jerry_init (JERRY_INIT_EMPTY); - ... // receive or construct value + static uint8_t global_mode_snapshot_buffer[1024]; + const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();"; - jerry_value_t to_string_value = jerry_value_to_string (&value); + size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p, + strlen (code_to_snapshot_p), + true, + false, + global_mode_snapshot_buffer, + sizeof (global_mode_snapshot_buffer)); - jerry_release_value (to_string_value); + jerry_cleanup (); } ``` - -# jerry_object_field_foreach_t - -**Summary** - -Function type applied for each fields of an object by API function [jerry_foreach_object_field](#jerry_foreach_object_field). - -**Definition** - -```c -typedef bool (*jerry_object_field_foreach_t) (const jerry_string_t *field_name_p, - const jerry_value_t field_value, - void *user_data_p); -``` - -- `field_name_p` - name of the field -- `field_value` - value of the field -- `user_data_p` - user data -- return value - - true, if the operation executed successfully - - false, otherwise - **See also** -- [jerry_foreach_object_field](#jerry_foreach_object_field) +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_exec_snapshot](#jerry_exec_snapshot) -# jerry_foreach_object_field +## jerry_exec_snapshot **Summary** -Applies the given function to every fields in the given objects. +Execute snapshot from the specified buffer. + +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +is no longer needed. **Prototype** ```c -bool -jerry_foreach_object_field (jerry_object_t *object_p, - jerry_object_field_foreach_t foreach_p, - void *user_data_p); +jerry_value_t +jerry_exec_snapshot (const void *snapshot_p, + size_t snapshot_size, + bool copy_bytecode); ``` -- `object_p` - pointer to object -- `foreach_p` - foreach function, that will be apllied for each fields -- `user_data_p` - user data for foreach function +- `snapshot_p` - pointer to snapshot +- `snapshot_size` - size of snapshot +- `copy_bytecode` - flag, indicating whether the passed snapshot buffer should be copied to the + engine's memory. If set the engine should not reference the buffer after the function returns + (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not + set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup). - return value - - true, if object fields traversal was performed successfully, i.e.: - - no unhandled exceptions were thrown in object fields traversal - - object fields traversal was stopped on callback that returned false - - false, otherwise, if getter of field threw a exception or unhandled exceptions were thrown - during traversal + - result of bytecode, if run was successful + - thrown error, otherwise **Example** ```c -bool foreach_function (const jerry_string_t *field_name_p, - const jerry_value_t field_value, - void *user_data_p) -{ - - ... // implementation of the foreach function - -} - { - jerry_init (JERRY_FLAG_EMPTY); + jerry_value_t res; + static uint8_t global_mode_snapshot_buffer[1024]; + const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();"; - jerry_object_t* object_p; - ... // receive or construct object_p + jerry_init (JERRY_INIT_EMPTY); + size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p, + strlen (code_to_snapshot_p), + true, + global_mode_snapshot_buffer, + sizeof (global_mode_snapshot_buffer)); + jerry_cleanup (); - double data = 3.14; // example data + jerry_init (JERRY_INIT_EMPTY); - jerry_foreach_object_field (object_p, foreach_function, &data); + res = (jerry_exec_snapshot (global_mode_snapshot_buffer, + global_mode_snapshot_size, + false); + jerry_cleanup (); } ``` **See also** -- [jerry_object_field_foreach_t](#jerry_object_field_foreach_t) +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot) diff --git a/jerry-core/jerry-api.h b/jerry-core/jerry-api.h index 2407747305..82868d5b55 100644 --- a/jerry-core/jerry-api.h +++ b/jerry-core/jerry-api.h @@ -158,7 +158,7 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na /** - * Logger functions + * Logger */ #ifdef JERRY_ENABLE_LOG extern int jerry_debug_level; diff --git a/jerry-core/jerry.c b/jerry-core/jerry.c index 49d655cda2..65cdaf0dfc 100644 --- a/jerry-core/jerry.c +++ b/jerry-core/jerry.c @@ -832,7 +832,7 @@ jerry_create_external_function (jerry_external_handler_t handler_p) /**< pointer } /* jerry_create_external_function */ /** - * Creates a jerry_value_t representing a null value. + * Creates a jerry_value_t representing a number value. * * Note: * returned value must be freed with jerry_release_value, when it is no longer needed. @@ -882,7 +882,7 @@ jerry_create_object (void) * Note: * returned value must be freed with jerry_release_object, when it is no longer needed. * - * @return string value + * @return value of the created string */ jerry_value_t jerry_create_string (const jerry_char_t *str_p) /**< pointer to string */ @@ -896,7 +896,7 @@ jerry_create_string (const jerry_char_t *str_p) /**< pointer to string */ * Note: * returned value must be freed with jerry_release_object when it is no longer needed. * - * @return string value + * @return value of the created string */ jerry_value_t jerry_create_string_sz (const jerry_char_t *str_p, /**< pointer to string */ @@ -1122,7 +1122,7 @@ jerry_get_property (const jerry_value_t obj_val, /**< object value */ } /* jerry_get_property */ /** - * Get value of field in the specified object + * Get value by an index from the specified object. * * Note: * returned value must be freed with jerry_release_value, when it is no longer needed. @@ -1210,7 +1210,7 @@ jerry_set_property_by_index (const jerry_value_t obj_val, /**< object value */ } /* jerry_set_property_by_index */ /** - * Initialize property descriptor + * Initialize property descriptor. */ void jerry_init_property_descriptor_fields (jerry_property_descriptor_t *prop_desc_p) /**< property descriptor */ @@ -1314,7 +1314,7 @@ jerry_define_own_property (const jerry_value_t obj_val, /**< object value */ } /* jerry_define_own_property */ /** - * Construct property descriptor from specified property + * Construct property descriptor from specified property. * * @return true - if success, the prop_desc_p fields contains the property info * false - otherwise, the prop_desc_p is unchanged @@ -1386,7 +1386,7 @@ jerry_get_own_property_descriptor (const jerry_value_t obj_val, /**< object val } /* jerry_get_own_property_descriptor */ /** - * Free fields of property descriptor (setter, getter and value) + * Free fields of property descriptor (setter, getter and value). */ void jerry_free_property_descriptor_fields (const jerry_property_descriptor_t *prop_desc_p) /**< property descriptor */ @@ -1674,7 +1674,7 @@ jerry_set_object_native_handle (const jerry_value_t obj_val, /**< object to set } /* jerry_set_object_native_handle */ /** - * Applies the given function to the every fields in the objects + * Applies the given function to the every property in the object. * * @return true, if object fields traversal was performed successfully, i.e.: * - no unhandled exceptions were thrown in object fields traversal; @@ -2208,8 +2208,8 @@ snapshot_load_compiled_code (const uint8_t *snapshot_data_p, /**< snapshot data * Note: * returned value must be freed with jerry_release_value, when it is no longer needed. * - * @return true - if success - * false or thrown error - otherwise + * @return result of bytecode - if run was successful + * thrown error - otherwise */ jerry_value_t jerry_exec_snapshot (const void *snapshot_p, /**< snapshot */