diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index b1635163de..74fe12f2f2 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -1003,6 +1003,44 @@ jerry_value_is_array (const jerry_value_t value) - [jerry_release_value](#jerry_release_value) +## jerry_value_is_arraybuffer + +**Summary** + +Returns whether the given `jerry_value_t` is an ArrayBuffer object. + +**Prototype** + +```c +bool +jerry_value_is_arraybuffer (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is an ArrayBuffer object. + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_arraybuffer (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_create_arraybuffer](#jerry_create_arraybuffer) + ## jerry_value_is_boolean @@ -2401,6 +2439,42 @@ jerry_create_array (uint32_t size); - [jerry_get_property_by_index](#jerry_get_property_by_index) +## jerry_create_arraybuffer + +**Summary** + +Create a jerry_value_t representing an ArrayBuffer object. + +**Prototype** + +```c +jerry_value_t +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` + +**Example** + +```c +{ + jerry_value_t buffer_value = jerry_create_arraybuffer (15); + + ... // use the ArrayBuffer + + jerry_release_value (buffer_value); +} +``` + +**See also** + +- [jerry_arraybuffer_read](#jerry_arraybuffer_read) +- [jerry_arraybuffer_write](#jerry_arraybuffer_write) +- [jerry_value_is_arraybuffer](#jerry_value_is_arraybuffer) +- [jerry_release_value](#jerry_release_value) + + ## jerry_create_boolean **Summary** @@ -4689,3 +4763,171 @@ main (void) - [jerry_parse](#jerry_parse) - [jerry_run](#jerry_run) - [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t) + + +# ArrayBuffer and TypedArray functions + +## jerry_get_arraybuffer_byte_length + +**Summary** + +Get the byte length property of the ArrayBuffer. This is the +same value which was passed to the ArrayBuffer constructor call. + +**Prototype** + +```c +jerry_length_t +jerry_get_arraybuffer_byte_length (const jerry_value_t value); +``` + +- `value` - ArrayBuffer object +- return value + - size of the ArrayBuffer in bytes + - 0 if the `value` parameter is not an ArrayBuffer + +**Example** + +```c +{ + jerry_value_t buffer = jerry_create_arraybuffer (15); + jerry_length_t length = jerry_get_arraybuffer_byte_length (buffer); + // length should be 15 + + jerry_release_value (buffer); +} +``` + +**See also** +- [jerry_create_arraybuffer](#jerry_create_arraybuffer) + + +## jerry_arraybuffer_read + +**Summary** + +Copy the portion of the ArrayBuffer into a user provided buffer. +The start offset of the read operation can be specified. + +The number bytes to be read can be specified via the `buf_size` +parameter. It is not possible to read more than the length of +the ArrayBuffer. + +Function returns the number of bytes read from the ArrayBuffer +(and written to the buffer parameter). This value is +calculated in the following way: `min(array buffer length - offset, buf_size)`. + +**Prototype** + +```c +jerry_length_t +jerry_arraybuffer_read (const jerry_value_t value, + jerry_length_t offset, + uint8_t *buf_p, + jerry_length_t buf_size); +``` + +- `value` - ArrayBuffer to read from +- `offset` - start offset of the read operation +- `buf_p` - buffer to read the data to +- `buf_size` - maximum number of bytes to read into the buffer +- return value + - number of bytes written into the buffer (read from the ArrayBuffer) + - 0 if the `value` is not an ArrayBuffer object + - 0 if the `buf_size` is zero or there is nothing to read + +**Example** + +```c +{ + uint8_t data[20]; + jerry_value_t buffer; + // ... create the ArrayBuffer or acuiqre it from somewhere. + + jerry_value_t bytes_read; + + // read 10 bytes from the start of the ArrayBuffer. + bytes_read = jerry_arraybuffer_read (buffer, 0, data, 10); + // read the next 10 bytes + bytes_read += jerry_arraybuffer_read (buffer, bytes_read, data + bytes_read, 10); + + // process the data variable + + jerry_release_value (buffer); +} +``` + +**See also** + +- [jerry_create_arraybuffer](#jerry_create_arraybuffer) +- [jerry_arraybuffer_write](#jerry_arraybuffer_write) +- [jerry_get_arraybuffer_byte_length](#jerry_get_arraybuffer_byte_length) + + +## jerry_arraybuffer_write + +**Summary** + +Copy the contents of a buffer into the ArrayBuffer. +The start offset of the write operation can be specified. + +The number bytes to be written can be specified via the `buf_size` +parameter. It is not possible to write more than the length of +the ArrayBuffer. + +Function returns the number of bytes written into the ArrayBuffer +(and read from the buffer parameter). This value is +calculated in the following way: `min(array buffer length - offset, buf_size)`. + +**Prototype** + +```c +jerry_length_t +jerry_arraybuffer_write (const jerry_value_t value, + jerry_length_t offset, + const uint8_t *buf_p, + jerry_length_t buf_size); +``` + +- `value` - ArrayBuffer to write to +- `offset` - start offset of the write operation +- `buf_p` - buffer to read the data from +- `buf_size` - maximum number of bytes to write into the ArrayBuffer +- return value + - number of bytes written into the ArrayBuffer (read from the buffer parameter) + - 0 if the `value` is not an ArrayBuffer object + - 0 if the `buf_size` is zero or there is nothing to write + +**Example** + +```c +{ + uint8_t data[20]; + + // fill the data with values + for (int i = 0; i < 20; i++) + { + data[i] = (uint8_t) (i * 2); + } + + jerry_value_t buffer; + // ... create the ArrayBuffer or acquire it from somewhere. + + jerry_value_t bytes_written; + + // write 10 bytes from to the start of the ArrayBuffer. + bytes_written = jerry_arraybuffer_write (buffer, 0, data, 10); + // read the next 10 bytes + bytes_written += jerry_arraybuffer_write (buffer, bytes_written, data + bytes_written, 10); + + // use the ArrayBuffer + + jerry_release_value (buffer); +} +``` + +**See also** + +- [jerry_create_arraybuffer](#jerry_create_arraybuffer) +- [jerry_arraybuffer_write](#jerry_arraybuffer_write) +- [jerry_get_arraybuffer_byte_length](#jerry_get_arraybuffer_byte_length) diff --git a/09.EXT-REFERENCE-ARG.md b/09.EXT-REFERENCE-ARG.md index 470607d859..9f1fe3de2b 100644 --- a/09.EXT-REFERENCE-ARG.md +++ b/09.EXT-REFERENCE-ARG.md @@ -38,6 +38,7 @@ typedef struct - [jerryx_arg_number](#jerryx_arg_number) - [jerryx_arg_boolean](#jerryx_arg_boolean) - [jerryx_arg_string](#jerryx_arg_string) +- [jerryx_arg_utf8_string](#jerryx_arg_utf8_string) - [jerryx_arg_function](#jerryx_arg_function) - [jerryx_arg_native_pointer](#jerryx_arg_native_pointer) - [jerryx_arg_ignore](#jerryx_arg_ignore) @@ -471,7 +472,7 @@ jerryx_arg_boolean (bool *dest, **Summary** Create a validation/transformation step (`jerryx_arg_t`) that expects to -consume one `string` JS argument and stores it into a C `char` array. +consume one `string` JS argument and stores it into a CESU-8 C `char` array. **Prototype** @@ -492,6 +493,36 @@ jerryx_arg_string (char *dest, **See also** - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) +- [jerry_arg_utf8_string](#jerry_arg_utf8_string) + + +## jerryx_arg_utf8_string + +**Summary** + +Create a validation/transformation step (`jerryx_arg_t`) that expects to +consume one `string` JS argument and stores it into a UTF-8 C `char` array. + +**Prototype** + +```c +static inline jerryx_arg_t +jerryx_arg_utf8_string (char *dest, + uint32_t size, + jerryx_arg_coerce_t coerce_flag, + jerryx_arg_optional_t opt_flag) +``` + + - return value - the created `jerryx_arg_t` instance. + - `dest` - pointer to the native char array where the result should be stored. + - `size` - the size of native char array. + - `coerce_flag` - whether type coercion is allowed. + - `opt_flag` - whether the argument is optional. + +**See also** + +- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) +- [jerry_arg_string](#jerry_arg_string) ## jerryx_arg_function