@@ -3750,7 +3750,7 @@ jerry_error_type (const jerry_value_t value);
37503750
37513751```c
37523752{
3753- jerry_value_t error_obj = jerry_error_sz (JERRY_ERROR_RANGE, "error msg");
3753+ jerry_value_t error_obj = jerry_error_sz (JERRY_ERROR_RANGE, jerry_string_sz ( "error msg") );
37543754 jerry_error_t error_type = jerry_error_type (error_obj);
37553755
37563756 // error_type is now JERRY_ERROR_RANGE.
@@ -3868,7 +3868,7 @@ void main(void)
38683868
38693869 jerry_error_on_created (error_object_created_callback, NULL);
38703870
3871- jerry_value_free (jerry_error_sz (JERRY_ERROR_COMMON, "Message"));
3871+ jerry_value_free (jerry_error_sz (JERRY_ERROR_COMMON, jerry_string_sz ( "Message") ));
38723872
38733873 jerry_cleanup ();
38743874} /* main */
@@ -4062,7 +4062,7 @@ throw_exception (const jerry_call_info_t *call_info_p, /**< call info */
40624062 (void) argv;
40634063 (void) argc;
40644064
4065- jerry_value_t result_value = jerry_throw_sz (JERRY_ERROR_COMMON, "Error!");
4065+ jerry_value_t result_value = jerry_throw_sz (JERRY_ERROR_COMMON, jerry_string_sz ( "Error!") );
40664066
40674067 /* Ignore calling the vm_throw_callback function. */
40684068 jerry_exception_allow_capture (result_value, false);
@@ -4353,7 +4353,7 @@ main (void)
43534353
43544354 jerry_string_external_on_free (external_string_free_callback);
43554355
4356- const char * string_p = "This is a long external string, should not be duplicated!";
4356+ #define string_p "This is a long external string, should not be duplicated!"
43574357 jerry_value_t external_string = jerry_string_external_sz (string_p, NULL);
43584358 /* The external_string_free_callback is called. */
43594359 jerry_value_free (external_string);
@@ -4414,7 +4414,7 @@ main (void)
44144414{
44154415 jerry_init (JERRY_INIT_EMPTY);
44164416
4417- const char * string_p = "This is a long external string, should not be duplicated!";
4417+ #define string_p "This is a long external string, should not be duplicated!"
44184418
44194419 jerry_value_t external_string = jerry_string_external_sz (string_p, (void *) &user_value);
44204420
@@ -6903,13 +6903,13 @@ jerry_boolean (bool value);
69036903
69046904**Summary**
69056905
6906- Create new JavaScript Error object with the specified error message.
6906+ Create an Error object with the provided `message` string value as the error `message` property.
6907+ If the `message` value is not a string, the created error will not have a `message` property.
69076908
6908- Important! The `error_type` argument *must not be* `JERRY_ERROR_NONE`.
6909- Creating an Error object with no error type is not valid.
6910-
6911- *Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it
6912- is no longer needed.
6909+ *Note*:
6910+ - Important! The `error_type` argument *must not be* `JERRY_ERROR_NONE`.
6911+ Creating an Error object with no error type is not valid.
6912+ - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed.
69136913
69146914**Prototype**
69156915
@@ -6948,27 +6948,31 @@ jerry_error (jerry_error_t error_type, jerry_value_t message);
69486948
69496949**Summary**
69506950
6951- Create new JavaScript Error object, using the a zero-terminated string as the error message.
6951+ Create an Error object with the provided `message_sz` string value as the error `message` property.
6952+ If the `message_sz` value is not a string, the created error will not have a `message` property.
69526953
6953- *Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it
6954- is no longer needed.
6954+ *Note*:
6955+ - Important! The `error_type` argument *must not be* `JERRY_ERROR_NONE`.
6956+ Creating an Error object with no error type is not valid.
6957+ - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed.
6958+ - The `message_sz` value will be freed in this function.
69556959
69566960**Prototype**
69576961
69586962```c
69596963jerry_value_t
6960- jerry_error_sz (jerry_error_t error_type, const char *message_p );
6964+ jerry_error_sz (jerry_error_t error_type, const jerry_value_t message_sz );
69616965```
69626966
69636967- `error_type` - type of the error
6964- - `message_p ` - value of ' message' property of the constructed error object
6968+ - `message_sz ` - message of the error that will be free/take
69656969- return value - constructed error object
69666970
69676971**Example**
69686972
69696973```c
69706974{
6971- jerry_value_t error_obj = jerry_error_sz (JERRY_ERROR_TYPE, "error");
6975+ jerry_value_t error_obj = jerry_error_sz (JERRY_ERROR_TYPE, jerry_string_sz ( "error") );
69726976
69736977 ... // usage of error_obj
69746978
@@ -7472,26 +7476,28 @@ main (void)
74727476
74737477**Summary**
74747478
7475- Create string from a zero-terminated ASCII string.
7479+ Create string value from the zero-terminated UTF-8 encoded literal string.
7480+ The content of the buffer is assumed be encoded correctly, it's the callers
7481+ responsibility to validate the input.
74767482
7477- *Note*: Returned value must be freed with [jerry_value_free](#jerry_value_free) when it
7478- is no longer needed.
7483+ *Note*:
7484+ - This is a macro that only accept literal string
7485+ - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed.
74797486
74807487**Prototype**
74817488
74827489```c
7483- jerry_value_t
7484- jerry_string_sz (const char *str_p);
7490+ #define jerry_string_sz(str)
74857491```
74867492
7487- - `str_p ` - non-null pointer to string
7493+ - `str ` - An zero-terminated UTF-8 encoded literal string
74887494- return value - created string
74897495
74907496**Example**
74917497
74927498```c
74937499{
7494- const char char_array[] = "a string";
7500+ #define char_array "a string"
74957501 jerry_value_t string_value = jerry_string_sz (char_array);
74967502
74977503 ... // usage of string_value
@@ -7502,7 +7508,7 @@ jerry_string_sz (const char *str_p);
75027508
75037509**See also**
75047510
7505- - [jerry_string ](#jerry_string )
7511+ - [jerry_string_utf8 ](#jerry_string_utf8 )
75067512
75077513
75087514## jerry_string
@@ -7548,31 +7554,120 @@ jerry_string (const jerry_char_t *buffer_p,
75487554
75497555- [jerry_validate_string](#jerry_validate_string)
75507556- [jerry_string_sz](#jerry_string_sz)
7557+ - [jerry_string_utf8](#jerry_string_utf8)
7558+ - [jerry_string_cesu8](#jerry_string_cesu8)
75517559
75527560
7553- ## jerry_string_external_sz
7561+ ## jerry_string_utf8
75547562
75557563**Summary**
75567564
7557- Create an external string from a zero-terminated ASCII string. The string buffer passed to the function
7558- should not be modified until the free callback is called. This function can be used to avoid
7559- the duplication of large strings .
7565+ Create a string value from the input buffer using the UTF-8 encoding.
7566+ The content of the buffer is assumed to be valid in the UTF-8 encoding,
7567+ it's the callers responsibility to validate the input .
75607568
75617569*Note*:
7562- - The free callback can be set by [jerry_string_external_on_free](#jerry_string_external_on_free)
7563- - Returned value must be freed with [jerry_value_free](#jerry_value_free)
7564- when it is no longer needed.
7570+ - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed.
75657571
75667572**Prototype**
75677573
75687574```c
75697575jerry_value_t
7570- jerry_string_external_sz (const char *str_p, void *user_p);
7576+ jerry_string_utf8 (const jerry_char_t *buffer_p,
7577+ jerry_size_t buf_size)
75717578```
75727579
7573- - `str_p` - non-null pointer to string
7580+ - `buffer_p` - non-null pointer to buffer
7581+ - `buf_size` - size of the buffer
7582+
7583+ **Example**
7584+
7585+ ```c
7586+ {
7587+ const jerry_char_t char_array[] = "a string";
7588+ jerry_value_t string_value = jerry_string_utf8 (char_array,
7589+ sizeof (char_array) - 1);
7590+
7591+ ... // usage of string_value
7592+
7593+ jerry_value_free (string_value);
7594+ }
7595+
7596+ ```
7597+
7598+ **See also**
7599+
7600+ - [jerry_validate_string](#jerry_validate_string)
7601+ - [jerry_string_sz](#jerry_string_sz)
7602+ - [jerry_string](#jerry_string)
7603+
7604+
7605+ ## jerry_string_cesu8
7606+
7607+ **Summary**
7608+
7609+ Create a string value from the input buffer using the CESU-8 encoding.
7610+ The content of the buffer is assumed to be valid in the CESU-8 encoding,
7611+ it's the callers responsibility to validate the input.
7612+
7613+ *Note*:
7614+ - Returned value must be freed with [jerry_value_free](#jerry_value_free) when it is no longer needed.
7615+
7616+ **Prototype**
7617+
7618+ ```c
7619+ jerry_value_t
7620+ jerry_string_cesu8 (const jerry_char_t *buffer_p,
7621+ jerry_size_t buf_size)
7622+ ```
7623+
7624+ - `buffer_p` - non-null pointer to buffer
7625+ - `buf_size` - size of the buffer
7626+
7627+ **Example**
7628+
7629+ ```c
7630+ {
7631+ const jerry_char_t char_array[] = "\xed\xa0\x83\xed\xb2\x80";
7632+ jerry_value_t string_value = jerry_string_cesu8 (char_array,
7633+ sizeof (char_array) - 1);
7634+
7635+ ... // usage of string_value
7636+
7637+ jerry_value_free (string_value);
7638+ }
7639+
7640+ ```
7641+
7642+ **See also**
7643+
7644+ - [jerry_validate_string](#jerry_validate_string)
7645+ - [jerry_string](#jerry_string)
7646+
7647+
7648+ ## jerry_string_external_sz
7649+
7650+ **Summary**
7651+
7652+ Create external string from the zero-terminated ASCII encoded literal string.
7653+ The content of the buffer is assumed be encoded correctly, it's the callers
7654+ responsibility to validate the input.
7655+
7656+ *Note*:
7657+ - This is a macro that only accept literal string
7658+ - The free callback can be set by [jerry_string_external_on_free](#jerry_string_external_on_free)
7659+ - Returned value must be freed with [jerry_value_free](#jerry_value_free)
7660+ when it is no longer needed.
7661+
7662+ **Prototype**
7663+
7664+ ```c
7665+ #define jerry_string_external_sz(str, user_p)
7666+ ```
7667+
7668+ - `str_p` - zero-terminated ASCII encoded literal string
75747669- `user_p` - user pointer passed to the callback when the string is freed
7575- - return value - value of the created string
7670+ - return value - created external string
75767671
75777672*New in version 2.4*.
75787673
@@ -7794,10 +7889,10 @@ jerry_regexp_sz (const jerry_char_t *pattern_p, uint16_t flags);
77947889
77957890```c
77967891{
7797- jerry_char_t pattern_p = "[cgt]gggtaaa|tttaccc[acg]";
7892+ #define pattern "[cgt]gggtaaa|tttaccc[acg]"
77987893 uint16_t pattern_flags = JERRY_REGEXP_FLAG_IGNORE_CASE;
77997894
7800- jerry_value_t regexp = jerry_regexp_sz (pattern_p , pattern_flags);
7895+ jerry_value_t regexp = jerry_regexp_sz (jerry_string_sz (pattern) , pattern_flags);
78017896
78027897 ...
78037898
@@ -7836,7 +7931,7 @@ jerry_regexp (const jerry_value_t pattern, uint16_t flags);
78367931{
78377932 jerry_char_t pattern_p = "[cgt]gggtaaa|tttaccc[acg]";
78387933 jerry_size_t pattern_size = sizeof (pattern_p) - 1;
7839- jerry_value_t pattern_str = jerry_string (pattern_p, pattern_size, JERRY_ENCODING_UTF8 );
7934+ jerry_value_t pattern_str = jerry_string_utf8 (pattern_p, pattern_size);
78407935
78417936 uint16_t pattern_flags = JERRY_REGEXP_FLAG_IGNORE_CASE;
78427937
0 commit comments