diff --git a/03.api.md b/03.api.md index 069dfd9b4..d86259005 100644 --- a/03.api.md +++ b/03.api.md @@ -14,12 +14,12 @@ The simplest way to run JavaScript. **Prototype** -{% highlight cpp %} +```c jerry_completion_code_t -jerry_run_simple (const char * script_source, +jerry_run_simple (const jerry_api_char_t *script_source, size_t script_source_size, jerry_flag_t flags); -{% endhighlight %} +``` - `script_source` - source code; - `script_source_size` - size of source code buffer, in bytes; @@ -27,20 +27,20 @@ jerry_run_simple (const char * script_source, **Example** -{% highlight cpp %} +```c { - const char * script = "print ('Hello, World!');"; + const jerry_api_char_t *script = "print ('Hello, World!');"; - jerry_run_simple (script, strlen (script), JERRY_FLAG_EMPTY); + jerry_run_simple (script, strlen ((const char *) script), JERRY_FLAG_EMPTY); } -{% endhighlight %} +``` **See also** -- [jerry_init](#jerryinit) -- [jerry_cleanup](#jerrycleanup) -- [jerry_parse](#jerryparse) -- [jerry_run](#jerryrun) +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_parse](#jerry_parse) +- [jerry_run](#jerry_run) # jerry_init @@ -50,21 +50,22 @@ Initializes JerryScript engine, making possible to run JavaScript code and perfo **Prototype** -{% highlight cpp %} +```c void jerry_init (jerry_flag_t flags); -{% endhighlight %} +``` `flags` - combination of various engine configuration flags: -- `JERRY_FLAG_MEM_STATS` - dump memory statistics; -- `JERRY_FLAG_ENABLE_LOG` - enable logging; +- `JERRY_FLAG_EMPTY` - no flags, just initialize in default configuration; - `JERRY_FLAG_SHOW_OPCODES` - print compiled byte-code; -- `JERRY_FLAG_EMPTY` - no flags, just initialize in default configuration. +- `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; **Example** -{% highlight cpp %} +```c { jerry_init (JERRY_FLAG_ENABLE_LOG); @@ -72,11 +73,11 @@ jerry_init (jerry_flag_t flags); jerry_cleanup (); } -{% endhighlight %} +``` **See also** -- [jerry_cleanup](#jerrycleanup) +- [jerry_cleanup](#jerry_cleanup) # jerry_cleanup @@ -88,14 +89,14 @@ JavaScript values, received from engine, are inaccessible after the cleanup. **Prototype** -{% highlight cpp %} +```c void jerry_cleanup (void); -{% endhighlight %} +``` **See also** -- [jerry_init](#jerryinit) +- [jerry_init](#jerry_init) # jerry_parse @@ -107,31 +108,88 @@ so `jerry_parse` could be invoked only once between `jerry_init` and `jerry_clea **Prototype** -{% highlight cpp %} +```c bool -jerry_parse (const char* source_p, size_t source_size); -{% endhighlight %} +jerry_parse (const jerry_api_char_t *source_p, + size_t source_size, + jerry_api_object_t **error_obj_p); +``` - `source_p` - string, containing source code to parse; - `source_size` - size of the string, in bytes. +- `error_obj_p` - error object (output parameter) **Example** -{% highlight cpp %} +```c { - jerry_init (JERRY_FLAG_ENABLE_LOG); + jerry_init (JERRY_FLAG_EMPTY); char script [] = "print ('Hello, World!');"; - jerry_parse (script, strlen (script)); + size_t script_size = strlen ((const char *) script); - jerry_run (); + jerry_api_object_t *error_object_p = NULL; + if (!jerry_parse (script, script_size, &error_object_p)) + { + /* Error object must be freed, if parsing failed */ + jerry_api_release_object (error_object_p); + } jerry_cleanup (); } -{% endhighlight %} +``` **See also** -- [jerry_run](#jerryrun) +- [jerry_run](#jerry_run) + + +# jerry_parse_and_save_snapshot + +**Summary** + +Generate snapshot from the specified source. + +**Prototype** + +```c +size_t +jerry_parse_and_save_snapshot (const jerry_api_char_t *source_p, + size_t source_size, + bool is_for_global, + uint8_t *buffer_p, + size_t buffer_size); +``` + +- `source_p` - script source +- `source_size` - script source size +- `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 +- 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_init (JERRY_FLAG_EMPTY); + + static uint8_t global_mode_snapshot_buffer[1024]; + const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();"; + + size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_api_char_t *) code_to_snapshot_p, + strlen (code_to_snapshot_p), + true, + global_mode_snapshot_buffer, + sizeof (global_mode_snapshot_buffer)); +} +``` + +**See also** +- [jerry_init](#jerry_init) +- [jerry_exec_snapshot](#jerry_exec_snapshot) + # jerry_run @@ -142,31 +200,163 @@ The code should be previously registered through `jerry_parse`. **Prototype** -{% highlight cpp %} +```c jerry_completion_code_t -jerry_run (void); -{% endhighlight %} - -- 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`). +jerry_run (jerry_api_value_t *error_value_p); +``` +- `error_value_p` - error value (output parameter) +- returned 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 **Example** -{% highlight cpp %} +```c { - jerry_init (JERRY_FLAG_ENABLE_LOG); + const jerry_api_char_t script[] = "print ('Hello, World!');"; + size_t script_size = strlen ((const char *) script); - char script [] = "print ('Hello, World!');"; - jerry_parse (script, strlen (script)); + /* Initialize engine */ + jerry_init (JERRY_FLAG_EMPTY); - jerry_run (); + /* Setup Global scope code */ + jerry_api_object_t *error_object_p = NULL; + if (!jerry_parse (script, script_size, &error_object_p)) + { + /* Error object must be freed, if parsing failed */ + jerry_api_release_object (error_object_p); + } + else + { + /* Execute Global scope code + * + * Note: + * Initialization of 'error_value' is not mandatory here. + */ + jerry_api_value_t error_value = jerry_api_create_void_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_api_release_value (&error_value); + } + } jerry_cleanup (); } -{% endhighlight %} +``` **See also** -- [jerry_parse](#jerryparse) +- [jerry_parse](#jerry_parse) + + +# jerry_exec_snapshot + +**Summary** + +Execute snapshot from the specified buffer. + +**Prototype** + +```c +jerry_completion_code_t +jerry_exec_snapshot (const void *snapshot_p, + size_t snapshot_size, + bool copy_bytecode, + jerry_api_value_t *retval_p); +``` +- `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` - returned value (ECMA-262 'undefined' if code is executed as global scope code +- return value - completion code + +**Example** + +```c +{ + bool is_ok; + jerry_api_value_t res; + static uint8_t global_mode_snapshot_buffer[1024]; + const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();"; + + jerry_init (JERRY_FLAG_EMPTY); + size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_api_char_t *) code_to_snapshot_p, + strlen (code_to_snapshot_p), + true, + global_mode_snapshot_buffer, + sizeof (global_mode_snapshot_buffer)); + jerry_cleanup (); + + jerry_init (JERRY_FLAG_EMPTY); + + is_ok = (jerry_exec_snapshot (global_mode_snapshot_buffer, + global_mode_snapshot_size, + false, + &res) == JERRY_COMPLETION_CODE_OK); +} +``` + +**See also** + +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot) + + +# jerry_get_memory_limits + +**Summary** + +Gets configured memory limits of JerryScript. + +**Prototype** + +```c +void +jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p, + size_t *out_stack_limit_p); +``` +- `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); + + size_t stack_limit; + size_t data_dss_brk_limit; + jerry_get_memory_limits(&stack_limit, &data_dss_brk_limit); +``` + +**See also** + +- [jerry_init](#jerry_init) + + +# jerry_api_gc + +**Summary** +Performs garbage collection. + +**Prototype** + +```c +void +jerry_api_gc (void); +``` + +**Example** + +```c +jerry_api_gc (); +``` + # jerry_api_value_t @@ -175,16 +365,19 @@ The data type represents any JavaScript value that can be sent to or received fr 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** -{% highlight cpp %} +```c typedef struct jerry_api_value_t { jerry_api_data_type_t type; @@ -198,21 +391,17 @@ typedef struct jerry_api_value_t uint32_t v_uint32; - union - { - jerry_api_string_t * v_string; - jerry_api_object_t * v_object; - }; - }; + jerry_api_string_t v_string; + jerry_api_object_t v_object; + } u; } jerry_api_value_t; -{% endhighlight %} +``` **See also** -- [jerry_api_eval](#jerryapieval) -- [jerry_api_call_function](#jerryapicallfunction) -- [jerry_api_construct_object](#jerryapiconstructobject) - +- [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 @@ -221,14 +410,14 @@ Perform JavaScript `eval`. **Prototype** -{% highlight cpp %} +```c jerry_completion_code_t -jerry_api_eval (const char * source_p, +jerry_api_eval (const jerry_api_char_t *source_p, size_t source_size, bool is_direct, bool is_strict, - jerry_api_value_t * retval_p); -{% endhighlight %} + jerry_api_value_t *retval_p); +``` - `source_p` - source code to evaluate; - `source_size` - length of the source code; @@ -239,7 +428,7 @@ jerry_api_eval (const char * source_p, **Example** -{% highlight cpp %} +```c { jerry_api_value_t ret_val; @@ -248,48 +437,129 @@ jerry_api_eval (const char * source_p, false, false, &ret_val); } -{% endhighlight %} +``` **See also** -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_external_function](#jerryapicreateexternalfunction) -- [jerry_external_handler_t](#jerryexternalhandlert) +- [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_acquire_value + +**Summary** + +Acquires the specified Jerry API value. + +For values of string and object types this acquires the underlying data, for all other types it is a no-op. The acquired pointer have to be released by [jerry_api_release_value](#jerry_api_release_value). + +**Prototype** + +```c +jerry_api_value_t * +jerry_api_acquire_value (jerry_api_value_t *value_p); +``` +- `value_p` - pointer to an API value +- return value - pointer that may be used outside of the engine + +**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); + + jerry_api_value_t *acquired_object = jerry_api_acquire_value(&object_value); + + jerry_api_release_value(acquired_object); +} +``` + +**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) + + +# jerry_api_release_value + +**Summary** +Release specified pointer to the value. + +**Prototype** + +```c +void +jerry_api_release_value (jerry_api_value_t *value_p); +``` + +- `value_p` - pointer to the value. + +**Example** +```c +{ + jerry_api_value_t val1; + jerry_api_value_t val2; + + val1.type = JERRY_API_DATA_TYPE_OBJECT; + val1.u.v_object = jerry_api_create_object (); + + val2.type = JERRY_API_DATA_TYPE_STRING; + val2.u.v_string = jerry_api_create_string ("abc"); + + ... // usage of val1 + + jerry_api_release_value (&val1); + + ... // usage of val2 + + jerry_api_release_value (&val2); +} +``` + +**See also** + +- [jerry_api_value_t](#jerry_api_value_t) + # jerry_api_create_string **Summary** Create new JavaScript string. -Upon the JavaScript string becomes unused, all pointers to it should be released using [jerry_api_release_string](#jerryapireleasestring). +Upon the JavaScript string becomes unused, all pointers to it should be released using [jerry_api_release_string](#jerry_api_release_string). **Prototype** -{% highlight cpp %} -jerry_api_string_t* -jerry_api_create_string (const char * v); -{% endhighlight %} +```c +jerry_api_string_t * +jerry_api_create_string (const jerry_api_char_t *v); +``` - `v` - value of string to create; - returned value is pointer to created string. **Example** -{% highlight cpp %} +```c { - jerry_api_string_t * string_p = jerry_api_create_string ("abc"); + jerry_api_string_t *string_p = jerry_api_create_string ("abc"); ... jerry_api_release_string (string_p); } -{% endhighlight %} +``` **See also** -- [jerry_api_acquire_string](#jerryapiacquirestring) -- [jerry_api_release_string](#jerryapireleasestring) -- [jerry_api_string_to_char_buffer](#jerryapistringtocharbuffer) +- [jerry_api_acquire_string](#jerry_api_acquire_string) +- [jerry_api_release_string](#jerry_api_release_string) +- [jerry_api_string_to_char_buffer](#jerry_api_string_to_char_buffer) # jerry_api_string_to_char_buffer @@ -298,12 +568,12 @@ Copy string characters to specified buffer, append zero character at end of the **Prototype** -{% highlight cpp %} -ssize_t -jerry_api_string_to_char_buffer (const jerry_api_string_t * string_p, - char * buffer_p, - ssize_t buffer_size); -{% endhighlight %} +```c +jerry_api_size_t +jerry_api_string_to_char_buffer (const jerry_api_string_t *string_p, + jerry_api_char_t *buffer_p, + jerry_api_size_t buffer_size); +``` - `string_p` - pointer to a string; - `buffer_p` - pointer to output buffer (can be NULL, is `buffer_size` is 0); @@ -314,29 +584,29 @@ jerry_api_string_to_char_buffer (const jerry_api_string_t * string_p, **Example** -{% highlight cpp %} +```c { - jerry_api_object_t * obj_p = jerry_api_get_global (); + jerry_api_object_t *obj_p = jerry_api_get_global (); jerry_api_value_t val; bool is_ok = jerry_api_get_object_field_value (obj_p, "field_with_string_value", &val); - if (is_ok) { + if (is_ok) + { bool is_string = (val.type == JERRY_API_DATA_TYPE_STRING); - if (is_string) { + if (is_string) + { // neg_req_sz would be negative, as zero-size buffer is insufficient for any string - ssize_t neg_req_sz = jerry_api_string_to_char_buffer (val.string_p, - NULL, - 0); - char * str_buf_p = (char*) malloc (-neg_req_sz); + jerry_api_size_t req_sz = jerry_api_get_string_size (val.string_p); + jerry_api_char_t *str_buf_p = (jerry_api_char_t *) malloc (req_sz); // sz would be -neg_req_sz - size_t sz = jerry_api_string_to_char_buffer (val.string_p, - str_buf_p, - -neg_req_sz); + jerry_api_size_t sz = jerry_api_string_to_char_buffer (val.string_p, + str_buf_p, + req_sz); printf ("%s", str_buf_p); @@ -348,36 +618,36 @@ jerry_api_string_to_char_buffer (const jerry_api_string_t * string_p, jerry_api_release_object (obj_p); } -{% endhighlight %} +``` **See also** -- [jerry_api_create_string](#jerryapicreatestring) -- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_create_string](#jerry_api_create_string) +- [jerry_api_value_t](#jerry_api_value_t) # jerry_api_acquire_string **Summary** Acquire new pointer to the string for usage outside of the engine. -The acquired pointer should be released with [jerry_api_release_string](#jerryapireleasestring). +The acquired pointer should be released with [jerry_api_release_string](#jerry_api_release_string). **Prototype** -{% highlight cpp %} -jerry_api_string_t* -jerry_api_acquire_string (jerry_api_string_t * string_p); -{% endhighlight %} +```c +jerry_api_string_t * +jerry_api_acquire_string (jerry_api_string_t *string_p); +``` - `string_p` - pointer to the string; - returned value - new pointer to the string. **Example** -{% highlight cpp %} +```c { - jerry_api_string_t * str_ptr1_p = jerry_api_create_string ("abc"); - jerry_api_string_t * str_ptr2_p = jerry_api_acquire_string (str_ptr1_p); + jerry_api_string_t *str_ptr1_p = jerry_api_create_string ("abc"); + jerry_api_string_t *str_ptr2_p = jerry_api_acquire_string (str_ptr1_p); ... // usage of both pointers @@ -387,12 +657,12 @@ jerry_api_acquire_string (jerry_api_string_t * string_p); jerry_api_release_string (str_ptr2_p); } -{% endhighlight %} +``` **See also** -- [jerry_api_release_string](#jerryapireleasestring) -- [jerry_api_create_string](#jerryapicreatestring) +- [jerry_api_release_string](#jerry_api_release_string) +- [jerry_api_create_string](#jerry_api_create_string) # jerry_api_release_string @@ -401,19 +671,19 @@ Release specified pointer to the string. **Prototype** -{% highlight cpp %} +```c void -jerry_api_release_string (jerry_api_string_t * string_p); -{% endhighlight %} +jerry_api_release_string (jerry_api_string_t *string_p); +``` - `string_p` - pointer to the string. **Example** -{% highlight cpp %} +```c { - jerry_api_string_t * str_ptr1_p = jerry_api_create_string ("abc"); - jerry_api_string_t * str_ptr2_p = jerry_api_acquire_string (str_ptr1_p); + jerry_api_string_t *str_ptr1_p = jerry_api_create_string ("abc"); + jerry_api_string_t *str_ptr2_p = jerry_api_acquire_string (str_ptr1_p); ... // usage of both pointers @@ -423,75 +693,75 @@ jerry_api_release_string (jerry_api_string_t * string_p); jerry_api_release_string (str_ptr2_p); } -{% endhighlight %} +``` **See also** -- [jerry_api_acquire_string](#jerryapiacquirestring) -- [jerry_api_create_string](#jerryapicreatestring) +- [jerry_api_acquire_string](#jerry_api_acquire_string) +- [jerry_api_create_string](#jerry_api_create_string) # jerry_api_create_object **Summary** Create new JavaScript object, like with `new Object()`. -Upon the JavaScript object becomes unused, all pointers to it should be released using [jerry_api_release_object](#jerryapireleaseobject). +Upon the JavaScript object becomes unused, all pointers to it should be released using [jerry_api_release_object](#jerry_api_release_object). **Prototype** -{% highlight cpp %} -jerry_api_object_t* +```c +jerry_api_object_t * jerry_api_create_object (); -{% endhighlight %} +``` - returned value is pointer to the created object. **Example** -{% highlight cpp %} +```c { - jerry_api_object_t * object_p = jerry_api_create_object (); + jerry_api_object_t *object_p = jerry_api_create_object (); ... jerry_api_release_object (object_p); } -{% endhighlight %} +``` **See also** -- [jerry_api_acquire_object](#jerryapiacquireobject) -- [jerry_api_release_object](#jerryapireleaseobject) -- [jerry_api_add_object_field](#jerryapiaddobjectfield) -- [jerry_api_delete_object_field](#jerryapideleteobjectfield) -- [jerry_api_get_object_field_value](#jerryapigetobjectfieldvalue) -- [jerry_api_set_object_field_value](#jerryapisetobjectfieldvalue) -- [jerry_api_get_object_native_handle](#jerryapigetobjectnativehandle) -- [jerry_api_set_object_native_handle](#jerryapisetobjectnativehandle) +- [jerry_api_acquire_object](#jerry_api_acquire_object) +- [jerry_api_release_object](#jerry_api_release_object) +- [jerry_api_add_object_field](#jerry_api_add_object_field) +- [jerry_api_delete_object_field](#jerry_api_delete_object_field) +- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) +- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) +- [jerry_api_get_object_native_handle](#jerry_api_get_object_native_handle) +- [jerry_api_set_object_native_handle](#jerry_api_set_object_native_handle) # jerry_api_acquire_object **Summary** Acquire new pointer to the object for usage outside of the engine. -The acquired pointer should be released with [jerry_api_release_object](#jerryapireleaseobject). +The acquired pointer should be released with [jerry_api_release_object](#jerry_api_release_object). **Prototype** -{% highlight cpp %} -jerry_api_object_t* -jerry_api_acquire_object (jerry_api_object_t * object_p); -{% endhighlight %} +```c +jerry_api_object_t * +jerry_api_acquire_object (jerry_api_object_t *object_p); +``` - `object_p` - pointer to the object; - returned value - new pointer to the object. **Example** -{% highlight cpp %} +```c { - jerry_api_object_t * obj_ptr1_p = jerry_api_create_object (); - jerry_api_object_t * obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p); + jerry_api_object_t *obj_ptr1_p = jerry_api_create_object (); + jerry_api_object_t *obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p); ... // usage of both pointers @@ -501,12 +771,12 @@ jerry_api_acquire_object (jerry_api_object_t * object_p); jerry_api_release_object (obj_ptr2_p); } -{% endhighlight %} +``` **See also** -- [jerry_api_release_object](#jerryapireleaseobject) -- [jerry_api_create_object](#jerryapicreateobject) +- [jerry_api_release_object](#jerry_api_release_object) +- [jerry_api_create_object](#jerry_api_create_object) # jerry_api_release_object @@ -515,19 +785,19 @@ Release specified pointer to the object. **Prototype** -{% highlight cpp %} +```c void -jerry_api_release_object (jerry_api_object_t * object_p); -{% endhighlight %} +jerry_api_release_object (jerry_api_object_t *object_p); +``` - `object_p` - pointer to the object. **Example** -{% highlight cpp %} +```c { - jerry_api_object_t * obj_ptr1_p = jerry_api_create_object (); - jerry_api_object_t * obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p); + jerry_api_object_t *obj_ptr1_p = jerry_api_create_object (); + jerry_api_object_t *obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p); ... // usage of both pointers @@ -537,12 +807,12 @@ jerry_api_release_object (jerry_api_object_t * object_p); jerry_api_release_object (obj_ptr2_p); } -{% endhighlight %} +``` **See also** -- [jerry_api_acquire_object](#jerryapiacquireobject) -- [jerry_api_create_object](#jerryapicreateobject) +- [jerry_api_acquire_object](#jerry_api_acquire_object) +- [jerry_api_create_object](#jerry_api_create_object) # jerry_api_get_global @@ -551,20 +821,20 @@ Get the Global object. **Prototype** -{% highlight cpp %} -jerry_api_object_t* +```c +jerry_api_object_t * jerry_api_get_global (void); -{% endhighlight %} +``` - returned value - pointer to the Global object. -Received pointer should be released with [jerry_api_release_object](#jerryapireleaseobject), just when the value becomes unnecessary. +Received pointer should be released with [jerry_api_release_object](#jerry_api_release_object), just when the value becomes unnecessary. **Example** -{% highlight cpp %} +```c { - jerry_api_object_t * glob_obj_p = jerry_api_get_global (); + jerry_api_object_t *glob_obj_p = jerry_api_get_global (); jerry_api_value_t val; bool is_ok = jerry_api_get_object_field_value (glob_obj_p, "some_field_name", &val); @@ -577,15 +847,15 @@ Received pointer should be released with [jerry_api_release_object](#jerryapirel jerry_api_release_object (glob_obj_p); } -{% endhighlight %} +``` **See also** -- [jerry_api_release_object](#jerryapireleaseobject) -- [jerry_api_add_object_field](#jerryapiaddobjectfield) -- [jerry_api_delete_object_field](#jerryapideleteobjectfield) -- [jerry_api_get_object_field_value](#jerryapigetobjectfieldvalue) -- [jerry_api_set_object_field_value](#jerryapisetobjectfieldvalue) +- [jerry_api_release_object](#jerry_api_release_object) +- [jerry_api_add_object_field](#jerry_api_add_object_field) +- [jerry_api_delete_object_field](#jerry_api_delete_object_field) +- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) +- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) # jerry_api_add_object_field @@ -594,13 +864,13 @@ Create field (named data property) in an object **Prototype** -{% highlight cpp %} +```c bool -jerry_api_add_object_field (jerry_api_object_t * object_p, - const char * field_name_p, - const jerry_api_value_t * field_value_p, +jerry_api_add_object_field (jerry_api_object_t *object_p, + const jerry_api_char_t *field_name_p, + const jerry_api_value_t *field_value_p, bool is_writable); -{% endhighlight %} +``` - `object_p` - object to add field at; - `field_name_p` - name of the field; @@ -612,9 +882,9 @@ jerry_api_add_object_field (jerry_api_object_t * object_p, **Example** -{% highlight cpp %} +```c { - jerry_api_object_t * obj_p = jerry_api_create_object (); + jerry_api_object_t *obj_p = jerry_api_create_object (); jerry_api_value_t val; @@ -623,13 +893,13 @@ jerry_api_add_object_field (jerry_api_object_t * object_p, // Make new constant field jerry_api_add_object_field (obj_p, "some_field_name", &val, false); } -{% endhighlight %} +``` **See also** -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_object](#jerryapicreateobject) +- [jerry_api_value_t](#jerry_api_value_t) +- [jerry_api_create_object](#jerry_api_create_object) # jerry_api_delete_object_field @@ -638,11 +908,11 @@ Delete field (property) in the specified object **Prototype** -{% highlight cpp %} +```c bool -jerry_api_delete_object_field (jerry_api_object_t * object_p, - const char * field_name_p); -{% endhighlight %} +jerry_api_delete_object_field (jerry_api_object_t *object_p, + const jerry_api_char_t *field_name_p); +``` - `object_p` - object to delete field at; - `field_name_p` - name of the field. @@ -651,19 +921,19 @@ jerry_api_delete_object_field (jerry_api_object_t * object_p, **Example** -{% highlight cpp %} +```c { - jerry_api_object_t* obj_p; + jerry_api_object_t *obj_p; ... // receive or construct obj_p jerry_api_delete_object_field (obj_p, "some_field_name"); } -{% endhighlight %} +``` **See also** -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_object](#jerryapicreateobject) +- [jerry_api_value_t](#jerry_api_value_t) +- [jerry_api_create_object](#jerry_api_create_object) # jerry_api_get_object_field_value @@ -672,12 +942,12 @@ Get value of field (property) in the specified object, i.e. perform [[Get]] oper **Prototype** -{% highlight cpp %} +```c bool -jerry_api_get_object_field_value (jerry_api_object_t * object_p, - const char * field_name_p, - jerry_api_value_t * field_value_p); -{% endhighlight %} +jerry_api_get_object_field_value (jerry_api_object_t *object_p, + const jerry_api_char_t *field_name_p, + jerry_api_value_t *field_value_p); +``` - `object_p` - object; - `field_name_p` - name of the field; @@ -685,13 +955,13 @@ jerry_api_get_object_field_value (jerry_api_object_t * object_p, - returned value - true, if field value was retrieved successfully, i.e. upon the call: - there is field with specified name in the object. -If value was retrieved successfully, it should be freed with [jerry_api_release_object](#jerryapireleaseobject) just when it becomes unnecessary. +If value was retrieved successfully, it should be freed with [jerry_api_release_object](#jerry_api_release_object) just when it becomes unnecessary. **Example** -{% highlight cpp %} +```c { - jerry_api_object_t* obj_p; + jerry_api_object_t *obj_p; ... // receive or construct obj_p jerry_api_value_t val; @@ -703,12 +973,74 @@ If value was retrieved successfully, it should be freed with [jerry_api_release_ jerry_api_release_value (&val); } } -{% endhighlight %} +``` **See also** -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_object](#jerryapicreateobject) +- [jerry_api_value_t](#jerry_api_value_t) +- [jerry_api_create_object](#jerry_api_create_object) + + +# jerry_api_get_object_field_value_sz + +**Summary** + +Gets the value of a field in the specified object. +If the value was retrieved successfully, it should be freed with jerry_api_release_value when it becomes unnecessary. + +**Prototype** + +```c +bool +jerry_api_get_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, + 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` - Output parameter, that gives the value of the field if retrieved +- return value + - true, if field value was retrieved successfully + - false, otherwise + +**Example** +```c +{ + jerry_init (JERRY_FLAG_EMPTY); + + jerry_api_char_t field_name[] = "field"; + 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_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... + + jerry_api_release_object(object_p); +} +``` + +**See also** + +[jerry_init](#jerry_init) +[jerry_api_create_object](#jerry_api_create_object) +[jerry_api_release_object](#jerry_api_release_object) +[jerry_api_add_object_field](#jerry_api_add_object_field) +[jerry_api_get_object_field_value](#jerry_api_get_object_field_value) +[jerry_api_set_object_field_value](#jerry_api_set_object_field_value) +[jerry_api_set_object_field_value_sz](#jerry_api_set_object_field_value_sz) + # jerry_api_set_object_field_value @@ -717,12 +1049,12 @@ Set value of a field (property) in the specified object, i.e. perform [[Put]] op **Prototype** -{% highlight cpp %} +```c bool -jerry_api_set_object_field_value (jerry_api_object_t * object_p, - const char * field_name_p, - jerry_api_value_t * field_value_p); -{% endhighlight %} +jerry_api_set_object_field_value (jerry_api_object_t *object_p, + const jerry_api_char_t *field_name_p, + jerry_api_value_t *field_value_p); +``` - `object_p` - object; - `field_name_p` - name of the field; @@ -732,21 +1064,21 @@ jerry_api_set_object_field_value (jerry_api_object_t * object_p, **Example** -{% highlight cpp %} +```c { - jerry_api_object_t* obj_p; + jerry_api_object_t *obj_p; jerry_api_value_t val; ... // receive or construct obj_p and val bool is_ok = jerry_api_set_object_field_value (obj_p, "some_field_name", &val); } -{% endhighlight %} +``` **See also** -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_object](#jerryapicreateobject) +- [jerry_api_value_t](#jerry_api_value_t) +- [jerry_api_create_object](#jerry_api_create_object) # jerry_api_get_object_native_handle @@ -756,11 +1088,11 @@ Get native handle, previously associated with specified object. **Prototype** -{% highlight cpp %} +```c bool -jerry_api_get_object_native_handle (jerry_api_object_t * object_p, - uintptr_t* out_handle_p); -{% endhighlight %} +jerry_api_get_object_native_handle (jerry_api_object_t *object_p, + uintptr_t *out_handle_p); +``` - `object_p` - object to get handle from; - `out_handle_p` - handle value (output parameter); @@ -768,9 +1100,9 @@ jerry_api_get_object_native_handle (jerry_api_object_t * object_p, **Example** -{% highlight cpp %} +```c { - jerry_api_object_t* obj_p; + jerry_api_object_t *obj_p; uintptr_t handle_set; ... // receive or construct obj_p and handle_set value @@ -783,12 +1115,12 @@ jerry_api_get_object_native_handle (jerry_api_object_t * object_p, bool is_there_associated_handle = jerry_api_get_object_native_handle (obj_p, &handle_get); } -{% endhighlight %} +``` **See also** -- [jerry_api_create_object](#jerryapicreateobject) -- [jerry_api_set_object_native_handle](#jerryapisetobjectnativehandle) +- [jerry_api_create_object](#jerry_api_create_object) +- [jerry_api_set_object_native_handle](#jerry_api_set_object_native_handle) # jerry_api_set_object_native_handle @@ -800,12 +1132,12 @@ If native handle or "free" callback were already set for the object, correspondi **Prototype** -{% highlight cpp %} +```c void -jerry_api_set_object_native_handle (jerry_api_object_t * object_p, +jerry_api_set_object_native_handle (jerry_api_object_t *object_p, uintptr_t handle, jerry_object_free_callback_t freecb_p); -{% endhighlight %} +``` - `object_p` - object to set handle in; - `handle` - handle value; @@ -813,9 +1145,9 @@ jerry_api_set_object_native_handle (jerry_api_object_t * object_p, **Example** -{% highlight cpp %} +```c { - jerry_api_object_t* obj_p; + jerry_api_object_t *obj_p; uintptr_t handle_set; ... // receive or construct obj_p and handle_set value @@ -828,12 +1160,12 @@ jerry_api_set_object_native_handle (jerry_api_object_t * object_p, bool is_there_associated_handle = jerry_api_get_object_native_handle (obj_p, &handle_get); } -{% endhighlight %} +``` **See also** -- [jerry_api_create_object](#jerryapicreateobject) -- [jerry_api_get_object_native_handle](#jerryapigetobjectnativehandle) +- [jerry_api_create_object](#jerry_api_create_object) +- [jerry_api_get_object_native_handle](#jerry_api_get_object_native_handle) # jerry_api_is_function @@ -842,35 +1174,37 @@ Check whether the specified object is a function object. **Prototype** -{% highlight cpp %} +```c bool -jerry_api_is_function (const jerry_api_object_t* object_p); -{% endhighlight %} +jerry_api_is_function (const jerry_api_object_t *object_p); +``` - `object_p` - object to check; - returned value - just boolean, indicating whether the specified object can be called as function. **Example** -{% highlight cpp %} +```c { jerry_api_value_t val; ... // receiving val - if (val.type == JERRY_API_DATA_TYPE_OBJECT) { - if (jerry_api_is_function (val.v_object)) { + if (val.type == JERRY_API_DATA_TYPE_OBJECT) + { + if (jerry_api_is_function (val.u.v_object)) + { // the object is function object } } } -{% endhighlight %} +``` **See also** -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_is_constructor](#jerryapiisconstructor) -- [jerry_api_call_function](#jerryapicallfunction) +- [jerry_api_value_t](#jerry_api_value_t) +- [jerry_api_is_constructor](#jerry_api_is_constructor) +- [jerry_api_call_function](#jerry_api_call_function) # jerry_api_is_constructor @@ -879,35 +1213,37 @@ Check whether the specified object is a constructor function object. **Prototype** -{% highlight cpp %} +```c bool -jerry_api_is_constructor (const jerry_api_object_t* object_p); -{% endhighlight %} +jerry_api_is_constructor (const jerry_api_object_t *object_p); +``` - `object_p` - object to check; - returned value - just boolean, indicating whether the specified object can be called as constructor. **Example** -{% highlight cpp %} +```c { jerry_api_value_t val; ... // receiving val - if (val.type == JERRY_API_DATA_TYPE_OBJECT) { - if (jerry_api_is_constructor (val.v_object)) { + if (val.type == JERRY_API_DATA_TYPE_OBJECT) + { + if (jerry_api_is_constructor (val.u.v_object)) + { // the object is constructor function object } } } -{% endhighlight %} +``` **See also** -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_is_function](#jerryapiisfunction) -- [jerry_api_construct_object](#jerryapiconstructobject) +- [jerry_api_value_t](#jerry_api_value_t) +- [jerry_api_is_function](#jerry_api_is_function) +- [jerry_api_construct_object](#jerry_api_construct_object) # jerry_api_call_function @@ -916,14 +1252,14 @@ Call function object. **Prototype** -{% highlight cpp %} +```c bool -jerry_api_call_function (jerry_api_object_t * function_object_p, - jerry_api_object_t * this_arg_p, - jerry_api_value_t * retval_p, +jerry_api_call_function (jerry_api_object_t *function_object_p, + jerry_api_object_t *this_arg_p, + jerry_api_value_t *retval_p, const jerry_api_value_t args_p[], uint16_t args_count); -{% endhighlight %} +``` - `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'; @@ -933,26 +1269,29 @@ jerry_api_call_function (jerry_api_object_t * function_object_p, - specified object is a function object (see also jerry_api_is_function); - no unhandled exceptions were thrown in connection with the call. - If call was performed successfully, returned value should be freed with [jerry_api_release_object](#jerryapireleaseobject) just when it becomes unnecessary. + If call was performed successfully, returned value should be freed with [jerry_api_release_object](#jerry_api_release_object) just when it becomes unnecessary. **Example** -{% highlight cpp %} +```c { jerry_api_value_t val; ... // receiving val - if (val.type == JERRY_API_DATA_TYPE_OBJECT) { - if (jerry_api_is_function (val.v_object)) { + if (val.type == JERRY_API_DATA_TYPE_OBJECT) + { + if (jerry_api_is_function (val.u.v_object)) + { jerry_api_value_t ret_val; - bool is_ok = jerry_api_call_function (val.v_object, + bool is_ok = jerry_api_call_function (val.u.v_object, NULL, &ret_val, NULL, 0); - if (is_ok) { + if (is_ok) + { ... // handle return value jerry_api_release_value (&ret_val); @@ -960,13 +1299,13 @@ jerry_api_call_function (jerry_api_object_t * function_object_p, } } } -{% endhighlight %} +``` **See also** -- [jerry_api_is_function](#jerryapiisfunction) -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_external_function](#jerryapicreateexternalfunction) +- [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 @@ -975,13 +1314,13 @@ Construct object invoking specified function object as constructor. **Prototype** -{% highlight cpp %} +```c bool -jerry_api_construct_object (jerry_api_object_t * function_object_p, - jerry_api_value_t * retval_p, +jerry_api_construct_object (jerry_api_object_t *function_object_p, + jerry_api_value_t *retval_p, const jerry_api_value_t args_p[], uint16_t args_count); -{% endhighlight %} +``` - `function_object_p` - the function object to invoke; - `retval_p` - return value of function invoked as constructor, i.e. like with 'new' operator (output parameter); @@ -990,25 +1329,28 @@ jerry_api_construct_object (jerry_api_object_t * function_object_p, - specified object is a constructor function object; - no unhandled exceptions were thrown in connection with the call. -If call was performed successfully, returned value should be freed with [jerry_api_release_object](#jerryapireleaseobject) just when it becomes unnecessary. +If call was performed successfully, returned value should be freed with [jerry_api_release_object](#jerry_api_release_object) just when it becomes unnecessary. **Example** -{% highlight cpp %} +```c { jerry_api_value_t val; ... // receiving val - if (val.type == JERRY_API_DATA_TYPE_OBJECT) { - if (jerry_api_is_constructor (val.v_object)) { + if (val.type == JERRY_API_DATA_TYPE_OBJECT) + { + if (jerry_api_is_constructor (val.u.v_object)) + { jerry_api_value_t ret_val; - bool is_ok = jerry_api_construct_object (val.v_object, + bool is_ok = jerry_api_construct_object (val.u.v_object, &ret_val, NULL, 0); - if (is_ok) { + if (is_ok) + { ... // handle return value jerry_api_release_value (&ret_val); @@ -1016,12 +1358,12 @@ If call was performed successfully, returned value should be freed with [jerry_a } } } -{% endhighlight %} +``` **See also** - - [jerry_api_is_constructor](#jerryapiisconstructor) - - [jerry_api_value_t](#jerryapivaluet) + - [jerry_api_is_constructor](#jerry_api_is_constructor) + - [jerry_api_value_t](#jerry_api_value_t) # jerry_external_handler_t @@ -1031,17 +1373,17 @@ The data type represents pointer to call handler of a native function object. **Structure** -{% highlight cpp %} -typedef bool (* jerry_external_handler_t) (const jerry_api_object_t * function_obj_p, - const jerry_api_value_t * this_p, - jerry_api_value_t * ret_val_p, - const jerry_api_value_t args_p[], - const uint16_t args_count); -{% endhighlight %} +```c +typedef bool (* jerry_external_handler_t) (const jerry_api_object_t *function_obj_p, + const jerry_api_value_t *this_p, + jerry_api_value_t *ret_val_p, + const jerry_api_value_t args_p[], + const uint16_t args_count); +``` **See also** -- [jerry_api_create_external_function](#jerryapicreateexternalfunction) +- [jerry_api_create_external_function](#jerry_api_create_external_function) # jerry_api_create_external_function @@ -1050,39 +1392,39 @@ Create an external function object. **Prototype** -{% highlight cpp %} -jerry_api_object_t* +```c +jerry_api_object_t * jerry_api_create_external_function (jerry_external_handler_t handler_p); -{% endhighlight %} +``` - `handler_p` - pointer to native handler of the function object; - returned value - pointer to constructed external function object. -Received pointer should be released with [jerry_api_release_object](#jerryapireleaseobject), just when the value becomes unnecessary. +Received pointer should be released with [jerry_api_release_object](#jerry_api_release_object), just when the value becomes unnecessary. **Example** -{% highlight cpp %} +```c static bool -handler (const jerry_api_object_t * function_obj_p, - const jerry_api_value_t * this_p, - jerry_api_value_t * ret_val_p, +handler (const jerry_api_object_t *function_obj_p, + const jerry_api_value_t *this_p, + jerry_api_value_t *ret_val_p, const jerry_api_value_t args_p[], const uint16_t args_cnt) { printf ("native handler called!\n"); ret_val_p->type = JERRY_API_DATA_TYPE_BOOLEAN; - ret_val_p->v_bool = true; + ret_val_p->u.v_bool = true; } { - jerry_api_object_t * obj_p = jerry_api_create_external_function (handler); - jerry_api_object_t * glob_obj_p = jerry_api_get_global (); + jerry_api_object_t *obj_p = jerry_api_create_external_function (handler); + jerry_api_object_t *glob_obj_p = jerry_api_get_global (); jerry_api_value_t val; val.type = JERRY_API_DATA_TYPE_OBJECT; - val.v_object = obj_p; + val.u.v_object = obj_p; // after this, script can invoke the native handler through "handler_field (1, 2, 3);" jerry_api_set_object_field_value (glob_obj_p, "handler_field", &val); @@ -1090,56 +1432,56 @@ handler (const jerry_api_object_t * function_obj_p, jerry_api_release_object (glob_obj_p); jerry_api_release_object (obj_p); } -{% endhighlight %} +``` **See also** -- [jerry_external_handler_t](#jerryexternalhandlert) -- [jerry_api_is_function](#jerryapiisfunction) -- [jerry_api_call_function](#jerryapicallfunction) -- [jerry_api_release_object](#jerryapireleaseobject) +- [jerry_external_handler_t](#jerry_external_handler_t) +- [jerry_api_is_function](#jerry_api_is_function) +- [jerry_api_call_function](#jerry_api_call_function) +- [jerry_api_release_object](#jerry_api_release_object) # jerry_api_create_array_object **Summary** Create new JavaScript array object. -Upon the JavaScript array object becomes unused, all pointers to it should be released using [jerry_api_release_object](#jerryapireleaseobject). +Upon the JavaScript array object becomes unused, all pointers to it should be released using [jerry_api_release_object](#jerry_api_release_object). **Prototype** -{% highlight cpp %} -jerry_api_object_t* +```c +jerry_api_object_t * jerry_api_create_array_object (jerry_api_size_t array_size); -{% endhighlight %} +``` - `array_size` - size of array; - returned value is pointer to the created array object. **Example** -{% highlight cpp %} +```c { - jerry_api_object_t * array_object_p = jerry_api_create_array_object (10); + jerry_api_object_t *array_object_p = jerry_api_create_array_object (10); ... jerry_api_release_object (array_object_p); } -{% endhighlight %} +``` **See also** -- [jerry_api_acquire_object](#jerryapiacquireobject) -- [jerry_api_release_object](#jerryapireleaseobject) -- [jerry_api_set_array_index_value](#jerryapisetarrayindexvalue) -- [jerry_api_get_array_index_value](#jerryapigetarrayindexvalue) -- [jerry_api_add_object_field](#jerryapiaddobjectfield) -- [jerry_api_delete_object_field](#jerryapideleteobjectfield) -- [jerry_api_get_object_field_value](#jerryapigetobjectfieldvalue) -- [jerry_api_set_object_field_value](#jerryapisetobjectfieldvalue) -- [jerry_api_get_object_native_handle](#jerryapigetobjectnativehandle) -- [jerry_api_set_object_native_handle](#jerryapisetobjectnativehandle) +- [jerry_api_acquire_object](#jerry_api_acquire_object) +- [jerry_api_release_object](#jerry_api_release_object) +- [jerry_api_set_array_index_value](#jerry_api_set_array_index_value) +- [jerry_api_get_array_index_value](#jerry_api_get_array_index_value) +- [jerry_api_add_object_field](#jerry_api_add_object_field) +- [jerry_api_delete_object_field](#jerry_api_delete_object_field) +- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) +- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) +- [jerry_api_get_object_native_handle](#jerry_api_get_object_native_handle) +- [jerry_api_set_object_native_handle](#jerry_api_set_object_native_handle) # jerry_api_set_array_index_value @@ -1148,12 +1490,12 @@ Set value of an indexed element in the specified array object. **Prototype** -{% highlight cpp %} +```c bool -jerry_api_set_array_index_value (jerry_api_object_t * array_object_p, +jerry_api_set_array_index_value (jerry_api_object_t *array_object_p, jerry_api_length_t index, - jerry_api_value_t * value_p); -{% endhighlight %} + jerry_api_value_t *value_p); +``` - `array_object_p` - pointer to the array object; - `index` - index of the array element; @@ -1162,9 +1504,9 @@ jerry_api_set_array_index_value (jerry_api_object_t * array_object_p, **Example** -{% highlight cpp %} +```c { - jerry_api_object_t * array_object_p = jerry_api_create_array_object (10); + jerry_api_object_t *array_object_p = jerry_api_create_array_object (10); jerry_api_value_t val; ... // receive or construct val @@ -1173,12 +1515,12 @@ jerry_api_set_array_index_value (jerry_api_object_t * array_object_p, jerry_api_release_object (array_object_p); } -{% endhighlight %} +``` **See also** -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_array_object](#jerryapicreatearrayobject) +- [jerry_api_value_t](#jerry_api_value_t) +- [jerry_api_create_array_object](#jerry_api_create_array_object) # jerry_api_get_array_index_value @@ -1187,12 +1529,12 @@ Get value of an indexed element in the specified array object. **Prototype** -{% highlight cpp %} +```c bool -jerry_api_get_array_index_value (jerry_api_object_t * array_object_p, +jerry_api_get_array_index_value (jerry_api_object_t *array_object_p, jerry_api_length_t index, - jerry_api_value_t * value_p); -{% endhighlight %} + jerry_api_value_t *value_p); +``` - `array_object_p` - pointer to the array object; - `index` - index of the array element; @@ -1201,9 +1543,9 @@ jerry_api_get_array_index_value (jerry_api_object_t * array_object_p, **Example** -{% highlight cpp %} +```c { - jerry_api_object_t* array_object_p; + jerry_api_object_t *array_object_p; ... // receive or construct array_object_p jerry_api_value_t val; @@ -1213,52 +1555,13 @@ jerry_api_get_array_index_value (jerry_api_object_t * array_object_p, ... // usage of 'val' } } -{% endhighlight %} +``` **See also** -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_array_object](#jerryapicreatearrayobject) +- [jerry_api_value_t](#jerry_api_value_t) +- [jerry_api_create_array_object](#jerry_api_create_array_object) -# jerry_api_release_value - -**Summary** -Release specified pointer to the value. - -**Prototype** - -{% highlight cpp %} -void -jerry_api_release_value (jerry_api_value_t * value_p); -{% endhighlight %} - -- `value_p` - pointer to the value. - -**Example** -{% highlight cpp %} -{ - jerry_api_value_t val1; - jerry_api_value_t val2; - - val1.type = JERRY_API_DATA_TYPE_OBJECT; - val1.v_object = jerry_api_create_object (); - - val2.type = JERRY_API_DATA_TYPE_STRING; - val2.v_string = jerry_api_create_string ("abc"); - - ... // usage of val1 - - jerry_api_release_value (&val1); - - ... // usage of val2 - - jerry_api_release_value (&val2); -} -{% endhighlight %} - -**See also** - -- [jerry_api_value_t](#jerryapivaluet) # jerry_api_create_error @@ -1268,11 +1571,11 @@ it should be throwed inside of handle attached to external function object. **Prototype** -{% highlight cpp %} -jerry_api_object_t* +```c +jerry_api_object_t * jerry_api_create_error (jerry_api_error_t error_type, - const jerry_api_char_t * message_p); -{% endhighlight %} + const jerry_api_char_t *message_p); +``` - `error_type` - error type of object; - `message_p` - human-readable description of the error; @@ -1280,20 +1583,20 @@ jerry_api_create_error (jerry_api_error_t error_type, **Example** -{% highlight cpp %} +```c static bool -handler (const jerry_api_object_t * function_obj_p, - const jerry_api_value_t * this_p, - jerry_api_value_t * ret_val_p, +handler (const jerry_api_object_t *function_obj_p, + const jerry_api_value_t *this_p, + jerry_api_value_t *ret_val_p, const jerry_api_value_t args_p[], const uint16_t args_cnt) { - jerry_api_object_t * error_p = jerry_api_create_error (JERRY_API_ERROR_TYPE, - (jerry_api_char_t *) "error"); + jerry_api_object_t *error_p = jerry_api_create_error (JERRY_API_ERROR_TYPE, + (jerry_api_char_t * ) "error"); jerry_api_acquire_object (error_p); ret_val_p->type = JERRY_API_DATA_TYPE_OBJECT; - ret_val_p->v_object = error_p; + ret_val_p->u.v_object = error_p; jerry_api_release_object (error_p); @@ -1301,12 +1604,12 @@ handler (const jerry_api_object_t * function_obj_p, } { - jerry_api_object_t * throw_obj_p = jerry_api_create_external_function (handler); - jerry_api_object_t * glob_obj_p = jerry_api_get_global (); + jerry_api_object_t *throw_obj_p = jerry_api_create_external_function (handler); + jerry_api_object_t *glob_obj_p = jerry_api_get_global (); jerry_api_value_t val; val.type = JERRY_API_DATA_TYPE_OBJECT; - val.v_object = throw_obj_p; + val.u.v_object = throw_obj_p; // after this, script can invoke the native handler through "error_func ();" // and "error_func" throw a error on called @@ -1315,11 +1618,57 @@ handler (const jerry_api_object_t * function_obj_p, jerry_api_release_object (glob_obj_p); jerry_api_release_object (throw_obj_p); } -{% endhighlight %} +``` **See also** -- [jerry_external_handler_t](#jerryexternalhandlert) -- [jerry_api_is_function](#jerryapiisfunction) -- [jerry_api_call_function](#jerryapicallfunction) -- [jerry_api_release_object](#jerryapireleaseobject) -- [jerry_api_create_external_function](#jerryapicreateexternalfunction) +- [jerry_external_handler_t](#jerry_external_handler_t) +- [jerry_api_is_function](#jerry_api_is_function) +- [jerry_api_call_function](#jerry_api_call_function) +- [jerry_api_release_object](#jerry_api_release_object) +- [jerry_api_create_external_function](#jerry_api_create_external_function) + + + + + +# jerry_register_external_magic_strings + +**Summary** +Registers an external magic string array. + +**Prototype** +```c +void +jerry_register_external_magic_strings (const jerry_api_char_ptr_t *ex_str_items, + uint32_t count, + const jerry_api_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_FLAG_EMPTY); + + const jerry_api_char_ptr_t magic_string_items[] = { + (const jerry_api_char_ptr_t)"magicstring1", + (const jerry_api_char_ptr_t)"magicstring2", + (const jerry_api_char_ptr_t)"magicstring3" + }; + uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_api_char_ptr_t)); + const jerry_api_length_t magic_string_lengths[] = { + (jerry_api_length_t)strlen(magic_string_items[0]), + (jerry_api_length_t)strlen(magic_string_items[1]), + (jerry_api_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)