Update documentation for jerry string to buffer function with suggestions to use substring. (#2174) (#2174)

In some use cases, you want to reliably copy jerry strings to buffer, even if it doesn't fit target buffer, but is acceptable to lose some bytes. In those cases, the documentation will now suggest using the substring function as an alternative instead.

JerryScript-DCO-1.0-Signed-off-by: Brian Khuu mofosyne@gmail.com

1 files changed, 19 insertions, 6 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 1d18b611..37cb0549 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -1612,13 +1612,13 @@ jerry_value_set_abort_flag (jerry_value_t *value_p);
 If the input value is an error value, then return a new reference to its referenced value.
 Otherwise, return a new reference to the value itself.
 
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) 
+*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_value_t
 jerry_get_value_without_error_flag (jerry_value_t value)
 ```
 
@@ -1630,12 +1630,12 @@ jerry_get_value_without_error_flag (jerry_value_t value)
 {
   jerry_value_t value;
   ... // create or acquire value
-  
+
   jerry_value_set_error_flag (&value);
-  
+
   jerry_value_t real_value = jerry_get_value_without_error_flag (value);
-  ... // process the real_value. Different from `jerry_value_clear_error_flag`, 
-      // the error `value` will not be automatically released after calling 
+  ... // process the real_value. Different from `jerry_value_clear_error_flag`,
+      // the error `value` will not be automatically released after calling
       // `jerry_get_value_without_error_flag`.
 
   jerry_release_value (value);
@@ -1905,6 +1905,12 @@ enough for the whole string.
 *Note*: Does not put '\0' to the end of string, the return value identifies
 the number of valid bytes in the output buffer.
 
+*Note*: If the size of the string in jerry value is larger than the size of the
+target buffer, the copy will fail. To copy a substring the
+[jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer) API function
+is recommended instead.
+
+
 **Prototype**
 
 ```c
@@ -1940,6 +1946,7 @@ jerry_string_to_char_buffer (const jerry_value_t value,
 - [jerry_create_string](#jerry_create_string)
 - [jerry_get_string_size](#jerry_get_string_size)
 - [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
+- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer)
 
 
 ## jerry_string_to_utf8_char_buffer
@@ -1954,6 +1961,11 @@ large enough for the whole string.
 *Note*: Does not put '\0' to the end of string, the return value identifies
 the number of valid bytes in the output buffer.
 
+*Note*: If the size of the string in jerry value is larger than the size of the
+target buffer, the copy will fail. To copy a substring the
+[jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer)
+API function is recommended instead.
+
 **Prototype**
 
 ```c
@@ -1989,6 +2001,7 @@ jerry_string_to_utf8_char_buffer (const jerry_value_t value,
 - [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)
 - [jerry_get_utf8_string_size](#jerry_get_utf8_string_size)
 - [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string)
+- [jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer)
 
 
 ## jerry_substring_to_char_buffer