archive-gh-me/jerryscript
1
0
Fork 0
mirror of https://github.com/jerryscript-project/jerryscript.git synced 2025-12-15 16:29:21 +00:00
Code Issues Projects Releases Wiki Activity
jerryscript/docs/02.API-REFERENCE.md
Robert Fancsik 77d9314b1d Simplify source evaluation options. (#2431) 
JerryScript-DCO-1.0-Signed-off-by: Robert Fancsik frobert@inf.u-szeged.hu
2018-07-20 08:50:39 +02:00

5911 lines
136 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# JerryScript types
## jerry_init_flag_t
Enum that contains the following elements:
- JERRY_INIT_EMPTY - empty flag set
- JERRY_INIT_SHOW_OPCODES - dump byte-code to log after parse
- JERRY_INIT_SHOW_REGEXP_OPCODES - dump regexp byte-code to log after compilation
- JERRY_INIT_MEM_STATS - dump memory statistics
- JERRY_INIT_MEM_STATS_SEPARATE - dump memory statistics and reset peak values after parse
- JERRY_INIT_DEBUGGER - deprecated, an unused placeholder now
## jerry_type_t
Enum that contains JerryScript API value types:
- JERRY_TYPE_NONE - no type information
- JERRY_TYPE_UNDEFINED - undefined type
- JERRY_TYPE_NULL - null type
- JERRY_TYPE_BOOLEAN - boolean type
- JERRY_TYPE_NUMBER - number type
- JERRY_TYPE_STRING - string type
- JERRY_TYPE_OBJECT - object type
- JERRY_TYPE_FUNCTION - function type
- JERRY_TYPE_ERROR - error/abort type
## 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
There is also a special value `JERRY_ERROR_NONE` which is not an error type
this value can only be returned by the [jerry_get_error_type](#jerry_get_error_type).
## jerry_feature_t
Possible compile time enabled feature types:
- JERRY_FEATURE_CPOINTER_32_BIT - 32 bit compressed pointers
- JERRY_FEATURE_ERROR_MESSAGES - error messages
- JERRY_FEATURE_JS_PARSER - js-parser
- JERRY_FEATURE_MEM_STATS - memory statistics
- JERRY_FEATURE_PARSER_DUMP - parser byte-code dumps
- JERRY_FEATURE_REGEXP_DUMP - regexp byte-code dumps
- JERRY_FEATURE_SNAPSHOT_SAVE - saving snapshot files
- JERRY_FEATURE_SNAPSHOT_EXEC - executing snapshot files
- JERRY_FEATURE_DEBUGGER - debugging
- JERRY_FEATURE_VM_EXEC_STOP - stopping ECMAScript execution
- JERRY_FEATURE_JSON - JSON support
- JERRY_FEATURE_PROMISE - promise support
- JERRY_FEATURE_TYPEDARRAY - Typedarray support
- JERRY_FEATURE_DATE - Date support
- JERRY_FEATURE_REGEXP - RegExp support
- JERRY_FEATURE_LINE_INFO - line info available
## jerry_parse_opts_t
Option bits for [jerry_parse](#jerry_parse) and
[jerry_parse_function](#jerry_parse_function) functions:
- JERRY_PARSE_NO_OPTS - no options passed
- JERRY_PARSE_STRICT_MODE - enable strict mode
## jerry_gc_mode_t
Set garbage collection operational mode
- JERRY_GC_SEVERITY_LOW - free unused objects
- JERRY_GC_SEVERITY_HIGH - free as much memory as possible
The difference between `JERRY_GC_SEVERITY_LOW` and `JERRY_GC_SEVERITY_HIGH`
is that the former keeps memory allocated for performance improvements such
as property hash tables for large objects. The latter frees all possible
memory blocks but the performance may drop after the garbage collection.
## jerry_generate_snapshot_opts_t
Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and
[jerry_generate_function_snapshot](#jerry_generate_function_snapshot) functions:
- JERRY_SNAPSHOT_SAVE_STATIC - generate static snapshot (see below)
- JERRY_SNAPSHOT_SAVE_STRICT - strict source code provided
**Generate static snapshots**
Snapshots contain literal pools, and these literal pools contain references
to constant literals (strings, numbers, etc.). When a snapshot is executed,
these literals are converted to jerry values and the literal pool entries
are changed to their corresponding jerry value. To support this conversion,
the literals and literal pools are copied into RAM even if the
`JERRY_SNAPSHOT_EXEC_COPY_DATA` option is passed to
[jerry_exec_snapshot](#jerry_exec_snapshot). This non-negligible memory
consumption can be avoided by using static snapshots. The literals of
these snapshots are limited to magic strings and 28 bit signed integers,
so their constant pools do not need to be loaded into the memory.
Hence these snapshots can be executed from ROM.
***Important note:*** The [jerry_exec_snapshot](#jerry_exec_snapshot)
function rejects static snaphots unless the `JERRY_SNAPSHOT_EXEC_ALLOW_STATIC`
option bit is set. The caller must also ensure that the same magic
strings are set by [jerry_register_magic_strings](#jerry_register_magic_strings)
when the snapshot is generated and executed. Furthermore the
`JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed.
## jerry_exec_snapshot_opts_t
Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) and
[jerry_load_function_snapshot](#jerry_load_function_snapshot) functions:
- JERRY_SNAPSHOT_EXEC_COPY_DATA - copy snapshot data into memory (see below)
- JERRY_SNAPSHOT_EXEC_ALLOW_STATIC - allow executing static snapshots
**Copy snapshot data into memory**
By default the snapshot buffer is expected to be present in memory until
[jerry_cleanup](#jerry_cleanup) is called. For example `static const` buffers
compiled into the application binary satisfy this requirement.
If the snapshot buffer is freed after [jerry_exec_snapshot](#jerry_exec_snapshot)
is called the `JERRY_SNAPSHOT_EXEC_COPY_DATA` must be passed to copy the necessary
parts of the snapshot buffer into memory.
The `JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed for static snapshots.
## jerry_char_t
**Summary**
Jerry's char value
**Prototype**
```c
typedef uint8_t jerry_char_t;
```
## jerry_char_ptr_t
**Summary**
Pointer to an array of character values
**Prototype**
```c
typedef jerry_char_t *jerry_char_ptr_t;
```
## jerry_size_t
**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_context_data_manager_t
**Summary**
Structure that defines how a context data item will be initialized and deinitialized. JerryScript zeroes out the memory
for the item by default, and if the `init_cb` field is not NULL, it will be called with the pointer to the memory as
an additional custom initializer. The `deinit_cb` (if non-`NULL`) is called during a call to `jerry_cleanup ()` to run
any custom deinitialization *before* the VM has been fully cleaned up. The `finalize_cb` (if non-`NULL`) is also called
during a call to `jerry_cleanup ()` to run any custom deinitialization *after* the VM has been fully cleaned up.
**Prototype**
```c
typedef struct
{
/**
* Callback responsible for initializing a context item, or NULL to zero out the memory. This is called lazily, the
* first time jerry_get_context_data () is called with this manager.
*
* @param [in] data The buffer that JerryScript allocated for the manager. The buffer is zeroed out. The size is
* determined by the bytes_needed field. The buffer is kept alive until jerry_cleanup () is called.
*/
void (*init_cb) (void *data);
/**
* Callback responsible for deinitializing a context item, or NULL. This is called as part of jerry_cleanup (),
* right *before* the VM has been cleaned up. This is a good place to release strong references to jerry_value_t's
* that the manager may be holding.
* Note: because the VM has not been fully cleaned up yet, jerry_object_native_info_t free_cb's can still get called
* *after* all deinit_cb's have been run. See finalize_cb for a callback that is guaranteed to run *after* all
* free_cb's have been run.
*
* @param [in] data The buffer that JerryScript allocated for the manager.
*/
void (*deinit_cb) (void *data);
/**
* Callback responsible for finalizing a context item, or NULL. This is called as part of jerry_cleanup (),
* right *after* the VM has been cleaned up and destroyed and jerry_... APIs cannot be called any more. At this point,
* all values in the VM have been cleaned up. This is a good place to clean up native state that can only be cleaned
* up at the very end when there are no more VM values around that may need to access that state.
*
* @param [in] data The buffer that JerryScript allocated for the manager. After returning from this callback,
* the data pointer may no longer be used.
*/
void (*finalize_cb) (void *data);
/**
* Number of bytes to allocate for this manager. This is the size of the buffer that JerryScript will allocate on
* behalf of the manager. The pointer to this buffer is passed into init_cb, deinit_cb and finalize_cb. It is also
* returned from the jerry_get_context_data () API.
*/
size_t bytes_needed;
} jerry_context_data_manager_t;
```
## jerry_property_descriptor_t
**Summary**
Description of ECMA property descriptor
**Prototype**
```c
typedef struct
{
/** Is [[Value]] defined? */
bool is_value_defined;
/** 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;
```
## jerry_heap_stats_t
**summary**
Description of JerryScript heap memory stats.
It is for memory profiling.
**Prototype**
```c
typedef struct
{
size_t version /**< the version of the stats struct */
size_t size; /**< heap total size */
size_t allocated_bytes; /**< currently allocated bytes */
size_t peak_allocated_bytes; /**< peak allocated bytes */
size_t reserved[4]; /**< padding for future extensions */
} jerry_heap_stats_t;
```
## jerry_external_handler_t
**Summary**
Type of an external function handler
**Prototype**
```c
typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj,
const jerry_value_t this_val,
const jerry_value_t args_p[],
const jerry_length_t args_count);
```
## jerry_object_free_callback_t
**Summary**
**Deprecated: Please use jerry_object_native_free_callback_t instead.**
Native free callback of an object.
**Prototype**
```c
typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p);
```
## jerry_object_native_free_callback_t
**Summary**
Native free callback of an object. It is used in jerry_object_native_info_t.
**Prototype**
```c
typedef void (*jerry_object_native_free_callback_t) (void *native_p);
```
## jerry_object_native_info_t
**Summary**
The type information of the native pointer.
It includes the free callback that will be called when associated JavaScript object is garbage collected. It can be left NULL in case it is not needed.
Typically, one would create a `static const jerry_object_native_info_t` for
each distinct C type for which a pointer is used with
`jerry_set_object_native_pointer ()` and `jerry_get_object_native_pointer ()`.
This way, each `const jerry_object_native_info_t *` pointer address value itself
uniquely identifies the C type of the native pointer.
See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
for a best-practice code example.
**Prototype**
```c
typedef struct
{
jerry_object_native_free_callback_t free_cb;
} jerry_object_native_info_t;
```
**See also**
- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
## 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,
const jerry_value_t property_value,
void *user_data_p);
```
## jerry_objects_foreach_t
**Summary**
Function type applied for each object in the engine
**Prototype**
```c
typedef bool (*jerry_objects_foreach_t) (const jerry_value_t object,
void *user_data_p);
```
## jerry_objects_foreach_by_native_info_t
**Summary**
Function type applied for each matching object in the engine
**Prototype**
```c
typedef bool (*jerry_objects_foreach_by_native_info_t) (const jerry_value_t object,
void *object_data_p,
void *user_data_p);
```
## jerry_vm_exec_stop_callback_t
**Summary**
Callback which tells whether the ECMAScript execution should be stopped.
If it returns with undefined value the ECMAScript execution continues.
Otherwise the result is thrown by the engine (if the error flag is not
set for the returned value the engine automatically sets it). The
callback function might be called again even if it threw an error.
In this case the function must throw the same error again.
**Prototype**
```c
typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p);
```
**See also**
- [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback)
## jerry_typedarray_type_t
Enum which describes the TypedArray types.
Possible values:
- JERRY_TYPEDARRAY_UINT8 - represents the Uint8Array TypedArray
- JERRY_TYPEDARRAY_UINT8CLAMPED - represents the Uint8ClampedArray TypedArray
- JERRY_TYPEDARRAY_INT8 - represents the Int8Array TypedArray
- JERRY_TYPEDARRAY_UINT16 - represents the Uint16Array TypedArray
- JERRY_TYPEDARRAY_INT16 - represents the Int16Array TypedArray
- JERRY_TYPEDARRAY_UINT32 - represents the Uint32Array TypedArray
- JERRY_TYPEDARRAY_INT32 - represents the Int32Array TypedArray
- JERRY_TYPEDARRAY_FLOAT32 - represents the Float32Array TypedArray
- JERRY_TYPEDARRAY_FLOAT64 - represents the Float64Array TypedArray
- JERRY_TYPEDARRAY_INVALID - represents an invalid TypedArray
API functions can return the `JERRY_TYPEDARRAY_INVALID` value if the
TypedArray support is not in the engine.
# General engine functions
## jerry_init
**Summary**
Initializes the JerryScript engine, making it possible to run JavaScript code and perform operations
on JavaScript values.
**Prototype**
```c
void
jerry_init (jerry_init_flag_t flags)
```
`flags` - combination of various engine configuration flags:
- `JERRY_INIT_EMPTY` - no flags, just initialize in default configuration.
- `JERRY_INIT_SHOW_OPCODES` - print compiled byte-code.
- `JERRY_INIT_SHOW_REGEXP_OPCODES` - print compiled regexp byte-code.
- `JERRY_INIT_MEM_STATS` - dump memory statistics.
- `JERRY_INIT_MEM_STATS_SEPARATE` - dump memory statistics and reset peak values after parse.
- `JERRY_INIT_DEBUGGER` - deprecated, an unused placeholder now
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_SHOW_REGEXP_OPCODES);
// ...
jerry_cleanup ();
}
```
**See also**
- [jerry_cleanup](#jerry_cleanup)
## jerry_cleanup
**Summary**
Finish JavaScript engine execution, freeing memory and JavaScript values.
*Note*: JavaScript values, received from engine, will be inaccessible after the cleanup.
**Prototype**
```c
void
jerry_cleanup (void);
```
**See also**
- [jerry_init](#jerry_init)
## jerry_get_context_data
**Summary**
Retrieve a pointer to the item stored within the current context by the given manager.
*Note*: Since internally the pointer to a manager's context data item is linked to the next such pointer in a linked
list, it is inadvisable to invoke too many different managers, because doing so will increase the time it takes
to retrieve a manager's context data item, degrading performance. For example, try to keep the number of
managers below five.
**Prototype**
```c
void *
jerry_get_context_data (const jerry_context_data_manager *manager_p);
```
- `manager_p`: the manager of this context data item.
- return value: the item created by `manager_p` when `jerry_get_context_data ()` was first called, or a new item created
by `manager_p`, which will be stored for future identical calls to `jerry_get_context_data ()`, and which will be
deinitialized using the `deinit_cb` callback provided by `manager_p` when the context will be destroyed.
**Example**
[doctest]: # (test="compile")
```c
#include "jerryscript.h"
typedef struct
{
int my_data1;
double my_data2;
char *my_data3;
} my_context_data_t;
/* Define how context items will be initialized. */
static void
my_context_data_new (void *user_data_p)
{
my_context_data_t *my_data_p = (my_context_data_t *) user_data_p;
/*
* Initialize my_data_p. JerryScript will store it on the current context and return it whenever
* jerry_get_context_data () is called with a pointer to my_manager as defined below.
*/
}
/* Define how context items will be deinitialized */
static void
my_context_data_free (void *user_data_p)
{
my_context_data_t *my_data_p = ((my_context_data_t *) user_data_p);
/* Perform any necessary cleanup on my_data. JerryScript will free the pointer after this function completes. */
}
/* Wrap the creation and destruction functions into a manager */
static const jerry_context_data_manager_t my_manager =
{
.init_cb = my_context_data_new,
.deinit_cb = my_context_data_free,
.bytes_needed = sizeof (my_context_data_t)
};
/*
* Then, in some function in your code, you can retrieve an item of type my_context_data_t from the currently active
* context such that JerryScript will create and store such an item if one was not previously created
*/
static void
someplace_in_the_code (void)
{
my_context_data_t *my_data = (my_context_data_t *) jerry_get_context_data (&my_manager);
/* Perform useful things using the data found in my_data */
}
```
## jerry_register_magic_strings
**Summary**
Registers an external magic string array.
*Note*: The strings in the array must be sorted by size at first, then lexicographically.
**Prototype**
```c
void
jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p,
uint32_t count,
const jerry_length_t *str_lengths_p);
```
- `ex_str_items_p` - character arrays, representing external magic strings' contents
- `count` - number of the strings
- `str_lengths_p` - lengths of the strings
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
// must be static, because 'jerry_register_magic_strings' does not copy
// the items must be sorted by size at first, then lexicographically
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[] = {
12,
12,
12
};
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_parse_and_save_literals](#jerry_parse_and_save_literals)
## jerry_get_memory_stats
**Summary**
Get heap memory stats.
**Prototype**
```c
bool
jerry_get_memory_stats (jerry_heap_stats_t *out_stats_p);
```
- `out_stats_p` - out parameter, that provides the heap statistics.
- return value
- true, if run was successful
- false, otherwise. Usually it is because the MEM_STATS feature is not enabled.
**Example**
```c
jerry_heap_stats_t stats = {0};
bool get_stats_ret = jerry_get_memory_stats (&stats);
```
**See also**
- [jerry_init](#jerry_init)
## jerry_gc
**Summary**
Performs garbage collection.
**Prototype**
```c
void
jerry_gc (jerry_gc_mode_t mode);
```
- `mode` - operational mode, see [jerry_gc_mode_t](#jerry_gc_mode_t)
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t object_value = jerry_create_object ();
jerry_release_value (object_value);
jerry_gc (JERRY_GC_SEVERITY_LOW);
jerry_cleanup ();
}
```
**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_p,
size_t script_source_size,
jerry_init_flag_t flags);
```
- `script_source_p` - 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**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
const jerry_char_t *script = (const jerry_char_t *) "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
**Summary**
Parse script and construct an EcmaScript function. The lexical environment is
set to the global lexical environment. The resource name can be used by
debugging systems to provide line / backtrace info.
*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_parse (const jerry_char_t *resource_name_p, /**< resource name (usually a file name) */
size_t resource_name_length, /**< length of resource name */
const jerry_char_t *source_p,
size_t source_size,
uint32_t parse_opts);
```
- `resource_name_p` - resource name, usually a file name (must be a valid UTF8 string).
- `resource_name_length` - size of the resource name, in bytes.
- `source_p` - string, containing source code to parse (must be a valid UTF8 string).
- `source_size` - size of the string, in bytes.
- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags.
- return value
- function object value, if script was parsed successfully,
- thrown error, otherwise
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
jerry_release_value (parsed_code);
jerry_cleanup ();
}
```
**See also**
- [jerry_run](#jerry_run)
## jerry_parse_function
**Summary**
Parse function source code and construct an ECMAScript
function. The function arguments and function body are
passed as separated arguments. The lexical environment
is set to the global lexical environment. The resource
name (usually a file name) is also passed to this function
which is used by the debugger to find the source code.
*Note*: The returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
jerry_value_t
jerry_parse_function (const jerry_char_t *resource_name_p, /**< resource name (usually a file name) */
size_t resource_name_length, /**< length of resource name */
const jerry_char_t *arg_list_p, /**< script source */
size_t arg_list_size, /**< script source size */
const jerry_char_t *source_p, /**< script source */
size_t source_size, /**< script source size */
uint32_t parse_opts) /**< strict mode */
```
- `resource_name_p` - resource name, usually a file name (must be a valid UTF8 string).
- `resource_name_length` - size of the resource name, in bytes.
- `arg_list_p` - argument list of the function (must be a valid UTF8 string).
- `arg_list_size` - size of the argument list, in bytes.
- `source_p` - string, containing source code to parse (must be a valid UTF8 string).
- `source_size` - size of the string, in bytes.
- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags.
- return value
- function object value, if script was parsed successfully,
- thrown error, otherwise
## jerry_run
**Summary**
Run an EcmaScript function created by `jerry_parse`.
*Note*: The code should be previously parsed with `jerry_parse`.
**Prototype**
```c
jerry_value_t
jerry_run (const jerry_value_t func_val);
```
- `func_val` - function to run
- return value
- result of bytecode, if run was successful
- thrown error, otherwise
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
/* Initialize engine */
jerry_init (JERRY_INIT_EMPTY);
/* Setup Global scope code */
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
if (!jerry_value_is_error (parsed_code))
{
/* 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 ();
}
```
**See also**
- [jerry_parse](#jerry_parse)
## jerry_eval
**Summary**
Perform JavaScript `eval`.
**Prototype**
```c
jerry_value_t
jerry_eval (const jerry_char_t *source_p,
size_t source_size,
uint32_t parse_opts);
```
- `source_p` - source code to evaluate, it must be a valid utf8 string.
- `source_size` - length of the source code
- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags.
- return value - result of eval, may be error value.
**Example**
```c
{
jerry_value_t ret_val = jerry_eval (str_to_eval,
strlen (str_to_eval),
JERRY_PARSE_NO_OPTS);
}
```
**See also**
- [jerry_create_external_function](#jerry_create_external_function)
- [jerry_external_handler_t](#jerry_external_handler_t)
## jerry_run_all_enqueued_jobs
**Summary**
Run enqueued Promise jobs until the first thrown error or until all get executed.
**Prototype**
```c
jerry_value_t
jerry_run_all_enqueued_jobs (void)
```
- return value - result of last executed job, may be error value.
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
const jerry_char_t script[] = "new Promise(function(f,r) { f('Hello, World!'); }).then(function(x) { print(x); });";
size_t script_size = strlen ((const char *) script);
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
jerry_value_t script_value = jerry_run (parsed_code);
jerry_value_t job_value = jerry_run_all_enqueued_jobs ();
jerry_release_value (job_value);
jerry_release_value (script_value);
jerry_release_value (parsed_code);
jerry_cleanup ();
}
```
# Get the global context
## jerry_get_global_object
**Summary**
Get the Global 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_global_object (void);
```
- return value - api value of global object
**Example**
```c
{
jerry_value_t glob_obj_val = jerry_get_global_object ();
... // Do something with global object, ex: add properties
jerry_release_value (glob_obj_val);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
- [jerry_define_own_property](#jerry_define_own_property)
# Checker functions
Functions to check the type of an API value ([jerry_value_t](#jerry_value_t)).
## jerry_value_is_abort
**Summary**
Returns whether the given `jerry_value_t` has the error and abort value set.
**Prototype**
```c
bool
jerry_value_is_abort (const jerry_value_t value);
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` has the error and abort value set
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_abort (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_value_is_error](#jerry_value_is_error)
## jerry_value_is_array
**Summary**
Returns whether the given `jerry_value_t` is an array.
**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_arraybuffer
**Summary**
Returns whether the given `jerry_value_t` is an ArrayBuffer object.
**Prototype**
```c
bool
jerry_value_is_arraybuffer (const jerry_value_t value)
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` is an ArrayBuffer object.
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_arraybuffer (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_create_arraybuffer](#jerry_create_arraybuffer)
- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)
## jerry_value_is_boolean
**Summary**
Returns whether the given `jerry_value_t` is a boolean value.
**Prototype**
```c
bool
jerry_value_is_boolean (const jerry_value_t value)
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` is a boolean value
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_boolean (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_value_is_constructor
**Summary**
Returns whether the given `jerry_value_t` is a constructor function.
**Prototype**
```c
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_value_t value;
... // create or acquire value
if (jerry_value_is_constructor (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_value_is_error
**Summary**
Returns whether the given `jerry_value_t` is error value.
**Prototype**
```c
bool
jerry_value_is_error (const jerry_value_t value);
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` is error value.
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_error (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_value_is_abort](#jerry_value_is_abort)
## jerry_value_is_function
**Summary**
Returns whether the given `jerry_value_t` is a function.
**Prototype**
```c
bool
jerry_value_is_function (const jerry_value_t value)
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` is a function
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_function (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_value_is_number
**Summary**
Returns whether the given `jerry_value_t` is a number.
**Prototype**
```c
bool
jerry_value_is_function (const jerry_value_t value)
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` is a number
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_number (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_value_is_null
**Summary**
Returns whether the given `jerry_value_t` is a null value.
**Prototype**
```c
bool
jerry_value_is_null (const jerry_value_t value)
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` is a null
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_null (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_value_is_object
**Summary**
Returns whether the given `jerry_value_t` is an object value.
**Prototype**
```c
bool
jerry_value_is_object (const jerry_value_t value)
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` is an object
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_object (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_value_is_promise
**Summary**
Returns whether the given `jerry_value_t` is a promise value.
*Note*: This API depends on the ES2015-subset profile.
**Prototype**
```c
bool
jerry_value_is_promise (const jerry_value_t value)
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` is a promise
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_promise (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_value_is_string
**Summary**
Returns whether the given `jerry_value_t` is a string value.
**Prototype**
```c
bool
jerry_value_is_string (const jerry_value_t value)
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` is a string
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_string (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_value_is_typedarray
**Summary**
Checks whether the given `jerry_value_t` is a TypedArray object or not.
**Prototype**
```c
bool
jerry_value_is_typedarray (const jerry_value_t value)
```
- `value` - object to check
- return value
- true, if the given `jerry_value_t` is a TypedArray object.
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_typedarray (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_create_typedarray](#jerry_create_typedarray)
## jerry_value_is_undefined
**Summary**
Returns whether the given `jerry_value_t` is an undefined value.
**Prototype**
```c
bool
jerry_value_is_undefined (const jerry_value_t value)
```
- `value` - api value
- return value
- true, if the given `jerry_value_t` is an undefined value
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_undefined (value))
{
...
}
jerry_release_value (value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_value_get_type
**Summary**
Returns the JavaScript type
for a given value as a [jerry_type_t](#jerry_type_t) enum value.
This is a similar operation to the 'typeof' operator
in the standard with an exception that the 'null'
value has its own enum value.
**Prototype**
```c
jerry_type_t
jerry_value_get_type (const jerry_value_t value);
```
**Example**
```c
{
jerry_value_t number = jerry_create_number (3.3);
jerry_type_t type_info = jerry_value_get_type (number);
if (type_info == JERRY_TYPE_NUMBER)
{
...
}
jerry_value_release (number);
}
```
**See also**
- [jerry_type_t](#jerry_type_t)
## jerry_is_feature_enabled
**Summary**
Returns whether the specified compile time feature is enabled.
**Prototype**
```c
bool
jerry_is_feature_enabled (const jerry_feature_t feature);
```
- `feature` - jerry feature
- return value
- true, if the given `jerry_feature_t` is enabled
- false, otherwise
**Example**
```c
{
...
jerry_feature_t feature = JERRY_FEATURE_SNAPSHOT_SAVE;
if (jerry_is_feature_enabled (feature))
{
...
}
}
```
# Error manipulation functions
## jerry_create_abort_from_value
**Summary**
Create (api) abort from a value.
This function creates an API abort value from an API value. The second argument defines
whether the input value must be released or not. If it is set to `true`,
then a [`jerry_release_value`](#jerry_release_value) function will be called
for the first argument, so the api value won't be available after the call of
`jerry_create_abort_from_value`. The second argument should be false if both value
and created abort value are needed.
**Prototype**
```c
jerry_value_t
jerry_create_abort_from_value (jerry_value_t value, bool release);
```
- `value` - api value
- `release` - raw boolean, defines whether input value must be released
- return value - abort (api) value
**Example 1**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t abort = jerry_create_abort_from_value (value, true);
// using the 'value' variable after release is invalid.
jerry_release_value (abort);
}
```
**Example 2**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t abort = jerry_create_abort_from_value (value, false);
// both 'abort' and 'value' can be used and must be released when they are no longer needed
jerry_release_value (abort);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_create_error_from_value](#jerry_create_error_from_value)
## jerry_create_error_from_value
**Summary**
Create (api) error from a value.
This function creates an API error value from an API value. The second argument defines
whether the input value must be released or not. If it is set to `true`,
then a [`jerry_release_value`](#jerry_release_value) function will be called
for the first argument, so the api value won't be available after the call of
`jerry_create_error_from_value`. The second argument should be false if both value
and created error value are needed.
**Prototype**
```c
jerry_value_t
jerry_create_error_from_value (jerry_value_t value, bool release);
```
- `value` - api value
- `release` - raw boolean, defines whether input value must be released
- return value - error (api) value
**Example 1**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t error = jerry_create_error_from_value (value, true);
// using the 'value' variable after release is invalid.
jerry_release_value (error);
}
```
**Example 2**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t error = jerry_create_error_from_value (value, false);
// both 'error' and 'value' can be used and must be released when they are no longer needed
jerry_release_value (error);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_create_abort_from_value](#jerry_create_abort_from_value
## jerry_get_error_type
**Summary**
Returns the type of the Error object if possible.
If a non-error object is used as the input for the function the method
will return `JERRY_ERROR_NONE` indicating that the value was not
an Error object. However it is still possible that the value contains
error semantics. To correctly detect if a value have error use the
[jerry_value_is_error](#jerry_value_is_error) method.
**Prototype**
```c
jerry_error_t
jerry_get_error_type (const jerry_value_t value);
```
- `value` - api value (possible error object)
- return value
- JERRY_ERROR_NONE if the input is not an error object
- one of the [jerry_error_t](#jerry_error_t) value
**Example**
```c
{
jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_RANGE,
(const jerry_char_t *) "error msg");
jerry_error_t error_type = jerry_get_error_type (error_obj);
// error_type is now JERRY_ERROR_RANGE.
jerry_release_value (error_obj);
}
```
**See also**
- [jerry_create_error](#jerry_create_error)
- [jerry_value_is_error](#jerry_value_is_error)
## jerry_get_value_from_error
**Summary**
Get the value from an error.
Many API functions cannot be called with an error value.
This function extracts the API value from an error. The second argument defines
whether the input error value must be released or not. If it is set to `true`,
then a [`jerry_release_value`](#jerry_release_value) function will be called
for the first argument, so the error value won't be available after the call of
`jerry_get_value_from_error`. The second argument should be false if both error
and its represented value are needed.
*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_value_from_error (jerry_value_t value, bool release)
```
- `value` - error (api) value
- `release` - raw boolean, defines whether input value must be released
- return value - api value
**Example 1**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t error = jerry_create_error_from_value (value, true);
jerry_value_t value_from_error = jerry_get_value_from_error (error, true);
// using the 'error' variable after release is invalid.
jerry_release_value (value_from_error);
}
```
**Example 2**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t error = jerry_create_error_from_value (value, true);
jerry_value_t value_from_error = jerry_get_value_from_error (error, false);
// both 'error' and 'value_from_error' can be used and must be released when they are no longer needed
jerry_release_value (value_from_error);
jerry_release_value (error);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_create_error_from_value](#jerry_create_error_from_value)
- [jerry_create_abort_from_value](#jerry_create_abort_from_value)
# Getter functions of 'jerry_value_t'
Get raw data from API values.
## jerry_get_boolean_value
**Summary**
Gets the raw bool value from a `jerry_value_t`.
**Prototype**
```c
bool
jerry_get_boolean_value (const jerry_value_t value);
```
- `value` - api value
- return value - boolean value represented by the argument.
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_boolean (value))
{
bool raw_value = jerry_get_boolean_value (value);
... // usage of raw value
}
jerry_release_value (value);
}
```
**See also**
- [jerry_value_is_boolean](#jerry_value_is_boolean)
- [jerry_release_value](#jerry_release_value)
## jerry_get_number_value
**Summary**
Gets the number value of the given `jerry_value_t` parameter as a raw double.
**Prototype**
```c
double
jerry_get_number_value (const jerry_value_t value);
```
- `value` - api value
- return value - the number value of the given `jerry_value_t` parameter as a raw double.
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
if (jerry_value_is_number (value))
{
double raw_value = jerry_get_number_value (value);
... // usage of raw value
}
jerry_release_value (value);
}
```
**See also**
- [jerry_value_is_number](#jerry_value_is_number)
- [jerry_release_value](#jerry_release_value)
# Functions for string values
## jerry_get_string_size
**Summary**
Get the size of a string. Returns zero, if the value parameter is not a string.
**Prototype**
```c
jerry_size_t
jerry_get_string_size (const jerry_value_t value);
```
- `value` - api value
- return value - number of bytes in the buffer needed to represent the string.
**Example**
```c
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string = jerry_create_string (char_array);
jerry_size_t string_size = jerry_get_string_size (string);
... // usage of string_size
jerry_release_value (string);
}
```
**See also**
- [jerry_create_string](#jerry_create_string)
- [jerry_get_string_length](#jerry_get_string_length)
- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
## jerry_get_utf8_string_size
**Summary**
Get the size of an utf8-encoded string. Returns zero, if the value parameter is not a string.
*Note*: The difference from [jerry_get_string_size](#jerry_get_string_size) is that it returns with utf-8 string size
instead of the cesu-8 string size.
**Prototype**
```c
jerry_size_t
jerry_get_utf8_string_size (const jerry_value_t value);
```
- `value` - api value
- return value - number of bytes in the buffer needed to represent the utf8-encoded string.
**Example**
```c
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string = jerry_create_string (char_array);
jerry_size_t string_size = jerry_get_utf8_string_size (string);
... // usage of string_size
jerry_release_value (string);
}
```
**See also**
- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)
- [jerry_get_utf8_string_length](#jerry_get_utf8_string_length)
- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string)
## jerry_get_string_length
**Summary**
Get the length of a string. Returns zero, if the value parameter is not a string.
**Prototype**
```c
jerry_length_t
jerry_get_string_length (const jerry_value_t value);
```
- `value` - api value
- return value - number of characters in the string
**Example**
```c
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string = jerry_create_string (char_array);
jerry_length_t string_length = jerry_get_string_length (string);
... // usage of string_length
jerry_release_value (string);
}
```
**See also**
- [jerry_create_string](#jerry_create_string)
- [jerry_get_string_size](#jerry_get_string_size)
- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
## jerry_get_utf8_string_length
**Summary**
Get the length of an UTF-8 encoded string. Returns zero, if the value parameter is not a string.
*Note*: The difference from [jerry_get_string_length](#jerry_get_string_length) is that it
returns with utf-8 string length instead of the cesu-8 string length.
**Prototype**
```c
jerry_length_t
jerry_get_utf8_string_length (const jerry_value_t value);
```
- `value` - input string value
- return value - number of characters in the string
**Example**
```c
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string = jerry_create_string_from_utf8 (char_array);
jerry_length_t string_length = jerry_get_utf8_string_length (string);
... // usage of string_length
jerry_release_value (string);
}
```
**See also**
- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)
- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size)
- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string)
## jerry_string_to_char_buffer
**Summary**
Copy the characters of a string into a specified cesu-8 buffer.
The '\0' character could occur in the character buffer. Returns 0,
if the value parameter is not a string or the buffer is not large
enough for the whole string.
*Note*: Does not put '\0' to the end of string, the return value identifies
the number of valid bytes in the output buffer.
*Note*: If the size of the string in jerry value is larger than the size of the
target buffer, the copy will fail. To copy a substring the
[jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer) API function
is recommended instead.
**Prototype**
```c
jerry_size_t
jerry_string_to_char_buffer (const jerry_value_t value,
jerry_char_t *buffer_p,
jerry_size_t buffer_size);
```
- `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_value_t value;
... // create or acquire value
jerry_size_t req_sz = jerry_get_string_size (value);
jerry_char_t str_buf_p[req_sz];
jerry_string_to_char_buffer (value, str_buf_p, req_sz);
jerry_release_value (value);
}
```
**See also**
- [jerry_create_string](#jerry_create_string)
- [jerry_get_string_size](#jerry_get_string_size)
- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer)
## jerry_string_to_utf8_char_buffer
**Summary**
Copy the characters of a string into a specified utf-8 buffer.
The '\0' character could occur in character buffer. Returns 0,
if the value parameter is not a string or the buffer is not
large enough for the whole string.
*Note*: Does not put '\0' to the end of string, the return value identifies
the number of valid bytes in the output buffer.
*Note*: If the size of the string in jerry value is larger than the size of the
target buffer, the copy will fail. To copy a substring the
[jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer)
API function is recommended instead.
**Prototype**
```c
jerry_size_t
jerry_string_to_utf8_char_buffer (const jerry_value_t value,
jerry_char_t *buffer_p,
jerry_size_t buffer_size);
```
- `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_value_t value;
... // create or acquire value
jerry_size_t req_sz = jerry_get_utf8_string_size (value);
jerry_char_t str_buf_p[req_sz];
jerry_string_to_utf8_char_buffer (value, str_buf_p, req_sz);
jerry_release_value (value);
}
```
**See also**
- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)
- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size)
- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string)
- [jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer)
## jerry_substring_to_char_buffer
**Summary**
Copy the characters of a cesu-8 encoded substring into a specified buffer.
The '\0' character could occur in character buffer. Returns 0, if the value
parameter is not a string. It will extract the substring between the
specified start position and the end position (or the end of the string,
whichever comes first).
*Note*: Does not put '\0' to the end of string, the return value identifies
the number of valid bytes in the output buffer.
**Prototype**
```c
jerry_size_t
jerry_substring_to_char_buffer (const jerry_value_t value,
jerry_length_t start_pos,
jerry_length_t end_pos,
jerry_char_t *buffer_p,
jerry_size_t buffer_size);
```
- `value` - input string value
- `start_pos` - position of the first character
- `end_pos` - position of the last character
- `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_value_t value;
... // create or acquire value
jerry_size_t req_sz = jerry_get_string_size (value);
jerry_char_t str_buf_p[req_sz];
jerry_length_t start_pos = 0;
jerry_length_t end_pos = jerry_get_string_length (value);
jerry_substring_to_char_buffer (value, start_pos, end_pos, str_buf_p, req_sz);
jerry_release_value (value);
}
```
**See also**
- [jerry_create_string](#jerry_create_string)
- [jerry_get_string_size](#jerry_get_string_size)
- [jerry_get_string_length](#jerry_get_string_length)
- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
## jerry_substring_to_utf8_char_buffer
**Summary**
Copy the characters of an utf-8 encoded substring into a specified buffer.
The '\0' character could occur in character buffer. Returns 0, if the value
parameter is not a string. It will extract the substring between the specified
start position and the end position (or the end of the string, whichever
comes first).
*Note*: Does not put '\0' to the end of string, the return value identifies
the number of valid bytes in the output buffer.
**Prototype**
```c
jerry_size_t
jerry_substring_to_utf8_char_buffer (const jerry_value_t value,
jerry_length_t start_pos,
jerry_length_t end_pos,
jerry_char_t *buffer_p,
jerry_size_t buffer_size);
```
- `value` - input string value
- `start_pos` - position of the first character
- `end_pos` - position of the last character
- `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_value_t value;
... // create or acquire value
jerry_size_t req_sz = jerry_get_utf8_string_size (value);
jerry_char_t str_buf_p[req_sz];
jerry_length_t start_pos = 0;
jerry_length_t end_pos = jerry_get_utf8_string_length (value);
jerry_substring_to_utf8_char_buffer (value, start_pos, end_pos, str_buf_p, req_sz);
jerry_release_value (value);
}
```
**See also**
- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)
- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size)
- [jerry_get_utf8_string_length](#jerry_get_utf8_string_length)
- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string)
# Functions for array object values
## jerry_get_array_length
**Summary**
Get length of an array object. Returns zero, if the given parameter is not an array object.
**Prototype**
```c
uint32_t
jerry_get_array_length (const jerry_value_t value);
```
- `value` - input array value
- return value - length of the given array
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
uint32_t len = jerry_get_array_length (value);
jerry_release_value (value);
}
```
**See also**
- [jerry_create_array](#jerry_create_array)
# Converters of 'jerry_value_t'
Functions for converting API values to another value type.
## jerry_value_to_boolean
**Summary**
Call ToBoolean operation on the api value.
**Prototype**
```c
bool
jerry_value_to_boolean (const jerry_value_t value);
```
- `value` - api value
- return value
- true, if the logical value is true
- false, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
bool b = jerry_value_to_boolean (value);
jerry_release_value (value);
}
```
**See also**
- [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_to_object
**Summary**
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
jerry_value_t
jerry_value_to_object (const jerry_value_t value);
```
- `value` - api value
- return value
- converted object value, if success
- thrown error, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t object_value = jerry_value_to_object (value);
jerry_release_value (object_value);
jerry_release_value (value);
}
```
**See also**
- [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_to_string
**Summary**
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
jerry_value_t
jerry_value_to_string (const jerry_value_t value);
```
- `value` - api value
- return value
- converted string value, if success
- thrown error, otherwise
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t string_value = jerry_value_to_string (value);
jerry_release_value (string_value);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_to_primitive](#jerry_value_to_primitive)
# Functions for promise objects
These APIs all depends on the ES2015-subset profile.
## jerry_resolve_or_reject_promise
**Summary**
Resolve or reject the promise with an argument.
**Prototype**
```c
jerry_value_t
jerry_resolve_or_reject_promise (jerry_value_t promise,
jerry_value_t argument,
bool is_resolve)
```
- `promise` - the promise value
- `argument` - the argument for resolve or reject
- `is_resolve` - whether the promise should be resolved or rejected
- return value
- undefined jerry value - resolve or reject successed
- jerry value with error flag - otherwise
**Example**
```c
{
jerry_value_t promise = ... // acquire/create a promise object.
...
bool is_resolve = ... // whether the promise should be resolved or rejected
jerry_value_t argument = ... // prepare the argumnent for the resolve or reject.
jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
argument,
is_resolve);
if (jerry_value_is_error (is_ok))
{
// handle the error.
}
jerry_release_value (is_ok);
jerry_release_value (argument);
jerry_release_value (promise);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
- [jerry_value_is_error](#jerry_value_is_error)
# Acquire and release API values
## jerry_acquire_value
**Summary**
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
jerry_value_t
jerry_acquire_value (jerry_value_t value);
```
- `value` - api value
- return value - acquired value that may be used outside of the engine
**Example**
```c
{
jerry_value_t object_value = jerry_create_object ();
jerry_value_t acquired_object = jerry_acquire_value (object_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_release_value](#jerry_release_value)
- [jerry_value_t](#jerry_value_t)
## jerry_release_value
**Summary**
Release specified Jerry API value.
**Prototype**
```c
void
jerry_release_value (jerry_value_t value);
```
- `value` - api value
**Example**
```c
{
jerry_value_t object_value = jerry_create_object ();
...
jerry_release_value (object_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_create_array
**Summary**
Create an array object value.
**Prototype**
```c
jerry_value_t
jerry_create_array (uint32_t size);
```
- `size` - size of array;
- return value - value of the constructed array object
**Example**
```c
{
jerry_value_t array = jerry_create_array (10);
...
jerry_release_value (array);
}
```
**See also**
- [jerry_set_property_by_index](#jerry_set_property_by_index)
- [jerry_get_property_by_index](#jerry_get_property_by_index)
## jerry_create_arraybuffer
**Summary**
Create a jerry_value_t representing an ArrayBuffer object.
**Prototype**
```c
jerry_value_t
jerry_create_arraybuffer (jerry_length_t size);
```
- `size` - size of the ArrayBuffer to create **in bytes**
- return value - the new ArrayBuffer as a `jerry_value_t`
**Example**
```c
{
jerry_value_t buffer_value = jerry_create_arraybuffer (15);
... // use the ArrayBuffer
jerry_release_value (buffer_value);
}
```
**See also**
- [jerry_arraybuffer_read](#jerry_arraybuffer_read)
- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
- [jerry_value_is_arraybuffer](#jerry_value_is_arraybuffer)
- [jerry_release_value](#jerry_release_value)
## jerry_create_arraybuffer_external
**Summary**
Creates a jerry_value_t representing an ArrayBuffer object with
user specified back-buffer.
User must pass a buffer pointer which is at least `size` big.
After the object is not needed the GC will call the `free_cb`
so the user can release the buffer which was provided.
**Prototype**
```c
jerry_value_t
jerry_create_arraybuffer_external (const jerry_length_t size
uint8_t *buffer_p,
jerry_object_native_free_callback_t free_cb);
```
- `size` - size of the buffer to use **in bytes** (should not be 0)
- `buffer_p` - the buffer used for the Array Buffer object (should not be a null pointer)
- `free_cb` - the callback function called when the object is released
- return value
- the new ArrayBuffer as a `jerry_value_t`
- if the `size` is zero or `buffer_p` is a null pointer will return RangeError
**Example**
```c
{
uint8_t buffer_p[15];
jerry_value_t buffer_value = jerry_create_arraybuffer_external (15, buffer_p, NULL);
... // use the array buffer
jerry_release_value (buffer_value);
}
```
**See also**
- [jerry_get_arraybuffer_pointer](#jerry_get_arraybuffer_pointer)
- [jerry_arraybuffer_read](#jerry_arraybuffer_read)
- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
- [jerry_value_is_arraybuffer](#jerry_value_is_arraybuffer)
- [jerry_release_value](#jerry_release_value)
- [jerry_object_native_free_callback_t](#jerry_object_native_free_callback_t)
## jerry_create_boolean
**Summary**
Create a jerry_value_t representing a boolean value from the given boolean parameter.
**Prototype**
```c
jerry_value_t
jerry_create_boolean (bool value);
```
- `value` - raw boolean value.
- return value - a `jerry_value_t` created from the given boolean argument.
**Example**
```c
{
jerry_value_t boolean_value = jerry_create_boolean (true);
... // usage of the value
jerry_release_value (boolean_value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_create_error
**Summary**
Create new JavaScript error object.
Important! The `error_type` argument *must not be*
`JERRY_ERROR_NONE`.
Creating an error with no error type is not valid.
**Prototype**
```c
jerry_value_t
jerry_create_error (jerry_error_t error_type,
const jerry_char_t *message_p);
```
- `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_value_t error_obj = jerry_create_error (JERRY_ERROR_TYPE,
(const jerry_char_t *) "error");
... // usage of error_obj
jerry_release_value (error_obj);
}
```
**See also**
- [jerry_value_is_error](#jerry_value_is_error)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_create_error_from_value](#jerry_create_error_from_value)
## jerry_create_error_sz
**Summary**
Create new JavaScript error object.
**Prototype**
```c
jerry_value_t
jerry_create_error_sz (jerry_error_t error_type,
const jerry_char_t *message_p,
jerry_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 - value of the constructed error object
**Example**
```c
{
const jerry_char_t *message = "error";
jerry_value_t error_obj = jerry_create_error_sz (JERRY_ERROR_COMMON,
message,
strlen ((const char *) message));
... // usage of error_obj
jerry_release_value (error_obj);
}
```
**See also**
- [jerry_create_error](#jerry_create_error)
## jerry_create_external_function
**Summary**
Create an external function object.
**Prototype**
```c
jerry_value_t
jerry_create_external_function (jerry_external_handler_t handler_p);
```
- `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,
const jerry_value_t this_val,
const jerry_value_t args_p[],
const jerry_length_t args_cnt)
{
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 ((const jerry_char_t *) "handler_field");
// set property and release the return value without any check
jerry_release_value (jerry_set_property (glob_obj, prop_name, func_val));
jerry_release_value (prop_name);
jerry_release_value (func_val);
jerry_release_value (glob_obj);
}
```
**See also**
- [jerry_external_handler_t](#jerry_external_handler_t)
- [jerry_set_property](#jerry_set_property)
- [jerry_call_function](#jerry_call_function)
## jerry_create_number
**Summary**
Creates a `jerry_value_t` representing a number value.
**Prototype**
```c
jerry_value_t
jerry_create_number (double 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
**Example**
```c
{
jerry_value_t number_value = jerry_create_number (3.14);
... // usage of the value
jerry_release_value (number_value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
- [jerry_create_number_infinity](#jerry_create_number_infinity)
- [jerry_create_number_nan](#jerry_create_number_nan)
## jerry_create_number_infinity
**Summary**
Creates a `jerry_value_t` representing a positive or negative infinity value.
**Prototype**
```c
jerry_value_t
jerry_create_number_infinity (bool sign);
```
- `sign` - true for negative Infinity and false for positive Infinity
- return value - a `jerry_value_t` representing the infinity value
**Example**
```c
{
jerry_value_t positive_inf_value = jerry_create_number_infinity (false);
... // usage of the positive_inf_value
jerry_release_value (positive_inf_value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
- [jerry_create_number](#jerry_create_number)
- [jerry_create_number_nan](#jerry_create_number_nan)
## jerry_create_number_nan
**Summary**
Creates a `jerry_value_t` representing a not-a-number value.
**Prototype**
```c
jerry_value_t
jerry_create_number_nan (void);
```
- return value - a `jerry_value_t` representing the not-a-number value
**Example**
```c
{
jerry_value_t nan_value = jerry_create_number_nan ();
... // usage of the nan_value
jerry_release_value (nan_value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
- [jerry_create_number](#jerry_create_number)
- [jerry_create_number_infinity](#jerry_create_number_infinity)
## jerry_create_null
**Summary**
Creates and returns a `jerry_value_t` with type null object.
**Prototype**
```c
jerry_value_t
jerry_create_null (void);
```
- return value - a `jerry_value_t` representing null.
**Example**
```c
{
jerry_value_t null_value = jerry_create_null ();
... // usage of the value
jerry_release_value (null_value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_create_object
**Summary**
Create new JavaScript object, like with new Object().
**Prototype**
```c
jerry_value_t
jerry_create_object (void);
```
- return value - value of the created object
**Example**
```c
{
jerry_value_t object_value = jerry_create_object ();
... // usage of object_value
jerry_release_value (object_value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
## jerry_create_promise
**Summary**
Create an empty promise object which can be resolved or rejected later
by calling jerry_resolve_or_reject_promise.
*Note*: This API depends on the ES2015-subset profile.
**Prototype**
```c
jerry_value_t
jerry_create_promise (void)
```
- return value - value of the newly created promise
**Example**
```c
{
jerry_value_t p = jerry_create_promise ();
...// usage of the promise
jerry_release_value (p);
}
```
**See also**
- [jerry_resolve_or_reject_promise](#jerry_resolve_or_reject_promise)
- [jerry_release_value](#jerry_release_value)
## jerry_create_string
**Summary**
Create string from a valid CESU8 string.
**Prototype**
```c
jerry_value_t
jerry_create_string (const jerry_char_t *str_p);
```
- `str_p` - pointer to string
- return value - value of the created string
**Example**
```c
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string_value = jerry_create_string (char_array);
... // usage of string_value
jerry_release_value (string_value);
}
```
**See also**
- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
- [jerry_create_string_sz](#jerry_create_string_sz)
## jerry_create_string_sz
**Summary**
Create string from a valid CESU8 string.
**Prototype**
```c
jerry_value_t
jerry_create_string_sz (const jerry_char_t *str_p,
jerry_size_t str_size)
```
- `str_p` - pointer to string
- `str_size` - size of the string
- return value - value of the created string
**Example**
```c
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string_value = jerry_create_string_sz (char_array,
strlen ((const char *) char_array));
... // usage of string_value
jerry_release_value (string_value);
}
```
**See also**
- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
- [jerry_create_string](#jerry_create_string)
## jerry_create_string_from_utf8
**Summary**
Create string from a valid UTF8 string.
*Note*: The difference from [jerry_create_string](#jerry_create_string) is that it accepts utf-8 string instead of cesu-8 string.
**Prototype**
```c
jerry_value_t
jerry_create_string_from_utf8 (const jerry_char_t *str_p);
```
- `str_p` - pointer to string
- return value - value of the created string
**Example**
```c
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string_value = jerry_create_string_from_utf8 (char_array);
... // usage of string_value
jerry_release_value (string_value);
}
```
**See also**
- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string)
- [jerry_create_string_sz_from_utf8](#jerry_create_string_sz_from_utf8)
## jerry_create_string_sz_from_utf8
**Summary**
Create string from a valid UTF8 string.
*Note*: The difference from [jerry_create_string_sz](#jerry_create_string_sz) is that it accepts utf-8 string instead of cesu-8 string.
**Prototype**
```c
jerry_value_t
jerry_create_string_sz (const jerry_char_t *str_p,
jerry_size_t str_size)
```
- `str_p` - pointer to string
- `str_size` - size of the string
- return value - value of the created string
**Example**
```c
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string_value = jerry_create_string_sz_from_utf8 (char_array,
strlen ((const char *) char_array));
... // usage of string_value
jerry_release_value (string_value);
}
```
**See also**
- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string)
- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)
## jerry_create_typedarray
**Summary**
Create a jerry_value_t representing an TypedArray object.
For the new object the type of the TypedArray (see: [jerry_typedarray_type_t](#jerry_typedarray_type_t))
and element count can be specified.
**Prototype**
```c
jerry_value_t
jerry_create_typedarray (jerry_typedarray_type_t type_name, jerry_length_t item_count);
```
- `type_name` - type of TypedArray to create
- `item_count` - number of items in the new TypedArray
- return value - the new TypedArray as a `jerry_value_t`
**Example**
```c
{
jerry_value_t array = jerry_create_typedarray (JERRY_TYPEDARRAY_UINT16, 15);
... // use the TypedArray
jerry_release_value (array);
}
```
**See also**
- [jerry_typedarray_type_t](#jerry_typedarray_type_t)
- [jerry_value_is_typedarray](#jerry_value_is_typedarray)
- [jerry_release_value](#jerry_release_value)
## jerry_create_typedarray_for_arraybuffer
**Summary**
Create a jerry_value_t representing an TypedArray object using
an already existing ArrayBuffer object.
For the new object the type of the TypedArray (see: [jerry_typedarray_type_t](#jerry_typedarray_type_t))
and element count can be specified.
The developer must ensure that the ArrayBuffer has the correct length for the given
type of TypedArray otherwise an error is generated.
The JavaScript equivalent of this function is: `new %TypedArray%(arraybuffer)` where `%TypedArray%` is
one of the allowed TypedArray functions.
**Prototype**
```c
jerry_value_t
jerry_create_typedarray_for_arraybuffer (jerry_typedarray_type_t type_name,
const jerry_value_t arraybuffer);
```
- `type_name` - type of TypedArray to create
- `arraybuffer` - the ArrayBuffer to use for the new TypedArray
- return value
- the new TypedArray as a `jerry_value_t`
- Error if the ArrayBuffer does not have enough space for the given type of TypedArray
**Example**
```c
{
jerry_value_t buffer = jerry_create_array_buffer (12 * 2);
jerry_value_t array = jerry_create_typedarray_for_arraybuffer (JERRY_TYPEDARRAY_UINT16, buffer);
jerry_release_value (buffer);
... // use the TypedArray
jerry_release_value (array);
}
```
**See also**
- [jerry_typedarray_type_t](#jerry_typedarray_type_t)
- [jerry_value_is_typedarray](#jerry_value_is_typedarray)
- [jerry_release_value](#jerry_release_value)
## jerry_create_typedarray_for_arraybuffer_sz
**Summary**
Create a jerry_value_t representing an TypedArray object using
an already existing ArrayBuffer object and by specifying the byteOffset, and length properties.
For the new object the type of the TypedArray (see: [jerry_typedarray_type_t](#jerry_typedarray_type_t))
and element count can be specified.
The developer must ensure that the ArrayBuffer has the correct length for the given
type of TypedArray otherwise an error is generated.
The JavaScript equivalent of this function is: `new %TypedArray%(arraybuffer, byteOffset, length)` where `%TypedArray%` is
one of the allowed TypedArray functions.
**Prototype**
```c
jerry_value_t
jerry_create_typedarray_for_arraybuffer_sz (jerry_typedarray_type_t type_name,
const jerry_value_t arraybuffer,
jerry_length_t byte_offset,
jerry_length_t length);
```
- `type_name` - type of TypedArray to create
- `arraybuffer` - the ArrayBuffer to use for the new TypedArray
- `byte_offset` - start offset to use for the ArrayBuffer
- `length` - number of elements to used from the ArrayBuffer (this is not the same as the byteLength)
- return value
- the new TypedArray as a `jerry_value_t`
- Error if the ArrayBuffer does not have enough space for the given type of TypedArray
**Example**
```c
{
jerry_value_t buffer = jerry_create_array_buffer (12 * 2);
jerry_value_t array = jerry_create_typedarray_for_arraybuffer_sz (JERRY_TYPEDARRAY_UINT16, buffer, 4, 10);
jerry_release_value (buffer);
... // use the TypedArray
jerry_release_value (array);
}
```
**See also**
- [jerry_typedarray_type_t](#jerry_typedarray_type_t)
- [jerry_value_is_typedarray](#jerry_value_is_typedarray)
- [jerry_release_value](#jerry_release_value)
## jerry_create_undefined
**Summary**
Creates a `jerry_value_t` representing an undefined value.
**Prototype**
```c
jerry_value_t
jerry_create_undefined (void);
```
- return value - value of undefined
**Example**
```c
{
jerry_value_t undefined_value = jerry_create_undefined ();
... // usage of the value
jerry_release_value (undefined_value);
}
```
**See also**
- [jerry_release_value](#jerry_release_value)
# General API functions of JS objects
## jerry_has_property
**Summary**
Checks whether the object or its prototype objects have the given property.
*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_has_property (const jerry_value_t obj_val,
const jerry_value_t prop_name_val);
```
- `obj_val` - object value
- `prop_name_val` - property name
- return value - JavaScript boolean value that evaluates to
- true, if the property exists
- false, otherwise
**Example**
```c
{
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field");
jerry_value_t has_prop_js = jerry_has_property (global_object, prop_name);
bool has_prop = jerry_get_boolean_value (has_prop_js);
jerry_release_value (has_prop_js);
jerry_release_value (prop_name);
jerry_release_value (global_object);
}
```
**See also**
- [jerry_has_own_property](#jerry_has_own_property)
- [jerry_delete_property](#jerry_delete_property)
## jerry_has_own_property
**Summary**
Checks whether the object has the given property.
*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_has_own_property (const jerry_value_t obj_val,
const jerry_value_t prop_name_val);
```
- `obj_val` - object value
- `prop_name_val` - property name
- return value - JavaScript boolean value that evaluates to
- true, if the property exists
- false, otherwise
**Example**
```c
{
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field");
jerry_value_t has_prop_js = jerry_has_own_property (global_object, prop_name);
bool has_prop = jerry_get_boolean_value (has_prop_js);
jerry_release_value (jas_prop_js);
jerry_release_value (prop_name);
jerry_release_value (global_object);
}
```
**See also**
- [jerry_has_property](#jerry_has_property)
- [jerry_delete_property](#jerry_delete_property)
## jerry_delete_property
**Summary**
Delete a property from an object.
**Prototype**
```c
bool
jerry_delete_property (const jerry_value_t obj_val,
const jerry_value_t prop_name_val);
```
- `obj_val` - object value
- `prop_name_val` - property name
- return value
- true, if property was deleted successfully
- false, otherwise
**Example**
```c
{
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop");
jerry_delete_property (global_object, prop_name);
jerry_release_value (prop_name);
jerry_release_value (global_object);
}
```
**See also**
- [jerry_has_property](#jerry_has_property)
- [jerry_has_own_property](#jerry_has_own_property)
- [jerry_delete_property_by_index](#jerry_delete_property_by_index)
- [jerry_get_property](#jerry_get_property)
## jerry_delete_property_by_index
**Summary**
Delete indexed property from the specified object.
**Prototype**
```c
bool
jerry_delete_property_by_index (const jerry_value_t obj_val,
uint32_t index);
```
- `obj_val` - object value
- `index` - index number
- return value
- true, if property was deleted successfully
- false, otherwise
**Example**
```c
{
jerry_value_t object;
... // create or acquire object
jerry_delete_property_by_index (object, 5);
jerry_release_value (object);
}
```
**See also**
- [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_set_property_by_index](#jerry_set_property_by_index)
## jerry_get_property
**Summary**
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_property (const jerry_value_t obj_val,
const jerry_value_t prop_name_val);
```
- `obj_val` - object value
- `prop_name_val` - property name
- return value
- value of property, if success
- thrown error, otherwise
**Example**
```c
{
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 prop_value = jerry_get_property (obj_val, prop_name);
jerry_release_value (prop_name);
jerry_release_value (global_object);
}
```
**See also**
- [jerry_has_property](#jerry_has_property)
- [jerry_has_own_property](#jerry_has_own_property)
- [jerry_delete_property](#jerry_delete_property)
- [jerry_delete_property_by_index](#jerry_delete_property_by_index)
- [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_property_by_index
**Summary**
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_property_by_index (const jerry_value_t obj_val,
uint32_t index);
```
- `obj_val` - object value
- `index` - index number
- return value
- stored value on the specified index, if success
- thrown exception, otherwise.
**Example**
```c
{
jerry_value_t object;
... // create or acquire object
jerry_value_t value = jerry_get_property_by_index (object, 5);
...
jerry_release_value (value);
jerry_release_value (object);
}
```
**See also**
- [jerry_has_property](#jerry_has_property)
- [jerry_has_own_property](#jerry_has_own_property)
- [jerry_delete_property](#jerry_delete_property)
- [jerry_delete_property_by_index](#jerry_delete_property_by_index)
- [jerry_get_property](#jerry_get_property)
- [jerry_set_property](#jerry_set_property)
- [jerry_set_property_by_index](#jerry_set_property_by_index)
## jerry_set_property
**Summary**
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
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)
```
- `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_value_t value_to_set;
... // create or acquire value to set
jerry_value_t glob_obj = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop");
jerry_value_t set_result = jerry_set_property (glob_obj, prop_name, value_to_set);
... // check result of property set call
jerry_release_value (set_result);
jerry_release_value (prop_name);
...
jerry_release_value (value_to_set);
jerry_release_value (glob_obj);
}
```
**See also**
- [jerry_has_property](#jerry_has_property)
- [jerry_has_own_property](#jerry_has_own_property)
- [jerry_delete_property](#jerry_delete_property)
- [jerry_delete_property_by_index](#jerry_delete_property_by_index)
- [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_property_by_index
**Summary**
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
jerry_value_t
jerry_set_property_by_index (const jerry_value_t obj_val,
uint32_t index,
const jerry_value_t 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
- thrown exception, otherwise
**Example**
```c
{
jerry_value_t object;
jerry_value_t value_to_set;
... // create or acquire object and value to set
jerry_value_t ret_val = jerry_set_property_by_index (object, 5, value_to_set);
...
jerry_release_value (value_to_set);
jerry_release_value (ret_val);
jerry_release_value (object);
}
```
**See also**
- [jerry_has_property](#jerry_has_property)
- [jerry_has_own_property](#jerry_has_own_property)
- [jerry_delete_property](#jerry_delete_property)
- [jerry_delete_property_by_index](#jerry_delete_property_by_index)
- [jerry_get_property](#jerry_get_property)
- [jerry_set_property](#jerry_set_property)
- [jerry_get_property_by_index](#jerry_get_property_by_index)
## jerry_init_property_descriptor_fields
**Summary**
Initialize property descriptor.
**Prototype**
```c
void
jerry_init_property_descriptor_fields (jerry_property_descriptor_t *prop_desc_p);
```
- `prop_desc_p` - pointer to property descriptor
**Example**
```c
{
jerry_property_descriptor_t prop_desc;
jerry_init_property_descriptor_fields (&prop_desc);
... // usage of prop_desc
jerry_free_property_descriptor_fields (&prop_desc);
}
```
**See also**
- [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_define_own_property
**Summary**
Define 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_define_own_property (const jerry_value_t obj_val,
const jerry_value_t prop_name_val,
const jerry_property_descriptor_t *prop_desc_p);
```
- `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_value_t global_obj_val = jerry_get_global_object ();
jerry_property_descriptor_t prop_desc;
jerry_init_property_descriptor_fields (&prop_desc);
jerry_value_t value_to_set;
... // create or acquire value to set
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_value_t return_value = jerry_define_own_property (global_obj_val, prop_name, &prop_desc);
jerry_release_value (return_value);
jerry_release_value (prop_name);
jerry_free_property_descriptor_fields (&prop_desc);
jerry_release_value (global_obj_val);
}
```
**See also**
- [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_get_own_property_descriptor
**Summary**
Construct property descriptor from specified property.
**Prototype**
```c
bool
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);
```
- `obj_val` - object value
- `prop_name_val` - property name
- `prop_desc_p` - pointer to property descriptor
- return value
**Example**
```c
{
jerry_value_t global_obj_val = jerry_get_global_object ();
jerry_property_descriptor_t prop_desc;
jerry_init_property_descriptor_fields (&prop_desc);
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_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_free_property_descriptor_fields
**Summary**
Free fields of property descriptor (setter, getter and value).
**Prototype**
```c
void
jerry_free_property_descriptor_fields (const jerry_property_descriptor_t *prop_desc_p);
```
- `prop_desc_p` - pointer to property descriptor
**Example**
```c
{
jerry_property_descriptor_t prop_desc;
jerry_init_property_descriptor_fields (&prop_desc);
... // usage of property descriptor
jerry_free_property_descriptor_fields (&prop_desc);
}
```
**See also**
- [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
**Summary**
Call function specified by a function value. Error flag must
not be set for any arguments of this function. Value of `this`
parameter should be set to `undefined` for non-method calls.
*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 (const jerry_value_t func_obj_val,
const jerry_value_t this_val,
const jerry_value_t args_p[],
jerry_size_t args_count);
```
- `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**
```c
{
jerry_value_t val;
... // receiving val
if (jerry_value_is_function (val))
{
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);
jerry_release_value (this_val);
}
jerry_release_value (val);
}
```
**See also**
- [jerry_is_function](#jerry_is_function)
- [jerry_create_external_function](#jerry_create_external_function)
## jerry_construct_object
**Summary**
Construct object, invoking specified function object as constructor.
Error flag must not be set for any arguments of this function.
*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 (const jerry_value_t func_obj_val,
const jerry_value_t args_p[],
jerry_size_t args_count);
```
- `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**
```c
{
jerry_value_t val;
... // receiving val
if (jerry_is_constructor (val))
{
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);
}
}
```
**See also**
- [jerry_is_constructor](#jerry_is_constructor)
## jerry_get_object_keys
**Summary**
Get keys of the specified object value.
**Prototype**
```c
jerry_value_t
jerry_get_object_keys (const jerry_value_t obj_val);
```
- `obj_val` - object value
- return value
- array object value, if success
- thrown error, otherwise
**Example**
```c
{
jerry_value_t object;
... // create or acquire object
jerry_value_t keys_array = jerry_get_object_keys (object);
... // usage of keys_array
jerry_release_value (keys_array);
}
```
**See also**
- [jerry_get_property](#jerry_get_property)
- [jerry_set_property](#jerry_set_property)
## jerry_get_prototype
**Summary**
Get the prototype of the specified object.
**Prototype**
```c
jerry_value_t
jerry_get_prototype (const jerry_value_t obj_val);
```
- `obj_val` - object value
- return value
- object value, if success
- null or thrown error, otherwise
**Example**
```c
{
jerry_value_t object;
... // create or acquire object
jerry_value_t prototype = jerry_get_prototype (object);
... // usage of prototype object
jerry_release_value (prototype);
jerry_release_value (object);
}
```
**See also**
- [jerry_set_prototype](#jerry_set_prototype)
## jerry_set_prototype
**Summary**
Set the prototype of the specified object.
**Prototype**
```c
jerry_value_t
jerry_set_prototype (const jerry_value_t obj_val,
const jerry_value_t proto_obj_val);
```
- `obj_val` - object value
- `proto_obj_val` - prototype object value
- return value
- true, if success
- thrown error, otherwise
**Example**
```c
{
jerry_value_t object;
jerry_value_t prototype;
... // create or acquire object and prototype
jerry_value_t ret_val = jerry_set_prototype (object, prototype);
jerry_release_value (ret_val);
jerry_release_value (prototype);
jerry_release_value (object);
}
```
**See also**
- [jerry_get_prototype](#jerry_get_prototype)
## jerry_get_object_native_handle
**Summary**
**Deprecated: Please use jerry_get_object_native_pointer instead.**
Get native handle, previously associated with specified object.
**Prototype**
```c
bool
jerry_get_object_native_handle (const jerry_value_t obj_val,
uintptr_t *out_handle_p);
```
- `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_value_t object;
uintptr_t handle_set;
... // 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_object](#jerry_create_object)
- [jerry_set_object_native_handle](#jerry_set_object_native_handle)
- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
## jerry_set_object_native_handle
**Summary**
**Deprecated: Please use jerry_set_object_native_pointer instead.**
Set native handle and an optional free callback for the specified object.
*Note*: If native handle was already set for the object, its value is updated.
*Note*: If a non-NULL free callback is specified, it will be called
by the garbage collector when the object is freed. The free
callback always overwrites the previous value, so passing
a NULL value deletes the current free callback.
**Prototype**
```c
void
jerry_set_object_native_handle (const jerry_value_t obj_val,
uintptr_t handle_p,
jerry_object_free_callback_t freecb_p);
```
- `obj_val` - object value to set handle in
- `handle_p` - handle value
- `freecb_p` - pointer to "free" callback or NULL
**Example**
```c
{
jerry_value_t object;
uintptr_t handle_set;
... // 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_object](#jerry_create_object)
- [jerry_get_object_native_handle](#jerry_get_object_native_handle)
- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
## jerry_get_object_native_pointer
**Summary**
Get native pointer and its type information.
The pointer and the type information are previously associated with the object by jerry_set_object_native_pointer.
*Note*: It is recommended to ensure that the `out_native_info_p` value pointer
is equal to the native info pointer that is expected, before casting
and accessing the `out_native_pointer_p`.
An example of when this is important: external functions that expect
`this` to have a native pointer of a certain C type.
It is possible in JavaScript to change `this` at will – using `call()`,
`apply()` or `bind()`. Therefore, it is possible that the native pointer
of `this` is not of the expected C type. To handle this safely and
securely, one must always add type checks to make sure that the
`out_native_pointer_p` is of the expected type, before casting
and dereferencing `out_native_pointer_p`.
*Note*: `out_native_pointer_p` and `out_native_info_p` can be NULL, and it means the
caller doesn't want to get the native_pointer or type information.
**Prototype**
```c
bool
jerry_get_object_native_pointer (const jerry_value_t obj_val,
void **out_native_pointer_p,
const jerry_object_native_info_t **out_native_info_p)
```
- `obj_val` - object value to get native pointer from.
- `out_native_pointer_p` - native pointer (output parameter).
- `out_native_info_p` - native pointer's type information (output parameter).
- return value
- true, if there is native pointer associated with the object
- false, otherwise
**Example**
```c
typedef struct {
int foo;
bool bar;
} native_obj_t;
static void native_freecb (void *native_p)
{
... // free the native pointer
}
// NOTE: The address (!) of type_info acts as a way to uniquely "identify" the
// C type `native_obj_t *`.
static const jerry_object_native_info_t native_obj_type_info =
{
.free_cb = native_freecb
};
// Function creating JS object that is "backed" by a native_obj_t *:
{
...
// construct object and native_set value:
jerry_value_t object = ...;
native_obj_t *native_obj = malloc(sizeof(*native_obj));
jerry_set_object_native_pointer (object, native_obj, &native_obj_type_info);
...
}
// Native method, `this` is expected to be "backed" by a native_obj_t *:
{
void *native_p;
const jerry_object_native_info_t *type_p;
bool has_p = jerry_get_object_native_pointer (this_val, &native_p, &type_p);
if (has_p)
{
// The type_p pointer address itself is used to identify the type:
if (type_p == &native_obj_type_info)
{
// The type of this's native pointer matches what is expected.
// Only now is it safe to cast to native_obj_t * and dereference the
// pointer:
native_obj_t *native_obj = native_p;
native_obj->bar = ...; // Safe to access now!
}
else
{
// The type of this's native pointer is NOT what we expected!
// We should not cast to native_obj_t * and dereference because it's unsafe.
// Handle the error here, for example throw an error.
}
}
...
}
```
**See also**
- [jerry_create_object](#jerry_create_object)
- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
- [jerry_object_native_info_t](#jerry_object_native_info_t)
## jerry_set_object_native_pointer
**Summary**
Set native pointer and an optional type information for the specified object.
You can get them by calling jerry_get_object_native_pointer later.
*Note*: If native pointer was already set for the object, its value is updated.
*Note*: If a non-NULL free callback is specified in the native type information,
it will be called by the garbage collector when the object is freed.
The type info is always overwrites the previous value, so passing
a NULL value deletes the current type info.
**Prototype**
```c
bool
jerry_set_object_native_pointer (const jerry_value_t obj_val,
void *native_p,
const jerry_object_native_info_t *info_p)
```
- `obj_val` - object to set native pointer in.
- `native_p` - native pointer.
- `info_p` - native pointer's type information or NULL. When used, this should
be a long-lived pointer, usually a pointer to a
`static const jerry_object_native_info_t` makes most sense.
**Example**
See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) for a
best-practice example.
**See also**
- [jerry_create_object](#jerry_create_object)
- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
- [jerry_object_native_info_t](#jerry_object_native_info_t)
## jerry_foreach_object_property
**Summary**
Applies the given function to every property in the given object.
**Prototype**
```c
bool
jerry_foreach_object_property (jerry_value_t obj_val,
jerry_object_property_foreach_t foreach_p,
void *user_data_p);
```
- `obj_val` - object value
- `foreach_p` - foreach function, that will be applied 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
**Example**
```c
bool foreach_function (const jerry_value_t prop_name,
const jerry_value_t prop_value,
void *user_data_p)
{
... // 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);
}
```
**See also**
- [jerry_object_property_foreach_t](#jerry_object_property_foreach_t)
## jerry_objects_foreach
**Summary**
Iterate over objects.
*Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value).
**Prototype**
```c
bool jerry_objects_foreach (jerry_objects_foreach_t foreach_p,
void *user_data_p);
```
- `foreach_p` - function that will be invoked for each object.
- `user_data_p` - User data to pass to the function.
- return value
- `true`, if the search function terminated the traversal by returning `false`
- `false`, if the end of the list of objects was reached
**Example**
```c
typedef struct
{
jerry_value_t property_name;
jerry_value_t result;
} find_my_object_info_t;
/*
* Find the first object with the given property.
*/
static bool
find_my_object(const jerry_value_t candidate,
void *user_data_p)
{
find_my_object_info_t *info_p = (find_my_object_info_t *) user_data_p;
jerry_value_t has_property = jerry_object_has_property (candidate, info_p->property_name);
bool keep_searching = (jerry_value_is_error (has_property) || !jerry_get_boolean_value ());
if (!keep_searching)
{
/* We found it, so we acquire the value and record it. */
info_p->result = jerry_acquire_value (candidate);
}
jerry_release_value (has_property);
return keep_searching;
} /* find_my_object */
{
find_my_object_info_t search_info =
{
.property_name = jerry_create_string ("desired_property")
};
if (jerry_object_foreach (find_my_object, &search_info))
{
/* The search was successful. Do something useful with search_info.result. */
...
/* Release the found object after we're done using it. */
jerry_release_value (search_info.result);
}
else
{
/* The search has failed. */
}
jerry_release_value (search_info.desired_property);
}
```
**See also**
- [jerry_objects_foreach_t](#jerry_objects_foreach_t)
## jerry_objects_foreach_by_native_info
**Summary**
Iterate over objects matching a certain native data type.
*Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value).
**Prototype**
```c
bool jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *native_info_p,
jerry_objects_foreach_by_native_info_t foreach_p,
void *user_data_p);
```
- `native_info_p` - native pointer's type information.
- return value
- `true`, if the search function terminated the traversal by returning `false`
- `false`, if the end of the list of objects was reached
**Example**
```c
typedef struct
{
int foo;
bool bar;
} native_obj_t;
typedef struct
{
jerry_value_t found_object;
void *match_data_p;
} find_object_data_t;
static void native_freecb (void *native_p)
{
... // free the native pointer
} /* native_freecb */
// NOTE: The address (!) of type_info acts as a way to uniquely "identify" the
// C type `native_obj_t *`.
static const jerry_object_native_info_t native_obj_type_info =
{
.free_cb = native_freecb
};
// Function creating JS object that is "backed" by a native_obj_t *:
{
...
// construct object and native_set value:
jerry_value_t object = ...;
native_obj_t *native_obj_p = malloc (sizeof (*native_obj_p));
jerry_set_object_native_pointer (object, native_obj_p, &native_obj_type_info);
...
}
// Native method that retrieves the JavaScript object by way of its native data:
static bool find_object (const jerry_value_t candidate, void *data_p, void *user_data_p)
{
find_object_data_t *find_data_p = (find_object_data_t *) user_data_p;
if (find_data_p->match_data_p == data_p)
{
// If the object was found, acquire it and store it in the user data.
find_data_p->found_object = jerry_acquire_value (candidate);
// Stop traversing over the objects.
return false;
}
// Indicate that the object was not found, so traversal must continue.
return true;
} /* find_object */
...
{
find_object_data_t find_data =
{
.match_data = native_obj
};
if (jerry_objects_foreach_by_native_info (&native_obj_type_info, find_object, &find_data))
{
// The object was found and is now stored in find_data.found_object. After using it, it must be released.
...
jerry_release_value (find_data.found_object);
}
else
{
// The object was not found.
}
...
}
```
**See also**
- [jerry_create_object](#jerry_create_object)
- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
- [jerry_object_native_info_t](#jerry_object_native_info_t)
- [jerry_objects_foreach](#jerry_objects_foreach)
# Input validator functions
## jerry_is_valid_utf8_string
**Summary**
Validate UTF-8 string.
**Prototype**
```c
bool
jerry_is_valid_utf8_string (const jerry_char_t *utf8_buf_p, /**< UTF-8 string */
jerry_size_t buf_size) /**< string size */
```
- `utf8_buf_p` - UTF-8 input string
- `buf_size` - input string size
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
if (jerry_is_valid_utf8_string (script, (jerry_size_t) script_size))
{
jerry_run_simple (script, script_size, JERRY_INIT_EMPTY);
}
}
```
**See also**
- [jerry_run_simple](#jerry_run_simple)
- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)
- [jerry_create_string_sz_from_utf8](#jerry_create_string_sz_from_utf8)
- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size)
- [jerry_get_utf8_string_length](#jerry_get_utf8_string_length)
- [jerry_string_to_utf8_char_buffer](#jerry_string_to_utf8_char_buffer)
- [jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer)
## jerry_is_valid_cesu8_string
**Summary**
Validate CESU-8 string.
**Prototype**
```c
bool
jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string */
jerry_size_t buf_size) /**< string size */
```
- `cesu8_buf_p` - CESU-8 input string
- `buf_size` - input string size
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
const jerry_char_t script[] = "Hello, World!";
size_t script_size = strlen ((const char *) script);
if (jerry_is_valid_cesu8_string (script, (jerry_size_t) script_size))
{
jerry_value_t string_value = jerry_create_string_sz (script,
(jerry_size_t) script_size);
// usage of string_value
jerry_release_value (string_value);
}
jerry_cleanup ();
}
```
**See also**
- [jerry_create_string](#jerry_create_string)
- [jerry_create_string_sz](#jerry_create_string_sz)
- [jerry_get_string_size](#jerry_get_string_size)
- [jerry_get_string_length](#jerry_get_string_length)
- [jerry_string_to_char_buffer](#jerry_string_to_char_buffer)
- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer)
# Snapshot functions
## jerry_generate_snapshot
**Summary**
Generate snapshot from the specified source code.
**Prototype**
```c
jerry_value_t
jerry_generate_snapshot (const jerry_char_t *resource_name_p,
size_t resource_name_length,
const jerry_char_t *source_p,
size_t source_size,
uint32_t generate_snapshot_opts,
uint32_t *buffer_p,
size_t buffer_size);
```
- `resource_name_p` - resource (file) name of the source code. Currently unused, the debugger may use it in the future.
- `resource_name_length` - length of resource name.
- `source_p` - script source, it must be a valid utf8 string.
- `source_size` - script source size, in bytes.
- `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags.
- `buffer_p` - buffer to save snapshot to.
- `buffer_size` - the buffer's size.
- return value
- the size of the snapshot as a number value, 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_SAVE)
- thrown error, otherwise.
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
static uint32_t global_mode_snapshot_buffer[256];
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
jerry_value_t generate_result;
generate_result = jerry_generate_snapshot (NULL,
0,
code_to_snapshot_p,
strlen ((const char *) code_to_snapshot_p),
0,
global_mode_snapshot_buffer,
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
jerry_cleanup ();
}
```
**See also**
- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
- [jerry_generate_function_snapshot](#jerry_generate_function_snapshot)
- [jerry_exec_snapshot](#jerry_exec_snapshot)
## jerry_generate_function_snapshot
**Summary**
Generate function snapshot from the specified source code
with the given arguments.
The function arguments and function body are
passed as separated arguments.
**Prototype**
```c
jerry_value_t
jerry_generate_function_snapshot (const jerry_char_t *resource_name_p,
size_t resource_name_length,
const jerry_char_t *source_p,
size_t source_size,
const jerry_char_t *args_p,
size_t args_size,
uint32_t generate_snapshot_opts,
uint32_t *buffer_p,
size_t buffer_size)
```
- `resource_name_p` - resource (file) name of the source code. Currently unused, the debugger may use it in the future.
- `resource_name_length` - length of resource name.
- `source_p` - script source, it must be a valid utf8 string.
- `source_size` - script source size, in bytes.
- `args_p` - function arguments, it must be a valid utf8 string.
- `args_size` - function argument size, in bytes.
- `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags.
- `buffer_p` - buffer to save snapshot to.
- `buffer_size` - the buffer's size.
- return value
- the size of the snapshot as a number value, 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_SAVE)
- thrown error, otherwise.
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
static uint32_t func_snapshot_buffer[256];
const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
jerry_value_t generate_result;
generate_result = jerry_generate_function_snapshot (NULL,
0,
src_p,
strlen ((const char *) src_p),
args_p,
strlen ((const char *) args_p),
0,
func_snapshot_buffer,
sizeof (func_snapshot_buffer) / sizeof (uint32_t));
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
jerry_cleanup ();
}
```
**See also**
- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
- [jerry_generate_snapshot](#jerry_generate_snapshot)
- [jerry_load_function_snapshot_at](#jerry_load_function_snapshot_at)
## jerry_exec_snapshot
**Summary**
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
jerry_value_t
jerry_exec_snapshot (const uint32_t *snapshot_p,
size_t snapshot_size,
size_t func_index,
uint32_t exec_snapshot_opts);
```
- `snapshot_p` - pointer to snapshot
- `snapshot_size` - size of snapshot
- `func_index` - index of executed function
- `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags.
- return value
- result of bytecode, if run was successful
- thrown error, otherwise
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
static uint32_t global_mode_snapshot_buffer[256];
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t generate_result;
generate_result = jerry_generate_snapshot (NULL,
0,
code_to_snapshot_p,
strlen ((const char *) code_to_snapshot_p),
0,
global_mode_snapshot_buffer,
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
size_t global_mode_snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
jerry_cleanup ();
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t res = jerry_exec_snapshot (global_mode_snapshot_buffer,
global_mode_snapshot_size,
0,
0);
jerry_release_value (res);
jerry_cleanup ();
}
```
**See also**
- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot)
## jerry_load_function_snapshot
**Summary**
Load the selected snapshot function from the specified buffer as a function object.
The lexical environment of the loaded function is always the global lexical environment.
*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_load_function_snapshot (const uint32_t *snapshot_p,
size_t snapshot_size,
size_t func_index,
uint32_t exec_snapshot_opts);
```
- `snapshot_p` - pointer to snapshot
- `snapshot_size` - size of snapshot
- `func_index` - index of function to load
- `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags.
- return value
- function object built from the snapshot
- thrown error, otherwise
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
static uint32_t snapshot_buffer[256];
const jerry_char_t *args_p = (const jerry_char_t *)"a, b";
const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t generate_result;
generate_result = jerry_generate_function_snapshot (NULL,
0,
src_p,
strlen ((const char *) src_p),
args_p,
strlen ((const char *) args_p),
false,
snapshot_buffer,
sizeof (snapshot_buffer) / sizeof (uint32_t));
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
jerry_cleanup ();
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t func = jerry_load_function_snapshot (snapshot_buffer,
snapshot_size,
0,
0);
/* 'func' can be used now as a function object */
jerry_value_t this_value = jerry_create_undefined ();
jerry_value_t args[2];
args[0] = jerry_create_number (1.0);
args[1] = jerry_create_number (2.0);
jerry_value_t res = jerry_call_function (func, this_value, args, 2);
/* 'res' now contains the value 3 as a jerry_value_t */
jerry_release_value (args[0]);
jerry_release_value (args[1]);
jerry_release_value (this_value);
jerry_release_value (func);
jerry_cleanup ();
return 0;
}
```
**See also**
- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
- [jerry_parse_and_save_function_snapshot](#jerry_parse_and_save_function_snapshot)
## jerry_parse_and_save_literals
**Summary**
Collect the used literals from the given source code and save them into a specific file in a list or C format.
These literals are generated by the parser, they are valid identifiers and none of them are magic string.
**Prototype**
```c
size_t
jerry_parse_and_save_literals (const jerry_char_t *source_p,
size_t source_size,
bool is_strict,
uint32_t *buffer_p,
size_t buffer_size,
bool is_c_format);
```
- `source_p` - script source, it must be a valid utf8 string.
- `source_size` - script source size, in bytes.
- `is_strict` - strict mode.
- `buffer_p` - buffer to save literals to.
- `buffer_size` - the buffer's size.
- `is_c_format` - the output format would be C-style (true) or a simple list (false).
- return value
- the size of the literal-list, if it was generated succesfully (i.e. the list of literals isn't empty,
and literal-save support is enabled in current configuration through JERRY_ENABLE_SNAPSHOT_SAVE)
- 0 otherwise.
**Example**
[doctest]: # (test="link")
```c
#include <stdio.h>
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
static uint32_t save_literal_buffer[256];
const jerry_char_t *code_for_literal_save_p = (const jerry_char_t *) "var obj = { a:'aa', bb:'Bb' }";
size_t literal_sizes = jerry_parse_and_save_literals (code_for_literal_save_p,
strlen ((const char *) code_for_literal_save_p),
false,
save_literal_buffer,
sizeof (save_literal_buffer) / sizeof (uint32_t),
true);
if (literal_sizes != 0)
{
FILE *literal_file_p = fopen ("literals.txt", "w");
fwrite (save_literal_buffer, sizeof (uint8_t), literal_sizes, literal_file_p);
fclose (literal_file_p);
}
jerry_cleanup ();
}
```
**See also**
- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
- [jerry_register_magic_strings](#jerry_register_magic_strings)
# Miscellaneous functions
## jerry_set_vm_exec_stop_callback
**Summary**
When JERRY_FEATURE_VM_EXEC_STOP is enabled a callback function can be
specified by this function. This callback is periodically called when
JerryScript executes an ECMAScript program.
If the callback returns with undefined value the ECMAScript execution
continues. Otherwise the result is thrown by the engine (if the error
flag is not set for the returned value the engine automatically sets
it). The callback function might be called again even if it threw
an error. In this case the function must throw the same error again.
To reduce the CPU overhead of constantly checking the termination
condition the callback is called when a backward jump is executed
or an exception is caught. Setting the `frequency` to a greater
than `1` value reduces this overhead further. If its value is N
only every Nth event (backward jump, etc.) trigger the next check.
**Prototype**
```c
void
jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb,
void *user_p,
uint32_t frequency);
```
- `stop_cb` - periodically called callback (passing NULL disables this feature)
- `user_p` - user pointer passed to the `stop_cb` function
- `frequency` - frequency of calling the `stop_cb` function
**Example**
[doctest]: # (test="link")
```c
#include <string.h>
#include "jerryscript.h"
static int countdown = 10;
static jerry_value_t
vm_exec_stop_callback (void *user_p)
{
while (countdown > 0)
{
countdown--;
return jerry_create_undefined ();
}
// The error flag is added automatically.
return jerry_create_string ((const jerry_char_t *) "Abort script");
}
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_set_vm_exec_stop_callback (vm_exec_stop_callback, &countdown, 16);
// Inifinte loop.
const char *src_p = "while(true) {}";
jerry_value_t src = jerry_parse (NULL, 0, (jerry_char_t *) src_p, strlen (src_p), JERRY_PARSE_NO_OPTS);
jerry_release_value (jerry_run (src));
jerry_release_value (src);
jerry_cleanup ();
}
```
**See also**
- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
- [jerry_parse](#jerry_parse)
- [jerry_run](#jerry_run)
- [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t)
## jerry_get_backtrace
**Summary**
Get backtrace. The backtrace is an array of strings where
each string contains the position of the corresponding frame.
The array length is zero if the backtrace is not available.
This function is typically called from native callbacks.
**Prototype**
```c
jerry_value_t
jerry_get_backtrace (uint32_t max_depth);
```
- `max_depth` - backtrace collection stops after reaching this value, 0 = unlimited
- return value
- a new array
**See also**
- [jerry_create_external_function](#jerry_create_external_function)
# ArrayBuffer and TypedArray functions
## jerry_get_arraybuffer_byte_length
**Summary**
Get the byte length property of the ArrayBuffer. This is the
same value which was passed to the ArrayBuffer constructor call.
**Prototype**
```c
jerry_length_t
jerry_get_arraybuffer_byte_length (const jerry_value_t value);
```
- `value` - ArrayBuffer object
- return value
- size of the ArrayBuffer in bytes
- 0 if the `value` parameter is not an ArrayBuffer
**Example**
```c
{
jerry_value_t buffer = jerry_create_arraybuffer (15);
jerry_length_t length = jerry_get_arraybuffer_byte_length (buffer);
// length should be 15
jerry_release_value (buffer);
}
```
**See also**
- [jerry_create_arraybuffer](#jerry_create_arraybuffer)
## jerry_arraybuffer_read
**Summary**
Copy the portion of the ArrayBuffer into a user provided buffer.
The start offset of the read operation can be specified.
The number bytes to be read can be specified via the `buf_size`
parameter. It is not possible to read more than the length of
the ArrayBuffer.
Function returns the number of bytes read from the ArrayBuffer
(and written to the buffer parameter). This value is
calculated in the following way: `min(array buffer length - offset, buf_size)`.
**Prototype**
```c
jerry_length_t
jerry_arraybuffer_read (const jerry_value_t value,
jerry_length_t offset,
uint8_t *buf_p,
jerry_length_t buf_size);
```
- `value` - ArrayBuffer to read from
- `offset` - start offset of the read operation
- `buf_p` - buffer to read the data to
- `buf_size` - maximum number of bytes to read into the buffer
- return value
- number of bytes written into the buffer (read from the ArrayBuffer)
- 0 if the `value` is not an ArrayBuffer object
- 0 if the `buf_size` is zero or there is nothing to read
**Example**
```c
{
uint8_t data[20];
jerry_value_t buffer;
// ... create the ArrayBuffer or acuiqre it from somewhere.
jerry_value_t bytes_read;
// read 10 bytes from the start of the ArrayBuffer.
bytes_read = jerry_arraybuffer_read (buffer, 0, data, 10);
// read the next 10 bytes
bytes_read += jerry_arraybuffer_read (buffer, bytes_read, data + bytes_read, 10);
// process the data variable
jerry_release_value (buffer);
}
```
**See also**
- [jerry_create_arraybuffer](#jerry_create_arraybuffer)
- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
- [jerry_get_arraybuffer_byte_length](#jerry_get_arraybuffer_byte_length)
## jerry_arraybuffer_write
**Summary**
Copy the contents of a buffer into the ArrayBuffer.
The start offset of the write operation can be specified.
The number bytes to be written can be specified via the `buf_size`
parameter. It is not possible to write more than the length of
the ArrayBuffer.
Function returns the number of bytes written into the ArrayBuffer
(and read from the buffer parameter). This value is
calculated in the following way: `min(array buffer length - offset, buf_size)`.
**Prototype**
```c
jerry_length_t
jerry_arraybuffer_write (const jerry_value_t value,
jerry_length_t offset,
const uint8_t *buf_p,
jerry_length_t buf_size);
```
- `value` - ArrayBuffer to write to
- `offset` - start offset of the write operation
- `buf_p` - buffer to read the data from
- `buf_size` - maximum number of bytes to write into the ArrayBuffer
- return value
- number of bytes written into the ArrayBuffer (read from the buffer parameter)
- 0 if the `value` is not an ArrayBuffer object
- 0 if the `buf_size` is zero or there is nothing to write
**Example**
```c
{
uint8_t data[20];
// fill the data with values
for (int i = 0; i < 20; i++)
{
data[i] = (uint8_t) (i * 2);
}
jerry_value_t buffer;
// ... create the ArrayBuffer or acquire it from somewhere.
jerry_value_t bytes_written;
// write 10 bytes from to the start of the ArrayBuffer.
bytes_written = jerry_arraybuffer_write (buffer, 0, data, 10);
// read the next 10 bytes
bytes_written += jerry_arraybuffer_write (buffer, bytes_written, data + bytes_written, 10);
// use the ArrayBuffer
jerry_release_value (buffer);
}
```
**See also**
- [jerry_create_arraybuffer](#jerry_create_arraybuffer)
- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
- [jerry_get_arraybuffer_byte_length](#jerry_get_arraybuffer_byte_length)
## jerry_get_arraybuffer_pointer
**Summary**
The function allows access to the contents of the Array Buffer directly.
Only allowed for Array Buffers which were created with
[jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)
function calls. In any other case this function will return `NULL`.
After using the pointer the [jerry_release_value](#jerry_release_value)
function must be called.
**WARNING!** This operation is for expert use only! The programmer must
ensure that the returned memory area is used correctly. That is
there is no out of bounds reads or writes.
**Prototype**
```c
uint8_t *
jerry_get_arraybuffer_pointer (const jerry_value_t value);
```
- `value` - Array Buffer object.
- return value
- pointer to the Array Buffer's data area.
- NULL if the `value` is not an Array Buffer object with external memory.
**Example**
```c
{
jerry_value_t buffer;
// acquire buffer somewhere which was created by a jerry_create_array_buffer_external call.
uint8_t *const data = jerry_get_arraybuffer_pointer (buffer);
for (int i = 0; i < 22; i++)
{
data[i] = (uint8_t) (i + 4);
}
// required after jerry_get_arraybuffer_pointer call.
jerry_release_value (buffer);
// use the Array Buffer
// release buffer as it is not needed after this point
jerry_release_value (buffer);
}
```
**See also**
- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)
## jerry_get_typedarray_type
**Summary**
Get the type of the TypedArray.
The returned type is one of the [jerry_typedarray_type_t](#jerry_typedarray_type_t)
enum value.
**Prototype**
```c
jerry_typedarray_type_t
jerry_get_typedarray_type (jerry_value_t value);
```
- `value` - TypedArray object to query for type.
- return
- the type of the TypedArray
- JERRY_TYPEDARRAY_INVALID if the object was not a TypedArray
**Example**
```c
{
jerry_typedarray_type_t expected_type = JERRY_TYPEDARRAY_UINT32;
jerry_value_t typedarray = jerry_create_typedarray (expected_klass, 25);
jerry_typedarray_type_t type = jerry_get_typedarray_type (typedarray);
// 'type' is now JERRY_TYPEDARRAY_UINT32
jerry_release_value (typedarray);
}
```
**See also**
- [jerry_create_typedarray](#jerry_create_typedarray)
- [jerry_typedarray_type_t](#jerry_typedarray_type_t)
## jerry_get_typedarray_length
**Summary**
Get the element count of the TypedArray as specified during creation.
This is not the same as the byteLength property of a TypedArray object.
**Prototype**
```
jerry_length_t
jerry_get_typedarray_length (jerry_value_t value);
```
- `value` - TypedArray object to query
- return
- length (element count) of the TypedArray object
- 0 if the object is not a TypedArray
**Example**
```c
{
jerry_value_t array = jerry_create_typedarray (JERRY_TYPEDARRAY_INT32, 21);
jerry_length_t element_count = jerry_get_typedarray_length (array);
// element_count is now 21.
jerry_release_value (array);
}
```
**See also**
- [jerry_create_typedarray](#jerry_create_typedarray)
## jerry_get_typedarray_buffer
**Summary**
Get the ArrayBuffer object used by a TypedArray object.
Additionally returns the byteLength and byteOffset properties
of the TypedArray object.
For the returned ArrayBuffer the [jerry_release_value](#jerry_release_value)
must be called.
**Prototype**
```c
jerry_value_t jerry_get_typedarray_buffer (jerry_value_t value,
jerry_length_t *byteOffset,
jerry_length_t *byteLength);
```
- `value` - TypedArray to get the ArrayBuffer from
- `byteOffset` - (Optional) returns the start offset of the ArrayBuffer for the TypedArray
- `byteLength` - (Optional) returns the number of bytes used from the ArrayBuffer for the TypedArray
- return
- TypedArray object's underlying ArrayBuffer object
- TypeError if the `value` is not a TypedArray object
**Example**
```c
{
jerry_value_t array = jerry_create_typedarray (JERRY_TYPEDARRAY_INT16, 11);
jerry_length_t byteLength = 0;
jerry_length_t byteOffset = 0;
jerry_value_t buffer = jerry_get_typedarray_buffer (array, &byteOffset, &byteLength);
// buffer is an ArrayBuffer object and ArrayBuffer operations can be performed on it
// byteLength is 11 * 2 (2 as the TypedArray stores Int16 that is 2 byte elements)
// byteOffset is 0
jerry_release_value (buffer);
jerry_release_value (array);
}
```
**See also**
- [jerry_create_typedarray](#jerry_create_typedarray)
# JSON functions
## jerry_json_parse
**Summary**
Returns the same result as JSON.parse ecmascript function.
**Prototype**
```c
jerry_value_t jerry_json_parse (const jerry_char_t *string_p, jerry_size_t string_size)
```
- `string_p` - a JSON string
- `string_size` - size of the string
- return
- jerry_value_t containing the same as json.parse()
- jerry_value_t containing error massage
**Example**
```c
{
const char *data = "{\"name\": \"John\", \"age\": 5}";
jerry_size_t str_length = (jerry_size_t)strlen (data);
jerry_value_t parsed_json = jerry_json_parse ((jerry_char_t*)data, str_length);
// parsed_json now conatins all data stored in data_in_json
jerry_release_value (parsed_json);
}
```
## jerry_stringify
**Summary**
Returns the same value as JSON.stringify() ecmascript function.
**Prototype**
```c
jerry_value_t jerry_json_stringfy (const jerry_value_t object_to_stringify)
```
- `object_to_stringify` - a jerry_value_t object to stringify
- return
- jerry_value_t containing the same as json.stringify()
- jerry_value_t containing error massage
**Example**
```c
{
jerry_value_t obj = jerry_create_object ();
jerry_value_t key = jerry_create_string ((const jerry_char_t *) "name");
jerry_value_t value = jerry_create_string ((const jerry_char_t *) "John");
jerry_set_property (obj, key, value);
jerry_value_t stringified = jerry_json_stringfy (obj);
//stringified now contains a json formated string
jerry_release_value (obj);
jerry_release_value (key);
jerry_release_value (value);
jerry_release_value (stringified);
}
```
Reference in New Issue View Git Blame Copy Permalink