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
2018-02-06 08:01:32 +01:00
parent 0cc98340c3
commit 8041953a7a
6 changed files with 1168 additions and 1 deletions
@@ -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)