Replace the jerry_value_set_error_flag function with jerry_create_error_from_value (#2367)

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

docs/02.API-REFERENCE.md

@@ -1742,14 +1742,14 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
 
 ```c
 {
-  jerry_value_t error;
+  jerry_value_t value;
   ... // create or acquire value
 
-  jerry_value_set_error_flag (&error);
+  jerry_value_t error = jerry_create_error_from_value (value, true);
-  jerry_value_t value = jerry_get_value_from_error (error, true);
+  jerry_value_t value_from_error = jerry_get_value_from_error (error, true);
   // using the 'error' variable after release is invalid.
 
-  jerry_release_value (value);
+  jerry_release_value (value_from_error);
 }
 ```
 
@@ -1757,14 +1757,14 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
 
 ```c
 {
-  jerry_value_t error;
+  jerry_value_t value;
   ... // create or acquire value
 
-  jerry_value_set_error_flag (&error);
+  jerry_value_t error = jerry_create_error_from_value (value, true);
-  jerry_value_t value = jerry_get_value_from_error (error, false);
+  jerry_value_t value_from_error = jerry_get_value_from_error (error, false);
-  // both 'error' and 'value' can be used and must be released when they are no longer needed
+  // both 'error' and 'value_from_error' can be used and must be released when they are no longer needed
 
-  jerry_release_value (value);
+  jerry_release_value (value_from_error);
   jerry_release_value (error);
 }
 ```
@@ -1772,33 +1772,59 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
 **See also**
 
 - [jerry_value_t](#jerry_value_t)
-- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
+- [jerry_create_error_from_value](#jerry_create_error_from_value)
 - [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
 
-## jerry_value_set_error_flag
+## jerry_create_error_from_value
 
 **Summary**
 
-Set the error flag.
+Create (api) error from a value.
+
+This function creates an API error value from an API value. The second argument defines
+whether the input 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 api value won't be available after the call of
+`jerry_create_error_from_value`. The second argument should be false if both value
+and created error value are needed.
 
 **Prototype**
 
 ```c
-void
+jerry_value_t
-jerry_value_set_error_flag (jerry_value_t *value_p);
+jerry_create_error_from_value (jerry_value_t value, bool release);
 ```
 
-- `value_p` - pointer to an api value
+- `value` - api value
+- `release` - raw boolean, defines whether input value must be released
+- return value - error (api) value
 
-**Example**
+**Example 1**
 
 ```c
 {
   jerry_value_t value;
   ... // create or acquire value
 
-  jerry_value_set_error_flag (&value);
+  jerry_value_t error = jerry_create_error_from_value (value, true);
+  // using the 'value' variable after release is invalid.
 
+
+  jerry_release_value (error);
+}
+```
+
+**Example 2**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t error = jerry_create_error_from_value (value, false);
+  // both 'error' and 'value' can be used and must be released when they are no longer needed
+
+  jerry_release_value (error);
   jerry_release_value (value);
 }
 ```
@@ -1842,7 +1868,7 @@ jerry_value_set_abort_flag (jerry_value_t *value_p);
 
 - [jerry_value_t](#jerry_value_t)
 - [jerry_get_value_from_error](#jerry_get_value_from_error)
-- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
+- [jerry_create_error_from_value](#jerry_create_error_from_value)
 
 
 # Getter functions of 'jerry_value_t'
@@ -2880,7 +2906,7 @@ jerry_create_error (jerry_error_t error_type,
 
 - [jerry_value_is_error](#jerry_value_is_error)
 - [jerry_get_value_from_error](#jerry_get_value_from_error)
-- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
+- [jerry_create_error_from_value](#jerry_create_error_from_value)
 
 
 ## jerry_create_error_sz

jerry-core/api/jerry.c

@@ -934,26 +934,40 @@ jerry_get_value_from_error (jerry_value_t value, /**< api value */
 } /* jerry_get_value_from_error */
 
 /**
- * Set the error flag if the value is not an error reference.
+ * Create error from an api value.
+ *
+ * Create error value from an api value. If the second argument is true
+ * it will release the input api value.
+ *
+ * @return api error value
  */
-void
+jerry_value_t
-jerry_value_set_error_flag (jerry_value_t *value_p) /**< api value */
+jerry_create_error_from_value (jerry_value_t value, /**< api value */
+                               bool release) /**< release api value */
 {
   jerry_assert_api_available ();
 
-  if (JERRY_UNLIKELY (ecma_is_value_error_reference (*value_p)))
+  if (JERRY_UNLIKELY (ecma_is_value_error_reference (value)))
   {
     /* This is a rare case so it is optimized for
      * binary size rather than performance. */
-    if (!jerry_value_is_abort (*value_p))
+    if (!jerry_value_is_abort (value))
     {
-      return;
+      return (release ? value : jerry_acquire_value (value));
     }
-    *value_p = ecma_clear_error_reference (*value_p, false);
+
+    value = jerry_get_value_from_error (value, release);
+    release = true;
   }
 
-  *value_p = ecma_create_error_reference (*value_p, true);
+  jerry_value_t ret_val = ecma_create_error_reference (value, true);
-} /* jerry_value_set_error_flag */
+  if (release)
+  {
+    jerry_release_value (value);
+  }
+
+  return ret_val;
+} /* jerry_create_error_from_value */
 
 /**
  * Set both the abort and error flags if the value is not an error reference.

jerry-core/include/jerryscript-core.h

@@ -369,7 +369,7 @@ bool jerry_is_feature_enabled (const jerry_feature_t feature);
  * Error manipulation functions.
  */
 jerry_value_t jerry_get_value_from_error (jerry_value_t value, bool release);
-void jerry_value_set_error_flag (jerry_value_t *value_p);
+jerry_value_t jerry_create_error_from_value (jerry_value_t value, bool release);
 void jerry_value_set_abort_flag (jerry_value_t *value_p);
 
 /**

tests/unit-core/test-abort.c

@@ -118,7 +118,7 @@ main (void)
   TEST_ASSERT (jerry_value_is_abort (value));
   TEST_ASSERT (jerry_value_is_error (value));
 
-  jerry_value_set_error_flag (&value);
+  value = jerry_create_error_from_value (value, true);
   TEST_ASSERT (!jerry_value_is_abort (value));
   TEST_ASSERT (jerry_value_is_error (value));
 

tests/unit-core/test-api-set-and-clear-error-flag.c

@@ -24,14 +24,24 @@ main (void)
   jerry_init (JERRY_INIT_EMPTY);
 
   jerry_value_t obj_val = jerry_create_object ();
-  jerry_value_set_error_flag (&obj_val);
+  obj_val = jerry_create_error_from_value (obj_val, true);
   jerry_value_t err_val = jerry_acquire_value (obj_val);
 
   obj_val = jerry_get_value_from_error (err_val, true);
 
   JERRY_ASSERT (obj_val != err_val);
   jerry_release_value (err_val);
-  jerry_release_value (obj_val);
+
+  jerry_value_t value = jerry_create_number (42);
+  jerry_value_t error = jerry_create_error_from_value (value, true);
+  error = jerry_create_error_from_value (error, true);
+  jerry_release_value (error);
+
+  value = jerry_create_number (42);
+  error = jerry_create_error_from_value (value, true);
+  jerry_value_t error2 = jerry_create_error_from_value (error, false);
+  jerry_release_value (error);
+  jerry_release_value (error2);
 
   jerry_cleanup ();
 } /* main */

tests/unit-core/test-api.c

@@ -1053,7 +1053,7 @@ main (void)
   {
     jerry_init (JERRY_INIT_EMPTY);
     jerry_value_t num_val = jerry_create_number (123);
-    jerry_value_set_error_flag (&num_val);
+    num_val = jerry_create_error_from_value (num_val, true);
     TEST_ASSERT (jerry_value_is_error (num_val));
     jerry_value_t num2_val = jerry_get_value_from_error (num_val, false);
     TEST_ASSERT (jerry_value_is_error (num_val));