Update the webpage (#2206)

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
2025-12-15 16:29:21 +00:00 · 2018-02-19 03:28:57 +01:00 · 2018-02-19 03:28:57 +01:00 · 41fa2aa172
commit 41fa2aa172
parent 38bb39e744
1 changed files with 457 additions and 7 deletions
--- 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)