Add api: jerry_get_value_without_error_flag (#2096)

It is used to get the reference value from a error value

JerryScript-DCO-1.0-Signed-off-by: Zidong Jiang zidong.jiang@intel.com

docs/02.API-REFERENCE.md

@@ -1486,6 +1486,49 @@ jerry_value_set_error_flag (jerry_value_t *value_p);
 - [jerry_value_t](#jerry_value_t)
 
 
+## 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.

jerry-core/api/jerry.c

@@ -849,6 +849,20 @@ jerry_value_set_error_flag (jerry_value_t *value_p)
   }
 } /* jerry_value_set_error_flag */
 
+/**
+ * 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, when it is no longer needed.
+ *
+ * @return the real value of the jerry_value
+ */
+jerry_value_t jerry_get_value_without_error_flag (jerry_value_t value) /**< api value */
+{
+  return jerry_acquire_value (jerry_get_arg_value (value));
+} /* jerry_get_value_without_error_flag */
+
 /**
  * Get boolean from the specified value.
  *

jerry-core/include/jerryscript-core.h

@@ -295,6 +295,7 @@ bool jerry_is_feature_enabled (const jerry_feature_t feature);
 bool jerry_value_has_error_flag (const jerry_value_t value);
 void jerry_value_clear_error_flag (jerry_value_t *value_p);
 void jerry_value_set_error_flag (jerry_value_t *value_p);
+jerry_value_t jerry_get_value_without_error_flag (jerry_value_t value);
 
 /**
  * Getter functions of 'jerry_value_t'.

tests/unit-core/test-api.c

@@ -1060,6 +1060,21 @@ main (void)
 
   TEST_ASSERT (test_api_is_free_callback_was_called);
 
+  /* Test: jerry_get_value_without_error_flag */
+  {
+    jerry_init (JERRY_INIT_EMPTY);
+    jerry_value_t num_val = jerry_create_number (123);
+    jerry_value_set_error_flag (&num_val);
+    TEST_ASSERT (jerry_value_has_error_flag (num_val));
+    jerry_value_t num2_val = jerry_get_value_without_error_flag (num_val);
+    TEST_ASSERT (!jerry_value_has_error_flag (num2_val));
+    double num = jerry_get_number_value (num2_val);
+    TEST_ASSERT (num == 123);
+    jerry_release_value (num_val);
+    jerry_release_value (num2_val);
+    jerry_cleanup ();
+  }
+
   /* Test: parser error location */
   if (jerry_is_feature_enabled (JERRY_FEATURE_ERROR_MESSAGES))
   {