Add new symbol related API functions. (#2741)

New functions: - ecma_create_symbol - ecma_value_is_symbol - jerry_get_symbol_descriptive_string Also improve the jerryx_handler_print to be able to print symbol values via using the jerry_get_symbol_descriptive_string API function for symbol values. JerryScript-DCO-1.0-Signed-off-by: Robert Fancsik frobert@inf.u-szeged.hu
2019-02-19 07:45:50 +01:00
parent cffb299f37
commit 60bbd731e5
6 changed files with 486 additions and 15 deletions
@@ -24,6 +24,7 @@ Enum that contains JerryScript API value types:
 - JERRY_TYPE_OBJECT - object type
 - JERRY_TYPE_FUNCTION - function type
 - JERRY_TYPE_ERROR - error/abort type
+ - JERRY_TYPE_SYMBOL - symbol type

 ## jerry_error_t

@@ -61,6 +62,7 @@ Possible compile time enabled feature types:
 - JERRY_FEATURE_REGEXP - RegExp support
 - JERRY_FEATURE_LINE_INFO - line info available
 - JERRY_FEATURE_LOGGING - logging
+ - JERRY_FEATURE_SYMBOL - symbol support

 ## jerry_regexp_flags_t

@@ -1567,6 +1569,57 @@ jerry_value_is_string (const jerry_value_t value)
 - [jerry_release_value](#jerry_release_value)


+## jerry_value_is_symbol
+
+**Summary**
+
+Returns whether the given `jerry_value_t` is a symbol value.
+
+**Prototype**
+
+```c
+bool
+jerry_value_is_symbol (const jerry_value_t value)
+```
+
+- `value` - API value
+- return value
+  - true, if the given `jerry_value_t` is a symbol
+  - false, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "Symbol description string");
+  jerry_value_t symbol_value = jerry_create_symbol (string_value);
+
+  jerry_release_value (string_value);
+
+  if (jerry_value_is_symbol (symbol_value))
+  {
+    // usage of symbol_value
+  }
+
+  jerry_release_value (symbol_value);
+
+  jerry_cleanup ();
+}
+```
+
+**See also**
+
+- [jerry_release_value](#jerry_release_value)
+
+
 ## jerry_value_is_typedarray

 **Summary**
@@ -2821,6 +2874,59 @@ jerry_resolve_or_reject_promise (jerry_value_t promise,
 - [jerry_release_value](#jerry_release_value)
 - [jerry_value_is_error](#jerry_value_is_error)

+# Functions for symbols
+
+These APIs all depend on the ES2015-subset profile.
+
+## jerry_get_symbol_descriptive_string
+
+**Summary**
+
+Call the SymbolDescriptiveString ecma builtin operation on the API 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_get_symbol_descriptive_string (const jerry_value_t value);
+```
+
+- `value` - symbol value
+- return value
+  - string value containing the symbol's descriptive string - if success
+  - thrown error, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "foo");
+  jerry_value_t symbol_value = jerry_create_symbol (string_value);
+
+  jerry_release_value (string_value);
+
+  jerry_value_t symbol_desc_string = jerry_get_symbol_descriptive_string (symbol_value);
+
+  // usage of symbol_desc_string
+
+  jerry_release_value (symbol_desc_string);
+  jerry_release_value (symbol_value);
+
+  jerry_cleanup ();
+}
+```
+

 # Acquire and release API values

@@ -3546,6 +3652,58 @@ jerry_create_string_sz (const jerry_char_t *str_p,
 - [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)


+## jerry_create_symbol
+
+**Summary**
+
+Create symbol from an API value.
+
+*Note*: The given argument is converted to string. This operation can throw an error.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_symbol (const jerry_value_t value)
+```
+
+- `value` - API value
+- return value
+  - value of the created symbol, if success
+  - thrown error, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "Symbol description string");
+  jerry_value_t symbol_value = jerry_create_symbol (string_value);
+
+  // The description value is no longer needed
+  jerry_release_value (string_value);
+
+  // usage of symbol_value
+
+  jerry_release_value (symbol_value);
+
+  jerry_cleanup ();
+}
+```
+
+**See also**
+
+- [jerry_value_is_symbol](#jerry_value_is_symbol)
+- [jerry_release_value](#jerry_release_value)
+
+
 ## jerry_create_regexp

 **Summary**