From 97303eb8e42edab38f104403a8ca77fbea996d85 Mon Sep 17 00:00:00 2001
From: Robert Sipka <rsipka.uszeged@partner.samsung.com>
Date: Thu, 24 Nov 2016 00:12:09 +0100
Subject: [PATCH] Add API documentation for jerry_create_string_from_utf8 and
 jerry_create_string_sz_from_utf8 functions. (#1444)

JerryScript-DCO-1.0-Signed-off-by: Robert Sipka rsipka.uszeged@partner.samsung.com
---
 docs/02.API-REFERENCE.md | 74 ++++++++++++++++++++++++++++++++++++++++
 tests/unit/test-api.c    | 18 ++++++++++
 2 files changed, 92 insertions(+)

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 510363e7c..3b9a7354d 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 41564cde6..bb31a2853 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));