Introduce C API to query the type of an Error object (#2177)

New api function:
* jerry_get_error_type

Additionally update a few places where this new function
can be used.

JerryScript-DCO-1.0-Signed-off-by: Peter Gal pgal.u-szeged@partner.samsung.com

1 files changed, 52 insertions, 1 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index f41a4560..22e6f6ac 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -23,6 +23,9 @@ Possible types of an error:
  - JERRY_ERROR_TYPE - type error
  - JERRY_ERROR_URI - URI error
 
+There is also a special value `JERRY_ERROR_NONE` which is not an error type
+this value can only be returned by the [jerry_get_error_type](#jerry_get_error_type).
+
 ## jerry_feature_t
 
 Possible compile time enabled feature types:
@@ -1477,7 +1480,50 @@ jerry_is_feature_enabled (const jerry_feature_t feature);
 }
 ```
 
-# Error flag manipulation functions
+# Error manipulation functions
+
+## jerry_get_error_type
+
+**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_has_error_flag](#jerry_value_has_error_flag) 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**
+
+- [jerry_create_error](#jerry_create_error)
+- [jerry_value_has_error_flag](#jerry_value_has_error_flag)
 
 ## jerry_value_has_error_flag
 
@@ -2707,6 +2753,11 @@ jerry_create_boolean (bool value);
 
 Create new JavaScript error object.
 
+Important! The `error_type` argument *must not be*
+`JERRY_ERROR_NONE`.
+Creating an error with no error type is not valid.
+
+
 **Prototype**
 
 ```c