Implement getter function for external string user pointer (#4742)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2021-08-30 14:04:13 +02:00
parent 4175037fb0
commit 8cbe1b59c1
4 changed files with 143 additions and 1 deletions
@@ -4283,6 +4283,77 @@ main (void)
 **See also**

 - [jerry_external_string_free_callback_t](#jerry_external_string_free_callback_t)
+- [jerry_string_get_external_user_pointer](#jerry_string_get_external_user_pointer)
+- [jerry_create_external_string](#jerry_create_external_string)
+- [jerry_create_external_string_sz](#jerry_create_external_string_sz)
+
+
+# jerry_string_get_external_user_pointer
+
+**Summary**
+
+Returns the user pointer assigned to an external string.
+
+*Note*:
+  - In some cases (e.g. when the string is also a magic string registered by
+    [jerry_register_magic_strings](#jerry_register_magic_strings)), the
+    string is a normal string without a user pointer even if it is created
+    by [jerry_create_external_string](#jerry_create_external_string).
+
+**Prototype**
+
+```c
+void *jerry_string_get_external_user_pointer (const jerry_value_t value,
+                                              bool *is_external);
+```
+
+- `value` - string value.
+- `is_external` - when `is_external` is non-NULL, the referenced boolean value is set
+                  to true, if `value` is an external string, and set to false otherwise
+- return value
+  - user pointer - if `value` argument is an external string
+  - NULL - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+#include <stdio.h>
+
+static int user_value = 1;
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  const char *string_p = "This is a long external string, should not be duplicated!";
+
+  jerry_value_t external_string = jerry_create_external_string ((jerry_char_t *) string_p, (void *) &user_value);
+
+  bool is_external;
+  void *user_p = jerry_string_get_external_user_pointer (external_string, &is_external);
+
+  if (is_external)
+  {
+    /* Prints the address of user_value. */
+    printf("User pointer of an external string: %p\n", user_p);
+  }
+
+  jerry_release_value (external_string);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_string_set_external_string_free_callback](#jerry_string_set_external_string_free_callback)
 - [jerry_create_external_string](#jerry_create_external_string)
 - [jerry_create_external_string_sz](#jerry_create_external_string_sz)