diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index a9af3bcc8..5b7a50e45 100644 --- a/docs/02.API-REFERENCE.md +++ b/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`). diff --git a/jerry-core/api/jerry.c b/jerry-core/api/jerry.c index f13cd5112..0696b4d0d 100644 --- a/jerry-core/api/jerry.c +++ b/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. * diff --git a/jerry-core/include/jerryscript-core.h b/jerry-core/include/jerryscript-core.h index 00b93ec30..0d7f07313 100644 --- a/jerry-core/include/jerryscript-core.h +++ b/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); /** diff --git a/tests/unit-core/test-symbol.c b/tests/unit-core/test-symbol.c index 1aed532fc..ad84010fd 100644 --- a/tests/unit-core/test-symbol.c +++ b/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);