diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index cad788d01..92ae85328 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -675,47 +675,6 @@ main (void) - [jerry_parse_and_save_literals](#jerry_parse_and_save_literals) -## jerry_get_memory_limits - -**Summary** - -Gets configured memory limits of JerryScript. - -**Prototype** - -```c -void -jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p, - size_t *out_stack_limit_p); -``` - -- `out_data_bss_brk_limit_p` - out parameter, that gives the maximum size of data + bss + brk sections. -- `out_stack_limit_p` - out parameter, that gives the maximum size of the stack. - -**Example** - -[doctest]: # () - -```c -#include "jerryscript.h" - -int -main (void) -{ - jerry_init (JERRY_INIT_EMPTY); - - size_t stack_limit; - size_t data_bss_brk_limit; - jerry_get_memory_limits (&stack_limit, &data_bss_brk_limit); -} -``` - -**See also** - -- [jerry_init](#jerry_init) -- [jerry_cleanup](#jerry_cleanup) - - ## jerry_get_memory_stats **Summary** @@ -1761,41 +1720,71 @@ jerry_get_error_type (const jerry_value_t value); - [jerry_create_error](#jerry_create_error) - [jerry_value_is_error](#jerry_value_is_error) -## jerry_value_clear_error_flag +## jerry_get_value_from_error **Summary** -Clear both the error and abort flags. +Get the value from an error. + +Many API functions cannot be called with an error value. +This function extracts the API value from an error. The second argument defines +whether the input error value must be released or not. If it is set to `true`, +then a [`jerry_release_value`](#jerry_release_value) function will be called +for the first argument, so the error value won't be available after the call of +`jerry_get_value_from_error`. The second argument should be false if both error +and its represented value are needed. The first argument is returned unchanged if it is not an error. + +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +is no longer needed. **Prototype** ```c -void -jerry_value_clear_error_flag (jerry_value_t *value_p); +jerry_value_t +jerry_get_value_from_error (jerry_value_t value, bool release) ``` -- `value_p` - pointer to an api value +- `value` - error (api) value +- `release` - raw boolean, defines whether input value must be released +- return value - api value -**Example** +**Example 1** ```c { - jerry_value_t value; + jerry_value_t error; ... // create or acquire value - jerry_value_clear_error_flag (&value); + jerry_value_set_error_flag (&error); + jerry_value_t value = jerry_get_value_from_error (error, true); + // using the 'error' variable after release is invalid. jerry_release_value (value); } ``` +**Example 2** + +```c +{ + jerry_value_t error; + ... // create or acquire value + + jerry_value_set_error_flag (&error); + jerry_value_t value = jerry_get_value_from_error (error, false); + // both 'error' and 'value' can be used and must be released when they are no longer needed + + jerry_release_value (value); + jerry_release_value (error); +} +``` + **See also** - [jerry_value_t](#jerry_value_t) - [jerry_value_set_error_flag](#jerry_value_set_error_flag) - [jerry_value_set_abort_flag](#jerry_value_set_abort_flag) - ## jerry_value_set_error_flag **Summary** @@ -1827,7 +1816,7 @@ jerry_value_set_error_flag (jerry_value_t *value_p); **See also** - [jerry_value_t](#jerry_value_t) -- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag) +- [jerry_get_value_from_error](#jerry_get_value_from_error) - [jerry_value_set_abort_flag](#jerry_value_set_abort_flag) @@ -1862,53 +1851,10 @@ jerry_value_set_abort_flag (jerry_value_t *value_p); **See also** - [jerry_value_t](#jerry_value_t) -- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag) +- [jerry_get_value_from_error](#jerry_get_value_from_error) - [jerry_value_set_error_flag](#jerry_value_set_error_flag) -## jerry_get_value_without_error_flag - -**Summary** - -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) -when it is no longer needed. - -**Prototype** - -```c -jerry_value_t -jerry_get_value_without_error_flag (jerry_value_t value) -``` - -- `value` - api value - -**Example** - -```c -{ - 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 - // `jerry_get_value_without_error_flag`. - - jerry_release_value (value); - jerry_release_value (real_value); -} -``` - -**See also** - -- [jerry_acquire_value](#jerry_acquire_value) -- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag) - # Getter functions of 'jerry_value_t' Get raw data from API values. @@ -2943,7 +2889,7 @@ jerry_create_error (jerry_error_t error_type, **See also** - [jerry_value_is_error](#jerry_value_is_error) -- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag) +- [jerry_get_value_from_error](#jerry_get_value_from_error) - [jerry_value_set_error_flag](#jerry_value_set_error_flag)