diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index ea839d17b1..74e3ce4257 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -21,6 +21,19 @@ Enum that contains the following elements: - JERRY_INIT_MEM_STATS_SEPARATE - dump memory statistics and reset peak values after parse - JERRY_INIT_DEBUGGER - deprecated, an unused placeholder now +## jerry_type_t + +Enum that contains a set of elements to represent JavaScript type: + + - JERRY_TYPE_NONE - no type information + - JERRY_TYPE_UNDEFINED - undefined value + - JERRY_TYPE_NULL - null value + - JERRY_TYPE_BOOLEAN - boolean value + - JERRY_TYPE_NUMBER - number value + - JERRY_TYPE_STRING - string value + - JERRY_TYPE_OBJECT - object value + - JERRY_TYPE_FUNCTION - function value + ## jerry_error_t Possible types of an error: @@ -33,6 +46,9 @@ Possible types of an error: - JERRY_ERROR_TYPE - type error - JERRY_ERROR_URI - URI error +There is also a special value `JERRY_ERROR_NONE` which is not an error type +this value can only be returned by the [jerry_get_error_type](#jerry_get_error_type). + ## jerry_feature_t Possible compile time enabled feature types: @@ -306,6 +322,26 @@ typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p); - [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback) +## jerry_typedarray_type_t + +Enum which describes the TypedArray types. +Possible values: + + - JERRY_TYPEDARRAY_UINT8 - represents the Uint8Array TypedArray + - JERRY_TYPEDARRAY_UINT8CLAMPED - represents the Uint8ClampedArray TypedArray + - JERRY_TYPEDARRAY_INT8 - represents the Int8Array TypedArray + - JERRY_TYPEDARRAY_UINT16 - represents the Uint16Array TypedArray + - JERRY_TYPEDARRAY_INT16 - represents the Int16Array TypedArray + - JERRY_TYPEDARRAY_UINT32 - represents the Uint32Array TypedArray + - JERRY_TYPEDARRAY_INT32 - represents the Int32Array TypedArray + - JERRY_TYPEDARRAY_FLOAT32 - represents the Float32Array TypedArray + - JERRY_TYPEDARRAY_FLOAT64 - represents the Float64Array TypedArray + - JERRY_TYPEDARRAY_INVALID - represents an invalid TypedArray + +API functions can return the `JERRY_TYPEDARRAY_INVALID` value if the +TypedArray support is not in the engine. + + # General engine functions ## jerry_init @@ -1357,6 +1393,45 @@ jerry_value_is_string (const jerry_value_t value) - [jerry_release_value](#jerry_release_value) +## jerry_value_is_typedarray + +**Summary** + +Checks whether the given `jerry_value_t` is a TypedArray object or not. + +**Prototype** + +```c +bool +jerry_value_is_typedarray (const jerry_value_t value) +``` + +- `value` - object to check +- return value + - true, if the given `jerry_value_t` is a TypedArray object. + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_typedarray (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_create_typedarray](#jerry_create_typedarray) + + ## jerry_value_is_undefined **Summary** @@ -1395,6 +1470,44 @@ jerry_value_is_undefined (const jerry_value_t value) - [jerry_release_value](#jerry_release_value) +## jerry_value_get_type + +**Summary** + +Returns the JavaScript type +for a given value as a [jerry_type_t](#jerry_type_t) enum value. + +This is a similar operation as the 'typeof' operator +in the standard with an exception that the 'null' +value has its own enum value. + +**Prototype** + +```c +jerry_type_t +jerry_value_get_type (const jerry_value_t value); +``` + +**Example** + +```c +{ + jerry_value_t number = jerry_create_number (3.3); + + jerry_type_t type_info = jerry_value_get_type (number); + + if (type_info == JERRY_TYPE_NUMBER) + { + ... + } + + jerry_value_release (number); +} +``` + +**See also** +- [jerry_type_t](#jerry_type_t) + ## jerry_is_feature_enabled **Summary** @@ -1428,7 +1541,50 @@ jerry_is_feature_enabled (const jerry_feature_t feature); } ``` -# Error flag manipulation functions +# Error manipulation functions + +## jerry_get_error_type + +**Summary** + +Returns the type of the Error object if possible. + +If a non-error object is used as the input for the function the method +will return `JERRY_ERROR_NONE` indicating that the value was not +an Error object. However it is still possible that the value contains +error semantics. To correctly detect if a value have error use the +[jerry_value_has_error_flag](#jerry_value_has_error_flag) method. + +**Prototype** + +```c +jerry_error_t +jerry_get_error_type (const jerry_value_t value); +``` + +- `value` - api value (possible error object) +- return value + - JERRY_ERROR_NONE if the input is not an error object + - one of the [jerry_error_t](#jerry_error_t) value + +**Example** + +```c +{ + jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_RANGE, + (const jerry_char_t *) "error msg"); + jerry_error_t error_type = jerry_get_error_type (error_obj); + + // error_type is now JERRY_ERROR_RANGE. + + jerry_release_value (error_obj); +} +``` + +**See also** + +- [jerry_create_error](#jerry_create_error) +- [jerry_value_has_error_flag](#jerry_value_has_error_flag) ## jerry_value_has_error_flag @@ -1622,13 +1778,13 @@ jerry_value_set_abort_flag (jerry_value_t *value_p); If the input value is an error value, then return a new reference to its referenced value. Otherwise, return a new reference to the value itself. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_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_t jerry_get_value_without_error_flag (jerry_value_t value) ``` @@ -1640,12 +1796,12 @@ jerry_get_value_without_error_flag (jerry_value_t value) { jerry_value_t value; ... // create or acquire value - + jerry_value_set_error_flag (&value); - + jerry_value_t real_value = jerry_get_value_without_error_flag (value); - ... // process the real_value. Different from `jerry_value_clear_error_flag`, - // the error `value` will not be automatically released after calling + ... // process the real_value. Different from `jerry_value_clear_error_flag`, + // the error `value` will not be automatically released after calling // `jerry_get_value_without_error_flag`. jerry_release_value (value); @@ -1915,6 +2071,12 @@ enough for the whole string. *Note*: Does not put '\0' to the end of string, the return value identifies the number of valid bytes in the output buffer. +*Note*: If the size of the string in jerry value is larger than the size of the +target buffer, the copy will fail. To copy a substring the +[jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer) API function +is recommended instead. + + **Prototype** ```c @@ -1950,6 +2112,7 @@ jerry_string_to_char_buffer (const jerry_value_t value, - [jerry_create_string](#jerry_create_string) - [jerry_get_string_size](#jerry_get_string_size) - [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) +- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer) ## jerry_string_to_utf8_char_buffer @@ -1964,6 +2127,11 @@ large enough for the whole string. *Note*: Does not put '\0' to the end of string, the return value identifies the number of valid bytes in the output buffer. +*Note*: If the size of the string in jerry value is larger than the size of the +target buffer, the copy will fail. To copy a substring the +[jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer) +API function is recommended instead. + **Prototype** ```c @@ -1999,6 +2167,7 @@ jerry_string_to_utf8_char_buffer (const jerry_value_t value, - [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) - [jerry_get_utf8_string_size](#jerry_get_utf8_string_size) - [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) +- [jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer) ## jerry_substring_to_char_buffer @@ -2645,6 +2814,11 @@ jerry_create_boolean (bool value); Create new JavaScript error object. +Important! The `error_type` argument *must not be* +`JERRY_ERROR_NONE`. +Creating an error with no error type is not valid. + + **Prototype** ```c @@ -3126,6 +3300,151 @@ jerry_create_string_sz (const jerry_char_t *str_p, - [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) +## jerry_create_typedarray + +**Summary** + +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. + +**Prototype** + +```c +jerry_value_t +jerry_create_typedarray (jerry_typedarray_type_t type_name, jerry_length_t item_count); +``` + +- `type_name` - type of TypedArray to create +- `item_count` - number of items in the new TypedArray +- return value - the new TypedArray as a `jerry_value_t` + +**Example** + +```c +{ + jerry_value_t array = jerry_create_typedarray (JERRY_TYPEDARRAY_UINT16, 15); + + ... // use the TypedArray + + jerry_release_value (array); +} +``` + +**See also** + +- [jerry_typedarray_type_t](#jerry_typedarray_type_t) +- [jerry_value_is_typedarray](#jerry_value_is_typedarray) +- [jerry_release_value](#jerry_release_value) + + +## jerry_create_typedarray_for_arraybuffer + +**Summary** + +Create a jerry_value_t representing an TypedArray object using +an already existing ArrayBuffer 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. + +The developer must ensure that the ArrayBuffer has the correct length for the given +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. + +**Prototype** + +```c +jerry_value_t +jerry_create_typedarray_for_arraybuffer (jerry_typedarray_type_t type_name, + const jerry_value_t arraybuffer); +``` + +- `type_name` - type of TypedArray to create +- `arraybuffer` - the ArrayBuffer to use for the new TypedArray +- return value + - the new TypedArray as a `jerry_value_t` + - Error if the ArrayBuffer does not have enough space for the given type of TypedArray + +**Example** + +```c +{ + jerry_value_t buffer = jerry_create_array_buffer (12 * 2); + jerry_value_t array = jerry_create_typedarray_for_arraybuffer (JERRY_TYPEDARRAY_UINT16, buffer); + jerry_release_value (buffer); + + ... // use the TypedArray + + jerry_release_value (array); +} +``` + +**See also** + +- [jerry_typedarray_type_t](#jerry_typedarray_type_t) +- [jerry_value_is_typedarray](#jerry_value_is_typedarray) +- [jerry_release_value](#jerry_release_value) + + +## jerry_create_typedarray_for_arraybuffer_sz + +**Summary** + +Create a jerry_value_t representing an TypedArray object using +an already existing ArrayBuffer object and by specifying the byteOffset, and length properties. + +For the new object the type of the TypedArray (see: [jerry_typedarray_type_t](#jerry_typedarray_type_t)) +and element count can be specified. + +The developer must ensure that the ArrayBuffer has the correct length for the given +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. + +**Prototype** + +```c +jerry_value_t +jerry_create_typedarray_for_arraybuffer_sz (jerry_typedarray_type_t type_name, + const jerry_value_t arraybuffer, + jerry_length_t byte_offset, + jerry_length_t length); +``` + +- `type_name` - type of TypedArray to create +- `arraybuffer` - the ArrayBuffer to use for the new TypedArray +- `byte_offset` - start offset to use for the ArrayBuffer +- `length` - number of elements to used from the ArrayBuffer (this is not the same as the byteLength) +- return value + - the new TypedArray as a `jerry_value_t` + - Error if the ArrayBuffer does not have enough space for the given type of TypedArray + +**Example** + +```c +{ + jerry_value_t buffer = jerry_create_array_buffer (12 * 2); + jerry_value_t array = jerry_create_typedarray_for_arraybuffer_sz (JERRY_TYPEDARRAY_UINT16, buffer, 4, 10); + jerry_release_value (buffer); + + ... // use the TypedArray + + jerry_release_value (array); +} +``` + +**See also** + +- [jerry_typedarray_type_t](#jerry_typedarray_type_t) +- [jerry_value_is_typedarray](#jerry_value_is_typedarray) +- [jerry_release_value](#jerry_release_value) + + ## jerry_create_undefined **Summary** @@ -5120,3 +5439,134 @@ jerry_get_arraybuffer_pointer (const jerry_value_t value); **See also** - [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) + + +## jerry_get_typedarray_type + +**Summary** + +Get the type of the TypedArray. + +The returned type is one of the [jerry_typedarray_type_t](#jerry_typedarray_type_t) +enum value. + +**Prototype** + +```c +jerry_typedarray_type_t +jerry_get_typedarray_type (jerry_value_t value); +``` + +- `value` - TypedArray object to query for type. +- return + - the type of the TypedArray + - JERRY_TYPEDARRAY_INVALID if the object was not a TypedArray + +**Example** + +```c +{ + jerry_typedarray_type_t expected_type = JERRY_TYPEDARRAY_UINT32; + jerry_value_t typedarray = jerry_create_typedarray (expected_klass, 25); + + jerry_typedarray_type_t type = jerry_get_typedarray_type (typedarray); + + // 'type' is now JERRY_TYPEDARRAY_UINT32 + + jerry_release_value (typedarray); +} +``` + +**See also** + +- [jerry_create_typedarray](#jerry_create_typedarray) +- [jerry_typedarray_type_t](#jerry_typedarray_type_t) + + +## jerry_get_typedarray_length + +**Summary** + +Get the element count of the TypedArray as specified during creation. + +This is not the same as the byteLength property of a TypedArray object. + +**Prototype** + +``` +jerry_length_t +jerry_get_typedarray_length (jerry_value_t value); +``` + +- `value` - TypedArray object to query +- return + - length (element count) of the TypedArray object + - 0 if the object is not a TypedArray + +**Example** + +```c +{ + jerry_value_t array = jerry_create_typedarray (JERRY_TYPEDARRAY_INT32, 21); + + jerry_length_t element_count = jerry_get_typedarray_length (array); + + // element_count is now 21. + + jerry_release_value (array); +} +``` + +**See also** + +- [jerry_create_typedarray](#jerry_create_typedarray) + + +## jerry_get_typedarray_buffer + +**Summary** + +Get the ArrayBuffer object used by a TypedArray object. +Additionally returns the byteLength and byteOffset properties +of the TypedArray object. + +For the returned ArrayBuffer the [jerry_release_value](#jerry_release_value) +must be called. + +**Prototype** + +```c +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 +- `byteOffset` - (Optional) returns the start offset of the ArrayBuffer for the TypedArray +- `byteLength` - (Optional) returns the number of bytes used from the ArrayBuffer for the TypedArray +- return + - TypedArray object's underlying ArrayBuffer object + - TypeError if the `value` is not a TypedArray object + +**Example** + +```c +{ + jerry_value_t array = jerry_create_typedarray (JERRY_TYPEDARRAY_INT16, 11); + + jerry_length_t byteLength = 0; + jerry_length_t byteOffset = 0; + jerry_value_t buffer = jerry_get_typedarray_buffer (array, &byteOffset, &byteLength); + + // buffer is an ArrayBuffer object and ArrayBuffer operations can be performed on it + // byteLength is 11 * 2 (2 as the TypedArray stores Int16 that is 2 byte elements) + // byteOffset is 0 + + jerry_release_value (buffer); + jerry_release_value (array); +} +``` + +**See also** + +- [jerry_create_typedarray](#jerry_create_typedarray)