Merge jerry_get_value_without_error and jerry_value_clear_error_flag functions (#2350)

JerryScript-DCO-1.0-Signed-off-by: Istvan Miklos imiklos2@inf.u-szeged.hu

1 files changed, 42 insertions, 55 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index b0224f0d..c620745f 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -1710,41 +1710,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**
@@ -1776,7 +1806,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)
 
 
@@ -1811,53 +1841,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.
@@ -2892,7 +2879,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)