diff options
author | Péter Gál <pgal.u-szeged@partner.samsung.com> | 2018-02-06 08:01:32 +0100 |
---|---|---|
committer | László Langó <llango.u-szeged@partner.samsung.com> | 2018-02-06 08:01:32 +0100 |
commit | 8041953a7ab60cc91a6fe1ae65f728bb25f29bda (patch) | |
tree | 309979f838bcce285023987b167ab118c4e45d5c /docs | |
parent | 0cc98340c327e4e6bac409508a5e132e4b3d9622 (diff) |
Add TypedArray C API (#2165)
New API functions added:
- jerry_value_is_typedarray
- jerry_create_typedarray
- jerry_create_typedarray_for_arraybuffer_sz
- jerry_create_typedarray_for_arraybuffer
- jerry_get_typedarray_type
- jerry_get_typedarray_length
- jerry_get_typedarray_buffer
JerryScript-DCO-1.0-Signed-off-by: Peter Gal pgal.u-szeged@partner.samsung.com
Diffstat (limited to 'docs')
-rw-r--r-- | docs/02.API-REFERENCE.md | 335 |
1 files changed, 335 insertions, 0 deletions
diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index 37cb0549..f41a4560 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -296,6 +296,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 @@ -1347,6 +1367,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** @@ -3129,6 +3188,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** @@ -5123,3 +5327,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) |