Replace jerry_value_set_abort_flag with jerry_create_abort_from_value (#2411)

Replaced the function, added some tests for it. Also changed the functions order to
alphabetical.

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

1 files changed, 101 insertions, 78 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index d5a0c4b6..bcfe92a7 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -1696,76 +1696,29 @@ jerry_is_feature_enabled (const jerry_feature_t feature);
 
 # Error manipulation functions
 
-## jerry_get_error_type
+## jerry_create_abort_from_value
 
 **Summary**
 
-Returns the type of the Error object if possible.
-
-If a non-error object is used as the input for the function the method
-will return `JERRY_ERROR_NONE` indicating that the value was not
-an Error object. However it is still possible that the value contains
-error semantics. To correctly detect if a value have error use the
-[jerry_value_is_error](#jerry_value_is_error) method.
-
-**Prototype**
-
-```c
-jerry_error_t
-jerry_get_error_type (const jerry_value_t value);
-```
-
-- `value` - api value (possible error object)
-- return value
-  - JERRY_ERROR_NONE if the input is not an error object
-  - one of the [jerry_error_t](#jerry_error_t) value
-
-**Example**
-
-```c
-{
-  jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_RANGE,
-                                                (const jerry_char_t *) "error msg");
-  jerry_error_t error_type = jerry_get_error_type (error_obj);
-
-  // error_type is now JERRY_ERROR_RANGE.
-
-  jerry_release_value (error_obj);
-}
-```
-
-**See also**
+Create (api) abort from a value.
 
-- [jerry_create_error](#jerry_create_error)
-- [jerry_value_is_error](#jerry_value_is_error)
-
-## jerry_get_value_from_error
-
-**Summary**
-
-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`,
+This function creates an API abort 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 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.
-
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
-is no longer needed.
+for the first argument, so the api value won't be available after the call of
+`jerry_create_abort_from_value`. The second argument should be false if both value
+and created abort value are needed.
 
 **Prototype**
 
 ```c
 jerry_value_t
-jerry_get_value_from_error (jerry_value_t value, bool release)
+jerry_create_abort_from_value (jerry_value_t value, bool release);
 ```
 
-- `value` - error (api) value
+- `value` - api value
 - `release` - raw boolean, defines whether input value must be released
-- return value - api value
+- return value - abort (api) value
 
 **Example 1**
 
@@ -1774,11 +1727,10 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
   jerry_value_t value;
   ... // create or acquire value
 
-  jerry_value_t error = jerry_create_error_from_value (value, true);
-  jerry_value_t value_from_error = jerry_get_value_from_error (error, true);
-  // using the 'error' variable after release is invalid.
+  jerry_value_t abort = jerry_create_abort_from_value (value, true);
+  // using the 'value' variable after release is invalid.
 
-  jerry_release_value (value_from_error);
+  jerry_release_value (abort);
 }
 ```
 
@@ -1789,20 +1741,19 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
   jerry_value_t value;
   ... // create or acquire value
 
-  jerry_value_t error = jerry_create_error_from_value (value, true);
-  jerry_value_t value_from_error = jerry_get_value_from_error (error, false);
-  // both 'error' and 'value_from_error' can be used and must be released when they are no longer needed
+  jerry_value_t abort = jerry_create_abort_from_value (value, false);
+  // both 'abort' and 'value' can be used and must be released when they are no longer needed
 
-  jerry_release_value (value_from_error);
-  jerry_release_value (error);
+  jerry_release_value (abort);
+  jerry_release_value (value);
 }
 ```
 
 **See also**
 
 - [jerry_value_t](#jerry_value_t)
+- [jerry_get_value_from_error](#jerry_get_value_from_error)
 - [jerry_create_error_from_value](#jerry_create_error_from_value)
-- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
 
 ## jerry_create_error_from_value
 
@@ -1862,43 +1813,115 @@ jerry_create_error_from_value (jerry_value_t value, bool release);
 
 - [jerry_value_t](#jerry_value_t)
 - [jerry_get_value_from_error](#jerry_get_value_from_error)
-- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
-
+- [jerry_create_abort_from_value](#jerry_create_abort_from_value
 
-## jerry_value_set_abort_flag
+## jerry_get_error_type
 
 **Summary**
 
-Set both the error and abort flags.
+Returns the type of the Error object if possible.
+
+If a non-error object is used as the input for the function the method
+will return `JERRY_ERROR_NONE` indicating that the value was not
+an Error object. However it is still possible that the value contains
+error semantics. To correctly detect if a value have error use the
+[jerry_value_is_error](#jerry_value_is_error) method.
 
 **Prototype**
 
 ```c
-void
-jerry_value_set_abort_flag (jerry_value_t *value_p);
+jerry_error_t
+jerry_get_error_type (const jerry_value_t value);
 ```
 
-- `value_p` - pointer to an api value
+- `value` - api value (possible error object)
+- return value
+  - JERRY_ERROR_NONE if the input is not an error object
+  - one of the [jerry_error_t](#jerry_error_t) value
 
 **Example**
 
 ```c
 {
+  jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_RANGE,
+                                                (const jerry_char_t *) "error msg");
+  jerry_error_t error_type = jerry_get_error_type (error_obj);
+
+  // error_type is now JERRY_ERROR_RANGE.
+
+  jerry_release_value (error_obj);
+}
+```
+
+**See also**
+
+- [jerry_create_error](#jerry_create_error)
+- [jerry_value_is_error](#jerry_value_is_error)
+
+## jerry_get_value_from_error
+
+**Summary**
+
+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.
+
+*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_from_error (jerry_value_t value, bool release)
+```
+
+- `value` - error (api) value
+- `release` - raw boolean, defines whether input value must be released
+- return value - api value
+
+**Example 1**
+
+```c
+{
   jerry_value_t value;
   ... // create or acquire value
 
-  jerry_value_set_abort_flag (&value);
+  jerry_value_t error = jerry_create_error_from_value (value, 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);
+}
+```
+
+**Example 2**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t error = jerry_create_error_from_value (value, true);
+  jerry_value_t value_from_error = jerry_get_value_from_error (error, false);
+  // both 'error' and 'value_from_error' can be used and must be released when they are no longer needed
+
+  jerry_release_value (value_from_error);
+  jerry_release_value (error);
 }
 ```
 
 **See also**
 
 - [jerry_value_t](#jerry_value_t)
-- [jerry_get_value_from_error](#jerry_get_value_from_error)
 - [jerry_create_error_from_value](#jerry_create_error_from_value)
-
+- [jerry_create_abort_from_value](#jerry_create_abort_from_value)
 
 # Getter functions of 'jerry_value_t'