Introduce new API function to obtain well-known symbols (#4163)

- jerry_get_well_known_symbol JerryScript-DCO-1.0-Signed-off-by: Robert Fancsik frobert@inf.u-szeged.hu
2020-08-31 10:03:05 +02:00
parent 2f08d8ac08
commit 1fd0cac8c9
5 changed files with 259 additions and 1 deletions
@@ -141,6 +141,25 @@ Container object types:

 *New in version 2.3*.

+## jerry_well_known_symbol_t
+
+Well-known symbols:
+
+ - JERRY_SYMBOL_HAS_INSTANCE - @@hasInstance well-known symbol
+ - JERRY_SYMBOL_IS_CONCAT_SPREADABLE - @@isConcatSpreadable well-known symbol
+ - JERRY_SYMBOL_ITERATOR - @@iterator well-known symbol
+ - JERRY_SYMBOL_ASYNC_ITERATOR - @@asyncIterator well-known symbol
+ - JERRY_SYMBOL_MATCH - @@match well-known symbol
+ - JERRY_SYMBOL_REPLACE - @@replace well-known symbol
+ - JERRY_SYMBOL_SEARCH - @@search well-known symbol
+ - JERRY_SYMBOL_SPECIES - @@species well-known symbol
+ - JERRY_SYMBOL_SPLIT - @@split well-known symbol
+ - JERRY_SYMBOL_TO_PRIMITIVE - @@toPrimitive well-known symbol
+ - JERRY_SYMBOL_TO_STRING_TAG - @@toStringTag well-known symbol
+ - JERRY_SYMBOL_UNSCOPABLES - @@unscopables well-known symbol
+
+ *New in version [[NEXT_RELEASE]]*.
+
 ## jerry_regexp_flags_t

 RegExp object optional flags:
@@ -3917,6 +3936,66 @@ jerry_resolve_or_reject_promise (jerry_value_t promise,

 These APIs all depend on the es.next profile (or on build options).

+## jerry_get_well_known_symbol
+
+**Summary**
+
+Get the well-known symbol corresponding to the given [well-known symbol id](#jerry_well_known_symbol_t).
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_BUILTIN_SYMBOL`) and can be checked
+  in runtime with the `JERRY_FEATURE_SYMBOL` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The es.next profile enables this by default.
+- If the symbol support is not enabled an undefined will be returned.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_well_known_symbol (jerry_well_known_symbol_t symbol);
+```
+
+- `symbol` - [jerry_well_known_symbol_t](#jerry_well_known_symbol_t) enum value
+- return value
+  - undefined value - if invalid well-known symbol was requested
+  - well-known symbol value, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t array_value = jerry_create_array (5);
+  jerry_value_t symbol_iterator = jerry_get_well_known_symbol (JERRY_SYMBOL_ITERATOR);
+  jerry_value_t array_iterator = jerry_get_property (array_value, symbol_iterator);
+
+  // usage of array_iterator
+
+  jerry_release_value (array_iterator);
+  jerry_release_value (symbol_iterator);
+  jerry_release_value (array_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_well_known_symbol_t](#jerry_well_known_symbol_t)
+
 ## jerry_get_symbol_descriptive_string

 **Summary**