mirror of
https://github.com/jerryscript-project/jerryscript.git
synced 2025-12-15 16:29:21 +00:00
Migration Guide (#2419)
* Migration Guide Migration guide from JerryScript 1.0 to 2.0. Co-authored-by: László Langó llango.u-szeged@partner.samsung.com Co-authored-by: Peter Gal pgal.u-szeged@partner.samsung.com JerryScript-DCO-1.0-Signed-off-by: Istvan Miklos imiklos2@inf.u-szeged.hu * Add version information for API methods For each API method/type the documentation now includes the version it was introduced or a change occured. JerryScript-DCO-1.0-Signed-off-by: Peter Gal pgal.u-szeged@partner.samsung.com
This commit is contained in:
Istvan Miklos
Robert Fancsik
parent
d3c78d8c6a
commit
7575fa454a
@ -50,6 +50,7 @@ For additional information see [Getting Started](docs/00.GETTING-STARTED.md).
|
||||
- [API Reference](docs/02.API-REFERENCE.md)
|
||||
- [API Example](docs/03.API-EXAMPLE.md)
|
||||
- [Internals](docs/04.INTERNALS.md)
|
||||
- [Migration Guide](docs/16.MIGRATION-GUIDE.md)
|
||||
|
||||
## Contributing
|
||||
The project can only accept contributions which are licensed under the [Apache License 2.0](LICENSE) and are signed according to the JerryScript [Developer's Certificate of Origin](DCO.md). For further information please see our [Contribution Guidelines](CONTRIBUTING.md).
|
||||
|
||||
@ -11,6 +11,8 @@ Enum that contains the following elements:
|
||||
- JERRY_INIT_MEM_STATS_SEPARATE - **deprecated**, dump memory statistics and reset peak values after parse
|
||||
- JERRY_INIT_DEBUGGER - **deprecated**, an unused placeholder now
|
||||
|
||||
*Changed in version 2.0*: JERRY_INIT_MEM_STATS_SEPARATE and JERRY_INIT_DEBUGGER are now deprecated and not used internally.
|
||||
|
||||
## jerry_type_t
|
||||
|
||||
Enum that contains JerryScript API value types:
|
||||
@ -26,6 +28,8 @@ Enum that contains JerryScript API value types:
|
||||
- JERRY_TYPE_ERROR - error/abort type
|
||||
- JERRY_TYPE_SYMBOL - symbol type
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
## jerry_error_t
|
||||
|
||||
Possible types of an error:
|
||||
@ -41,6 +45,8 @@ Possible types of an error:
|
||||
There is also a special value `JERRY_ERROR_NONE` which is not an error type
|
||||
this value can only be returned by the [jerry_get_error_type](#jerry_get_error_type).
|
||||
|
||||
*Changed in version 2.0*: The `JERRY_ERROR_NONE` was added to be used by the [jerry_get_error_type](#jerry_get_error_type) method.
|
||||
|
||||
## jerry_feature_t
|
||||
|
||||
Possible compile time enabled feature types:
|
||||
@ -65,6 +71,8 @@ Possible compile time enabled feature types:
|
||||
- JERRY_FEATURE_SYMBOL - symbol support
|
||||
- JERRY_FEATURE_DATAVIEW - DataView support
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
## jerry_regexp_flags_t
|
||||
|
||||
RegExp object optional flags:
|
||||
@ -75,6 +83,8 @@ RegExp object optional flags:
|
||||
multiple lines (i.e., match the beginning or end of each line (delimited by \n or \r), not only the
|
||||
very beginning or end of the whole input string)
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
## jerry_parse_opts_t
|
||||
|
||||
Option bits for [jerry_parse](#jerry_parse) and
|
||||
@ -83,6 +93,8 @@ Option bits for [jerry_parse](#jerry_parse) and
|
||||
- JERRY_PARSE_NO_OPTS - no options passed
|
||||
- JERRY_PARSE_STRICT_MODE - enable strict mode
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
## jerry_gc_mode_t
|
||||
|
||||
Set garbage collection operational mode
|
||||
@ -95,6 +107,8 @@ is that the former keeps memory allocated for performance improvements such
|
||||
as property hash tables for large objects. The latter frees all possible
|
||||
memory blocks but the performance may drop after the garbage collection.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
## jerry_generate_snapshot_opts_t
|
||||
|
||||
Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and
|
||||
@ -123,6 +137,8 @@ strings are set by [jerry_register_magic_strings](#jerry_register_magic_strings)
|
||||
when the snapshot is generated and executed. Furthermore the
|
||||
`JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
## jerry_exec_snapshot_opts_t
|
||||
|
||||
Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) and
|
||||
@ -143,6 +159,7 @@ parts of the snapshot buffer into memory.
|
||||
|
||||
The `JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed for static snapshots.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
## jerry_char_t
|
||||
|
||||
@ -254,6 +271,8 @@ typedef struct
|
||||
} jerry_context_data_manager_t;
|
||||
```
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
## jerry_context_alloc_t
|
||||
|
||||
**Summary**
|
||||
@ -269,6 +288,7 @@ typedef void *(*jerry_context_alloc_t) (size_t size, void *cb_data_p);
|
||||
- `size` - allocation size
|
||||
- `cb_data_p` - pointer to user data
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
## jerry_context_t
|
||||
|
||||
@ -282,6 +302,8 @@ An opaque declaration of the JerryScript context structure.
|
||||
typedef struct jerry_context_t jerry_context_t;
|
||||
```
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
|
||||
## jerry_binary_operation_t
|
||||
|
||||
@ -294,6 +316,8 @@ Enum that contains the supported binary operation types
|
||||
- JERRY_BIN_OP_GREATER_EQUAL - greater or equal relation (>=)
|
||||
- JERRY_BIN_OP_INSTANCEOF - instanceof operation
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_binary_operation](#jerry_binary_operation)
|
||||
@ -378,6 +402,8 @@ typedef struct
|
||||
} jerry_heap_stats_t;
|
||||
```
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_get_memory_stats](#jerry_get_memory_stats)
|
||||
@ -420,6 +446,8 @@ Native free callback of an object. It is used in `jerry_object_native_info_t` an
|
||||
typedef void (*jerry_object_native_free_callback_t) (void *native_p);
|
||||
```
|
||||
|
||||
*New in version 2.0*: Renamed from `jerry_object_free_callback_t`.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_object_native_info_t](#jerry_object_native_info_t)
|
||||
@ -450,6 +478,8 @@ typedef struct
|
||||
} jerry_object_native_info_t;
|
||||
```
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
|
||||
@ -503,6 +533,8 @@ typedef bool (*jerry_objects_foreach_t) (const jerry_value_t object,
|
||||
- true, to continue the iteration
|
||||
- false, to stop the iteration
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_objects_foreach](#jerry_objects_foreach)
|
||||
@ -530,6 +562,8 @@ typedef bool (*jerry_objects_foreach_by_native_info_t) (const jerry_value_t obje
|
||||
- true, to continue the iteration
|
||||
- false, to stop the iteration
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_objects_foreach_by_native_info](#jerry_objects_foreach_by_native_info)
|
||||
@ -551,6 +585,8 @@ In this case the function must throw the same error again.
|
||||
typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p);
|
||||
```
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback)
|
||||
@ -575,6 +611,8 @@ Possible values:
|
||||
API functions can return the `JERRY_TYPEDARRAY_INVALID` value if the
|
||||
TypedArray support is not in the engine.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_get_typedarray_type](#jerry_get_typedarray_type)
|
||||
@ -666,6 +704,8 @@ jerry_get_context_data (const jerry_context_data_manager *manager_p);
|
||||
by `manager_p`, which will be stored for future identical calls to `jerry_get_context_data ()`, and which will be
|
||||
deinitialized using the `deinit_cb` callback provided by `manager_p` when the context will be destroyed.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # (test="compile")
|
||||
@ -746,6 +786,8 @@ jerry_register_magic_strings (const jerry_char_t * const *ex_str_items_p,
|
||||
- `count` - number of elements in `ext_str_items_p` array
|
||||
- `str_lengths_p` - array of lengths for each magic string
|
||||
|
||||
*Changed in version 2.0*: The first function argument type was changed.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -810,6 +852,8 @@ jerry_get_memory_stats (jerry_heap_stats_t *out_stats_p);
|
||||
- true, if stats were written into the `out_stats_p` pointer.
|
||||
- false, otherwise. Usually it is because the `JERRY_FEATURE_MEM_STATS` feature is not enabled.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -840,6 +884,8 @@ jerry_gc (jerry_gc_mode_t mode);
|
||||
|
||||
- `mode` - operational mode, see [jerry_gc_mode_t](#jerry_gc_mode_t)
|
||||
|
||||
*Changed in version 2.0*: Added `mode` argument.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -949,6 +995,8 @@ jerry_parse (const jerry_char_t *resource_name_p, /**< resource name (usually a
|
||||
- function object value, if script was parsed successfully,
|
||||
- thrown error, otherwise
|
||||
|
||||
*Changed in version 2.0*: Added `resource_name_p`, and `resource_name_length` arguments.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -1014,6 +1062,7 @@ jerry_parse_function (const jerry_char_t *resource_name_p, /**< resource name (u
|
||||
- function object value, if script was parsed successfully,
|
||||
- thrown error, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
@ -1208,6 +1257,8 @@ jerry_run_all_enqueued_jobs (void)
|
||||
|
||||
- return value - result of last executed job, may be error value.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -1296,6 +1347,8 @@ jerry_value_is_abort (const jerry_value_t value);
|
||||
- true, if the given `jerry_value_t` has the error and abort value set
|
||||
- false, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -1379,6 +1432,8 @@ jerry_value_is_arraybuffer (const jerry_value_t value)
|
||||
- true, if the given `jerry_value_t` is an ArrayBuffer object.
|
||||
- false, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -1502,6 +1557,8 @@ jerry_value_is_dataview (const jerry_value_t value)
|
||||
- true, if the given `jerry_value_t` is a DataView object
|
||||
- false, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -1554,6 +1611,8 @@ jerry_value_is_error (const jerry_value_t value);
|
||||
- true, if the given `jerry_value_t` is error value.
|
||||
- false, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -1756,6 +1815,8 @@ jerry_value_is_promise (const jerry_value_t value)
|
||||
- true, if the given `jerry_value_t` is a promise
|
||||
- false, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -1841,6 +1902,8 @@ jerry_value_is_symbol (const jerry_value_t value)
|
||||
- true, if the given `jerry_value_t` is a symbol
|
||||
- false, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -1899,6 +1962,8 @@ jerry_value_is_typedarray (const jerry_value_t value)
|
||||
- true, if the given `jerry_value_t` is a TypedArray object.
|
||||
- false, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -1991,6 +2056,8 @@ jerry_value_get_type (const jerry_value_t value);
|
||||
- return value
|
||||
- One of the [jerry_type_t](#jerry_type_t) value.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -2030,6 +2097,8 @@ jerry_is_feature_enabled (const jerry_feature_t feature);
|
||||
- true, if the given `jerry_feature_t` is enabled
|
||||
- false, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -2077,6 +2146,8 @@ jerry_binary_operation (jerry_binary_operation_t op,
|
||||
- error, if argument has an error flag or operation is unsuccessful or unsupported
|
||||
- true/false, the result of the binary operation on the given operands otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example - JERRY_BIN_OP_EQUAL**
|
||||
|
||||
```c
|
||||
@ -2168,6 +2239,8 @@ main (void)
|
||||
|
||||
# Error manipulation functions
|
||||
|
||||
*Changed in version 2.0*: The error handling and manipulation was modified and the old methods were replaced.
|
||||
|
||||
## jerry_create_abort_from_value
|
||||
|
||||
**Summary**
|
||||
@ -2192,6 +2265,8 @@ jerry_create_abort_from_value (jerry_value_t value, bool release);
|
||||
- `release` - raw boolean, defines whether input value must be released
|
||||
- return value - abort (api) value
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example 1**
|
||||
|
||||
```c
|
||||
@ -2251,6 +2326,8 @@ jerry_create_error_from_value (jerry_value_t value, bool release);
|
||||
- `release` - raw boolean, defines whether input value must be released
|
||||
- return value - error (api) value
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example 1**
|
||||
|
||||
```c
|
||||
@ -2311,6 +2388,8 @@ jerry_get_error_type (const jerry_value_t value);
|
||||
- JERRY_ERROR_NONE if the input is not an error object
|
||||
- one of the [jerry_error_t](#jerry_error_t) value
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -2358,6 +2437,8 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
|
||||
- `release` - raw boolean, defines whether input value must be released
|
||||
- return value - api value
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example 1**
|
||||
|
||||
```c
|
||||
@ -2545,6 +2626,8 @@ jerry_get_utf8_string_size (const jerry_value_t value);
|
||||
- `value` - api value
|
||||
- return value - number of bytes in the buffer needed to represent the utf8-encoded string.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -2631,6 +2714,8 @@ jerry_get_utf8_string_length (const jerry_value_t value);
|
||||
- `value` - input string value
|
||||
- return value - number of characters in the string
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -2760,6 +2845,8 @@ jerry_string_to_utf8_char_buffer (const jerry_value_t value,
|
||||
- `buffer_size` - size of the buffer
|
||||
- return value - number of bytes, actually copied to the buffer
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -2815,6 +2902,8 @@ jerry_substring_to_char_buffer (const jerry_value_t value,
|
||||
- `buffer_size` - size of the buffer
|
||||
- return value - number of bytes, actually copied to the buffer
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -2872,6 +2961,8 @@ jerry_substring_to_utf8_char_buffer (const jerry_value_t value,
|
||||
- `buffer_size` - size of the buffer
|
||||
- return value - number of bytes, actually copied to the buffer
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -3167,6 +3258,8 @@ jerry_resolve_or_reject_promise (jerry_value_t promise,
|
||||
- undefined jerry value - resolve or reject successed
|
||||
- jerry value with error flag - otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -3230,6 +3323,8 @@ jerry_get_symbol_descriptive_string (const jerry_value_t value);
|
||||
- string value containing the symbol's descriptive string - if success
|
||||
- thrown error, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -3397,6 +3492,8 @@ jerry_create_arraybuffer (jerry_length_t size);
|
||||
- `size` - size of the ArrayBuffer to create **in bytes**
|
||||
- return value - the new ArrayBuffer as a `jerry_value_t`
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -3449,6 +3546,8 @@ jerry_create_arraybuffer_external (const jerry_length_t size
|
||||
- the new ArrayBuffer as a `jerry_value_t`
|
||||
- if the `size` is zero or `buffer_p` is a null pointer will return RangeError
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -3620,6 +3719,8 @@ jerry_create_dataview (const jerry_value_t array_buffer,
|
||||
- value of the constructed DataView object - if success
|
||||
- created error - otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -3927,6 +4028,8 @@ jerry_create_promise (void)
|
||||
|
||||
- return value - value of the newly created promise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -4045,6 +4148,8 @@ jerry_create_string_from_utf8 (const jerry_char_t *str_p);
|
||||
- `str_p` - pointer to string
|
||||
- return value - value of the created string
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -4086,6 +4191,8 @@ jerry_create_string_sz (const jerry_char_t *str_p,
|
||||
- `str_size` - size of the string
|
||||
- return value - value of the created string
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -4131,6 +4238,8 @@ jerry_create_symbol (const jerry_value_t value)
|
||||
- value of the created symbol, if success
|
||||
- thrown error, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -4184,6 +4293,8 @@ jerry_create_regexp (const jerry_char_t *pattern_p, uint16_t flags);
|
||||
- `flags` - optional flags for the RegExp object, see [jerry_regexp_flags_t](#jerry_regexp_flags_t)
|
||||
- return value - the RegExp object as a `jerry_value_t`
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -4222,6 +4333,8 @@ jerry_create_regexp_sz (const jerry_char_t *pattern_p, jerry_size_t pattern_size
|
||||
- `flags` - optional flags for the RegExp object, see [jerry_regexp_flags_t](#jerry_regexp_flags_t)
|
||||
- return value - the RegExp object as a `jerry_value_t`
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -4267,6 +4380,8 @@ jerry_create_typedarray (jerry_typedarray_type_t type_name, jerry_length_t item_
|
||||
- `item_count` - number of items in the new TypedArray
|
||||
- return value - the new TypedArray as a `jerry_value_t`
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -4324,6 +4439,8 @@ jerry_create_typedarray_for_arraybuffer (jerry_typedarray_type_t type_name,
|
||||
- the new TypedArray as a `jerry_value_t`
|
||||
- Error if the ArrayBuffer does not have enough space for the given type of TypedArray
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -4387,6 +4504,8 @@ jerry_create_typedarray_for_arraybuffer_sz (jerry_typedarray_type_t type_name,
|
||||
- the new TypedArray as a `jerry_value_t`
|
||||
- Error if the ArrayBuffer does not have enough space for the given type of TypedArray
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -4465,6 +4584,8 @@ jerry_has_property (const jerry_value_t obj_val,
|
||||
- true, if the property exists
|
||||
- false, otherwise
|
||||
|
||||
*Changed in version 2.0*: The return value type is now a JavaScript value and not a primitive boolean value.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -4522,6 +4643,8 @@ jerry_has_own_property (const jerry_value_t obj_val,
|
||||
- true, if the property exists
|
||||
- false, otherwise
|
||||
|
||||
*Changed in version 2.0*: The return value type is now a JavaScript value and not a primitive boolean value.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -4619,6 +4742,8 @@ jerry_delete_property_by_index (const jerry_value_t obj_val,
|
||||
- true, if property was deleted successfully
|
||||
- false, otherwise
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -5437,6 +5562,8 @@ jerry_get_object_native_pointer (const jerry_value_t obj_val,
|
||||
- true, if there is native pointer associated of the specified object with the given native type info
|
||||
- false, otherwise
|
||||
|
||||
*New in version 2.0*: Changed from `jerry_get_object_native_handle`.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -5646,6 +5773,8 @@ jerry_set_object_native_pointer (const jerry_value_t obj_val,
|
||||
be a long-lived pointer, usually a pointer to a
|
||||
`static const jerry_object_native_info_t` makes most sense.
|
||||
|
||||
*New in version 2.0*: Changed from `jerry_set_object_native_handle`.
|
||||
|
||||
**Example**
|
||||
|
||||
See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) for a
|
||||
@ -5679,6 +5808,8 @@ jerry_delete_object_native_pointer (const jerry_value_t obj_val,
|
||||
- `obj_val` - object to delete native pointer from.
|
||||
- `info_p` - native pointer's type information.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) for a
|
||||
@ -5821,6 +5952,8 @@ jerry_objects_foreach (jerry_objects_foreach_t foreach_p,
|
||||
- `true`, if the search function terminated the traversal by returning `false`
|
||||
- `false`, if the end of the list of objects was reached
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # (name="02.API-REFERENCE-objects-foreach.c")
|
||||
@ -5958,6 +6091,8 @@ jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *native_i
|
||||
- `true`, if the search function terminated the traversal by returning `false`
|
||||
- `false`, if the end of the list of objects was reached
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # (name="02.API-REFERENCE-objects-foreach-nativeptr.c")
|
||||
@ -6112,6 +6247,8 @@ jerry_is_valid_utf8_string (const jerry_char_t *utf8_buf_p, /**< UTF-8 string */
|
||||
- true, if the provided string was a valid UTF-8 string.
|
||||
- false, if the string is not valid as an UTF-8 string.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -6167,6 +6304,8 @@ jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string
|
||||
- true, if the provided string was a valid CESU-8 string.
|
||||
- false, if the string is not valid as a CESU-8 string.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -6229,6 +6368,8 @@ void *jerry_heap_alloc (size_t size);
|
||||
- return value: non-NULL pointer, if the memory is successfully allocated,
|
||||
NULL otherwise.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_heap_free](#jerry_heap_free)
|
||||
@ -6248,6 +6389,8 @@ void jerry_heap_free (void *mem_p, size_t size);
|
||||
- `mem_p`: value returned by `jerry_heap_alloc`.
|
||||
- `size`: same size as passed to `jerry_heap_alloc`.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_heap_alloc](#jerry_heap_alloc)
|
||||
@ -6277,6 +6420,8 @@ jerry_create_context (uint32_t heap_size,
|
||||
- pointer to the newly created JerryScript context if success
|
||||
- NULL otherwise.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # (test="compile")
|
||||
@ -6389,6 +6534,8 @@ jerry_generate_snapshot (const jerry_char_t *resource_name_p,
|
||||
current configuration through JERRY_SNAPSHOT_SAVE)
|
||||
- thrown error, otherwise.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -6472,6 +6619,8 @@ jerry_generate_function_snapshot (const jerry_char_t *resource_name_p,
|
||||
current configuration through JERRY_SNAPSHOT_SAVE)
|
||||
- thrown error, otherwise.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -6542,6 +6691,8 @@ jerry_exec_snapshot (const uint32_t *snapshot_p,
|
||||
- result of bytecode, if run was successful
|
||||
- thrown error, otherwise
|
||||
|
||||
*Changed in version 2.0*: Added `func_index` and `exec_snapshot_opts` arguments. Removed the `copy_bytecode` last argument.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -6620,6 +6771,8 @@ jerry_load_function_snapshot (const uint32_t *snapshot_p,
|
||||
- function object built from the snapshot.
|
||||
- thrown error, otherwise.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -6714,6 +6867,8 @@ jerry_get_literals_from_snapshot (const uint32_t *snapshot_p,
|
||||
and literal-save support is enabled in current configuration through JERRY_SNAPSHOT_SAVE)
|
||||
- 0 otherwise.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # (test="link")
|
||||
@ -6802,6 +6957,8 @@ jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb,
|
||||
- `user_p` - user pointer passed to the `stop_cb` function
|
||||
- `frequency` - frequency of calling the `stop_cb` function
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # (test="link")
|
||||
@ -6877,6 +7034,8 @@ jerry_get_backtrace (uint32_t max_depth);
|
||||
- return value
|
||||
- a newly constructed JS array
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # (name="02.API-REFERENCE-jsbacktrace.c")
|
||||
@ -6993,6 +7152,8 @@ jerry_get_arraybuffer_byte_length (const jerry_value_t value);
|
||||
- size of the ArrayBuffer in bytes
|
||||
- 0 if the `value` parameter is not an ArrayBuffer
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -7043,6 +7204,8 @@ jerry_arraybuffer_read (const jerry_value_t value,
|
||||
- 0 if the `value` is not an ArrayBuffer object
|
||||
- 0 if the `buf_size` is zero or there is nothing to read
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -7105,6 +7268,8 @@ jerry_arraybuffer_write (const jerry_value_t value,
|
||||
- 0 if the `value` is not an ArrayBuffer object
|
||||
- 0 if the `buf_size` is zero or there is nothing to write
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -7165,6 +7330,8 @@ jerry_get_arraybuffer_pointer (const jerry_value_t value);
|
||||
- pointer to the Array Buffer's data area.
|
||||
- NULL if the `value` is not an Array Buffer object.
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -7218,6 +7385,8 @@ jerry_get_dataview_buffer (const jerry_value_t value,
|
||||
- DataView object's underlying ArrayBuffer object
|
||||
- TypeError if the `value` is not a DataView object
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
@ -7276,6 +7445,8 @@ jerry_get_typedarray_type (jerry_value_t value);
|
||||
- the type of the TypedArray
|
||||
- JERRY_TYPEDARRAY_INVALID if the object was not a TypedArray
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -7317,6 +7488,8 @@ jerry_get_typedarray_length (jerry_value_t value);
|
||||
- length (element count) of the TypedArray object
|
||||
- 0 if the object is not a TypedArray
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -7366,6 +7539,8 @@ jerry_get_typedarray_buffer (jerry_value_t value,
|
||||
- TypedArray object's underlying ArrayBuffer object
|
||||
- TypeError if the `value` is not a TypedArray object
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -7411,6 +7586,8 @@ jerry_json_parse (const jerry_char_t *string_p,
|
||||
- jerry_value_t containing the same as json.parse()
|
||||
- jerry_value_t containing error massage
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
@ -7442,6 +7619,8 @@ jerry_json_stringify (const jerry_value_t object_to_stringify);
|
||||
- jerry_value_t containing the same as json.stringify()
|
||||
- jerry_value_t containing error massage
|
||||
|
||||
*New in version 2.0*.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
|
||||
772
docs/16.MIGRATION-GUIDE.md
Normal file
772
docs/16.MIGRATION-GUIDE.md
Normal file
@ -0,0 +1,772 @@
|
||||
# Migration guide
|
||||
|
||||
This guide intends to describe the major changes between the JerryScript 1.0 and 2.0 versions.
|
||||
In addtion it is designed to provide a guide on how to modify the 1.0 version code to a
|
||||
2.0 compliant code.
|
||||
|
||||
During the development it was important to minimize the changes in the API functions and types.
|
||||
Each API method removal or chang is described below providing a ***before*** and ***after***
|
||||
code example.
|
||||
For more information on the current API methods please check the [API reference](02.API-REFERENCE.md) document.
|
||||
|
||||
# Short list of removed/renamed headers, types, functions, and macros
|
||||
|
||||
***Removed legacy headers***
|
||||
|
||||
- `jerry-internal.h`
|
||||
|
||||
***Renamed headers***
|
||||
|
||||
- `jerry-api.h` to `jerryscript.h`
|
||||
- `jerry-port.h` to `jerryscript-port.h`
|
||||
|
||||
***Removed API types***
|
||||
|
||||
- `jerry_char_ptr_t` usage replaced with `jerry_char_t *`
|
||||
- `jerry_object_free_callback_t` replaced by `jerry_object_native_free_callback_t`
|
||||
|
||||
***Removed API methods***
|
||||
|
||||
- `jerry_get_memory_limits`
|
||||
- `jerry_get_object_native_handle` replaced by `jerry_get_object_native_pointer`
|
||||
- `jerry_set_object_native_handle` replaced by `jerry_set_object_native_pointer`
|
||||
- `jerry_value_set_abort_flag` replaced by `jerry_create_abort_from_value`
|
||||
- `jerry_value_has_abort_flag` replaced by `jerry_value_is_abort`
|
||||
- `jerry_value_set_error_flag` replaced by `jerry_create_error_from_value`
|
||||
- `jerry_value_has_error_flag` replaced by `jerry_value_is_error`
|
||||
- `jerry_value_clear_error_flag` replaced by `jerry_get_value_from_error`
|
||||
- `jerry_get_value_without_error_flag` replaced by `jerry_get_value_from_error`
|
||||
- `jerry_parse_and_save_snapshot` replaced by `jerry_generate_snapshot`
|
||||
- `jerry_parse_and_save_function_snapshot` replaced by `jerry_generate_function_snapshot`
|
||||
|
||||
|
||||
***Removed unused configuration macros***
|
||||
|
||||
- `CONFIG_MEM_DATA_LIMIT_MINUS_HEAP_SIZE`
|
||||
- `CONFIG_MEM_STACK_LIMIT`
|
||||
- `CONFIG_VM_STACK_FRAME_INLINED_VALUES_NUMBER`
|
||||
- `CONFIG_ECMA_GLOBAL_ENVIRONMENT_DECLARATIVE`
|
||||
- All `CONFIG_..` macros have been renamed to use the `JERRY_` prefix format.
|
||||
|
||||
|
||||
# Modified API functions
|
||||
|
||||
## Error manipulating functions
|
||||
|
||||
The most important changes in the API are releated to error handling and manipulation.
|
||||
|
||||
### jerry_value_set_abort_flag
|
||||
|
||||
This function was replaced with [`jerry_create_abort_from_value`](02.API-REFERENCE.md#jerry_create_abort_from_value).
|
||||
Take note of the second argument of the new `jerry_create_abort_from_value` function which controls if the
|
||||
first argument should be usable after the call or not.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_set_abort_flag (&value);
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_t abort = jerry_create_abort_from_value (value, true);
|
||||
// using the 'value' variable after release is invalid
|
||||
|
||||
jerry_release_value (abort);
|
||||
}
|
||||
```
|
||||
|
||||
- OR
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
... // create or acquire value
|
||||
|
||||
jerry_value_t abort = jerry_create_abort_from_value (value, false);
|
||||
// both 'abort' and 'value' can be used and must be released when they are no longer needed
|
||||
|
||||
jerry_release_value (abort);
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
### jerry_value_has_abort_flag
|
||||
|
||||
This function was renamed to [`jerry_value_is_abort`](02.API-REFERENCE.md#jerry_value_is_abort).
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
if (jerry_value_has_abort_flag (value))
|
||||
{
|
||||
// ...
|
||||
}
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
if (jerry_value_is_abort (value))
|
||||
{
|
||||
// ...
|
||||
}
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
### jerry_value_set_error_flag
|
||||
|
||||
This function was replaced with [`jerry_create_error_from_value`](02.API-REFERENCE.md#jerry_create_error_from_value).
|
||||
Take note of the second argument of the new `jerry_create_error_from_value` function which controls if the
|
||||
first argument should be usable after the call or not.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_set_error_flag (&value);
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_t error = jerry_create_error_from_value (value, true);
|
||||
// using the 'value' variable after release is invalid
|
||||
|
||||
jerry_release_value (error);
|
||||
}
|
||||
```
|
||||
|
||||
- OR
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_t error = jerry_create_error_from_value (value, false);
|
||||
// both 'error' and 'value' can be used and must be released when they are no longer needed
|
||||
|
||||
jerry_release_value (error);
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
### jerry_value_has_error_flag
|
||||
|
||||
This function was renamed to [`jerry_value_is_error`](02.API-REFERENCE.md#jerry_value_is_error).
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
if (jerry_value_has_error_flag (value))
|
||||
{
|
||||
// ...
|
||||
}
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
if (jerry_value_is_error (value))
|
||||
{
|
||||
// ...
|
||||
}
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
### jerry_value_clear_error_flag AND jerry_get_value_without_error_flag
|
||||
|
||||
These functions were merged into [`jerry_get_value_from_error`](02.API-REFERENCE.md#jerry_get_value_from_error).
|
||||
Please note the second argument of the new function which controls if the first argument passed should be released
|
||||
or not.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_set_error_flag (&value);
|
||||
jerry_value_clear_error_flag (&value);
|
||||
// or
|
||||
jerry_value_t real_value = jerry_get_value_without_error_flag (value);
|
||||
|
||||
jerry_release_value (value);
|
||||
jerry_release_value (real_value);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_t error = jerry_create_error_from_value (value, true);
|
||||
|
||||
jerry_value_t real_value = jerry_get_value_from_error (error, true);
|
||||
|
||||
jerry_release_value (real_value);
|
||||
}
|
||||
```
|
||||
|
||||
## Other functions changed
|
||||
|
||||
### jerry_register_magic_strings
|
||||
|
||||
In case of the `jerry_register_magic_strings` function the change is that
|
||||
the first argument's base type `jerry_char_ptr_t` was changed to `jerry_char_t*`.
|
||||
For more details see: [`jerry_register_magic_strings`](02.API-REFERENCE.md#jerry_register_magic_strings).
|
||||
|
||||
In the following code parts please take note of the type used for the `magic_string_items` array.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
// must be static, because 'jerry_register_magic_strings' does not copy
|
||||
// the items must be sorted by size at first, then lexicographically
|
||||
static const jerry_char_ptr_t magic_string_items[] = {
|
||||
(const jerry_char_ptr_t) "magicstring1",
|
||||
(const jerry_char_ptr_t) "magicstring2",
|
||||
(const jerry_char_ptr_t) "magicstring3"
|
||||
};
|
||||
uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t));
|
||||
|
||||
// must be static, because 'jerry_register_magic_strings' does not copy
|
||||
static const jerry_length_t magic_string_lengths[] = { 12, 12, 12 };
|
||||
jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
// must be static, because 'jerry_register_magic_strings' does not copy
|
||||
// the items must be sorted by size at first, then lexicographically
|
||||
static const jerry_char_t *magic_string_items[] = {
|
||||
(const jerry_char_t *) "magicstring1",
|
||||
(const jerry_char_t *) "magicstring2",
|
||||
(const jerry_char_t *) "magicstring3"
|
||||
};
|
||||
uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_t *));
|
||||
|
||||
// must be static, because 'jerry_register_magic_strings' does not copy
|
||||
static const jerry_length_t magic_string_lengths[] = { 12, 12, 12 };
|
||||
jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
|
||||
}
|
||||
```
|
||||
|
||||
## Snapshot generating API
|
||||
|
||||
### jerry_parse_and_save_snapshot
|
||||
|
||||
This function was replaced with [`jerry_generate_snapshot`](02.API-REFERENCE.md#jerry_generate_snapshot).
|
||||
The function returns an error object if there was any problem during snapshot generation and
|
||||
if there was no problem the return value is a number value containing the snapshot size in bytes.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
static uint32_t global_mode_snapshot_buffer[256];
|
||||
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
|
||||
|
||||
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) / sizeof (uint32_t));
|
||||
// use "global_mode_snapshot_buffer"
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
static uint32_t global_mode_snapshot_buffer[256];
|
||||
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
|
||||
|
||||
jerry_value_t generate_result;
|
||||
generate_result = jerry_generate_snapshot (NULL,
|
||||
0,
|
||||
code_to_snapshot_p,
|
||||
strlen ((const char *) code_to_snapshot_p),
|
||||
global_mode_snapshot_buffer,
|
||||
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
|
||||
if (jerry_value_is_error (generate_result))
|
||||
{
|
||||
// There was a problem during snapshot generation, for example there is a SyntaxError.
|
||||
// Use the "generate_result" to check the error.
|
||||
}
|
||||
else
|
||||
{
|
||||
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
|
||||
// use "global_mode_snapshot_buffer"
|
||||
}
|
||||
jerry_release_value (generate_result);
|
||||
}
|
||||
```
|
||||
|
||||
### jerry_parse_and_save_function_snapshot
|
||||
|
||||
This function was replaced with [`jerry_generate_function_snapshot`](02.API-REFERENCE.md#jerry_parse_and_save_function_snapshot).
|
||||
The function returns an error object if there was any problem during snapshot generation and
|
||||
if there was no problem the return value is a number value containing the snapshot size in bytes.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
static uint32_t func_snapshot_buffer[1024];
|
||||
|
||||
const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
|
||||
const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
|
||||
|
||||
size_t func_snapshot_size =
|
||||
jerry_parse_and_save_function_snapshot (src_p,
|
||||
strlen ((const char *) src_p),
|
||||
args_p,
|
||||
strlen ((const char *) args_p),
|
||||
false,
|
||||
func_snapshot_buffer,
|
||||
sizeof (func_snapshot_buffer) / sizeof (uint32_t));
|
||||
// check "function_snapshot_size" and use "func_snapshot_buffer"
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
static uint32_t func_snapshot_buffer[1024];
|
||||
|
||||
const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
|
||||
const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
|
||||
|
||||
jerry_value_t generate_result;
|
||||
generate_result = jerry_generate_function_snapshot (NULL,
|
||||
0,
|
||||
src_p,
|
||||
strlen ((const char *) src_p),
|
||||
args_p,
|
||||
strlen ((const char *) args_p),
|
||||
0,
|
||||
func_snapshot_buffer,
|
||||
sizeof (func_snapshot_buffer) / sizeof (uint32_t));
|
||||
if (jerry_value_is_error (generate_result))
|
||||
{
|
||||
// There was a problem during snapshot generation, for example there is a SyntaxError.
|
||||
// Use the "generate_result" to check the error.
|
||||
}
|
||||
else
|
||||
{
|
||||
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
|
||||
// use "func_snapshot_buffer"
|
||||
}
|
||||
|
||||
jerry_release_value (generate_result)
|
||||
}
|
||||
```
|
||||
|
||||
## Garbage collection
|
||||
|
||||
### jerry_gc
|
||||
|
||||
The [`jerry_gc`](02.API-REFERENCE.md#jerry_gc) function was modified to handle an argument which represents the pressure for the garbage collector.
|
||||
For more information checkout the [`jerry_gc_mode_t`](02.API-REFERENCE.md#jerry_gc_mode_t) reference.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_gc ();
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_gc (JERRY_GC_PRESSURE_LOW);
|
||||
}
|
||||
```
|
||||
|
||||
## jerry_eval
|
||||
|
||||
The third argument of [`jerry_eval`](02.API-REFERENCE.md#jerry_eval) has been changed
|
||||
from `bool` to [`jerry_parse_opts_t`](02.API-REFERENCE.md#jerry_parse_opts_t).
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
const jerry_char_t *str_to_eval = (const jerry_char_t *) "1 + 1";
|
||||
jerry_value_t ret_val = jerry_eval (str_to_eval,
|
||||
strlen ((const char *) str_to_eval),
|
||||
false);
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
const jerry_char_t *str_to_eval = (const jerry_char_t *) "1 + 1";
|
||||
jerry_value_t ret_val = jerry_eval (str_to_eval,
|
||||
strlen ((const char *) str_to_eval),
|
||||
JERRY_PARSE_NO_OPTS);
|
||||
```
|
||||
|
||||
## Port API
|
||||
|
||||
### jerry_port_get_time_zone
|
||||
|
||||
The port API of handling timezones has been changed. The previous interface did not
|
||||
allow timezones to be handled correctly, even if the host system was up to the task.
|
||||
Check [the related issue](https://github.com/jerryscript-project/jerryscript/issues/1661)
|
||||
for more details.
|
||||
|
||||
The new port API function name is [jerry_port_get_local_time_zone_adjustment](05.PORT-API.md#date-1].
|
||||
|
||||
Below is the default implementations for both versions:
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
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 */
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
double jerry_port_get_local_time_zone_adjustment (double unix_ms,
|
||||
bool is_utc)
|
||||
{
|
||||
struct tm tm;
|
||||
time_t now = (time_t) (unix_ms / 1000);
|
||||
localtime_r (&now, &tm);
|
||||
if (!is_utc)
|
||||
{
|
||||
now -= tm.tm_gmtoff;
|
||||
localtime_r (&now, &tm);
|
||||
}
|
||||
return ((double) tm.tm_gmtoff) * 1000;
|
||||
} /* jerry_port_get_local_time_zone_adjustment */
|
||||
```
|
||||
|
||||
## Native pointers
|
||||
|
||||
The assignment of native pointers (previously called handles) have been changed
|
||||
since v1.0. In the previous version only one native pointer could be assigned to
|
||||
a `jerry_value_t`. Now it is allowed to register multiple native infos, which
|
||||
can be accessed with the corresponding
|
||||
[`jerry_object_native_info_t`](02.API-REFERENCE.md#jerry_object_native_info_t).
|
||||
The old functions were removed and replaced by new ones.
|
||||
|
||||
- `jerry_object_free_callback_t` callback type is replaced by `jerry_object_native_info_t`
|
||||
- `jerry_get_object_native_handle` is replaced by [`jerry_get_object_native_pointer`](02.API-REFERENCE.md#jerry_get_object_native_pointer)
|
||||
- `jerry_set_object_native_handle` is replaced by [`jerry_set_object_native_pointer`](02.API-REFERENCE.md#jerry_set_object_native_pointer)
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
struct
|
||||
{
|
||||
int data;
|
||||
} my_info;
|
||||
|
||||
static void
|
||||
handler_construct_freecb (uintptr_t native_p)
|
||||
{
|
||||
// Invoked when the JS object is released and the
|
||||
// native data should be freed.
|
||||
|
||||
struct my_info *info = (struct my_info *) native_p;
|
||||
free (info);
|
||||
}
|
||||
|
||||
void
|
||||
demo (void)
|
||||
{
|
||||
jerry_value_t this_val;
|
||||
// create or acquire this_val
|
||||
// ...
|
||||
|
||||
struct my_info *info = (struct my_info *) malloc (sizeof (struct my_info));
|
||||
info->data = 11;
|
||||
|
||||
// setting the native handle
|
||||
jerry_set_object_native_handle (this_val,
|
||||
(uintptr_t) info,
|
||||
handler_construct_freecb);
|
||||
// ...
|
||||
// reading back the native handle
|
||||
uintptr_t ptr = (uintptr_t) NULL;
|
||||
bool is_ok = jerry_get_object_native_handle (this_val, &ptr);
|
||||
if (is_ok)
|
||||
{
|
||||
struct my_info *obj_info = (struct my_info *) ptr;
|
||||
// use "obj_info"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
struct
|
||||
{
|
||||
int data;
|
||||
} my_info;
|
||||
|
||||
static void
|
||||
handler_construct_freecb (void *native_p)
|
||||
{
|
||||
// Invoked when the JS object is released and the
|
||||
// native data should be freed.
|
||||
|
||||
struct my_info *info = (struct my_info *) native_p;
|
||||
free (info);
|
||||
}
|
||||
|
||||
static const jerry_object_native_info_t my_info_type_info =
|
||||
{
|
||||
.free_cb = handler_construct_freecb
|
||||
};
|
||||
|
||||
void
|
||||
demo (void)
|
||||
{
|
||||
jerry_value_t this_val;
|
||||
// create or acquire this_val
|
||||
// ...
|
||||
|
||||
struct my_info *info = (struct my_info *) malloc (sizeof (struct my_info));
|
||||
info->data = 11;
|
||||
|
||||
// setting the native handle
|
||||
jerry_set_object_native_pointer (this_val,
|
||||
info,
|
||||
&my_info_type_info);
|
||||
// ...
|
||||
// reading back the native handle pointed by the "my_info_type_info" variable
|
||||
void *ptr = NULL;
|
||||
bool has_p = jerry_get_object_native_pointer (this_val, &ptr, &my_info_type_info);
|
||||
if (has_p)
|
||||
{
|
||||
struct my_info *obj_info = (struct my_info *) ptr;
|
||||
// use "obj_info"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
# New API functions
|
||||
|
||||
In this section the new API functions are listed.
|
||||
|
||||
## Built-in objects
|
||||
|
||||
***ArrayBuffer***
|
||||
|
||||
- [`jerry_create_arraybuffer`](02.API-REFERENCE.md#jerry_create_arraybuffer)
|
||||
- [`jerry_create_arraybuffer_external`](02.API-REFERENCE.md#jerry_create_arraybuffer_external)
|
||||
- [`jerry_get_arraybuffer_pointer`](02.API-REFERENCE.md#jerry_get_arraybuffer_pointer)
|
||||
|
||||
***DataView***
|
||||
|
||||
- [`jerry_create_dataview`](02.API-REFERENCE.md#jerry_create_dataview)
|
||||
- [`jerry_value_is_dataview`](02.API-REFERENCE.md#jerry_value_is_dataview)
|
||||
- [`jerry_get_dataview_buffer`](02.API-REFERENCE.md#jerry_get_dataview_buffer)
|
||||
|
||||
***JSON***
|
||||
|
||||
- [`jerry_json_parse`](02.API-REFERENCE.md#jerry_json_parse)
|
||||
- [`jerry_json_stringify`](02.API-REFERENCE.md#jerry_json_stringify)
|
||||
|
||||
***Number***
|
||||
|
||||
- [`jerry_create_number_infinity`](02.API-REFERENCE.md#jerry_create_number_infinity)
|
||||
- [`jerry_create_number_nan`](02.API-REFERENCE.md#jerry_create_number_nan)
|
||||
|
||||
***Promise***
|
||||
|
||||
- [`jerry_run_all_enqueued_jobs`](02.API-REFERENCE.md#jerry_run_all_enqueued_jobs)
|
||||
- [`jerry_create_promise`](02.API-REFERENCE.md#jerry_create_promise)
|
||||
- [`jerry_resolve_or_reject_promise`](02.API-REFERENCE.md#jerry_resolve_or_reject_promise)
|
||||
- [`jerry_value_is_promise`](02.API-REFERENCE.md#jerry_value_is_promise)
|
||||
|
||||
***RegExp***
|
||||
|
||||
- [`jerry_create_regexp`](02.API-REFERENCE.md#jerry_create_regexp)
|
||||
- [`jerry_create_regexp_sz`](02.API-REFERENCE.md#jerry_create_regexp_sz)
|
||||
|
||||
***String***
|
||||
|
||||
- [`jerry_substring_to_utf8_char_buffer`](02.API-REFERENCE.md#jerry_substring_to_utf8_char_buffer)
|
||||
- [`jerry_get_utf8_string_size`](02.API-REFERENCE.md#jerry_get_utf8_string_size)
|
||||
- [`jerry_get_utf8_string_length`](02.API-REFERENCE.md#jerry_get_utf8_string_length)
|
||||
- [`jerry_create_string_from_utf8`](02.API-REFERENCE.md#jerry_create_string_from_utf8)
|
||||
- [`jerry_create_string_sz_from_utf8`](02.API-REFERENCE.md#jerry_create_string_sz_from_utf8)
|
||||
|
||||
***Symbol***
|
||||
|
||||
- [`jerry_create_symbol`](02.API-REFERENCE.md#jerry_create_symbol)
|
||||
- [`jerry_get_symbol_descriptive_string`](02.API-REFERENCE.md#jerry_get_symbol_descriptive_string)
|
||||
- [`jerry_value_is_symbol`](02.API-REFERENCE.md#jerry_value_is_symbol)
|
||||
|
||||
***TypedArray***
|
||||
|
||||
- [`jerry_create_typedarray`](02.API-REFERENCE.md#jerry_create_typedarray)
|
||||
- [`jerry_create_typedarray_for_arraybuffer`](02.API-REFERENCE.md#jerry_create_typedarray_for_arraybuffer)
|
||||
- [`jerry_create_typedarray_for_arraybuffer_sz`](02.API-REFERENCE.md#jerry_create_typedarray_for_arraybuffer_sz)
|
||||
- [`jerry_get_typedarray_type`](02.API-REFERENCE.md#jerry_get_typedarray_type)
|
||||
- [`jerry_get_typedarray_length`](02.API-REFERENCE.md#jerry_get_typedarray_length)
|
||||
- [`jerry_get_typedarray_buffer`](02.API-REFERENCE.md#jerry_get_typedarray_buffer)
|
||||
- [`jerry_value_is_typedarray`](02.API-REFERENCE.md#jerry_value_is_typedarray)
|
||||
|
||||
|
||||
## Instances and memory management
|
||||
|
||||
***JerryScript instances***
|
||||
|
||||
- [`jerry_create_context`](02.API-REFERENCE.md#jerry_create_context)
|
||||
- [`jerry_get_context_data`](02.API-REFERENCE.md#jerry_get_context_data)
|
||||
|
||||
***Memory management***
|
||||
|
||||
- [`jerry_heap_alloc`](02.API-REFERENCE.md#jerry_heap_alloc)
|
||||
- [`jerry_heap_free`](02.API-REFERENCE.md#jerry_heap_free)
|
||||
|
||||
|
||||
## Operations with JavaScript values
|
||||
|
||||
***Binary operations***
|
||||
|
||||
- [`jerry_binary_operation`](02.API-REFERENCE.md#jerry_binary_operation)
|
||||
|
||||
***Error manipulating***
|
||||
|
||||
- [`jerry_get_error_type`](02.API-REFERENCE.md#jerry_get_error_type)
|
||||
- [`jerry_get_backtrace`](02.API-REFERENCE.md#jerry_get_backtrace)
|
||||
|
||||
***Native pointers***
|
||||
|
||||
- [`jerry_delete_object_native_pointer`](02.API-REFERENCE.md#jerry_delete_object_native_pointer)
|
||||
- [`jerry_objects_foreach_by_native_info`](02.API-REFERENCE.md#jerry_objects_foreach_by_native_info)
|
||||
|
||||
***Property***
|
||||
|
||||
- [`jerry_delete_property_by_index`](02.API-REFERENCE.md#jerry_delete_property_by_index)
|
||||
- [`jerry_objects_foreach`](02.API-REFERENCE.md#jerry_objects_foreach)
|
||||
|
||||
|
||||
## Debugger
|
||||
|
||||
- [`jerry_debugger_is_connected`](07.DEBUGGER.md#jerry_debugger_is_connected)
|
||||
- [`jerry_debugger_stop`](07.DEBUGGER.md#jerry_debugger_stop)
|
||||
- [`jerry_debugger_continue`](07.DEBUGGER.md#jerry_debugger_continue)
|
||||
- [`jerry_debugger_stop_at_breakpoint`](07.DEBUGGER.md#jerry_debugger_stop_at_breakpoint)
|
||||
- [`jerry_debugger_wait_for_client_source`](07.DEBUGGER.md#jerry_debugger_wait_for_client_source)
|
||||
- [`jerry_debugger_send_output`](07.DEBUGGER.md#jerry_debugger_send_output)
|
||||
- [`jerry_debugger_send_log`](07.DEBUGGER.md#jerry_debugger_send_log)
|
||||
|
||||
|
||||
## Other
|
||||
|
||||
- [`jerry_is_feature_enabled`](02.API-REFERENCE.md#jerry_is_feature_enabled)
|
||||
- [`jerry_parse_and_save_literals`](02.API-REFERENCE.md#jerry_parse_and_save_literals)
|
||||
- [`jerry_set_vm_exec_stop_callback`](02.API-REFERENCE.md#jerry_set_vm_exec_stop_callback)
|
||||
|
||||
|
||||
## Port API functions
|
||||
|
||||
- [`jerry_port_normalize_path`](05.PORT-API.md#jerry_port_normalize_path)
|
||||
- [`jerry_port_read_source`](05.PORT-API.md#jerry_port_read_source)
|
||||
- [`jerry_port_release_source`](05.PORT-API.md#jerry_port_release_source)
|
||||
- [`jerry_port_print_char`](05.PORT-API.md#jerry_port_print_char)
|
||||
- [`jerry_port_get_current_context`](05.PORT-API.md#jerry_port_get_current_context)
|
||||
- [`jerry_port_fatal`](05.PORT-API.md#jerry_port_fatal)
|
||||
- [`jerry_port_sleep`](05.PORT-API.md#jerry_port_sleep)
|
||||
@ -38,6 +38,7 @@ EXT_REFERENCE_MODULE_MD="12.EXT-REFERENCE-MODULE.md"
|
||||
DEBUGGER_TRANSPORT_MD="13.DEBUGGER-TRANSPORT.md"
|
||||
EXT_REFERENCE_HANDLE_SCOPE_MD="14.EXT-REFERENCE-HANDLE-SCOPE.md"
|
||||
MODULE_SYSTEM_MD="15.MODULE-SYSTEM.md"
|
||||
MIGRATION_GUIDE_MD="16.MIGRATION-GUIDE.md"
|
||||
|
||||
declare -A titles
|
||||
|
||||
@ -57,6 +58,7 @@ titles[$EXT_REFERENCE_MODULE_MD]="'Extension API: Module Support'"
|
||||
titles[$DEBUGGER_TRANSPORT_MD]="'Debugger Transport'"
|
||||
titles[$EXT_REFERENCE_HANDLE_SCOPE_MD]="'Extension API: Handle Scope'"
|
||||
titles[$MODULE_SYSTEM_MD]="'Module System (EcmaScript2015)'"
|
||||
titles[$MIGRATION_GUIDE_MD]="Migration Guide"
|
||||
|
||||
for docfile in $docs_dir/*.md; do
|
||||
docfile_base=`basename $docfile`
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user