Skip to content

Update the webpage #2765

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 20, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
290 changes: 289 additions & 1 deletion 02.API-REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ Enum that contains JerryScript API value types:
- JERRY_TYPE_OBJECT - object type
- JERRY_TYPE_FUNCTION - function type
- JERRY_TYPE_ERROR - error/abort type
- JERRY_TYPE_SYMBOL - symbol type

## jerry_error_t

Expand Down Expand Up @@ -71,6 +72,7 @@ Possible compile time enabled feature types:
- JERRY_FEATURE_REGEXP - RegExp support
- JERRY_FEATURE_LINE_INFO - line info available
- JERRY_FEATURE_LOGGING - logging
- JERRY_FEATURE_SYMBOL - symbol support

## jerry_regexp_flags_t

Expand Down Expand Up @@ -286,6 +288,19 @@ An opaque declaration of the JerryScript context structure.
typedef struct jerry_context_t jerry_context_t;
```


## jerry_binary_operation_t

Enum that contains the supported binary operation types
- JERRY_BIN_OP_EQUAL - equal comparison (==)
- JERRY_BIN_OP_STRICT_EQUAL - strict equal comparison (===)
- JERRY_BIN_OP_LESS - less relation (<)
- JERRY_BIN_OP_LESS_EQUAL - less or equal relation (<=)
- JERRY_BIN_OP_GREATER - greater relation (>)
- JERRY_BIN_OP_GREATER_EQUAL - greater or equal relation (>=)
- JERRY_BIN_OP_INSTANCEOF - instanceof operation


## jerry_property_descriptor_t

**Summary**
Expand Down Expand Up @@ -1090,6 +1105,7 @@ jerry_get_global_object (void);
- [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)).
Expand Down Expand Up @@ -1563,6 +1579,57 @@ jerry_value_is_string (const jerry_value_t value)
- [jerry_release_value](#jerry_release_value)


## jerry_value_is_symbol

**Summary**

Returns whether the given `jerry_value_t` is a symbol value.

**Prototype**

```c
bool
jerry_value_is_symbol (const jerry_value_t value)
```

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

**Example**

[doctest]: # ()

```c
#include "jerryscript.h"

int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);

jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "Symbol description string");
jerry_value_t symbol_value = jerry_create_symbol (string_value);

jerry_release_value (string_value);

if (jerry_value_is_symbol (symbol_value))
{
// usage of symbol_value
}

jerry_release_value (symbol_value);

jerry_cleanup ();
}
```

**See also**

- [jerry_release_value](#jerry_release_value)


## jerry_value_is_typedarray

**Summary**
Expand Down Expand Up @@ -1671,7 +1738,7 @@ jerry_value_get_type (const jerry_value_t value);
...
}

jerry_value_release (number);
jerry_release_value (number);
}
```

Expand Down Expand Up @@ -1711,6 +1778,122 @@ jerry_is_feature_enabled (const jerry_feature_t feature);
}
```

**See also**
- [jerry_feature_t](#jerry_feature_t)


# Binary operations

## jerry_binary_operation

**Summary**

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

**Prototype**

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

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

**Example - JERRY_BIN_OP_EQUAL**

```c
{
jerry_value_t value1;
jerry_value_t value2;
... // create or acquire value
jerry_value_t result = jerry_binary_operation (JERRY_BIN_OP_EQUAL, value1, value2)

if (!jerry_value_is_error (result))
{
if (jerry_get_boolean_value (result))
{
// value1 and value2 are equal
}
else
{
// value1 and value2 are NOT equal
}
}
else
{
... // handle error
}

jerry_release_value (value1);
jerry_release_value (value2);
jerry_release_value (result);
}
```

**Example - JERRY_BIN_OP_INSTANCEOF**

[doctest]: # ()

```c
#include "jerryscript.h"

static jerry_value_t
my_constructor (const jerry_value_t func_val,
const jerry_value_t this_val,
const jerry_value_t argv[],
const jerry_length_t argc)
{
return jerry_create_undefined ();
}

int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);

jerry_value_t base_obj = jerry_create_object ();
jerry_value_t constructor = jerry_create_external_function (my_constructor);

/* External functions does not have a prototype by default, so we need to create one */
jerry_value_t prototype_str = jerry_create_string ((const jerry_char_t *) ("prototype"));
jerry_release_value (jerry_set_property (constructor, prototype_str, base_obj));
jerry_release_value (prototype_str);

/* Construct the instance. */
jerry_value_t instance_val = jerry_construct_object (constructor, NULL, 0);

/* Call the API function of 'instanceof'. */
jerry_value_t is_instance = jerry_binary_operation (JERRY_BIN_OP_INSTANCEOF,
instance_val,
constructor);
if (!jerry_value_is_error (is_instance)
&& jerry_get_boolean_value (is_instance) == true)
{
/* ... */
}

/* Free all of the jerry values and cleanup the engine. */
jerry_release_value (base_obj);
jerry_release_value (constructor);
jerry_release_value (instance_val);
jerry_release_value (is_instance);

jerry_cleanup ();
return 0;
}
```

**See also**
- [jerry_binary_operation_t](#jerry_binary_operation_t)


# Error manipulation functions

## jerry_create_abort_from_value
Expand Down Expand Up @@ -2701,6 +2884,59 @@ jerry_resolve_or_reject_promise (jerry_value_t promise,
- [jerry_release_value](#jerry_release_value)
- [jerry_value_is_error](#jerry_value_is_error)

# Functions for symbols

These APIs all depend on the ES2015-subset profile.

## jerry_get_symbol_descriptive_string

**Summary**

Call the SymbolDescriptiveString 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_get_symbol_descriptive_string (const jerry_value_t value);
```

- `value` - symbol value
- return value
- string value containing the symbol's descriptive string - if success
- thrown error, otherwise

**Example**

[doctest]: # ()

```c
#include "jerryscript.h"

int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);

jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "foo");
jerry_value_t symbol_value = jerry_create_symbol (string_value);

jerry_release_value (string_value);

jerry_value_t symbol_desc_string = jerry_get_symbol_descriptive_string (symbol_value);

// usage of symbol_desc_string

jerry_release_value (symbol_desc_string);
jerry_release_value (symbol_value);

jerry_cleanup ();
}
```


# Acquire and release API values

Expand Down Expand Up @@ -3426,6 +3662,58 @@ jerry_create_string_sz (const jerry_char_t *str_p,
- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)


## jerry_create_symbol

**Summary**

Create symbol from an API value.

*Note*: The given argument is converted to string. This operation can throw an error.

**Prototype**

```c
jerry_value_t
jerry_create_symbol (const jerry_value_t value)
```

- `value` - API value
- return value
- value of the created symbol, if success
- thrown error, otherwise

**Example**

[doctest]: # ()

```c
#include "jerryscript.h"

int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);

jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "Symbol description string");
jerry_value_t symbol_value = jerry_create_symbol (string_value);

// The description value is no longer needed
jerry_release_value (string_value);

// usage of symbol_value

jerry_release_value (symbol_value);

jerry_cleanup ();
}
```

**See also**

- [jerry_value_is_symbol](#jerry_value_is_symbol)
- [jerry_release_value](#jerry_release_value)


## jerry_create_regexp

**Summary**
Expand Down
28 changes: 27 additions & 1 deletion 09.EXT-REFERENCE-ARG.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ typedef struct

**Summary**

The structure is used in `jerryx_arg_array`. It provides the array items' corresponding
The structure is used in `jerryx_arg_array`. It provides the array items' corresponding
JS-to-C mappings and count.

**Prototype**
Expand Down Expand Up @@ -823,6 +823,32 @@ jerryx_arg_js_iterator_peek (jerryx_arg_js_iterator_t *js_arg_iter_p)
- return value - the current `jerry_value_t` argument.
- `js_arg_iter_p` - the JS arg iterator from which to peek.

## jerryx_arg_js_iterator_restore

**Summary**

Restore the last item popped from the stack. This can be called as
many times as there are arguments on the stack -- if called when the
first element in the array is the current top of the stack, this
function does nothing.

*Note:* This function relies on the underlying implementation of the
arg stack as an array, as its function is to simply back up the "top
of stack" pointer to point to the previous element of the array.

*Note:* Like `jerryx_arg_js_iterator_pop ()`, this function will
change the `js_arg_idx` and `js_arg_p` values in the iterator.

**Prototype**

```c
jerry_value_t
jerryx_arg_js_iterator_restore (jerryx_arg_js_iterator_t *js_arg_iter_p)
```
- return value - the the new top of the stack.
- `js_arg_iter_p` - the JS arg iterator to restore.


## jerryx_arg_js_iterator_index

**Summary**
Expand Down