From 11e0c13094567c6a530def14574d72fa6d1f985d Mon Sep 17 00:00:00 2001
From: Zidong Jiang <zidong.jiang@intel.com>
Date: Wed, 13 Dec 2017 12:46:20 +0800
Subject: [PATCH] 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              | 43 +++++++++++++++++++++++++++
 jerry-core/api/jerry.c                | 14 +++++++++
 jerry-core/include/jerryscript-core.h |  1 +
 tests/unit-core/test-api.c            | 15 ++++++++++
 4 files changed, 73 insertions(+)

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 47089a6ac..ce9c1813e 100644
--- a/docs/02.API-REFERENCE.md
+++ b/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.
diff --git a/jerry-core/api/jerry.c b/jerry-core/api/jerry.c
index ba6f3122d..bf7fad071 100644
--- a/jerry-core/api/jerry.c
+++ b/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.
  *
diff --git a/jerry-core/include/jerryscript-core.h b/jerry-core/include/jerryscript-core.h
index 2b0f6e4f4..57abeb40b 100644
--- a/jerry-core/include/jerryscript-core.h
+++ b/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'.
diff --git a/tests/unit-core/test-api.c b/tests/unit-core/test-api.c
index 7de12e012..c9af2977a 100644
--- a/tests/unit-core/test-api.c
+++ b/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))
   {