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

Possible types of an error:

 - JERRY_ERROR_COMMON - common error
 - JERRY_ERROR_EVAL - eval error
 - JERRY_ERROR_RANGE - range error
 - JERRY_ERROR_REFERENCE - reference error
 - JERRY_ERROR_SYNTAX - syntax error
 - JERRY_ERROR_TYPE - type error
 - JERRY_ERROR_URI - URI error

## jerry_char_t

**Summary**

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

Native free callback of an object

**Prototype**

```c
typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p);
```

## jerry_object_property_foreach_t

**Summary**

Function type applied for each data property of an object

**Prototype**

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

# General engine functions

## jerry_init

**Summary**

Initializes the JerryScript engine, making 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.

**Example**

```c
{
  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_register_magic_strings

**Summary**

Registers an external magic string array.

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

```c
{
  jerry_init (JERRY_INIT_EMPTY);

  // must be static, because 'jerry_register_magic_strings' does not copy
  static const jerry_char_ptr_t magic_string_items[] = {
                                                         (const jerry_char_ptr_t) "magicstring1",
                                                         (const jerry_char_ptr_t) "magicstring2",
                                                         (const jerry_char_ptr_t) "magicstring3"
                                                        };
  uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t));

  // must be static, because 'jerry_register_magic_strings' does not copy
  static const jerry_length_t magic_string_lengths[] = {
                                                         (jerry_length_t)strlen (magic_string_items[0]),
                                                         (jerry_length_t)strlen (magic_string_items[1]),
                                                         (jerry_length_t)strlen (magic_string_items[2])
                                                       };
  jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
}
```

**See also**

- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)

## jerry_get_memory_limits

**Summary**

Gets configured memory limits of JerryScript.

**Prototype**

```c
void
jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p,
                         size_t *out_stack_limit_p);
```

- `out_data_bss_brk_limit_p` - out parameter, that gives the maximum size of data + bss + brk sections.
- `out_stack_limit_p` - out parameter, that gives the maximum size of the stack.

**Example**

```c
{
  jerry_init (JERRY_INIT_EMPTY);

  size_t stack_limit;
  size_t data_bss_brk_limit;
  jerry_get_memory_limits (&stack_limit, &data_bss_brk_limit);
}
```

**See also**

- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)

## jerry_gc

**Summary**

Performs garbage collection.

**Prototype**

```c
void
jerry_gc (void);
```

**Example**

```c
jerry_gc ();
```

**See also**

- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)

# Parser and executor functions

Functions to parse and run JavaScript source code.

## jerry_run_simple

**Summary**

The simplest way to run JavaScript.

**Prototype**

```c
bool
jerry_run_simple (const jerry_char_t *script_source_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**

```c
{
  const jerry_char_t *script = "print ('Hello, World!');";

  jerry_run_simple (script, strlen ((const char *) script), JERRY_INIT_EMPTY);
}
```

**See also**

- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
- [jerry_parse](#jerry_parse)
- [jerry_run](#jerry_run)

## jerry_parse

**Summary**

Parse script and construct an EcmaScript function. The
lexical environment is set to 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_parse (const jerry_char_t *source_p,
             size_t source_size,
             bool is_strict);
```

- `source_p` - string, containing source code to parse. It must be a valid utf8 string.
- `source_size` - size of the string, in bytes.
- `is_strict` - defines strict mode.
- return value
  - function object value, if script was parsed successfully,
  - thrown error, otherwise

**Example**

```c
{
  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 (script, script_size, false);
  jerry_release_value (parsed_code);

  jerry_cleanup ();
}
```

**See also**

- [jerry_run](#jerry_run)

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

```c
{
  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 (script, script_size, false);

  if (!jerry_value_has_error_flag (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,
            bool is_strict);
```

- `source_p` - source code to evaluate, it must be a valid utf8 string.
- `source_size` - length of the source code
- `is_strict` - perform `eval` as it is called from "strict mode" code.
- return value - result of eval, may be error value.

**Example**

```c
{
  jerry_value_t ret_val = jerry_eval (str_to_eval,
                                      strlen (str_to_eval),
                                      false);
}
```

**See also**

- [jerry_create_external_function](#jerry_create_external_function)
- [jerry_external_handler_t](#jerry_external_handler_t)

# Get the global context

## jerry_get_global_object

**Summary**

Get the Global object.

*Note*: Returned value must be freed with [jerry_release_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_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_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_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_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_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)

# Error flag manipulation functions

## jerry_value_has_error_flag

**Summary**

Returns whether the given `jerry_value_t` has the error flag set.

**Prototype**

```c
bool
jerry_value_has_error_flag (const jerry_value_t value);
```

- `value` - api value
- return value
  - true, if the given `jerry_value_t` has the error flag set
  - false, otherwise

**Example**

```c
{
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_has_error_flag (value))
  {
    ...
  }

  jerry_release_value (value);
}
```

**See also**

- [jerry_value_t](#jerry_value_t)

## jerry_value_clear_error_flag

**Summary**

Clear the error flag.

**Prototype**

```c
void
jerry_value_clear_error_flag (jerry_value_t *value_p);
```

- `value_p` - pointer to an api value

**Example**

```c
{
  jerry_value_t value;
  ... // create or acquire value

  jerry_value_clear_error_flag (&value);

  jerry_release_value (value);
}
```

**See also**

- [jerry_value_t](#jerry_value_t)

## jerry_value_set_error_flag

**Summary**

Set the error flag.

**Prototype**

```c
void
jerry_value_set_error_flag (jerry_value_t *value_p);
```

- `value_p` - pointer to an api value

**Example**

```c
{
  jerry_value_t value;
  ... // create or acquire value

  jerry_value_set_error_flag (&value);

  jerry_release_value (value);
}
```

**See also**

- [jerry_value_t](#jerry_value_t)

# 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_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_string_to_char_buffer

**Summary**

Copy the characters of a string into a specified 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.

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

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

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

**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_has_error_flag](#jerry_value_has_error_flag)
- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag)
- [jerry_value_set_error_flag](#jerry_value_set_error_flag)

## jerry_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");
  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_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_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_create_string](#jerry_create_string)

## 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 it's prototype objects have the given property.

**Prototype**

```c
bool
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
  - 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");

  bool has_prop = jerry_has_property (global_object, prop_name);

  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.

**Prototype**

```c
bool
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
  - 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");

  bool has_prop = jerry_has_own_property (global_object, prop_name);

  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_get_property](#jerry_get_property)

## 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_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_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_set_property (glob_obj, prop_name, value_to_set);

  jerry_release_value (prop_name);

  ...

  jerry_release_value (value_to_set);
  jerry_release_value (glob_obj);
}
```

**See also**

- [jerry_has_property](#jerry_has_property)
- [jerry_has_own_property](#jerry_has_own_property)
- [jerry_delete_property](#jerry_delete_property)
- [jerry_get_property](#jerry_get_property)
- [jerry_get_property_by_index](#jerry_get_property_by_index)
- [jerry_set_property_by_index](#jerry_set_property_by_index)

## jerry_set_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_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_define_own_property (global_obj_val, prop_name, &prop_desc);
  jerry_release_value (prop_name);

  jerry_free_property_descriptor_fields (&prop_desc);
  jerry_release_value (global_obj_val);
}
```

**See also**

- [jerry_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.

*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_has_error_flag (ret_val))
    {
      ... // handle return value
    }

    jerry_release_value (ret_val);
    jerry_release_value (this_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_has_error_flag (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_get_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**

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_set_object_native_handle

**Summary**

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

# Snapshot functions

## jerry_parse_and_save_snapshot

**Summary**

Generate snapshot from the specified source code.

**Prototype**

```c
size_t
jerry_parse_and_save_snapshot (const jerry_char_t *source_p,
                               size_t source_size,
                               bool is_for_global,
                               bool is_strict,
                               uint8_t *buffer_p,
                               size_t buffer_size);
```

- `source_p` - script source, it must be a valid utf8 string.
- `source_size` - script source size, in bytes.
- `is_for_global` - snapshot would be executed as global (true) or eval (false).
- `is_strict` - strict mode
- `buffer_p` - buffer to save snapshot to.
- `buffer_size` - the buffer's size.
- return value
  - the size of snapshot, if it was generated succesfully (i.e. there are no syntax errors in source
    code, buffer size is sufficient, and snapshot support is enabled in current configuration through
    JERRY_ENABLE_SNAPSHOT_SAVE)
  - 0 otherwise.

**Example**

```c
{
  jerry_init (JERRY_INIT_EMPTY);

  static uint8_t global_mode_snapshot_buffer[1024];
  const jerry_char_t *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";

  size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p,
                                                                    strlen ((const char *) code_to_snapshot_p),
                                                                    true,
                                                                    false,
                                                                    global_mode_snapshot_buffer,
                                                                    sizeof (global_mode_snapshot_buffer));

  jerry_cleanup ();
}
```

**See also**

- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
- [jerry_exec_snapshot](#jerry_exec_snapshot)

## 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 void *snapshot_p,
                     size_t snapshot_size,
                     bool copy_bytecode);
```

- `snapshot_p` - pointer to snapshot
- `snapshot_size` - size of snapshot
- `copy_bytecode` - flag, indicating whether the passed snapshot buffer should be copied to the
   engine's memory. If set the engine should not reference the buffer after the function returns
   (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not
   set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup).
- return value
  - result of bytecode, if run was successful
  - thrown error, otherwise

**Example**

```c
{
  jerry_value_t res;
  static uint8_t global_mode_snapshot_buffer[1024];
  const jerry_char_t *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";

  jerry_init (JERRY_INIT_EMPTY);
  size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p,
                                                                    strlen ((const char *) code_to_snapshot_p),
                                                                    true,
                                                                    global_mode_snapshot_buffer,
                                                                    sizeof (global_mode_snapshot_buffer));
  jerry_cleanup ();

  jerry_init (JERRY_INIT_EMPTY);

  res = (jerry_exec_snapshot (global_mode_snapshot_buffer,
                              global_mode_snapshot_size,
                              false);

  jerry_cleanup ();
}
```

**See also**

- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot)


JerryScript Engine can be embedded into any application, providing the way to run JavaScript in a large range of environments - from desktops to low-memory microcontrollers.

This guide is intended to introduce you to JerryScript embedding API through creation of simple JavaScript shell.

## Step 1. Execute JavaScript from your application

```c
#include <string.h>
#include "jerry-api.h"

int
main (int argc, char *argv[])
{
  const jerry_char_t script[] = "print ('Hello, World!');";
  size_t script_size = strlen ((const char *) script);

  bool ret_value = jerry_run_simple (script, script_size, JERRY_INIT_EMPTY);

  return (ret_value ? 0 : 1);
}
```

The application will generate the following output:

```bash
Hello, World!
```

## Step 2. Split engine initialization and script execution

Here we perform the same actions, as `jerry_run_simple`, while splitting into several steps:

- engine initialization
- script code setup
- script execution
- engine cleanup

```c
#include <string.h>
#include "jerry-api.h"

int
main (int argc, char *argv[])
{
  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 (script, script_size, false);

  if (!jerry_value_has_error_flag (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 ();

  return 0;
}
```

Our code is more complex now, but it introduces possibilities to interact with JerryScript step-by-step: setup native objects, call JavaScript functions, etc.

## Step 3. Execution in 'eval'-mode

```c
#include <string.h>
#include "jerry-api.h"

int
main (int argc, char *argv[])
{
  const jerry_char_t script_1[] = "var s = 'Hello, World!';";
  const jerry_char_t script_2[] = "print (s);";

  /* Initialize engine */
  jerry_init (JERRY_INIT_EMPTY);

  jerry_value_t eval_ret;

  /* Evaluate script1 */
  eval_ret = jerry_eval (script_1,
                         strlen ((const char *) script_1),
                         false);

  /* Free JavaScript value, returned by eval */
  jerry_release_value (eval_ret);

  /* Evaluate script2 */
  eval_ret = jerry_eval (script_2,
                         strlen ((const char *) script_2),
                         false);

  /* Free JavaScript value, returned by eval */
  jerry_release_value (eval_ret);

  /* Cleanup engine */
  jerry_cleanup ();

  return 0;
}
```

This way, we execute two independent script parts in one execution environment. The first part initializes string variable, and the second outputs the variable.

## Step 4. Interaction with JavaScript environment

```c
#include <string.h>
#include "jerry-api.h"

int
main (int argc, char *argv[]) {
  const jerry_char_t str[] = "Hello, World!";
  const jerry_char_t script[] = "print (s);";

  /* Initializing JavaScript environment */
  jerry_init (JERRY_INIT_EMPTY);

  /* Getting pointer to the Global object */
  jerry_value_t global_object = jerry_get_global_object ();

  /* Constructing strings */
  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "s");
  jerry_value_t prop_value = jerry_create_string (str);

  /* Setting the string value as a property of the Global object */
  jerry_set_property (global_object, prop_name, prop_value);

  /* Releasing string values, as it is no longer necessary outside of engine */
  jerry_release_value (prop_name);
  jerry_release_value (prop_value);

  /* Releasing the Global object */
  jerry_release_value (global_object);

  /* Now starting script that would output value of just initialized field */
  jerry_value_t eval_ret = jerry_eval (script,
                                       strlen ((const char *) script),
                                       false);

  /* Free JavaScript value, returned by eval */
  jerry_release_value (eval_ret);

  /* Freeing engine */
  jerry_cleanup ();

  return 0;
}
```

The sample will also output 'Hello, World!'. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine.

## Step 5. Description of JerryScript value descriptors

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.

The following example function will output a JavaScript value:

```c
#include <stdlib.h>
#include <string.h>

#include "jerry-api.h"
#include "jerry-port.h"

static void
print_value (const jerry_value_t value)
{
  if (jerry_value_is_undefined (value))
  {
    jerry_port_console ("undefined");
  }
  else if (jerry_value_is_null (value))
  {
    jerry_port_console ("null");
  }
  else if (jerry_value_is_boolean (value))
  {
    if (jerry_get_boolean_value (value))
    {
      jerry_port_console ("true");
    }
    else
    {
      jerry_port_console ("false");
    }
  }
  /* Float value */
  else if (jerry_value_is_number (value))
  {
    jerry_port_console ("number");
  }
  /* String value */
  else if (jerry_value_is_string (value))
  {
    /* Determining required buffer size */
    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);
    str_buf_p[req_sz] = '\0';

    jerry_port_console ("%s", (const char *) str_buf_p);
  }
  /* Object reference */
  else if (jerry_value_is_object (value))
  {
    jerry_port_console ("[JS object]");
  }

  jerry_port_console ("\n");
}
```

## Simple JavaScript shell

Now all building blocks, necessary to construct JavaScript shell, are ready.

Shell operation can be described with the following loop:

- read command;
- if command is 'quit'
  - exit loop;
- else
  - eval (command);
  - print result of eval;
  - loop.

```c
#include <stdlib.h>
#include <string.h>

#include "jerry-api.h"
#include "jerry-port.h"

static void print_value (const jerry_value_t);

int
main (int argc, char *argv[])
{
  bool is_done = false;

  /* Initialize engine */
  jerry_init (JERRY_INIT_EMPTY);

  while (!is_done)
  {
    char cmd[256] = {};
    char *cmd_tail = cmd;
    size_t len = 0;

    jerry_port_console ("> ");

    /* Read next command */
    while (true)
    {
      if (fread (cmd_tail, 1, 1, stdin) != 1 && len == 0)
      {
        is_done = true;
        break;
      }
      if (*cmd_tail == '\n')
      {
        break;
      }

      cmd_tail++;
      len++;
    }

    /* If the command is "quit", break the loop */
    if (!strncmp (cmd, "quit\n", strlen ("quit\n")))
    {
      break;
    }

    jerry_value_t ret_val;

    /* Evaluate entered command */
    ret_val = jerry_eval ((const jerry_char_t *) cmd,
                          len,
                          false);

    /* If command evaluated successfully, print value, returned by eval */
    if (jerry_value_has_error_flag (ret_val))
    {
      /* Evaluated JS code thrown an exception
       *  and didn't handle it with try-catch-finally */
      jerry_port_console ("Unhandled JS exception occured: ");
    }

    print_value (ret_val);
    jerry_release_value (ret_val);
  }

  /* Cleanup engine */
  jerry_cleanup ();

  return 0;
}
```

The application inputs commands and evaluates them, one after another.

## Step 6. Creating JS object in global context

In this example we demonstrate how to use native function and structures in JavaScript.

```c
#include <string.h>
#include "jerry-api.h"

struct my_struct
{
  const char *msg;
} my_struct;

/**
 * Get a string from a native object
 */
static jerry_value_t
get_msg_handler (const jerry_value_t func_value, /**< function object */
                 const jerry_value_t this_value, /**< this arg */
                 const jerry_value_t *args_p, /**< function arguments */
                 const jerry_length_t args_cnt) /**< number of function arguments */
{
  return jerry_create_string ((const jerry_char_t *) my_struct.msg);
} /* get_msg_handler */

int
main (int argc, char *argv[])
{
  /* Initialize engine */
  jerry_init (JERRY_INIT_EMPTY);

  /* Do something with the native object */
  my_struct.msg = "Hello World";

  /* Create an empty JS object */
  jerry_value_t object = jerry_create_object ();

  /* Create a JS function object and wrap into a jerry value */
  jerry_value_t func_obj = jerry_create_external_function (get_msg_handler);

  /* Set the native function as a property of the empty JS object */
  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "myFunc");
  jerry_set_property (object, prop_name, func_obj);
  jerry_release_value (prop_name);
  jerry_release_value (func_obj);

  /* Wrap the JS object (not empty anymore) into a jerry api value */
  jerry_value_t global_object = jerry_get_global_object ();

  /* Add the JS object to the global context */
  prop_name = jerry_create_string ((const jerry_char_t *) "MyObject");
  jerry_set_property (global_object, prop_name, object);
  jerry_release_value (prop_name);
  jerry_release_value (object);
  jerry_release_value (global_object);

  /* Now we have a "builtin" object called MyObject with a function called myFunc()
   *
   * Equivalent JS code:
   *                    var MyObject = { myFunc : function () { return "some string value"; } }
   */
  const jerry_char_t script[] = " \
    var str = MyObject.myFunc (); \
    print (str); \
  ";
  size_t script_size = strlen ((const char *) script);

  /* Evaluate script */
  jerry_value_t eval_ret = jerry_eval (script, script_size, false);

  /* Free JavaScript value, returned by eval */
  jerry_release_value (eval_ret);

  /* Cleanup engine */
  jerry_cleanup ();

  return 0;
}
```

The application will generate the following output:

```bash
Hello World
```

## Step 7. Extending JS Objects with native functions

Here we create a JS Object with `jerry_eval`, then extend it with a native function. This function shows how to get a property value from the object and how to manipulate it.

```c
#include <string.h>
#include "jerry-api.h"

/**
 * Add param to 'this.x'
 */
static jerry_value_t
add_handler (const jerry_value_t func_value, /**< function object */
             const jerry_value_t this_val, /**< this arg */
             const jerry_value_t *args_p, /**< function arguments */
             const jerry_length_t args_cnt) /**< number of function arguments */
{
  /* Get 'this.x' */
  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "x");
  jerry_value_t x_val = jerry_get_property (this_val, prop_name);

  if (!jerry_value_has_error_flag (x_val))
  {
    /* Convert Jerry API values to double */
    double x = jerry_get_number_value (x_val);
    double d = jerry_get_number_value (*args_p);

    /* Add the parameter to 'x' */
    jerry_value_t res_val = jerry_create_number (x + d);

    /* Set the new value of 'this.x' */
    jerry_set_property (this_val, prop_name, res_val);
    jerry_release_value (res_val);
  }

  jerry_release_value (x_val);
  jerry_release_value (prop_name);

  return jerry_create_undefined ();
} /* add_handler */

int
main (int argc, char *argv[])
{
  /* Initialize engine */
  jerry_init (JERRY_INIT_EMPTY);

  /* Create a JS object */
  const jerry_char_t my_js_object[] = " \
    MyObject = \
    { x : 12, \
      y : 'Value of x is ', \
      foo: function () \
      { \
        return this.y + this.x; \
      } \
    } \
  ";

  jerry_value_t my_js_obj_val;

  /* Evaluate script */
  my_js_obj_val = jerry_eval (my_js_object,
                              strlen ((const char *) my_js_object),
                              false);

  /* Create a JS function object and wrap into a jerry value */
  jerry_value_t add_func_obj = jerry_create_external_function (add_handler);

  /* Set the native function as a property of previously created MyObject */
  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "add2x");
  jerry_set_property (my_js_obj_val, prop_name, add_func_obj);
  jerry_release_value (add_func_obj);
  jerry_release_value (prop_name);

  /* Free JavaScript value, returned by eval (my_js_object) */
  jerry_release_value (my_js_obj_val);

  const jerry_char_t script[] = " \
    var str = MyObject.foo (); \
    print (str); \
    MyObject.add2x (5); \
    print (MyObject.foo ()); \
  ";
  size_t script_size = strlen ((const char *) script);

  /* Evaluate script */
  jerry_value_t eval_ret = jerry_eval (script, script_size, false);

  /* Free JavaScript value, returned by eval */
  jerry_release_value (eval_ret);

  /* Cleanup engine */
  jerry_cleanup ();

  return 0;
}
```

The application will generate the following output:

```bash
Value of x is 12
Value of x is 17
```

## Further steps

For further API description, please visit [API Reference page](https://samsung.github.io/jerryscript/api-reference/) on [JerryScript home page](https://samsung.github.io/jerryscript/).

This is the latest version of the internal repository from Pebble Technology providing the software to run on Pebble watches. Proprietary source code has been removed from this repository and it will not compile as-is. This is for information only.


# High-Level Design
![High-Level Design](img/engines_high_level_design.png)

The diagram above shows the interactions between the major components of JerryScript: Parser and Virtual Machine (VM). Parser performs translation of input ECMAScript application into the byte-code with the specified format (refer to [Bytecode](#byte-code) and [Parser](#parser) page for details). Prepared bytecode is executed by the Virtual Machine that performs interpretation (refer to [Virtual Machine](#virtual-machine) and [ECMA](#ecma) pages for details).

# Parser

The parser is implemented as a recursive descent parser. The parser converts the JavaScript source code directly into byte-code without building an Abstract Syntax Tree. The parser depends on the following subcomponents.

## Lexer

The lexer splits input string (ECMAScript program) into sequence of tokens. It is able to scan the input string not only forward, but it is possible to move to an arbitrary position. The token structure described by structure `lexer_token_t` in `./jerry-core/parser/js/js-lexer.h`.

## Scanner

Scanner (`./jerry-core/parser/js/js-parser-scanner.c`) pre-scans the input string to find certain tokens. For example, scanner determines whether the keyword `for` defines a general for or a for-in loop. Reading tokens in a while loop is not enough because a slash (`/`) can indicate the start of a regular expression or can be a division operator.

## Expression Parser

Expression parser is responsible for parsing JavaScript expressions. It is implemented in `./jerry-core/parser/js/js-parser-expr.c`.

## Statement Parser

JavaScript statements are parsed by this component. It uses the [Expression parser](#expression-parser) to parse the constituent expressions. The implementation of Statement parser is located in `./jerry-core/parser/js/js-parser-statm.c`.

Function `parser_parse_source` carries out the parsing and compiling of the input EcmaScript source code. When a function appears in the source `parser_parse_source` calls `parser_parse_function` which is responsible for processing the source code of functions recursively including argument parsing and context handling. After the parsing, function `parser_post_processing` dumps the created opcodes and returns an `ecma_compiled_code_t*` that points to the compiled bytecode sequence.

The interactions between the major components shown on the following figure.

![Parser dependency](img/parser_dependency.png)

# Byte-code

This section describes the compact byte-code (CBC) byte-code representation. The key focus is reducing memory consumption of the byte-code representation without sacrificing considerable performance. Other byte-code representations often focus on performance only so inventing this representation is an original research.

CBC is a CISC like instruction set which assigns shorter instructions for frequent operations. Many instructions represent multiple atomic tasks which reduces the byte code size. This technique is basically a data compression method.

## Compiled Code Format

The memory layout of the compiled byte code is the following.

![CBC layout](img/CBC_layout.png)

The header is a `cbc_compiled_code` structure with several fields. These fields contain the key properties of the compiled code.

The literals part is an array of ecma values. These values can contain any EcmaScript value types, e.g. strings, numbers, function and regexp templates. The number of literals is stored in the `literal_end` field of the header.

CBC instruction list is a sequence of byte code instructions which represents the compiled code.

## Byte-code Format

The memory layout of a byte-code is the following:

![byte-code layout](img/opcode_layout.png)

Each byte-code starts with an opcode. The opcode is one byte long for frequent and two byte long for rare instructions. The first byte of the rare instructions is always zero (`CBC_EXT_OPCODE`), and the second byte represents the extended opcode. The name of common and rare instructions start with `CBC_` and `CBC_EXT_` prefix respectively.

The maximum number of opcodes is 511, since 255 common (zero value excluded) and 256 rare instructions can be defined. Currently around 230 frequent and 120 rare instructions are available.

There are three types of bytecode arguments in CBC:

 * __byte argument__: A value between 0 and 255, which often represents the argument count of call like opcodes (function call, new, eval, etc.).

 * __literal argument__: An integer index which is greater or equal than zero and less than the `literal_end` field of the header. For further information see next section Literals (next).

 * __relative branch__: An 1-3 byte long offset. The branch argument might also represent the end of an instruction range. For example the branch argument of `CBC_EXT_WITH_CREATE_CONTEXT` shows the end of a `with` statement. More precisely the position after the last instruction.

Argument combinations are limited to the following seven forms:

* no arguments
* a literal argument
* a byte argument
* a branch argument
* a byte and a literal arguments
* two literal arguments
* three literal arguments

## Literals

Literals are organized into groups whose represent various literal types. Having these groups consuming less space than assigning flag bits to each literal.
(In the followings, the mentioned ranges represent those indicies which are greater than or equal to the left side and less than the right side of the range. For example a range between `ident_end` and `literal_end` fields of the byte-code header contains those indicies, which are greater than or equal to `ident_end`
and less than `literal_end`. If `ident_end` equals to `literal_end` the range is empty.)

The two major group of literals are _identifiers_ and _values_.

  * __identifier__: A named reference to a variable. Literals between zero and `ident_end` of the header belongs to here. All of these literals must be a string or undefined. Undefined can only be used for those literals which cannot be accessed by a literal name. For example `function (arg,arg)` has two arguments, but the `arg` identifier only refers to the second argument. In such cases the name of the first argument is undefined. Furthermore optimizations such as *CSE* may also introduce literals without name.

  * __value__: A reference to an immediate value. Literals between `ident_end` and `const_literal_end` are constant values such as numbers or strings. These literals can be used directly by the Virtual Machine. Literals between `const_literal_end` and `literal_end` are template literals. A new object needs to be constructed each time when their value is accessed. These literals are functions and regular expressions.

There are two other sub-groups of identifiers. *Registers* are those identifiers which are stored in the function call stack. *Arguments* are those registers which are passed by a caller function.

There are two types of literal encoding in CBC. Both are variable length, where the length is one or two byte long.

  * __small__: maximum 511 literals can be encoded.

One byte encoding for literals 0 - 254.

```c
byte[0] = literal_index
```

Two byte encoding for literals 255 - 510.

```c
byte[0] = 0xff
byte[1] = literal_index - 0xff
```

  * __full__: maximum 32767 literal can be encoded.

One byte encoding for literals 0 - 127.

```c
byte[0] = literal_index
```

Two byte encoding for literals 128 - 32767.

```c
byte[0] = (literal_index >> 8) | 0x80
byte[1] = (literal_index & 0xff)
```

Since most functions require less than 255 literal, small encoding provides a single byte literal index for all literals. Small encoding consumes less space than full encoding, but it has a limited range.

## Literal Store

JerryScript does not have a global string table for literals, but stores them into the Literal Store. During the parsing phase, when a new literal appears with the same identifier that has already occurred before, the string won't be stored once again, but the identifier in the Literal Store will be used. If a new literal is not in the Literal Store yet, it will be inserted.

## Byte-code Categories

Byte-codes can be placed into four main categories.

### Push Byte-codes

Byte-codes of this category serve for placing objects onto the stack. As there are many instructions representing multiple atomic tasks in CBC, there are also many instructions for pushing objects onto the stack according to the number and the type of the arguments. The following table list a few of these opcodes with a brief description.

| byte-code             | description                                          |
| --------------------- | ---------------------------------------------------- |
| CBC_PUSH_LITERAL      | Pushes the value of the given literal argument.      |
| CBC_PUSH_TWO_LITERALS | Pushes the value of the given two literal arguments. |
| CBC_PUSH_UNDEFINED    | Pushes an undefined value.                           |
| CBC_PUSH_TRUE         | Pushes a logical true.                               |
| CBC_PUSH_PROP_LITERAL | Pushes a property whose base object is popped from the stack, and the property name is passed as a literal argument. |

### Call Byte-codes

The byte-codes of this category perform calls in different ways.

| byte-code             | description                                                                          |
| --------------------- | ------------------------------------------------------------------------------------ |
| CBC_CALL0             | Calls a function without arguments. The return value won't be pushed onto the stack. |
| CBC_CALL1             | Calls a function with one argument. The return value won't be pushed onto the stack. |
| CBC_CALL              | Calls a function with n arguments. n is passed as a byte argument. The return value won't be pushed onto the stack. |
| CBC_CALL0_PUSH_RESULT | Calls a function without arguments. The return value will be pushed onto the stack.  |
| CBC_CALL1_PUSH_RESULT | Calls a function with one argument. The return value will be pushed onto the stack.  |
| CBC_CALL2_PROP        | Calls a property function with two arguments. The base object, the property name, and the two arguments are on the stack. |

### Arithmetic, Logical, Bitwise and Assignment Byte-codes

The opcodes of this category perform arithmetic, logical, bitwise and assignment operations.

| byte-code               | description                                                                                |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| CBC_LOGICAL_NOT         | Negates the logical value that popped from the stack. The result is pushed onto the stack.          |
| CBC_LOGICAL_NOT_LITERAL | Negates the logical value that given in literal argument. The result is pushed onto the stack.      |
| CBC_ADD                 | Adds two values that are popped from the stack. The result is pushed onto the stack.                |
| CBC_ADD_RIGHT_LITERAL   | Adds two values. The left one popped from the stack, the right one is given as literal argument.    |
| CBC_ADD_TWO_LITERALS    | Adds two values. Both are given as literal arguments.                                               |
| CBC_ASSIGN              | Assigns a value to a property. It has three arguments: base object, property name, value to assign. |
| CBC_ASSIGN_PUSH_RESULT  | Assigns a value to a property. It has three arguments: base object, property name, value to assign. The result will be pushed onto the stack. |

### Branch Byte-codes

Branch byte-codes are used to perform conditional and unconditional jumps in the byte-code. The arguments of these instructions are 1-3 byte long relative offsets. The number of bytes is part of the opcode, so each byte-code with a branch argument has three forms. The direction (forward, backward) is also defined by the opcode since the offset is an unsigned value. Thus, certain branch instructions has six forms. Some examples can be found in the following table.

| byte-code                  | description                                                 |
| -------------------------- | ----------------------------------------------------------- |
| CBC_JUMP_FORWARD           | Jumps forward by the 1 byte long relative offset argument.  |
| CBC_JUMP_FORWARD_2         | Jumps forward by the 2 byte long relative offset argument.  |
| CBC_JUMP_FORWARD_3         | Jumps forward by the 3 byte long relative offset argument.  |
| CBC_JUMP_BACKWARD          | Jumps backward by the 1 byte long relative offset argument. |
| CBC_JUMP_BACKWARD_2        | Jumps backward by the 2 byte long relative offset argument. |
| CBC_JUMP_BACKWARD_3        | Jumps backward by the 3 byte long relative offset argument. |
| CBC_BRANCH_IF_TRUE_FORWARD | Jumps if the value on the top of the stack is true by the 1 byte long relative offset argument. |

## Snapshot

The compiled byte-code can be saved into a snapshot, which also can be loaded back for execution. Directly executing the snapshot saves the costs of parsing the source in terms of memory consumption and performance. The snapshot can also be executed from ROM, in which case the overhead of loading it into the memory can also be saved.

# Virtual Machine

Virtual machine is an interpreter which executes byte-code instructions one by one. The function that starts the interpretation is `vm_run` in `./jerry-core/vm/vm.c`. `vm_loop` is the main loop of the virtual machine, which has the peculiarity that it is *non-recursive*. This means that in case of function calls it does not calls itself recursively but returns, which has the benefit that it does not burdens the stack as a recursive implementation.

# ECMA

ECMA component of the engine is responsible for the following notions:

* Data representation
* Runtime representation
* Garbage collection (GC)

## Data Representation

The major structure for data representation is `ECMA_value`. The lower two bits of this structure encode value tag, which determines the type of the value:

* simple
* number
* string
* object

![ECMA value representation](img/ecma_value.png)

In case of number, string and object the value contains an encoded pointer, and
simple value is a pre-defined constant which can be:

* undefined
* null
* true
* false
* empty (uninitialized value)

### Compressed Pointers

Compressed pointers were introduced to save heap space.

![Compressed Pointer](img/ecma_compressed.png)

These pointers are 8 byte aligned 16 bit long pointers which can address 512 Kb of
memory which is also the maximum size of the JerryScript heap. To support even more
memory the size of compressed pointers can be extended to 32 bit to cover the entire
address space of a 32 bit system by passing "--cpointer_32_bit on" to the build
system. These "uncompressed pointers" increases the memory consumption by around 20%.

### Number

There are two possible representation of numbers according to standard IEEE 754:
The default is 8-byte (double),
but the engine supports the 4-byte (single precision) representation by setting CONFIG_ECMA_NUMBER_TYPE as well.

![Number](img/number.png)

Several references to single allocated number are not supported. Each reference holds its own copy of a number.

### String

Strings in JerryScript are not just character sequences, but can hold numbers and so-called magic ids too. For common character sequences there is a table in the read only memory that contains magic id and character sequence pairs. If a string is already in this table, the magic id of its string is stored, not the character sequence itself. Using numbers speeds up the property access. These techniques save memory.

### Object / Lexical Environment

An object can be a conventional data object or a lexical environment object. Unlike other data types, object can have references (called properties) to other data types. Because of circular references, reference counting is not always enough to determine dead objects. Hence a chain list is formed from all existing objects, which can be used to find unreferenced objects during garbage collection. The `gc-next` pointer of each object shows the next allocated object in the chain list.

[Lexical environments](http://www.ecma-international.org/ecma-262/5.1/#sec-10.2) are implemented as objects in JerryScript, since lexical environments contains key-value pairs (called bindings) like objects. This simplifies the implementation and reduces code size.

![Object/Lexicat environment structures](img/ecma_object.png)

The objects are represented as following structure:

  * Reference counter - number of hard (non-property) references
  * Next object pointer for the garbage collector
  * GC's visited flag
  * type (function object, lexical environment, etc.)

### Properties of Objects

![Object properties](img/ecma_object_property.png)

Objects have a linked list that contains their properties. This list actually contains property pairs, in order to save memory described in the followings:
A property is 7 bit long and its type field is 2 bit long which consumes 9 bit which does not fit into 1 byte but consumes 2 bytes. Hence, placing together two properties (14 bit) with the 2 bit long type field fits into 2 bytes.

#### Property Hashmap

If the number of property pairs reach a limit (currently this limit is defined to 16), a hash map (called [Property Hashmap](#property-hashmap)) is inserted at the first position of the property pair list, in order to find a property using it, instead of finding it by iterating linearly over the property pairs.

Property hashmap contains 2n elements, where 2n is larger than the number of properties of the object. Each element can have tree types of value:

* null, indicating an empty element
* deleted, indicating a deleted property, or
* reference to the existing property

This hashmap is a must-return type cache, meaning that every property that the object have, can be found using it.

#### Internal Properties

Internal properties are special properties that carry meta-information that cannot be accessed by the JavaScript code, but important for the engine itself. Some examples of internal properties are listed below:

* [[Class]] - class (type) of the object (ECMA-defined)
* [[Code]] - points where to find bytecode of the function
* native code - points where to find the code of a native function
* [[PrimitiveValue]] for Boolean - stores the boolean value of a Boolean object
* [[PrimitiveValue]] for Number - stores the numeric value of a Number object

### LCache

LCache is a hashmap for finding a property specified by an object and by a property name. The object-name-property layout of the LCache presents multiple times in a row as it is shown in the figure below.

![LCache](img/ecma_lcache.png)

When a property access occurs, a hash value is extracted from the demanded property name and than this hash is used to index the LCache. After that, in the indexed row the specified object and property name will be searched.

It is important to note, that if the specified property is not found in the LCache, it does not mean that it does not exist (i.e. LCache is a may-return cache). If the property is not found, it will be searched in the property-list of the object, and if it is found there, the property will be placed into the LCache.

### Collections

Collections are array-like data structures, which are optimized to save memory. Actually, a collection is a linked list whose elements are not single elements, but arrays which can contain multiple elements.

### Exception Handling

In order to implement a sense of exception handling, the return values of JerryScript functions are able to indicate their faulty or "exceptional" operation. The return values are actually ECMA values (see section [Data Representation](#data-representation)) in which the error bit is set if an erroneous operation is occurred.

### Value Management and Ownership

Every ECMA value stored by the engine is associated with a virtual "ownership", that defines how to manage the value: when to free it when it is not needed anymore and how to pass the value to an other function.

Initially, value is allocated by its owner (i.e. with ownership). The owner has the responsibility for freeing the allocated value. When the value is passed to a function as an argument, the ownership of it will not pass, the called function have to make an own copy of the value. However, as long as a function returns a value, the ownership will pass, thus the caller will be responsible for freeing it.


# Reference

## Termination

It is questionable whether a library should be able to terminate an application. Any API function can signal an error (ex.: cannot allocate memory), so the engine use the termination approach with this port function.

```c
/**
 * Signal the port that jerry experienced a fatal failure from which it cannot
 * recover.
 *
 * @param code gives the cause of the error.
 *
 * Note: jerry expects the function not to return.
 *
 * Example: a libc-based port may implement this with exit() or abort(), or both.
 */
void jerry_port_fatal (jerry_fatal_code_t code);
```

Error codes

```c
typedef enum
{
  ERR_OUT_OF_MEMORY = 10,
  ERR_SYSCALL = 11,
  ERR_REF_COUNT_LIMIT = 12,
  ERR_FAILED_INTERNAL_ASSERTION = 120
} jerry_fatal_code_t;
```

## I/O

These are the only I/O functions jerry calls.

```c
/**
 * Print a string to the console. The function should implement a printf-like
 * interface, where the first argument specifies a format string on how to
 * stringify the rest of the parameter list.
 *
 * This function is only called with strings coming from the executed ECMAScript
 * wanting to print something as the result of its normal operation.
 *
 * It should be the port that decides what a "console" is.
 *
 * Example: a libc-based port may implement this with vprintf().
 */
void jerry_port_console (const char *fmt, ...);

/**
 * Jerry log levels. The levels are in severity order
 * where the most serious levels come first.
 */
typedef enum
{
  JERRY_LOG_LEVEL_ERROR,    /**< the engine will terminate after the message is printed */
  JERRY_LOG_LEVEL_WARNING,  /**< a request is aborted, but the engine continues its operation */
  JERRY_LOG_LEVEL_DEBUG,    /**< debug messages from the engine, low volume */
  JERRY_LOG_LEVEL_TRACE     /**< detailed info about engine internals, potentially high volume */
} jerry_log_level_t;

/**
 * Display or log a debug/error message. The function should implement a printf-like
 * interface, where the first argument specifies the log level
 * and the second argument specifies a format string on how to stringify the rest
 * of the parameter list.
 *
 * This function is only called with messages coming from the jerry engine as
 * the result of some abnormal operation or describing its internal operations
 * (e.g., data structure dumps or tracing info).
 *
 * It should be the port that decides whether error and debug messages are logged to
 * the console, or saved to a database or to a file.
 *
 * Example: a libc-based port may implement this with vfprintf(stderr) or
 * vfprintf(logfile), or both, depending on log level.
 */
void jerry_port_log (jerry_log_level_t level, const char *fmt, ...);
```

## Date

```c
/**
 * Jerry time zone structure
 */
typedef struct
{
  int offset;                /**< minutes from west */
  int daylight_saving_time;  /**< daylight saving time (1 - DST applies, 0 - not on DST) */
} jerry_time_zone_t;

/**
 * Get timezone and daylight saving data
 *
 * @return true  - if success
 *         false - otherwise
 */
bool jerry_port_get_time_zone (jerry_time_zone_t *);

/**
 * Get system time
 *
 * @return milliseconds since Unix epoch
 */
double jerry_port_get_current_time (void);
```

# How to port JerryScript

This section describes a basic port implementation which was created for Unix based systems.

## Termination

```c
#include <stdlib.h>
#include "jerry-port.h"

/**
 * Default implementation of jerry_port_fatal.
 */
void jerry_port_fatal (jerry_fatal_code_t code)
{
  exit (code);
} /* jerry_port_fatal */
```

## I/O

```c
#include <stdarg.h>
#include "jerry-port.h"

/**
 * Provide console message implementation for the engine.
 */
void
jerry_port_console (const char *format, /**< format string */
                    ...) /**< parameters */
{
  va_list args;
  va_start (args, format);
  vfprintf (stdout, format, args);
  va_end (args);
} /* jerry_port_console */

/**
 * Provide log message implementation for the engine.
 *
 * Note:
 *      This example ignores the log level.
 */
void
jerry_port_log (jerry_log_level_t level, /**< log level */
                const char *format, /**< format string */
                ...)  /**< parameters */
{
  va_list args;
  va_start (args, format);
  vfprintf (stderr, format, args);
  va_end (args);
} /* jerry_port_log */
```

## Date

```c
#include <sys/time.h>
#include "jerry-port.h"

/**
 * Default implementation of jerry_port_get_time_zone.
 */
bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p)
{
  struct timeval tv;
  struct timezone tz;

  /* gettimeofday may not fill tz, so zero-initializing */
  tz.tz_minuteswest = 0;
  tz.tz_dsttime = 0;

  if (gettimeofday (&tv, &tz) != 0)
  {
    return false;
  }

  tz_p->offset = tz.tz_minuteswest;
  tz_p->daylight_saving_time = tz.tz_dsttime > 0 ? 1 : 0;

  return true;
} /* jerry_port_get_time_zone */

/**
 * Default implementation of jerry_port_get_current_time.
 */
double jerry_port_get_current_time ()
{
  struct timeval tv;

  if (gettimeofday (&tv, NULL) != 0)
  {
    return 0;
  }

  return ((double) tv.tv_sec) * 1000.0 + ((double) tv.tv_usec) / 1000.0;
} /* jerry_port_get_current_time */
```