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

docs/02.API-REFERENCE.md

@@ -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

jerry-core/api/jerry.c

@@ -1521,6 +1521,11 @@ jerry_get_utf8_string_length (const jerry_value_t value) /**< input string */
  *      Returns 0, if the value parameter is not a string or
  *      the buffer is not large enough for the whole string.
  *
+ * 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 substring use jerry_substring_to_char_buffer() instead.
+ *
  * @return number of bytes, actually copied to the buffer.
  */
 jerry_size_t
@@ -1557,6 +1562,11 @@ jerry_string_to_char_buffer (const jerry_value_t value, /**< input string value
  *      Returns 0, if the value parameter is not a string or the buffer
  *      is not large enough for the whole string.
  *
+ * 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 use jerry_substring_to_utf8_char_buffer() instead.
+ *
  * @return number of bytes copied to the buffer.
  */
 jerry_size_t