diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index 510363e7c4..3b9a7354d6 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -1981,6 +1981,80 @@ jerry_create_string_sz (const jerry_char_t *str_p, - [jerry_create_string](#jerry_create_string) +## jerry_create_string_from_utf8 + +**Summary** + +Create string from a valid UTF8 string. + +*Note*: The difference from [jerry_create_string](#jerry_create_string) is that it accepts utf-8 string instead of cesu-8 string. + +**Prototype** + +```c +jerry_value_t +jerry_create_string_from_utf8 (const jerry_char_t *str_p); +``` + +- `str_p` - pointer to string +- return value - value of the created string + +**Example** + +```c +{ + const jerry_char_t char_array[] = "a string"; + jerry_value_t string_value = jerry_create_string_from_utf8 (char_array); + + ... // usage of string_value + + jerry_release_value (string_value); +} +``` + +**See also** + +- [jerry_create_string_sz_from_utf8](#jerry_create_string_sz_from_utf8) + + +## jerry_create_string_sz_from_utf8 + +**Summary** + +Create string from a valid UTF8 string. + +*Note*: The difference from [jerry_create_string_sz](#jerry_create_string_sz) is that it accepts utf-8 string instead of cesu-8 string. + +**Prototype** + +```c +jerry_value_t +jerry_create_string_sz (const jerry_char_t *str_p, + jerry_size_t str_size) +``` + +- `str_p` - pointer to string +- `str_size` - size of the string +- return value - value of the created string + +**Example** + +```c +{ + const jerry_char_t char_array[] = "a string"; + jerry_value_t string_value = jerry_create_string_sz_from_utf8 (char_array, + strlen ((const char *) char_array)); + + ... // usage of string_value + + jerry_release_value (string_value); +} + +``` + +**See also** + +- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) ## jerry_create_undefined diff --git a/tests/unit/test-api.c b/tests/unit/test-api.c index 41564cde68..bb31a28531 100644 --- a/tests/unit/test-api.c +++ b/tests/unit/test-api.c @@ -339,6 +339,24 @@ main (void) TEST_ASSERT (sz == 0); jerry_release_value (args[0]); + // Test create_jerry_string_from_utf8 with 4-byte long unicode sequences + args[0] = jerry_create_string_from_utf8 ((jerry_char_t *) "\x73\x74\x72\x3a\xf0\x90\x90\x80"); + args[1] = jerry_create_string ((jerry_char_t *) "\x73\x74\x72\x3a\xed\xa0\x81\xed\xb0\x80"); + + jerry_size_t utf8_sz = jerry_get_string_size (args[0]); + jerry_size_t cesu8_sz = jerry_get_string_size (args[1]); + + char string_from_utf8[utf8_sz]; + char string_from_cesu8[cesu8_sz]; + + jerry_string_to_char_buffer (args[1], (jerry_char_t *) string_from_utf8, utf8_sz); + jerry_string_to_char_buffer (args[1], (jerry_char_t *) string_from_cesu8, cesu8_sz); + + TEST_ASSERT (utf8_sz == cesu8_sz); + TEST_ASSERT (!strncmp (string_from_utf8, string_from_cesu8, utf8_sz)); + jerry_release_value (args[0]); + jerry_release_value (args[1]); + // Get global.boo (non-existing field) val_t = get_property (global_obj_val, "boo"); TEST_ASSERT (!jerry_value_has_error_flag (val_t));