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 - deprecated, dump memory statistics and reset peak values after parse
• JERRY_INIT_DEBUGGER - deprecated, an unused placeholder now

Changed in version 2.0: JERRY_INIT_MEM_STATS_SEPARATE and JERRY_INIT_DEBUGGER are now deprecated and not used internally.

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_TYPE_SYMBOL - symbol type

New in version 2.0.

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.

Changed in version 2.0: The JERRY_ERROR_NONE was added to be used by the jerry_get_error_type method.

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_FEATURE_LOGGING - logging
• JERRY_FEATURE_SYMBOL - symbol support
• JERRY_FEATURE_DATAVIEW - DataView support

New in version 2.0.

jerry_regexp_flags_t

RegExp object optional flags:

• JERRY_REGEXP_FLAG_GLOBAL - global match; find all matches rather than stopping after the first match
• JERRY_REGEXP_FLAG_IGNORE_CASE - ignore case
• JERRY_REGEXP_FLAG_MULTILINE - multiline; treat beginning and end characters (^ and $) as working over multiple lines (i.e., match the beginning or end of each line (delimited by \n or \r), not only the very beginning or end of the whole input string)

New in version 2.0.

jerry_parse_opts_t

Option bits for jerry_parse and jerry_parse_function functions:

• JERRY_PARSE_NO_OPTS - no options passed
• JERRY_PARSE_STRICT_MODE - enable strict mode

New in version 2.0.

jerry_gc_mode_t

Set garbage collection operational mode

• JERRY_GC_PRESSURE_LOW - free unused objects
• JERRY_GC_PRESSURE_HIGH - free as much memory as possible

The difference between JERRY_GC_PRESSURE_LOW and JERRY_GC_PRESSURE_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.

New in version 2.0.

jerry_generate_snapshot_opts_t

Flags for jerry_generate_snapshot and 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. 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 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 when the snapshot is generated and executed. Furthermore the JERRY_SNAPSHOT_EXEC_COPY_DATA option is not allowed.

New in version 2.0.

jerry_exec_snapshot_opts_t

Flags for jerry_exec_snapshot and 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 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 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.

New in version 2.0.

jerry_char_t

Summary

Jerry’s char value

Prototype

typedef uint8_t jerry_char_t;

jerry_size_t

Summary

Jerry’s size

Prototype

typedef uint32_t jerry_size_t;

jerry_length_t

Summary

Jerry’s length

Prototype

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.

Returned and created values by the API functions must be freed with jerry_release_value when they are no longer needed.

Prototype

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. If bytes_needed field is 0, no buffer is allocated for the manager, callback functions are called with NULL pointer.

Prototype

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;

New in version 2.0.

jerry_context_alloc_t

Summary

Function type for allocating buffer for JerryScript context.

Prototype

typedef void *(*jerry_context_alloc_t) (size_t size, void *cb_data_p);

• size - allocation size
• cb_data_p - pointer to user data

New in version 2.0.

jerry_context_t

Summary

An opaque declaration of the JerryScript context structure.

Prototype

typedef struct jerry_context_t jerry_context_t;

New in version 2.0.

jerry_binary_operation_t

Enum that contains the supported binary operation types

• JERRY_BIN_OP_EQUAL - equal comparison (==)
• JERRY_BIN_OP_STRICT_EQUAL - strict equal comparison (===)
• JERRY_BIN_OP_LESS - less relation (<)
• JERRY_BIN_OP_LESS_EQUAL - less or equal relation (<=)
• JERRY_BIN_OP_GREATER - greater relation (>)
• JERRY_BIN_OP_GREATER_EQUAL - greater or equal relation (>=)
• JERRY_BIN_OP_INSTANCEOF - instanceof operation

New in version 2.0.

See also

• jerry_binary_operation

jerry_property_descriptor_t

Summary

Description of ECMA property descriptor. This struct can be used for the jerry_define_own_property method to configure how the property should be registered.

The naming scheme is similar to the JavaScript Object.defineProperty method.

Fields should be used in pairs. That is if the is_value_defined is set to true the value field should contain the value for the property.

Prototype

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;

See also

• jerry_define_own_property

jerry_heap_stats_t

Summary

Description of JerryScript heap memory stats. It is for memory profiling.

Prototype

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;

New in version 2.0.

See also

• jerry_get_memory_stats

jerry_external_handler_t

Summary

Type of an external function handler

Prototype

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);

• function_object - the JavaScript function object which was invoked.
• this_val - the this value provided for the function call.
• args_p - the function arguments, array of JavaScript values.
• args_count - the number of arguments.
• return value
  • The function’s return value. If there is no return value, use jerry_create_undefined().

See also

• jerry_create_external_function

jerry_object_native_free_callback_t

Summary

Native free callback of an object. It is used in jerry_object_native_info_t and for external Array buffers.

Note:

• This callback method must not call any JerryScript API methods.

Prototype

typedef void (*jerry_object_native_free_callback_t) (void *native_p);

New in version 2.0: Renamed from jerry_object_free_callback_t.

See also

• jerry_object_native_info_t
• jerry_create_arraybuffer_external

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 for a best-practice code example.

Prototype

typedef struct
{
  jerry_object_native_free_callback_t free_cb;
} jerry_object_native_info_t;

New in version 2.0.

See also

• jerry_set_object_native_pointer
• jerry_get_object_native_pointer

jerry_object_property_foreach_t

Summary

Function type used as a callback for the jerry_foreach_object_property method. A function with this type must return “true” to continue the iteration or “false” to finish the iteration on the object’s properties.

Prototype

typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name,
                                                 const jerry_value_t property_value,
                                                 void *user_data_p);

• property_name - a property name, this is not always a string.
• property_value - the value for the given property.
• user_data_p - optional user data pointer supplied via the (jerry_foreach_object_property)[#jerry_foreach_object_property] method.
• return value
  • true, to continue the iteration
  • false, to stop the iteration

See also

• jerry_foreach_object_property

jerry_objects_foreach_t

Summary

Function type used as a callback for the (jerry_objects_foreach)[#jerry_objects_foreach] method. A function with this type must return “true” to continue the iteration or “false” to finish the iteration on the object’s properties.

Prototype

typedef bool (*jerry_objects_foreach_t) (const jerry_value_t object,
                                         void *user_data_p);

• object - the current JavaScript object in the for-each iteration.
• user_data_p - optional user data pointer supplied via the (jerry_objects_foreach)[#jerry_objects_foreach] method.
• return value
  • true, to continue the iteration
  • false, to stop the iteration

New in version 2.0.

See also

• jerry_objects_foreach

jerry_objects_foreach_by_native_info_t

Summary

Function type used as a callback for the (jerry_objects_foreach_by_native_info)[#jerry_objects_foreach_by_native_info] method. A function with this type must return “true” to continue the iteration or “false” to finish the iteration on the object’s properties.

Prototype

typedef bool (*jerry_objects_foreach_by_native_info_t) (const jerry_value_t object,
                                                        void *object_data_p,
                                                        void *user_data_p);

• object - the current JavaScript object in the for-each iteration.
• object_data_p - the current object’s native data pointer.
• user_data_p - optional user data pointer supplied via the (jerry_objects_foreach_by_native_info)[#jerry_objects_foreach_by_native_info] method.
• return value
  • true, to continue the iteration
  • false, to stop the iteration

New in version 2.0.

See also

• jerry_objects_foreach_by_native_info

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

typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p);

New in version 2.0.

See also

• 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.

New in version 2.0.

See also

• jerry_get_typedarray_type

General engine functions

jerry_init

Summary

Initializes the JerryScript engine, making it possible to run JavaScript code and perform operations on JavaScript values. This is required for almost all API functions.

Prototype

void
jerry_init (jerry_init_flag_t flags)

flags - combination of various engine configuration flags jerry_init_flag_t.

Example

#include "jerryscript.h"
int
main (void)
{
  jerry_init (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_SHOW_REGEXP_OPCODES);
  // ...
  jerry_cleanup ();
  return 0;
}

See also

• jerry_init_flag_t
• 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

void
jerry_cleanup (void);

See also

• 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

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.

New in version 2.0.

Example

#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.

Notes:

• The strings in the array must be sorted by size at first, then lexicographically.
• The maximum number of external magic strings is limited to 2147483648 (UINT32_MAX / 2). If there are more than 2147483648 external magic strings the extra is cropped.

Prototype

void
jerry_register_magic_strings  (const jerry_char_t * const *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 elements in ext_str_items_p array
• str_lengths_p - array of lengths for each magic string

Changed in version 2.0: The first function argument type was changed.

Example

#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_t * const magic_string_items[] = {
                                                             (const jerry_char_t *) "magicstring1",
                                                             (const jerry_char_t *) "magicstring2",
                                                             (const jerry_char_t *) "magicstring3"
                                                           };
  uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_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_cleanup
• jerry_get_literals_from_snapshot

jerry_get_memory_stats

Summary

Get heap memory stats.

Notes:

• The engine must be initialized with the JERRY_INIT_MEM_STATS option to allow heap statistic collections. See jerry_init
• This API depends on a build option (JERRY_MEM_STATS) and can be checked in runtime with the JERRY_FEATURE_MEM_STATS feature enum value, see: jerry_is_feature_enabled.

Prototype

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 stats were written into the out_stats_p pointer.
  • false, otherwise. Usually it is because the JERRY_FEATURE_MEM_STATS feature is not enabled.

New in version 2.0.

Example

jerry_init (JERRY_INIT_MEM_STATS);
// ...
jerry_heap_stats_t stats = {0};
bool get_stats_ret = jerry_get_memory_stats (&stats);

See also

• jerry_init

jerry_gc

Summary

Performs garbage collection.

Prototype

void
jerry_gc (jerry_gc_mode_t mode);

• mode - operational mode, see jerry_gc_mode_t

Changed in version 2.0: Added mode argument.

Example

#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_PRESSURE_LOW);
  jerry_cleanup ();
}

See also

• jerry_gc_mode_t
• jerry_init
• 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

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

#include "jerryscript.h"
int
main (void)
{
  const jerry_char_t script[] = "print ('Hello, World!');";
  jerry_run_simple (script, sizeof (script) - 1, JERRY_INIT_EMPTY);
  return 0;
}

See also

• jerry_init
• jerry_cleanup
• jerry_parse
• 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 when it is no longer needed.

Prototype

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 flags.
• return value
  • function object value, if script was parsed successfully,
  • thrown error, otherwise

Changed in version 2.0: Added resource_name_p, and resource_name_length arguments.

Example

#include "jerryscript.h"
int
main (void)
{
  jerry_init (JERRY_INIT_EMPTY);
  const jerry_char_t script[] = "print ('Hello, World!');";
  jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
  jerry_release_value (parsed_code);
  jerry_cleanup ();
  return 0;
}

See also

• jerry_run
• jerry_parse_function

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 when it is no longer needed.

Prototype

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 flags.
• return value
  • function object value, if script was parsed successfully,
  • thrown error, otherwise

New in version 2.0.

Example

#include <stdio.h>
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
  int return_value = 1;
  /* Initialize engine */
  jerry_init (JERRY_INIT_EMPTY);
  /* Parse the 'function (a,b) { return a + b; }' function */
  const char function_args[] = "a, b";
  const char function_source[] = "return a + b";
  jerry_value_t parsed_function = jerry_parse_function (NULL,
                                                        0,
                                                        (const jerry_char_t *) function_args,
                                                        strlen (function_args),
                                                        (const jerry_char_t *) function_source,
                                                        strlen (function_source),
                                                        JERRY_PARSE_NO_OPTS);
  if (!jerry_value_is_error (parsed_function))
  {
    /* Run the parsed function */
    jerry_value_t args[] = {
        jerry_create_number (3),
        jerry_create_number (55),
    };
    jerry_size_t argc = sizeof (args) / sizeof (args[0]);
    jerry_value_t ret_value = jerry_call_function (parsed_function,
                                                   jerry_create_undefined(),
                                                   args,
                                                   argc);
    /* Process result value */
    if (jerry_value_is_number (ret_value)) {
        double value = jerry_get_number_value (ret_value);
        printf ("Function result: %lf\n", value);
        return_value = !(value == (3 + 55));
    }
    /* Release the function arguments */
    for (jerry_size_t idx = 0; idx < argc; idx++) {
        jerry_release_value (args[idx]);
    }
    /* Returned value must be freed */
    jerry_release_value (ret_value);
  }
  /* Parsed function must be freed */
  jerry_release_value (parsed_function);
  /* Cleanup engine */
  jerry_cleanup ();
  return return_value;
}

See also

• jerry_call_function

jerry_run

Summary

Run an EcmaScript function created by jerry_parse.

Notes:

• The code should be previously parsed with jerry_parse.
• Returned value must be freed with jerry_release_value when it is no longer needed.

Prototype

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

#include "jerryscript.h"
int
main (void)
{
  const jerry_char_t script[] = "print ('Hello, World!');";
  /* Initialize engine */
  jerry_init (JERRY_INIT_EMPTY);
  /* Setup Global scope code */
  jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, 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_eval

Summary

Perform JavaScript eval function call (ECMA-262 v5.1 sec-15.1.2.1).

Note: Returned value must be freed with jerry_release_value when it is no longer needed.

Prototype

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 flags.
• return value - result of eval, may be an error value.

Example

{
  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_external_handler_t

jerry_run_all_enqueued_jobs

Summary

Run enqueued Promise jobs until the first thrown error or until all get executed.

Note: Returned value must be freed with jerry_release_value when it is no longer needed.

Prototype

jerry_value_t
jerry_run_all_enqueued_jobs (void)

• return value - result of last executed job, may be error value.

New in version 2.0.

Example

#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); });";
  jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, 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 ();
  return 0;
}

Get the global context

jerry_get_global_object

Summary

Get the Global object.

Note: Returned value must be freed with jerry_release_value when it is no longer needed.

Prototype

jerry_value_t
jerry_get_global_object (void);

• return value - api value of global object

Example

{
  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_define_own_property

Checker functions

Functions to check the type of an API value (jerry_value_t).

jerry_value_is_abort

Summary

Returns whether the given jerry_value_t has the error and abort value set.

Prototype

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

New in version 2.0.

Example

{
  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_is_error

jerry_value_is_array

Summary

Returns whether the given jerry_value_t is an array.

Prototype

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

{
  jerry_value_t value;
  ... // create or acquire value
  if (jerry_value_is_array (value))
  {
    ...
  }
  jerry_release_value (value);
}

See also

• jerry_release_value

jerry_value_is_arraybuffer

Summary

Returns whether the given jerry_value_t is an ArrayBuffer object.

Notes:

• This API depends on a build option (JERRY_ES2015_BUILTIN_TYPEDARRAY) and can be checked in runtime with the JERRY_FEATURE_TYPEDARRAY feature enum value, see: jerry_is_feature_enabled.
• The ES2015-subset profile enables this by default.

Prototype

bool
jerry_value_is_arraybuffer (const jerry_value_t value)

• value - api value to check.
• return value
  • true, if the given jerry_value_t is an ArrayBuffer object.
  • false, otherwise

New in version 2.0.

Example

{
  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_external

jerry_value_is_boolean

Summary

Returns whether the given jerry_value_t is a boolean value.

Prototype

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

{
  jerry_value_t value;
  ... // create or acquire value
  if (jerry_value_is_boolean (value))
  {
    ...
  }
  jerry_release_value (value);
}

See also

• jerry_release_value

jerry_value_is_constructor

Summary

Returns whether the given jerry_value_t is a constructor function.

Prototype

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

{
  jerry_value_t value;
  ... // create or acquire value
  if (jerry_value_is_constructor (value))
  {
    ...
  }
  jerry_release_value (value);
}

See also

• jerry_release_value

jerry_value_is_dataview

Summary

Returns whether the given jerry_value_t is a DataView object value.

Notes:

• This API depends on a build option (JERRY_ES2015_BUILTIN_DATAVIEW) and can be checked in runtime with the JERRY_FEATURE_DATAVIEW feature enum value, see: jerry_is_feature_enabled.
• The ES2015-subset profile enables this by default.

Prototype

bool
jerry_value_is_dataview (const jerry_value_t value)

• value - API value
• return value
  • true, if the given jerry_value_t is a DataView object
  • false, otherwise

New in version 2.0.

Example

#include "jerryscript.h"
int
main (void)
{
  jerry_init (JERRY_INIT_EMPTY);
  jerry_value_t arraybuffer = jerry_create_arraybuffer (16);
  jerry_value_t dataview = jerry_create_dataview (arraybuffer, 0, 16);
  if (jerry_value_is_dataview (dataview))
  {
    // usage of dataview
  }
  jerry_release_value (dataview);
  jerry_release_value (arraybuffer);
  jerry_cleanup ();
  return 0;
}

See also

• jerry_release_value
• jerry_create_dataview

jerry_value_is_error

Summary

Returns whether the given jerry_value_t is error value.

Prototype

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

New in version 2.0.

Example

{
  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_is_abort

jerry_value_is_function

Summary

Returns whether the given jerry_value_t is a function.

Prototype

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

{
  jerry_value_t value;
  ... // create or acquire value
  if (jerry_value_is_function (value))
  {
    ...
  }
  jerry_release_value (value);
}

See also

• jerry_release_value

jerry_value_is_number

Summary

Returns whether the given jerry_value_t is a number.

Prototype

bool
jerry_value_is_number (const jerry_value_t value)

• value - api value
• return value
  • true, if the given jerry_value_t is a number
  • false, otherwise

Example

{
  jerry_value_t value;
  ... // create or acquire value
  if (jerry_value_is_number (value))
  {
    ...
  }
  jerry_release_value (value);
}

See also

• jerry_release_value

jerry_value_is_null

Summary

Returns whether the given jerry_value_t is a null value.

Prototype

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

{
  jerry_value_t value;
  ... // create or acquire value
  if (jerry_value_is_null (value))
  {
    ...
  }
  jerry_release_value (value);
}

See also

• jerry_release_value

jerry_value_is_object

Summary

Returns whether the given jerry_value_t is an object value.

Prototype

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

{
  jerry_value_t value;
  ... // create or acquire value
  if (jerry_value_is_object (value))
  {
    ...
  }
  jerry_release_value (value);
}

See also

• jerry_release_value

jerry_value_is_promise

Summary

Returns whether the given jerry_value_t is a promise value.

Notes:

• This API depends on a build option (JERRY_ES2015_BUILTIN_PROMISE) and can be checked in runtime with the JERRY_FEATURE_PROMISE feature enum value, see: jerry_is_feature_enabled.
• The ES2015-subset profile enables this by default.

Prototype

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

New in version 2.0.

Example

{
  jerry_value_t value;
  ... // create or acquire value
  if (jerry_value_is_promise (value))
  {
    ...
  }
  jerry_release_value (value);
}

See also

• jerry_release_value
• jerry_create_promise

jerry_value_is_string

Summary

Returns whether the given jerry_value_t is a string value.

Prototype

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

{
  jerry_value_t value;
  ... // create or acquire value
  if (jerry_value_is_string (value))
  {
    ...
  }
  jerry_release_value (value);
}

See also

• jerry_release_value

jerry_value_is_symbol

Summary

Returns whether the given jerry_value_t is a symbol value.

Notes:

• This API depends on a build option (JERRY_ES2015_BUILTIN_SYMBOL) and can be checked in runtime with the JERRY_FEATURE_SYMBOL feature enum value, see: jerry_is_feature_enabled.
• The ES2015-subset profile enables this by default.

Prototype

bool
jerry_value_is_symbol (const jerry_value_t value)

• value - API value
• return value
  • true, if the given jerry_value_t is a symbol
  • false, otherwise

New in version 2.0.

Example

#include "jerryscript.h"
int
main (void)
{
  jerry_init (JERRY_INIT_EMPTY);
  jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "Symbol description string");
  jerry_value_t symbol_value = jerry_create_symbol (string_value);
  jerry_release_value (string_value);
  if (jerry_value_is_symbol (symbol_value))
  {
    // usage of symbol_value
  }
  jerry_release_value (symbol_value);
  jerry_cleanup ();
  return 0;
}

See also

• jerry_release_value
• jerry_create_symbol

jerry_value_is_typedarray

Summary

Checks whether the given jerry_value_t is a TypedArray object or not.

Notes:

• This API depends on a build option (JERRY_ES2015_BUILTIN_TYPEDARRAY) and can be checked in runtime with the JERRY_FEATURE_TYPEDARRAY feature enum value, see: jerry_is_feature_enabled.
• The ES2015-subset profile enables this by default.

Prototype

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

New in version 2.0.

Example

#include "jerryscript.h"
int
main (void)
{
  jerry_init (JERRY_INIT_EMPTY);
  jerry_value_t value = jerry_create_typedarray (JERRY_TYPEDARRAY_UINT16, 15);
  if (jerry_value_is_typedarray (value))
  {
    /* "value" is a typedarray. */
  }
  jerry_release_value (value);
  jerry_cleanup ();
  return 0;
}

See also

• jerry_create_typedarray

jerry_value_is_undefined

Summary

Returns whether the given jerry_value_t is an undefined value.

Prototype

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

{
  jerry_value_t value;
  ... // create or acquire value
  if (jerry_value_is_undefined (value))
  {
    ...
  }
  jerry_release_value (value);
}

See also

• jerry_release_value

jerry_value_get_type

Summary

Returns the JavaScript type for a given value as a 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

jerry_type_t
jerry_value_get_type (const jerry_value_t value);

• value - JavaScript value to check.
• return value
  • One of the jerry_type_t value.

New in version 2.0.

Example

{
  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_release_value (number);
}

See also

• jerry_type_t

jerry_is_feature_enabled

Summary

Returns whether the specified compile time feature is enabled.

Prototype

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

New in version 2.0.

Example

{
  /* ... */
  jerry_feature_t feature = JERRY_FEATURE_SNAPSHOT_SAVE;
  if (jerry_is_feature_enabled (feature))
  {
    /* ... */
  }
}

See also

• jerry_feature_t

Binary operations

jerry_binary_operation

Summary

Perform binary operation on the given operands (==, ===, <, >, etc.).

Note: Returned value must be freed with jerry_release_value when it is no longer needed.

Prototype

jerry_value_t
jerry_binary_operation (jerry_binary_operation_t op,
                        const jerry_value_t lhs,
                        const jerry_value_t rhs);

• op - binary operation
• lhs - left-hand side operand
• rhs - right-hand side operand
• return value
  • error, if argument has an error flag or operation is unsuccessful or unsupported
  • true/false, the result of the binary operation on the given operands otherwise

New in version 2.0.

Example - JERRY_BIN_OP_EQUAL

{
  jerry_value_t value1;
  jerry_value_t value2;
  ... // create or acquire value
  jerry_value_t result = jerry_binary_operation (JERRY_BIN_OP_EQUAL, value1, value2)
  if (!jerry_value_is_error (result))
  {
    if (jerry_get_boolean_value (result))
    {
       // value1 and value2 are equal
    }
    else
    {
      // value1 and value2 are NOT equal
    }
  }
  else
  {
    ... // handle error
  }
  jerry_release_value (value1);
  jerry_release_value (value2);
  jerry_release_value (result);
}

Example - JERRY_BIN_OP_INSTANCEOF

#include "jerryscript.h"
static jerry_value_t
my_constructor (const jerry_value_t func_val,
                const jerry_value_t this_val,
                const jerry_value_t argv[],
                const jerry_length_t argc)
{
  return jerry_create_undefined ();
}
int
main (void)
{
  jerry_init (JERRY_INIT_EMPTY);
  jerry_value_t base_obj = jerry_create_object ();
  jerry_value_t constructor = jerry_create_external_function (my_constructor);
  /* External functions does not have a prototype by default, so we need to create one */
  jerry_value_t prototype_str = jerry_create_string ((const jerry_char_t *) ("prototype"));
  jerry_release_value (jerry_set_property (constructor, prototype_str, base_obj));
  jerry_release_value (prototype_str);
  /* Construct the instance. */
  jerry_value_t instance_val = jerry_construct_object (constructor, NULL, 0);
  /* Call the API function of 'instanceof'. */
  jerry_value_t is_instance = jerry_binary_operation (JERRY_BIN_OP_INSTANCEOF,
                                                      instance_val,
                                                      constructor);
  if (!jerry_value_is_error (is_instance)
      && jerry_get_boolean_value (is_instance) == true)
  {
    /* ... */
  }
  /* Free all of the jerry values and cleanup the engine. */
  jerry_release_value (base_obj);
  jerry_release_value (constructor);
  jerry_release_value (instance_val);
  jerry_release_value (is_instance);
  jerry_cleanup ();
  return 0;
}

See also

• jerry_binary_operation_t

Error manipulation functions

Changed in version 2.0: The error handling and manipulation was modified and the old methods were replaced.

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 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

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

New in version 2.0.

Example 1

{
  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

{
  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_get_value_from_error
• 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 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

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

New in version 2.0.

Example 1

{
  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

{
  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_get_value_from_error
• 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 method.

Prototype

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 value

New in version 2.0.

Example

{
  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_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 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 when it is no longer needed.

Prototype

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

New in version 2.0.

Example 1

{
  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

{
  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_create_error_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

bool
jerry_get_boolean_value (const jerry_value_t value);

• value - api value
• return value - boolean value represented by the argument.

Example

{
  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_release_value

jerry_get_number_value

Summary

Gets the number value of the given jerry_value_t parameter as a raw double.

If the argument passed is not a number 0.0 will be returned.

Prototype

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.
  • 0.0 if the api value passed is not a number.

Example

{
  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_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. This is effectively the number of bytes required to store the string’s characters.

Prototype

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

{
  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_get_string_length
• 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. This is effectively the number of bytes required to store the utf8 encoded string’s characters.

Note: The difference from jerry_get_string_size is that it returns with utf-8 string size instead of the cesu-8 string size.

Prototype

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.

New in version 2.0.

Example

{
  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_get_utf8_string_length
• 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.

Notes:

• The difference from jerry_get_string_size is that it returns the number of bytes used for the string.
• This is not the number of bytes required to store the string.

Prototype

jerry_length_t
jerry_get_string_length (const jerry_value_t value);

• value - api value
• return value - number of characters in the string

Example

{
  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_get_string_size
• 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.

Notes:

• The difference from jerry_get_string_length is that it returns with utf-8 string length instead of the cesu-8 string length.
• This is not the number of bytes required to store the string.

Prototype

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

New in version 2.0.

Example

{
  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_get_utf8_string_size
• 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 API function is recommended instead.

Prototype

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

#include <stdio.h>
#include <stdlib.h>
#include "jerryscript.h"
int
main (void)
{
  jerry_init (JERRY_INIT_EMPTY);
  jerry_value_t value;
  // create or acquire value
  value = jerry_create_string ((const jerry_char_t *) "Demo string");
  // Read the string into a byte buffer.
  jerry_size_t string_size = jerry_get_string_size (value);
  jerry_char_t *string_buffer_p = (jerry_char_t *) malloc (sizeof (jerry_char_t) * (string_size + 1));
  jerry_size_t copied_bytes = jerry_string_to_char_buffer (value, string_buffer_p, string_size);
  string_buffer_p[copied_bytes] = '\0';
  jerry_release_value (value);
  jerry_cleanup ();
  printf ("Test string: %s\n", string_buffer_p);
  free (string_buffer_p);
  return 0;
}

See also

• jerry_create_string
• jerry_get_string_size
• jerry_is_valid_cesu8_string
• 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 API function is recommended instead.

Prototype

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

New in version 2.0.

Example

{
  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_size_t bytes_copied = jerry_string_to_utf8_char_buffer (value, str_buf_p, req_sz);
  jerry_release_value (value);
}

See also

• jerry_create_string_from_utf8
• jerry_get_utf8_string_size
• jerry_is_valid_utf8_string
• 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

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

New in version 2.0.

Example

{
  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_get_string_size
• jerry_get_string_length
• 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

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

New in version 2.0.

Example

{
  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_get_utf8_string_size
• jerry_get_utf8_string_length
• 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

uint32_t
jerry_get_array_length (const jerry_value_t value);

• value - input array value
• return value - length of the given array

Example

{
  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

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

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

{
  jerry_value_t value;
  ... // create or acquire value
  bool b = jerry_value_to_boolean (value);
  jerry_release_value (value);
}