archive-gh-me/jerryscript
1
0
Fork 0
mirror of https://github.com/jerryscript-project/jerryscript.git synced 2025-12-15 16:29:21 +00:00
Code Issues Projects Releases Wiki Activity

Updated the API reference (#2828)

Browse Source 
Fixed style issues, fixed inaccurate descriptions and added missing information.

JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com
This commit is contained in:
László Langó 2019-04-17 11:45:33 +02:00 committed by GitHub
parent 5c72d995e4
commit bc9efb07a5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 167 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

209
docs/02.API-REFERENCE.md
View File

@ -189,6 +189,9 @@ that indicates whether is an error or not. Every type has an error flag not only
be cleared before the value is passed as an argument, otherwise it can lead to a type error. The error objects
created by API functions has the error flag set.
Returned and created values by the API functions must be freed with
[jerry_release_value](#jerry_release_value) when they are no longer needed.
**Prototype**
```c
@ -930,7 +933,10 @@ jerry_parse_function (const jerry_char_t *resource_name_p, /**< resource name (u
Run an EcmaScript function created by `jerry_parse`.
*Note*: The code should be previously parsed with `jerry_parse`.
*Note*:
- The code should be previously parsed with `jerry_parse`.
- Returned value must be freed with [jerry_release_value](#jerry_release_value)
when it is no longer needed.
**Prototype**
@ -988,7 +994,10 @@ main (void)
**Summary**
Perform JavaScript `eval`.
Perform JavaScript `eval` function call (ECMA-262 v5.1 sec-15.1.2.1).
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
@ -1025,6 +1034,9 @@ jerry_eval (const jerry_char_t *source_p,
Run enqueued Promise jobs until the first thrown error or until all get executed.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -1186,6 +1198,8 @@ jerry_value_is_array (const jerry_value_t value)
Returns whether the given `jerry_value_t` is an ArrayBuffer object.
*Note*: This API depends on the ES2015-subset profile.
**Prototype**
```c
@ -1303,6 +1317,8 @@ jerry_value_is_constructor (const jerry_value_t value)
Returns whether the given `jerry_value_t` is a DataView object value.
*Note*: This API depends on the ES2015-subset profile.
**Prototype**
```c
@ -1628,6 +1644,8 @@ jerry_value_is_string (const jerry_value_t value)
Returns whether the given `jerry_value_t` is a symbol value.
*Note*: This API depends on the ES2015-subset profile.
**Prototype**
```c
@ -1833,6 +1851,9 @@ jerry_is_feature_enabled (const jerry_feature_t feature);
Perform binary operation on the given operands (==, ===, <, >, etc.).
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -2872,7 +2893,7 @@ jerry_value_to_string (const jerry_value_t value);
# Functions for promise objects
These APIs all depends on the ES2015-subset profile.
These APIs all depend on the ES2015-subset profile.
## jerry_resolve_or_reject_promise
@ -2880,6 +2901,9 @@ These APIs all depends on the ES2015-subset profile.
Resolve or reject the promise with an argument.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -3066,6 +3090,9 @@ is no longer needed.
Create an array object value.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -3100,6 +3127,11 @@ jerry_create_array (uint32_t size);
Create a jerry_value_t representing an ArrayBuffer object.
*Note*:
- This API depends on the ES2015-subset profile.
- Returned value must be freed with [jerry_release_value](#jerry_release_value)
when it is no longer needed.
**Prototype**
```c
@ -3141,6 +3173,11 @@ User must pass a buffer pointer which is at least `size` big.
After the object is not needed the GC will call the `free_cb`
so the user can release the buffer which was provided.
*Note*:
- This API depends on the ES2015-subset profile.
- Returned value must be freed with [jerry_release_value](#jerry_release_value)
when it is no longer needed.
**Prototype**
```c
@ -3219,10 +3256,11 @@ jerry_create_boolean (bool value);
Create new JavaScript error object.
Important! The `error_type` argument *must not be*
`JERRY_ERROR_NONE`.
Important! The `error_type` argument *must not be* `JERRY_ERROR_NONE`.
Creating an error with no error type is not valid.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
@ -3263,6 +3301,9 @@ jerry_create_error (jerry_error_t error_type,
Create new JavaScript error object.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -3303,9 +3344,10 @@ jerry_create_error_sz (jerry_error_t error_type,
Create new JavaScript DataView object.
*Note*: This API depends on the ES2015-subset profile.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
*Note*:
- This API depends on the ES2015-subset profile.
- Returned value must be freed with [jerry_release_value](#jerry_release_value)
when it is no longer needed.
**Prototype**
@ -3359,6 +3401,9 @@ main (void)
Create an external function object.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -3411,6 +3456,9 @@ handler (const jerry_value_t function_obj,
Creates a `jerry_value_t` representing a number value.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -3446,6 +3494,9 @@ jerry_create_number (double value);
Creates a `jerry_value_t` representing a positive or negative infinity value.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -3481,6 +3532,9 @@ jerry_create_number_infinity (bool sign);
Creates a `jerry_value_t` representing a not-a-number value.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -3547,6 +3601,9 @@ jerry_create_null (void);
Create new JavaScript object, like with new Object().
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -3580,7 +3637,10 @@ jerry_create_object (void);
Create an empty promise object which can be resolved or rejected later
by calling jerry_resolve_or_reject_promise.
*Note*: This API depends on the ES2015-subset profile.
*Note*:
- This API depends on the ES2015-subset profile.
- Returned value must be freed with [jerry_release_value](#jerry_release_value)
when it is no longer needed.
**Prototype**
@ -3615,6 +3675,9 @@ jerry_create_promise (void)
Create string from a valid CESU8 string.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -3650,6 +3713,9 @@ jerry_create_string (const jerry_char_t *str_p);
Create string from a valid CESU8 string.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -3690,6 +3756,8 @@ jerry_create_string_sz (const jerry_char_t *str_p,
Create string from a valid UTF8 string.
*Note*: The difference from [jerry_create_string](#jerry_create_string) is that it accepts utf-8 string instead of cesu-8 string.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
@ -3727,6 +3795,8 @@ jerry_create_string_from_utf8 (const jerry_char_t *str_p);
Create string from a valid UTF8 string.
*Note*: The difference from [jerry_create_string_sz](#jerry_create_string_sz) is that it accepts utf-8 string instead of cesu-8 string.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
@ -3767,7 +3837,11 @@ jerry_create_string_sz (const jerry_char_t *str_p,
Create symbol from an API value.
*Note*: The given argument is converted to string. This operation can throw an error.
*Note*:
- The given argument is converted to string. This operation can throw an error.
- This API depends on the ES2015-subset profile.
- Returned value must be freed with [jerry_release_value](#jerry_release_value)
when it is no longer needed.
**Prototype**
@ -3817,10 +3891,13 @@ main (void)
**Summary**
Returns a jerry_value_t RegExp object or an error, if the construction of the object fails.
Returns a `jerry_value_t` RegExp object or an error, if the construction of the object fails.
Optional flags can be set using [jerry_regexp_flags_t](#jerry_regexp_flags_t).
These flags can be combined together with the binary OR operator or used on their own as enum values.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
jerry_value_t
@ -3851,10 +3928,13 @@ jerry_create_regexp (const jerry_char_t *pattern_p, uint16_t flags);
**Summary**
Returns a jerry_value_t RegExp object or an error, if the construction of the object fails.
Returns a `jerry_value_t` RegExp object or an error, if the construction of the object fails.
Optional flags can be set using [jerry_regexp_flags_t](#jerry_regexp_flags_t).
These flags can be combined together with the binary OR operator or used on their own as enum values.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
jerry_value_t
@ -3892,6 +3972,11 @@ Create a jerry_value_t representing an TypedArray object.
For the new object the type of the TypedArray (see: [jerry_typedarray_type_t](#jerry_typedarray_type_t))
and element count can be specified.
*Note*:
- This API depends on the ES2015-subset profile.
- Returned value must be freed with [jerry_release_value](#jerry_release_value)
when it is no longer needed.
**Prototype**
```c
@ -3938,6 +4023,11 @@ type of TypedArray otherwise an error is generated.
The JavaScript equivalent of this function is: `new %TypedArray%(arraybuffer)` where `%TypedArray%` is
one of the allowed TypedArray functions.
*Note*:
- This API depends on the ES2015-subset profile.
- Returned value must be freed with [jerry_release_value](#jerry_release_value)
when it is no longer needed.
**Prototype**
```c
@ -3989,6 +4079,11 @@ type of TypedArray otherwise an error is generated.
The JavaScript equivalent of this function is: `new %TypedArray%(arraybuffer, byteOffset, length)` where `%TypedArray%` is
one of the allowed TypedArray functions.
*Note*:
- This API depends on the ES2015-subset profile.
- Returned value must be freed with [jerry_release_value](#jerry_release_value)
when it is no longer needed.
**Prototype**
```c
@ -4745,6 +4840,9 @@ jerry_construct_object (const jerry_value_t func_obj_val,
Get keys of the specified object value.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -4784,6 +4882,9 @@ jerry_get_object_keys (const jerry_value_t obj_val);
Get the prototype of the specified object.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -4823,6 +4924,9 @@ jerry_get_prototype (const jerry_value_t obj_val);
Set the prototype of the specified object.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -5081,7 +5185,7 @@ You can get them by calling jerry_get_object_native_pointer later.
**Prototype**
```c
bool
void
jerry_set_object_native_pointer (const jerry_value_t obj_val,
void *native_p,
const jerry_object_native_info_t *info_p)
@ -5166,9 +5270,10 @@ jerry_foreach_object_property (jerry_value_t obj_val,
**Example**
```c
bool foreach_function (const jerry_value_t prop_name,
const jerry_value_t prop_value,
void *user_data_p)
bool
foreach_function (const jerry_value_t prop_name,
const jerry_value_t prop_value,
void *user_data_p)
{
... // implementation of the foreach function
@ -5201,8 +5306,9 @@ Iterate over objects.
**Prototype**
```c
bool jerry_objects_foreach (jerry_objects_foreach_t foreach_p,
void *user_data_p);
bool
jerry_objects_foreach (jerry_objects_foreach_t foreach_p,
void *user_data_p);
```
- `foreach_p` - function that will be invoked for each object.
@ -5276,9 +5382,10 @@ Iterate over objects matching a certain native data type.
**Prototype**
```c
bool jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *native_info_p,
jerry_objects_foreach_by_native_info_t foreach_p,
void *user_data_p);
bool
jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *native_info_p,
jerry_objects_foreach_by_native_info_t foreach_p,
void *user_data_p);
```
- `native_info_p` - native pointer's type information.
@ -5630,6 +5737,9 @@ main (void)
Generate snapshot from the specified source code.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -5648,12 +5758,12 @@ jerry_generate_snapshot (const jerry_char_t *resource_name_p,
- `source_p` - script source, it must be a valid utf8 string.
- `source_size` - script source size, in bytes.
- `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags.
- `buffer_p` - buffer to save snapshot to.
- `buffer_p` - buffer (aligned to 4 bytes) to save snapshot to.
- `buffer_size` - the buffer's size.
- return value
- the size of the snapshot as a number value, if it was generated succesfully (i.e. there are no syntax
errors in source code, buffer size is sufficient, and snapshot support is enabled in current configuration
through JERRY_ENABLE_SNAPSHOT_SAVE)
- the size of the generated snapshot in bytes as number value, if it was generated succesfully (i.e. there
are no syntax errors in source code, buffer size is sufficient, and snapshot support is enabled in
current configuration through JERRY_ENABLE_SNAPSHOT_SAVE)
- thrown error, otherwise.
**Example**
@ -5705,6 +5815,9 @@ with the given arguments.
The function arguments and function body are
passed as separated arguments.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -5727,12 +5840,12 @@ jerry_generate_function_snapshot (const jerry_char_t *resource_name_p,
- `args_p` - function arguments, it must be a valid utf8 string.
- `args_size` - function argument size, in bytes.
- `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags.
- `buffer_p` - buffer to save snapshot to.
- `buffer_p` - buffer (aligned to 4 bytes) to save snapshot to.
- `buffer_size` - the buffer's size.
- return value
- the size of the snapshot as a number value, if it was generated succesfully (i.e. there are no syntax
errors in source code, buffer size is sufficient, and snapshot support is enabled in current configuration
through JERRY_ENABLE_SNAPSHOT_SAVE)
- the size of the generated snapshot in bytes as number value, if it was generated succesfully (i.e. there
are no syntax errors in source code, buffer size is sufficient, and snapshot support is enabled in
current configuration through JERRY_ENABLE_SNAPSHOT_SAVE)
- thrown error, otherwise.
**Example**
@ -5797,7 +5910,7 @@ jerry_exec_snapshot (const uint32_t *snapshot_p,
```
- `snapshot_p` - pointer to snapshot
- `snapshot_size` - size of snapshot
- `snapshot_size` - size of snapshot in bytes
- `func_index` - index of executed function
- `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags.
- return value
@ -5874,7 +5987,7 @@ jerry_load_function_snapshot (const uint32_t *snapshot_p,
```
- `snapshot_p` - pointer to snapshot
- `snapshot_size` - size of snapshot
- `snapshot_size` - size of snapshot in bytes
- `func_index` - index of function to load
- `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags.
- return value
@ -5966,7 +6079,7 @@ jerry_get_literals_from_snapshot (const uint32_t *snapshot_p,
```
- `snapshot_p` - input snapshot buffer.
- `snapshot_size` - snapshot size, in bytes.
- `snapshot_size` - size of snapshot in bytes.
- `lit_buf_p` - buffer to save literals to.
- `lit_buf_size` - the buffer's size.
- `is_c_format` - the output format would be C-style (true) or a simple list (false).
@ -6119,6 +6232,9 @@ The array length is zero if the backtrace is not available.
This function is typically called from native callbacks.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
@ -6128,7 +6244,7 @@ jerry_get_backtrace (uint32_t max_depth);
- `max_depth` - backtrace collection stops after reaching this value, 0 = unlimited
- return value
- a new array
- a newly constructed JS array
**See also**
@ -6137,6 +6253,8 @@ jerry_get_backtrace (uint32_t max_depth);
# ArrayBuffer and TypedArray functions
These APIs all depend on the ES2015-subset profile.
## jerry_get_arraybuffer_byte_length
**Summary**
@ -6517,12 +6635,16 @@ of the TypedArray object.
For the returned ArrayBuffer the [jerry_release_value](#jerry_release_value)
must be called.
*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_typedarray_buffer (jerry_value_t value,
jerry_length_t *byteOffset,
jerry_length_t *byteLength);
jerry_value_t
jerry_get_typedarray_buffer (jerry_value_t value,
jerry_length_t *byteOffset,
jerry_length_t *byteLength);
```
- `value` - TypedArray to get the ArrayBuffer from
@ -6561,12 +6683,14 @@ jerry_value_t jerry_get_typedarray_buffer (jerry_value_t value,
**Summary**
Returns the same result as JSON.parse ecmascript function.
Returns the same result as `JSON.parse` ecmascript function.
**Prototype**
```c
jerry_value_t jerry_json_parse (const jerry_char_t *string_p, jerry_size_t string_size)
jerry_value_t
jerry_json_parse (const jerry_char_t *string_p,
jerry_size_t string_size);
```
- `string_p` - a JSON string
@ -6590,14 +6714,15 @@ jerry_value_t jerry_json_parse (const jerry_char_t *string_p, jerry_size_t strin
## jerry_json_stringify
**Summary**
**Summary**
Returns the same value as JSON.stringify() ecmascript function.
Returns the same value as `JSON.stringify` ecmascript function.
**Prototype**
**Prototype**
```c
jerry_value_t jerry_json_stringify (const jerry_value_t object_to_stringify)
jerry_value_t
jerry_json_stringify (const jerry_value_t object_to_stringify);
```
- `object_to_stringify` - a jerry_value_t object to stringify