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

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

docs/02.API-REFERENCE.md

@@ -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)
 

jerry-core/api/jerry.c

@@ -3116,6 +3116,50 @@ jerry_string_set_external_free_callback (jerry_external_string_free_callback_t c
   JERRY_CONTEXT (external_string_free_callback_p) = callback_p;
 } /* jerry_string_set_external_free_callback */
 
+/**
+ * Returns the user pointer assigned to an external string.
+ *
+ * @return user pointer, if value is an external string
+ *         NULL, otherwise
+ */
+void *
+jerry_string_get_external_user_pointer (const jerry_value_t value, /**< string value */
+                                        bool *is_external) /**< [out] true - if value is an external string,
+                                                            *         false - otherwise */
+{
+  if (is_external != NULL)
+  {
+    *is_external = false;
+  }
+
+  if (!ecma_is_value_string (value))
+  {
+    return NULL;
+  }
+
+  ecma_string_t *string_p = ecma_get_string_from_value (value);
+
+  if (ECMA_IS_DIRECT_STRING (string_p)
+      || ECMA_STRING_GET_CONTAINER (string_p) != ECMA_STRING_CONTAINER_LONG_OR_EXTERNAL_STRING)
+  {
+    return NULL;
+  }
+
+  ecma_long_string_t *long_string_p = (ecma_long_string_t *) string_p;
+
+  if (long_string_p->string_p == ECMA_LONG_STRING_BUFFER_START (long_string_p))
+  {
+    return NULL;
+  }
+
+  if (is_external != NULL)
+  {
+    *is_external = true;
+  }
+
+  return ((ecma_external_string_t *) string_p)->user_p;
+} /* jerry_string_get_external_user_pointer */
+
 /**
  * Checks whether the object or it's prototype objects have the given property.
  *

jerry-core/include/jerryscript-core.h

@@ -136,6 +136,7 @@ jerry_size_t jerry_substring_to_utf8_char_buffer (const jerry_value_t value,
                                                   jerry_char_t *buffer_p,
                                                   jerry_size_t buffer_size);
 void jerry_string_set_external_free_callback (jerry_external_string_free_callback_t callback_p);
+void *jerry_string_get_external_user_pointer (const jerry_value_t value, bool *is_external);
 
 /**
  * Functions for array object values.

tests/unit-core/test-external-string.c

@@ -64,40 +64,56 @@ main (void)
 
   jerry_init (JERRY_INIT_EMPTY);
 
+  bool is_external;
+
   /* Test external callback calls. */
   jerry_string_set_external_free_callback (external_string_free_callback_1);
   jerry_value_t external_string = jerry_create_external_string ((jerry_char_t *) external_1, NULL);
   TEST_ASSERT (free_count == 0);
+  TEST_ASSERT (jerry_string_get_external_user_pointer (external_string, &is_external) == NULL);
+  TEST_ASSERT (is_external);
+  TEST_ASSERT (jerry_string_get_external_user_pointer (external_string, NULL) == NULL);
   jerry_release_value (external_string);
   TEST_ASSERT (free_count == 1);
 
   jerry_string_set_external_free_callback (NULL);
-  external_string = jerry_create_external_string ((jerry_char_t *) external_1, NULL);
+  external_string = jerry_create_external_string ((jerry_char_t *) external_1, (void *) &free_count);
   TEST_ASSERT (free_count == 1);
+  TEST_ASSERT (jerry_string_get_external_user_pointer (external_string, &is_external) == (void *) &free_count);
+  TEST_ASSERT (is_external);
+  TEST_ASSERT (jerry_string_get_external_user_pointer (external_string, NULL) == (void *) &free_count);
   jerry_release_value (external_string);
   TEST_ASSERT (free_count == 1);
 
   jerry_string_set_external_free_callback (external_string_free_callback_2);
   external_string = jerry_create_external_string ((jerry_char_t *) external_2, (void *) &free_count);
   TEST_ASSERT (free_count == 2);
+  TEST_ASSERT (jerry_string_get_external_user_pointer (external_string, &is_external) == NULL);
+  TEST_ASSERT (!is_external);
   jerry_release_value (external_string);
   TEST_ASSERT (free_count == 2);
 
   jerry_string_set_external_free_callback (NULL);
   external_string = jerry_create_external_string ((jerry_char_t *) external_2, (void *) &free_count);
   TEST_ASSERT (free_count == 2);
+  TEST_ASSERT (jerry_string_get_external_user_pointer (external_string, &is_external) == NULL);
+  TEST_ASSERT (!is_external);
   jerry_release_value (external_string);
   TEST_ASSERT (free_count == 2);
 
   jerry_string_set_external_free_callback (external_string_free_callback_3);
   external_string = jerry_create_external_string ((jerry_char_t *) external_3, (void *) external_3);
   TEST_ASSERT (free_count == 3);
+  TEST_ASSERT (jerry_string_get_external_user_pointer (external_string, &is_external) == NULL);
+  TEST_ASSERT (!is_external);
   jerry_release_value (external_string);
   TEST_ASSERT (free_count == 3);
 
   jerry_string_set_external_free_callback (NULL);
   external_string = jerry_create_external_string ((jerry_char_t *) external_3, (void *) external_3);
   TEST_ASSERT (free_count == 3);
+  TEST_ASSERT (jerry_string_get_external_user_pointer (external_string, &is_external) == NULL);
+  TEST_ASSERT (!is_external);
   jerry_release_value (external_string);
   TEST_ASSERT (free_count == 3);
 
@@ -176,6 +192,16 @@ main (void)
   jerry_release_value (external_string);
   jerry_release_value (other_string);
 
+  external_string = jerry_create_boolean (true);
+  TEST_ASSERT (jerry_string_get_external_user_pointer (external_string, &is_external) == NULL);
+  TEST_ASSERT (!is_external);
+  jerry_release_value (external_string);
+
+  external_string = jerry_create_object ();
+  TEST_ASSERT (jerry_string_get_external_user_pointer (external_string, &is_external) == NULL);
+  TEST_ASSERT (!is_external);
+  jerry_release_value (external_string);
+
   jerry_cleanup ();
   return 0;
 } /* main */