diff --git a/03.api.md b/03.api.md index d86259005..7a646698f 100644 --- a/03.api.md +++ b/03.api.md @@ -358,51 +358,6 @@ jerry_api_gc (); ``` -# jerry_api_value_t - -**Summary** -The data type represents any JavaScript value that can be sent to or received from the engine. - -Type of value is identified by `jerry_api_value_t::type`, and can be one of the following: - -- `JERRY_API_DATA_TYPE_VOID` - no return value -- `JERRY_API_DATA_TYPE_UNDEFINED` - JavaScript undefined; -- `JERRY_API_DATA_TYPE_NULL` - JavaScript null; -- `JERRY_API_DATA_TYPE_BOOLEAN` - boolean; -- `JERRY_API_DATA_TYPE_FLOAT32` - number; -- `JERRY_API_DATA_TYPE_FLOAT64` - number; -- `JERRY_API_DATA_TYPE_UINT32` - number; -- `JERRY_API_DATA_TYPE_STRING` - string; -- `JERRY_API_DATA_TYPE_OBJECT` - reference to JavaScript object. - -**Structure** - -```c -typedef struct jerry_api_value_t -{ - jerry_api_data_type_t type; - - union - { - bool v_bool; - - float v_float32; - double v_float64; - - uint32_t v_uint32; - - jerry_api_string_t v_string; - jerry_api_object_t v_object; - } u; -} jerry_api_value_t; -``` - -**See also** - -- [jerry_api_eval](#jerry_api_eval) -- [jerry_api_call_function](#jerry_api_call_function) -- [jerry_api_construct_object](#jerry_api_construct_object) - # jerry_api_eval **Summary** @@ -419,12 +374,12 @@ jerry_api_eval (const jerry_api_char_t *source_p, jerry_api_value_t *retval_p); ``` -- `source_p` - source code to evaluate; -- `source_size` - length of the source code; -- `is_direct` - whether to perform `eval` in "direct" mode (possible only if `eval` invocation is performed from native function, called from JavaScript); -- `is_strict` - perform `eval` as it is called from "strict mode" code; -- `retval_p` - value, returned by `eval` (output parameter); -- returned value - completion code that indicates whether run performed successfully (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`). +- `source_p` - source code to evaluate +- `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) +- returned value - completion code that indicates whether run performed successfully (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`) **Example** @@ -441,11 +396,871 @@ jerry_api_eval (const jerry_api_char_t *source_p, **See also** -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_create_external_function](#jerry_api_create_external_function) - [jerry_external_handler_t](#jerry_external_handler_t) +# jerry_api_create_undefined_value + +**Summary** + +Creates a jerry_api_value_t with type JERRY_API_DATA_TYPE_UNDEFINED representing an undefined value. The value have to be released by [jerry_api_release_value](#jerry_api_release_value). + +**Prototype** + +```c +jerry_api_value_t +jerry_api_create_undefined_value (void); +``` +- return value - a jerry_api_value_t with type JERRY_API_DATA_TYPE_UNDEFINED + +**Example** + +```c +{ + jerry_init(JERRY_FLAG_EMPTY); + jerry_api_value_t undefined_value = jerry_api_create_undefined_value(); + + ... // usage of the value + + jerry_api_release_value(&undefined_value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_create_void_value + +**Summary** + +Creates a jerry_api_value_t with type JERRY_API_DATA_TYPE_VOID representing a void value. The value have to be released by [jerry_api_release_value](#jerry_api_release_value). + +**Prototype** + +```c +jerry_api_value_t +jerry_api_create_void_value (void); +``` +- return value - a jerry_api_value_t with type JERRY_API_DATA_TYPE_VOID + +**Example** + +```c + jerry_init(JERRY_FLAG_EMPTY); + jerry_api_value_t void_value = jerry_api_create_void_value(); + + ... // usage of the value + + jerry_api_release_value(&void_value); +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_create_null_value + +**Summary** + +Creates a jerry_api_value_t with type JERRY_API_DATA_TYPE_NULL represneting a null value. The value have to be released by [jerry_api_release_value](#jerry_api_release_value). + +**Prototype** + +```c +jerry_api_value_t +jerry_api_create_null_value (void); +``` +- return value - a jerry_api_value_t with type JERRY_API_DATA_TYPE_NULL + +**Example** + +```c +{ + jerry_init(JERRY_FLAG_EMPTY); + jerry_api_value_t null_value = jerry_api_create_null_value(); + + ... // usage of the value + + jerry_api_release_value(&null_value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_create_boolean_value + +**Summary** + +Creates a JERRY_API_DATA_TYPE_BOOLEAN jerry_api_value_t from the given boolean parameter. The value have to be released by [jerry_api_release_value](#jerry_api_release_value). + +**Prototype** +```c +jerry_api_value_t +jerry_api_create_boolean_value (bool value); +``` +- `value` - bool value from which a jerry_api_value_t will be created +- return value - a jerry_api_value_t created from the given boolean argument + +**Example** + +```c + jerry_init(JERRY_FLAG_EMPTY); + jerry_api_value_t boolean_value = jerry_api_create_boolean_value(true); + + ... // usage of the value + + jerry_api_release_value(&boolean_value); +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_create_number_value + +**Summary** + +Creates a jerry_api_value_t from the given double parameter. The v_float64 member will be set and the type will be JERRY_API_DATA_TYPE_FLOAT64. The value have to be released by [jerry_api_release_value](#jerry_api_release_value). + +**Prototype** + +```c +jerry_api_value_t +jerry_api_create_number_value (double value); +``` +- `value` - double value from which a jerry_api_value_t will be created +- return value - a jerry_api_value_t created from the given double argument + +**Example** + +```c +{ + jerry_init(JERRY_FLAG_EMPTY); + jerry_api_value_t number_value = jerry_api_create_number_value(3.14); + + ... // usage of the value + + jerry_api_release_value(&number_value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_create_object_value + +**Summary** + +Creates a JERRY_API_DATA_TYPE_OBJECT type jerry_api_value_t from the given jerry_api_object_t parameter. The value have to be released by [jerry_api_release_value](#jerry_api_release_value) when it becomes unnecessary. + +**Prototype** + +```c +jerry_api_value_t +jerry_api_create_object_value (jerry_api_object_t *value); +``` +- `value` - jerry_api_object_t from which a value will be created +- return value - a jerry_api_value_t created from the given jerry_api_object_t argument + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_object_t *object_p = jerry_api_create_object(); + jerry_api_value_t object_value = jerry_api_create_object_value(object_p); + + ... // usage of object_value + + jerry_api_release_value(&object_value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_create_string_sz + +**Summary** + +Creates a string. The caller should release the string with [jerry_api_release_string](#jerry_api_release_string) when the value becomes unnecessary. + +**Prototype** +```c +jerry_api_string_t * +jerry_api_create_string_sz (const jerry_api_char_t *v, + jerry_api_size_t v_size) +``` +- `v` - string from which the result jerry_api_string_t will be created +- `v_size` - size of the string +- return value - a jerry_api_string_t* created from the given jerry_api_char_t* argument + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_char_t char_array[] = "a string"; + jerry_api_string_t *string = jerry_api_create_string_sz (char_array, + lit_zt_utf8_string_size (char_array)); + + ... // usage of string + + jerry_api_release_string(string); +} + +``` + +**See also** + +- [jerry_api_release_string](#jerry_api_release_string) + + +# jerry_api_create_string_value + +**Summary** + +Creates a JERRY_API_DATA_TYPE_STRING type jerry_api_value_t from the given jerry_api_string_t parameter. The value have to be released by [jerry_api_release_value](#jerry_api_release_value) when it becomes unnecessary. + +**Prototype** + +```c +jerry_api_value_t +jerry_api_create_string_value (jerry_api_string_t *value); +``` +- `value` - jerry_api_string_t from which a value will be created +- return value - a jerry_api_value_t created from the given jerry_api_string_t argument + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_char_t char_array[] = "a string"; + jerry_api_string_t *string = jerry_api_create_string_sz (char_array, + lit_zt_utf8_string_size (char_array)); + jerry_api_value_t string_value = jerry_api_create_string_value(string); + + ... // usage of string_value + + jerry_api_release_value(&string_value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_create_error_sz + +**Summary** + +Creates an error object. Caller should release the object with jerry_api_release_object, just when the value becomes unnecessary. + +**Prototype** + +```c +jerry_api_object_t * +jerry_api_create_error_sz (jerry_api_error_t error_type, + const jerry_api_char_t *message_p, + jerry_api_size_t message_size); +``` +- `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 created error object + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_char_t message[] = "error"; + jerry_api_object_t *error_obj = jerry_api_create_error_sz(JERRY_API_ERROR_COMMON, + message, + lit_zt_utf8_string_size (char_array)); + + ... // usage of error_obj + + jerry_api_release_object(error_obj); +} +``` + +**See also** + +- [jerry_api_create_error](#jerry_api_create_error) + + +# jerry_api_get_boolean_value + +**Summary** + +Gets the raw bool value form a jerry_api_value_t value. +If the given jerry_api_value_t structure has type other than JERRY_API_DATA_TYPE_BOOLEAN, JERRY_ASSERT fails. + +**Prototype** + +```c +bool +jerry_api_get_boolean_value (const jerry_api_value_t *value_p); +``` +- `value_p` - pointer to an api value +- return value - the boolean v_bool member of the given jerry_api_value_t structure + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_boolean (&value)) + { + bool raw_value = jerry_api_get_boolean_value (&value); + + ... // usage of raw value + + } + + jerry_api_release_value (&value); +} + +``` + +**See also** + +- [jerry_api_value_is_boolean](#jerry_api_value_is_boolean) +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_get_number_value + +**Summary** + +Gets the number value of the given jerry_api_value_t structure as a raw double. +If the given jerry_api_value_t structure has type JERRY_API_DATA_TYPE_UINT32 v_uint32 member will be returned as a double value. If the given jerry_api_value_t structure has type JERRY_API_DATA_TYPE_FLOAT32 v_float32 member will be returned as a double and if tpye is JERRY_API_DATA_TYPE_FLOAT64 the function returns the v_float64 member. As long as the type is none of the above, JERRY_ASSERT falis. + +**Prototype** + +```c +double +jerry_api_get_number_value (const jerry_api_value_t *value_p); +``` +- `value_p` - pointer to an api value +- return value - the number value of the given jerry_api_value_t structure as a raw double + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_number (&value)) + { + double raw_value = jerry_api_get_number_value (&value); + + ... // usage of raw value + + } + + jerry_api_release_value (&value); +} +``` + +**See also** + +- [jerry_api_value_is_number](#jerry_api_value_is_number) +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_get_object_value + +**Summary** + +Gets the v_object member of the given jerry_api_value_t structure. +If the given jerry_api_value_t structure has type other than JERRY_API_DATA_TYPE_OBJECT, JERRY_ASSERT fails. + +**Prototype** + +```c +jerry_api_object_t * +jerry_api_get_object_value (const jerry_api_value_t *value_p); +``` +- `value_p` - pointer to an api value +- return value - the v_object member of the given jerry_api_value_t structure + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_object (&value)) + { + jerry_api_object_t *raw_value = jerry_api_get_object_value (&value); + + ... // usage of raw value + + } + + jerry_api_release_value(&value); +} +``` + +**See also** + +- [jerry_api_value_is_object](#jerry_api_value_is_object) +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_get_string_value + +**Summary** + +Gets the v_string member of the given jerry_api_value_t structure. +If the given jerry_api_value_t structure has type other than JERRY_API_DATA_TYPE_STRING, JERRY_ASSERT fails. + +**Prototype** + +```c +jerry_api_string_t * +jerry_api_get_string_value (const jerry_api_value_t *value_p); +``` +- `value_p` - pointer to an api value +- return value - the v_string member of the given jerry_api_value_t structure + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_string (&value)) + { + jerry_api_string_t *raw_value = jerry_api_get_string_value (&value); + + ... // usage of raw value + + } + + jerry_api_release_value (&value); +} + +``` + +**See also** + +- [jerry_api_value_is_string](#jerry_api_value_is_string) +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_get_string_size + +**Summary** + +Gets the length of a jerry_api_string_t. + +**Prototype** + +```c +jerry_api_size_t +jerry_api_get_string_size (const jerry_api_string_t *str_p); +``` +- `str_p` - input string +- return value - number of bytes in the buffer needed to represent the string + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_char_t char_array[] = "a string"; + jerry_api_string_t *string = jerry_api_create_string (char_array); + + jerry_api_size_t string_size = jerry_api_get_string_size (); + + ... // usage of string_size + + jerry_api_release_string (string); +} +``` + +**See also** + +- [jerry_api_create_string](#jerry_api_create_string) +- [jerry_api_release_string](#jerry_api_release_string) +- [jerry_api_get_string_length](#jerry_api_get_string_length) + + +# jerry_api_get_string_length + +**Summary** + +Gets the length of a jerry_api_string_t. + +**Prototype** + +```c +jerry_api_length_t +jerry_api_get_string_length (const jerry_api_string_t *str_p); +``` +- `str_p` - input string +- return value - number of characters in the string + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_char_t char_array[] = "a string"; + jerry_api_string_t *string = jerry_api_create_string(char_array); + + jerry_api_length_t string_length = jerry_api_get_string_length(string); + + ... // usage of string_length + + jerry_api_release_string (string); +} +``` + +**See also** + +- [jerry_api_create_string](#jerry_api_create_string) +- [jerry_api_release_string](#jerry_api_release_string) +- [jerry_api_get_string_size](#jerry_api_get_string_size) + + +# jerry_api_value_is_undefined + +**Summary** + +Returns whether the given jerry_api_value_t is an undefined value. + +**Prototype** + +```c +bool +jerry_api_value_is_undefined (const jerry_api_value_t *value_p); +``` +- `value_p` - pointer to api an value +- return value + - true, if the given jerry_api_value_t is an undefined value, more specifically, if it's type field equals JERRY_API_DATA_TYPE_UNDEFINED + - false, otherwise + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_undefined (&value)) + { + ... + } + + jerry_api_release_value (&value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_value_is_void + +**Summary** + +Returns whether the given jerry_api_value_t is a void value. + +**Prototype** + +```c +bool +jerry_api_value_is_void (const jerry_api_value_t *value_p); +`` +- `value_p` - pointer to an api value +- return value + - true, if the given jerry_api_value_t is a void value, more specifically, if it's type field equals JERRY_API_DATA_TYPE_VOID + - false, otherwise + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_void (&value)) + { + ... + } + + jerry_api_release_value (&value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_value_is_boolean + +**Summary** + +Returns whether the given jerry_api_value_t is a boolean value. + +**Prototype** + +```c +bool +jerry_api_value_is_boolean (const jerry_api_value_t *value_p) +``` +- `value_p` - pointer to an api value +- return value + - true, if the given jerry_api_value_t is a boolean value, more specifically, if it's type field equals JERRY_API_DATA_TYPE_BOOLEAN + - false, otherwise + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_boolean (&value)) + { + ... + } + + jerry_api_release_value (&value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_value_is_number + +**Summary** + +Returns whether the given jerry_api_value_t is a number value. + +**Prototype** + +```c +bool +jerry_api_value_is_number (const jerry_api_value_t *value_p); +``` +- `value_p` - pointer to an api value +- return value + - true, if the given jerry_api_value_t is a number value, more specifically, if it's type is JERRY_API_DATA_TYPE_FLOAT32, JERRY_API_DATA_TYPE_FLOAT64 or JERRY_API_DATA_TYPE_UINT32 + - false, otherwise + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_number (&value)) + { + ... + } + + jerry_api_release_value (&value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_value_is_function + +**Summary** + +Returns whether the given jerry_api_value_t is a function object. + +**Prototype** + +```c +bool +jerry_api_value_is_function (const jerry_api_value_t *value_p); +``` +- `value_p` - pointer to an api value +- return value + - true, if the given jerry_api_value_t is a function object, more specifically, if it has JERRY_API_DATA_TYPE_OBJECT type and jerry_api_is_function() functiron return true for its v_object member + - false, otherwise + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_function (&value)) + { + ... + } + + jerry_api_release_value (&value); +} +``` + +**See also** + +- [jerry_api_is_function](#jerry_api_is_function) +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_value_is_null + +**Summary** + +Returns whether the given jerry_api_value_t is a null value. + +**Prototype** + +```c +bool +jerry_api_value_is_null (const jerry_api_value_t *value_p); +``` +- `value_p` - pointer to an api value +- return value + - true, if the given jerry_api_value_t is a null value, more specifically, if it's type is JERRY_API_DATA_TYPE_NULL + - false, otherwise + +**Example** + +```c + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_null (&value)) + { + ... + } + + jerry_api_release_value (&value); +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_value_is_object + +**Summary** + +Returns whether the given jerry_api_value_t is an object. + +**Prototype** + +```c +bool +jerry_api_value_is_object (const jerry_api_value_t *value_p); +``` +- `value_p` - pointer to an api value +- return value + - true, if the given jerry_api_value_t is a null value, more specifically, if it's type is JERRY_API_DATA_TYPE_OBJECT + - false, otherwise + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_object (&value)) + { + ... + } + + jerry_api_release_value (&value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + +# jerry_api_value_is_string + +**Summary** + +Returns whether the given jerry_api_value_t is a string. + +**Prototype** + +```c +bool +jerry_api_value_is_string (const jerry_api_value_t *value_p); +``` +- `value_p` - pointer to an api value +- return value + - true, if the given jerry_api_value_t is a string, more specifically, if it's type is JERRY_API_DATA_TYPE_STRING + - false, otherwise + +**Example** + +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + jerry_api_value_t value; + ... // create or acquire value + + if (jerry_api_value_is_string (&value)) + { + ... + } + + jerry_api_release_value (&value); +} +``` + +**See also** + +- [jerry_api_release_value](#jerry_api_release_value) + + # jerry_api_acquire_value **Summary** @@ -479,7 +1294,6 @@ jerry_api_acquire_value (jerry_api_value_t *value_p); **See also** -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_release_value](#jerry_api_release_value) - [jerry_api_acquire_string](#jerry_api_acquire_string) - [jerry_api_acquire_object](#jerry_api_acquire_object) @@ -521,10 +1335,6 @@ jerry_api_release_value (jerry_api_value_t *value_p); } ``` -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) - # jerry_api_create_string @@ -623,7 +1433,6 @@ jerry_api_string_to_char_buffer (const jerry_api_string_t *string_p, **See also** - [jerry_api_create_string](#jerry_api_create_string) -- [jerry_api_value_t](#jerry_api_value_t) # jerry_api_acquire_string @@ -876,7 +1685,8 @@ jerry_api_add_object_field (jerry_api_object_t *object_p, - `field_name_p` - name of the field; - `field_value_p` - value of the field; - `is_writable` - flag indicating whether the created field should be writable. -- returned value - true, if field was created successfully, i.e. upon the call: +- returned 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. @@ -898,7 +1708,6 @@ jerry_api_add_object_field (jerry_api_object_t *object_p, **See also** -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_create_object](#jerry_api_create_object) # jerry_api_delete_object_field @@ -932,7 +1741,6 @@ jerry_api_delete_object_field (jerry_api_object_t *object_p, **See also** -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_create_object](#jerry_api_create_object) # jerry_api_get_object_field_value @@ -977,8 +1785,9 @@ If value was retrieved successfully, it should be freed with [jerry_api_release_ **See also** -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_create_object](#jerry_api_create_object) +- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) +- [jerry_api_get_object_field_value_sz](#jerry_api_get_object_field_value_sz) # jerry_api_get_object_field_value_sz @@ -1014,19 +1823,20 @@ jerry_api_get_object_field_value_sz (jerry_api_object_t *object_p, jerry_api_value_t field_value = jerry_api_create_number_value(3.14); jerry_api_object_t* object_p = jerry_api_create_object(); - jerry_api_add_object_field(object_p, - field_name, - (jerry_api_size_t)strlen((char*)field_name), - &field_value, true); + jerry_api_add_object_field (object_p, + field_name, + lit_zt_utf8_string_size (field_name), + &field_value, true); jerry_api_value_t retrieved_field_value = jerry_api_create_undefined_value(); - bool is_get_ok = jerry_api_get_object_field_value_sz(object_p, - field_name, - (jerry_api_size_t)strlen((char*)field_name), - &retrieved_field_value); - - // usage of the retrieved field... - + bool is_get_ok = jerry_api_get_object_field_value_sz (object_p, + field_name, + lit_zt_utf8_string_size (field_name), + &retrieved_field_value); + if (is_get_ok) { + ... // usage of the retrieved field + } + jerry_api_release_object(object_p); } ``` @@ -1045,6 +1855,7 @@ jerry_api_get_object_field_value_sz (jerry_api_object_t *object_p, # jerry_api_set_object_field_value **Summary** + Set value of a field (property) in the specified object, i.e. perform [[Put]] operation. **Prototype** @@ -1077,8 +1888,60 @@ jerry_api_set_object_field_value (jerry_api_object_t *object_p, **See also** -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_create_object](#jerry_api_create_object) +- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) +- [jerry_api_get_object_field_value_sz](#jerry_api_set_object_field_value_sz) +- [jerry_api_set_object_field_value_sz](#jerry_api_set_object_field_value_sz) + + +# jerry_api_set_object_field_value_sz + +**Summary** + +Set value of field in the specified object. + +**Prototype** + +```c +bool +jerry_api_set_object_field_value_sz (jerry_api_object_t *object_p, + const jerry_api_char_t *field_name_p, + jerry_api_size_t field_name_size, + const jerry_api_value_t *field_value_p); +``` + +- `object_p` - object +- `field_name_p` - name of the field +- `field_name_size` - size of field name in bytes +- `field_value_p` - field value to set +- return value + - true, if field value was set successfully + - false, otherwise + +**Example** + +```c +{ + jerry_api_object_t *obj_p; + jerry_api_char_t field_name[] = "some_field_name"; + jerry_api_value_t val; + + ... // receive or construct obj_p and val + + bool is_ok = jerry_api_set_object_field_value_sz (obj_p, + field_name, + lit_zt_utf8_string_size (field_name), + &val); +} +``` + +**See also** + +- [jerry_api_create_object](#jerry_api_create_object) +- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) +- [jerry_api_get_object_field_value_sz](#jerry_api_set_object_field_value_sz) +- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) + # jerry_api_get_object_native_handle @@ -1202,7 +2065,6 @@ jerry_api_is_function (const jerry_api_object_t *object_p); **See also** -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_is_constructor](#jerry_api_is_constructor) - [jerry_api_call_function](#jerry_api_call_function) @@ -1241,7 +2103,6 @@ jerry_api_is_constructor (const jerry_api_object_t *object_p); **See also** -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_is_function](#jerry_api_is_function) - [jerry_api_construct_object](#jerry_api_construct_object) @@ -1304,7 +2165,6 @@ jerry_api_call_function (jerry_api_object_t *function_object_p, **See also** - [jerry_api_is_function](#jerry_api_is_function) -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_create_external_function](#jerry_api_create_external_function) # jerry_api_construct_object @@ -1363,7 +2223,6 @@ If call was performed successfully, returned value should be freed with [jerry_a **See also** - [jerry_api_is_constructor](#jerry_api_is_constructor) - - [jerry_api_value_t](#jerry_api_value_t) # jerry_external_handler_t @@ -1519,7 +2378,6 @@ jerry_api_set_array_index_value (jerry_api_object_t *array_object_p, **See also** -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_create_array_object](#jerry_api_create_array_object) # jerry_api_get_array_index_value @@ -1559,7 +2417,6 @@ jerry_api_get_array_index_value (jerry_api_object_t *array_object_p, **See also** -- [jerry_api_value_t](#jerry_api_value_t) - [jerry_api_create_array_object](#jerry_api_create_array_object) @@ -1628,9 +2485,6 @@ handler (const jerry_api_object_t *function_obj_p, - [jerry_api_create_external_function](#jerry_api_create_external_function) - - - # jerry_register_external_magic_strings **Summary** @@ -1672,3 +2526,110 @@ jerry_register_external_magic_strings (const jerry_api_char_ptr_t *ex_str_items **See also** - [jerry_init](#jerry_init) + + +# jerry_api_value_to_string + +**Summary** + +Creates the textual representation of an API value using the ToString ecma builtin operation. + +**Prototype** + +```c +jerry_api_string_t * +jerry_api_value_to_string (const jerry_api_value_t *in_value_p); +``` + +- `in_value_p` - input API value +- return value - textual representation of the given API value + +**Example** + +```c +{ + jerry_api_value_t value; + + ... // receive or construct value + + jerry_api_string_t *string_value = jerry_api_value_to_string(&value); +} +``` + + +# jerry_object_field_foreach_t + +**Summary** + +Function type applied for each fields of an object by API function [jerry_api_foreach_object_field](#jerry_api_foreach_object_field). + +**Definition** + +```c +typedef bool (*jerry_object_field_foreach_t) (const jerry_api_string_t *field_name_p, + const jerry_api_value_t *field_value_p, + void *user_data_p); +``` +- `field_name_p` - name of the field +- `field_value_p` - value of the field +- `user_data_p` - user data +- return value + - true, if the operation executed successfully + - false, otherwise + +**See also** + +- [jerry_api_foreach_object_field](#jerry_api_foreach_object_field) + + +# jerry_api_foreach_object_field + +**Summary** + +Applies the given function to every fields in the given objects. + +**Prototype** + +```c +bool +jerry_api_foreach_object_field (jerry_api_object_t *object_p, + jerry_object_field_foreach_t foreach_p, + void *user_data_p); +``` +- `object_p` - object +- `foreach_p` - foreach function, that will be apllied for each fields +- `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_api_string_t *field_name_p, + const jerry_api_value_t *field_value_p, + void *user_data_p) +{ + + ... // implementation of the foreach function + +} + +{ + jerry_init (JERRY_FLAG_EMPTY); + + jerry_api_object_t* object_p; + ... // receive or construct object_p + + double data = 3.14; // example data + + jerry_api_foreach_object_field(object_p, foreach_function, &data); + +} +``` + +**See also** + +- [jerry_object_field_foreach_t](#jerry_object_field_foreach_t)