Copy the characters of an UTF-8 encoded substring into a specified buffer (#1524)

JerryScript-DCO-1.0-Signed-off-by: Robert Sipka rsipka.uszeged@partner.samsung.com

docs/02.API-REFERENCE.md

@@ -1406,7 +1406,7 @@ jerry_string_to_utf8_char_buffer (const jerry_value_t value,
 
 Copy the characters of a cesu-8 encoded substring into a specified buffer.
 The '\0' character could occur in character buffer. Returns 0, if the value
-parameter is not a string. It will extract the substring beetween the
+parameter is not a string. It will extract the substring between the
 specified start position and the end position (or the end of the string,
 whichever comes first).
 
@@ -1452,6 +1452,57 @@ jerry_substring_to_char_buffer (const jerry_value_t value,
 - [jerry_get_string_size](#jerry_get_string_size)
 - [jerry_get_string_length](#jerry_get_string_length)
 
+## jerry_substring_to_utf8_char_buffer
+
+**Summary**
+
+Copy the characters of an utf-8 encoded substring into a specified buffer.
+The '\0' character could occur in character buffer. Returns 0, if the value
+parameter is not a string. It will extract the substring between the specified
+start position and the end position (or the end of the string, whichever
+comes first).
+
+**Prototype**
+
+```c
+jerry_size_t
+jerry_substring_to_utf8_char_buffer (const jerry_value_t value,
+                                     jerry_length_t start_pos,
+                                     jerry_length_t end_pos,
+                                     jerry_char_t *buffer_p,
+                                     jerry_size_t buffer_size);
+```
+
+- `value` - input string value
+- `start_pos` - position of the first character
+- `end_pos` - position of the last character
+- `buffer_p` - pointer to output buffer
+- `buffer_size` - size of the buffer
+- return value - number of bytes, actually copied to the buffer
+
+**Example**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_size_t req_sz = jerry_get_utf8_string_size (value);
+  jerry_char_t str_buf_p[req_sz];
+  jerry_length_t start_pos = 0;
+  jerry_length_t end_pos = jerry_get_utf8_string_length (value);
+
+  jerry_substring_to_utf8_char_buffer (value, start_pos, end_pos, str_buf_p, req_sz);
+
+  jerry_release_value (value);
+}
+```
+
+**See also**
+
+- [jerry_create_string_from_utf8](#jerry_create_string)
+- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size)
+- [jerry_get_utf8_string_length](#jerry_get_utf8_string_length)
 # Functions for array object values
 
 ## jerry_get_array_length