Get the 'this' binding of a realm value (#4365)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com

docs/02.API-REFERENCE.md

@@ -9125,6 +9125,10 @@ main (int argc, char** argv)
 
 - [jerry_construct_object](#jerry_construct_object)
 
+# Functions for realm objects
+
+These APIs all depend on build option (`JERRY_BUILTIN_REALMS`).
+
 ## jerry_set_realm
 
 **Summary**
@@ -9146,6 +9150,7 @@ which was active when the code was parsed or loaded regardless of the current re
 - This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked
   in runtime with the `JERRY_FEATURE_REALM` feature enum value,
   see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The es.next profile enables this by default.
 
 **Prototype**
 
@@ -9178,6 +9183,53 @@ jerry_set_realm (jerry_value_t realm_value);
 
 - [jerry_create_realm](#jerry_create_realm)
 
+## jerry_realm_get_this
+
+**Summary**
+
+Gets the 'this' binding of a realm. The 'this' binding is always an object.
+By default the 'this' binding is the same as the realm object and can be
+changed by [jerry_realm_set_this](#jerry_realm_set_this).
+
+*Notes*:
+- This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked
+  in runtime with the `JERRY_FEATURE_REALM` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The es.next profile enables this by default.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_realm_get_this (jerry_value_t realm_value)
+```
+- `realm_value` - realm value
+- return
+  - type error - if realm_value is not a realm
+  - 'this' binding object - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+```c
+{
+  jerry_value_t realm_value = jerry_create_realm ();
+
+  jerry_value_t this_value = jerry_realm_get_this (realm_value);
+
+  ... // usage of the this_value
+
+  jerry_release_value (this_value);
+  jerry_release_value (realm_value);
+}
+```
+
+**See also**
+
+- [jerry_create_realm](#jerry_create_realm)
+- [jerry_realm_set_this](#jerry_realm_set_this)
+
 ## jerry_realm_set_this
 
 **Summary**
@@ -9189,6 +9241,7 @@ any script on the realm. Otherwise the operation is undefined.
 - This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked
   in runtime with the `JERRY_FEATURE_REALM` feature enum value,
   see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The es.next profile enables this by default.
 
 **Prototype**
 
@@ -9199,7 +9252,7 @@ jerry_realm_set_this (jerry_value_t realm_value, jerry_value_t this_value)
 - `realm_value` - realm value
 - `this_value` - new this value
 - return
-  - exception - if any error is happened
+  - type error - if realm_value is not a realm or this_value is not object
   - true - otherwise
 
 *New in version [[NEXT_RELEASE]]*.
@@ -9225,6 +9278,7 @@ jerry_realm_set_this (jerry_value_t realm_value, jerry_value_t this_value)
 
 - [jerry_create_realm](#jerry_create_realm)
 - [jerry_set_realm](#jerry_set_realm)
+- [jerry_realm_get_this](#jerry_realm_get_this)
 
 # ArrayBuffer and TypedArray functions