New jerry_get_symbol_description API function (#4206)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com

docs/02.API-REFERENCE.md

@@ -3996,6 +3996,68 @@ main (void)
 
 - [jerry_well_known_symbol_t](#jerry_well_known_symbol_t)
 
+## jerry_get_symbol_description
+
+**Summary**
+
+Returns with the `[[Description]]` internal property of a symbol value.
+
+*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 error will be returned.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_symbol_description (const jerry_value_t value);
+```
+
+- `value` - symbol value
+- return value
+  - string or undefined value containing the symbol's description - if success
+  - thrown error, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**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_description = jerry_get_symbol_description (symbol_value);
+
+  // usage of symbol_desc_string
+
+  jerry_release_value (symbol_description);
+  jerry_release_value (symbol_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_get_symbol_descriptive_string](#jerry_get_symbol_descriptive_string)
+
 ## jerry_get_symbol_descriptive_string
 
 **Summary**
@@ -4055,6 +4117,10 @@ main (void)
 }
 ```
 
+**See also**
+
+- [jerry_get_symbol_description](#jerry_get_symbol_description)
+
 # Functions for BigInts
 
 These APIs all depend on build option (`JERRY_BUILTIN_BIGINT`).

jerry-core/api/jerry.c

@@ -3790,6 +3790,35 @@ jerry_get_well_known_symbol (jerry_well_known_symbol_t symbol) /**< jerry_well_k
 #endif /* ENABLED (JERRY_ESNEXT) */
 } /** jerry_get_well_known_symbol */
 
+/**
+ * Returns the description internal property of a symbol.
+ *
+ * Note:
+ *      returned value must be freed with jerry_release_value, when it is no longer needed.
+ *
+ * @return string or undefined value containing the symbol's description - if success
+ *         thrown error - otherwise
+ */
+jerry_value_t
+jerry_get_symbol_description (const jerry_value_t symbol) /**< symbol value */
+{
+  jerry_assert_api_available ();
+
+#if ENABLED (JERRY_ESNEXT)
+  if (!ecma_is_value_symbol (symbol))
+  {
+    return jerry_throw (ecma_raise_type_error (ECMA_ERR_MSG (wrong_args_msg_p)));
+  }
+
+  /* Note: This operation cannot throw an error */
+  return ecma_get_symbol_description (ecma_get_symbol_from_value (symbol));
+#else /* !ENABLED (JERRY_ESNEXT) */
+  JERRY_UNUSED (symbol);
+
+  return jerry_throw (ecma_raise_type_error (ECMA_ERR_MSG ("Symbol is not supported.")));
+#endif /* ENABLED (JERRY_ESNEXT) */
+} /* jerry_get_symbol_description */
+
 /**
  * Call the SymbolDescriptiveString ecma builtin operation on the symbol value.
  *

jerry-core/include/jerryscript-core.h

@@ -671,6 +671,7 @@ typedef enum
 } jerry_well_known_symbol_t;
 
 jerry_value_t jerry_get_well_known_symbol (jerry_well_known_symbol_t symbol);
+jerry_value_t jerry_get_symbol_description (const jerry_value_t symbol);
 jerry_value_t jerry_get_symbol_descriptive_string (const jerry_value_t symbol);
 
 /**

tests/unit-core/test-symbol.c

@@ -27,6 +27,9 @@
 /* Symbol(bar) desciptive string */
 #define SYMBOL_DESCIPTIVE_STRING_BAR "Symbol(bar)"
 
+/* bar string desciption */
+#define SYMBOL_DESCIPTION_BAR "bar"
+
 int
 main (void)
 {
@@ -177,8 +180,31 @@ main (void)
   TEST_ASSERT (memcmp (str_buff, SYMBOL_DESCIPTIVE_STRING_BAR, sizeof (SYMBOL_DESCIPTIVE_STRING_BAR) - 1) == 0);
 
   jerry_release_value (bar_symbol_string);
+
+  /* Test symbol get description operation with string description */
+  bar_symbol_string = jerry_get_symbol_description (bar_symbol);
+  TEST_ASSERT (jerry_value_is_string (bar_symbol_string));
+
+  bar_symbol_string_size = jerry_get_string_size (bar_symbol_string);
+  TEST_ASSERT (bar_symbol_string_size == (sizeof (SYMBOL_DESCIPTION_BAR) - 1));
+
+  jerry_string_to_char_buffer (bar_symbol_string, str_buff, bar_symbol_string_size);
+  TEST_ASSERT (memcmp (str_buff, STRING_BAR, sizeof (SYMBOL_DESCIPTION_BAR) - 1) == 0);
+
   jerry_release_value (bar_symbol);
 
+  /* Test symbol get description operation with undefined description */
+  jerry_value_t undefined_value = jerry_create_undefined ();
+  jerry_value_t undefined_symbol = jerry_create_symbol (undefined_value);
+  jerry_release_value (undefined_value);
+  TEST_ASSERT (!jerry_value_is_error (bar_symbol));
+  TEST_ASSERT (jerry_value_is_symbol (bar_symbol));
+
+  undefined_value = jerry_get_symbol_description (undefined_symbol);
+  TEST_ASSERT (jerry_value_is_undefined (undefined_value));
+  jerry_release_value (undefined_value);
+  jerry_release_value (undefined_symbol);
+
   /* Test symbol to string operation with non-symbol argument */
   jerry_value_t null_value = jerry_create_null ();
   jerry_value_t to_string_value = jerry_get_symbol_descriptive_string (null_value);