Implement external strings. (#4028)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2020-07-22 12:27:12 +02:00
parent 04f0a7a670
commit 0124368ae7
9 changed files with 504 additions and 122 deletions
@@ -4564,6 +4564,100 @@ jerry_create_string_sz_from_utf8 (const jerry_char_t *str_p,
 - [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)


+## jerry_create_external_string
+
+**Summary**
+
+Create an external string from a valid CESU8 string. The string buffer passed to the function
+should not be modified until the free callback is called. This function can be used to avoid
+the duplication of large strings.
+
+*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_external_string (const jerry_char_t *str_p,
+                              jerry_object_native_free_callback_t free_cb)
+```
+
+- `str_p` - non-null pointer to string
+- `free_cb` - optional callback which is called right before the string is freed
+- return value - value of the created string
+
+*New in version [[NEXT_RELEASE]]*
+
+**Example**
+
+```c
+{
+  const char* string_p = "a large and immutable string: this is a story about ....";
+  jerry_value_t string_value  = jerry_create_external_string ((const jerry_char_t *) string_p,
+                                                              NULL);
+
+  ... // usage of string_value
+
+  jerry_release_value (string_value);
+}
+```
+
+**See also**
+
+- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
+- [jerry_create_external_string_sz](#jerry_create_external_string_sz)
+
+
+## jerry_create_external_string_sz
+
+**Summary**
+
+Create an external string from a valid CESU8 string. The string buffer passed to the function
+should not be modified until the free callback is called. This function can be used to avoid
+the duplication of large strings.
+
+*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_external_string_sz (const jerry_char_t *str_p,
+                                 jerry_size_t str_size,
+                                 jerry_object_native_free_callback_t free_cb)
+```
+
+- `str_p` - non-null pointer to string
+- `str_size` - size of the string
+- `free_cb` - optional callback which is called right before the string is freed
+- return value - value of the created string
+
+*New in version [[NEXT_RELEASE]]*
+
+**Example**
+
+```c
+{
+  const char* string_p = "a large and immutable string: this is a story about ....";
+  jerry_value_t string_value  = jerry_create_external_string_sz ((const jerry_char_t *) string_p,
+                                                                 strlen (string_p),
+                                                                 NULL);
+
+  ... // usage of string_value
+
+  jerry_release_value (string_value);
+}
+
+```
+
+**See also**
+
+- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
+- [jerry_create_external_string](#jerry_create_external_string)
+
+
 ## jerry_create_symbol

 **Summary**