From b89c74fd3973d58d6564fa3f526a9eab32f2c2f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zsolt=20Borb=C3=A9ly?= Date: Thu, 26 Jan 2017 08:48:27 +0100 Subject: [PATCH] Update the webpage (#1542) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com --- 02.API-REFERENCE.md | 111 ++++++++++++++++++++++++++++++++++++++- 06.REFERENCE-COUNTING.md | 24 +++++---- _includes/header.html | 2 +- index.html | 4 +- 4 files changed, 125 insertions(+), 16 deletions(-) diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 13225e784..370afb74f 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -1409,6 +1409,109 @@ jerry_string_to_utf8_char_buffer (const jerry_value_t value, - [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) - [jerry_get_utf8_string_size](#jerrygetutf8stringsize) +## jerry_substring_to_char_buffer + +**Summary** + +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 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_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_string_size (value); + jerry_char_t str_buf_p[req_sz]; + jerry_length_t start_pos = 0; + jerry_length_t end_pos = jerry_get_string_length (value); + + jerry_substring_to_char_buffer (value, start_pos, end_pos, str_buf_p, req_sz); + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_create_string](#jerrycreatestring) +- [jerry_get_string_size](#jerrygetstringsize) +- [jerry_get_string_length](#jerrygetstringlength) + +## 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](#jerrycreatestring) +- [jerry_get_utf8_string_size](#jerrygetutf8stringsize) +- [jerry_get_utf8_string_length](#jerrygetutf8stringlength) # Functions for array object values ## jerry_get_array_length @@ -2774,8 +2877,9 @@ jerry_free_property_descriptor_fields (const jerry_property_descriptor_t *prop_d **Summary** -Call function specified by a function value. Error flag -must not be set for any arguments of this function. +Call function specified by a function value. Error flag must +not be set for any arguments of this function. Value of `this` +parameter should be set to `undefined` for non-method calls. *Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it is no longer needed. @@ -2817,6 +2921,8 @@ jerry_call_function (const jerry_value_t func_obj_val, jerry_release_value (ret_val); jerry_release_value (this_val); } + + jerry_release_value (val); } ``` @@ -3241,6 +3347,7 @@ jerry_exec_snapshot (const void *snapshot_p, size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p, strlen ((const char *) code_to_snapshot_p), true, + false, global_mode_snapshot_buffer, sizeof (global_mode_snapshot_buffer)); jerry_cleanup (); diff --git a/06.REFERENCE-COUNTING.md b/06.REFERENCE-COUNTING.md index 9d296b226..e8b6301c2 100644 --- a/06.REFERENCE-COUNTING.md +++ b/06.REFERENCE-COUNTING.md @@ -20,7 +20,7 @@ by `jerry_release_value`. /* The value stored in the 'global' variable contains a live * reference to the global object. The system also keeps its * own live reference to the global object. These two references - * are indepent, and both must be destroyed before the global + * are independent, and both must be destroyed before the global * object can be freed. */ jerry_release_value (global); @@ -57,16 +57,17 @@ following code is an **INCORRECT WAY** of releasing the 3.14 value. JerryScript API functions returning with a `jerry_value_t` always return with a new live reference. Passing a `jerry_value_t` to -an API function never releases its reference. The next example -shows this behaviour through property getting and setting. +an API function never releases its reference (unless explicitly +stated in the documentation). The next example shows this +behaviour through property getting and setting. ```c jerry_value_t prop_value = jerry_get_property (...); /* The prop_value must be released later because both the base * object and the prop_value have an independent reference to - * the same JavaScript value. When the operation is failed - * the prop_value contains a live reference to an error object. + * the same JavaScript value. When the operation fails, the + * prop_value contains a live reference to an error object. * This reference must be released as well. */ if (jerry_value_has_error_flag (prop_value)) @@ -85,20 +86,21 @@ shows this behaviour through property getting and setting. /* Property setting is the same. */ + jerry_value_t new_prop_value = jerry_create_number (2.718); jerry_value_t result = jerry_set_property (..., new_prop_value); - /* If the property set is successful a new reference is created + /* If the property set is successful, a new reference is created * for the value referenced by new_prop_value. The new_prop_value - * reference must be released regardless the operation is - * successful. */ + * reference must be released regardless of whether the operation + * is successful. */ /* The new_prop_value can be passed to other JerryScript API * functions before the jerry_release_value () call. */ jerry_release_value (new_prop_value); - /* The reference stored in 'result' variable contains whether - * the operation is successful and must also be freed. */ + /* The reference stored in the 'result' variable is live whether + * the operation is successful or not, and must also be freed. */ if (jerry_value_has_error_flag (result)) { @@ -179,5 +181,5 @@ References can be duplicated in C as long as only one of them is freed. jerry_release_value (c); /* Both 'b' and 'c' (boolean true) references become dead. */ - /* Since all references are released no memory leak is possible. */ + /* Since all references are released, no memory leak occurs. */ ``` diff --git a/_includes/header.html b/_includes/header.html index 0bc8d4517..7d4f52007 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -16,7 +16,7 @@ {% else %}
  • Home
    • {% endif %} -
  • View on Github
    • +
  • View on Github
  • Powering IoT.js