Merge pull request #1237 from svaarala/api-is-symbol

Add duk_is_symbol() API call

RELEASES.rst

@@ -1898,7 +1898,8 @@ Planned
   bindings; footprint reduction is around 14-15kB on 32-bit targets (GH-872)
 
 * Add experimental support for ES6 Symbol built-in (disabled by default,
-  enable using DUK_USE_SYMBOL_BUILTIN) (GH-982, GH-1227)
+  enable using DUK_USE_SYMBOL_BUILTIN), duk_is_symbol() API call (GH-982,
+  GH-1227, GH-1237)
 
 * Allow ES6 Annex B unescaped right bracket (']') in regular expressions
   (non-standard before ES6 Annex B), left bracket ('[') not yet supported

doc/release-notes-v2-0.rst

@@ -1025,7 +1025,7 @@ Small changes related to adding symbol support:
 * Symbols are represented as strings with an invalid UTF-8 representation (like
   internal keys in Duktape 1.x), and they behave like strings in the C API just
   like internal keys did in Duktape 1.x.  For example,  ``duk_is_string()`` is
-  true for symbols.
+  true for symbols.  Symbols can be distinguished using ``duk_is_symbol()``.
 
 * Symbol support is currently **experimental**.  The core semantics have been
   implemented but it's likely some of the internal details will change in future

src-input/duk_api_public.h.in

@@ -574,6 +574,7 @@ DUK_EXTERNAL_DECL duk_bool_t duk_is_buffer_data(duk_context *ctx, duk_idx_t idx)
 DUK_EXTERNAL_DECL duk_bool_t duk_is_pointer(duk_context *ctx, duk_idx_t idx);
 DUK_EXTERNAL_DECL duk_bool_t duk_is_lightfunc(duk_context *ctx, duk_idx_t idx);
 
+DUK_EXTERNAL_DECL duk_bool_t duk_is_symbol(duk_context *ctx, duk_idx_t idx);
 DUK_EXTERNAL_DECL duk_bool_t duk_is_array(duk_context *ctx, duk_idx_t idx);
 DUK_EXTERNAL_DECL duk_bool_t duk_is_function(duk_context *ctx, duk_idx_t idx);
 DUK_EXTERNAL_DECL duk_bool_t duk_is_c_function(duk_context *ctx, duk_idx_t idx);

src-input/duk_api_stack.c

@@ -3277,6 +3277,17 @@ DUK_EXTERNAL duk_bool_t duk_is_lightfunc(duk_context *ctx, duk_idx_t idx) {
 	return duk__tag_check(ctx, idx, DUK_TAG_LIGHTFUNC);
 }
 
+DUK_EXTERNAL duk_bool_t duk_is_symbol(duk_context *ctx, duk_idx_t idx) {
+	duk_hstring *h;
+
+	DUK_ASSERT_CTX_VALID(ctx);
+	h = duk_get_hstring(ctx, idx);
+	if (h != NULL && DUK_HSTRING_HAS_SYMBOL(h)) {
+		return 1;
+	}
+	return 0;
+}
+
 DUK_EXTERNAL duk_bool_t duk_is_array(duk_context *ctx, duk_idx_t idx) {
 	duk_hobject *obj;
 

tests/api/test-is-symbol.c

@@ -0,0 +1,40 @@
+/*===
+*** test_basic (duk_safe_call)
+0: 1 0
+1: 1 0
+2: 1 1
+3: 1 1
+4: 1 1
+5: 1 0
+6: 1 0
+7: 1 1
+8: 0 0
+final top: 8
+==> rc=0, result='undefined'
+===*/
+
+static duk_ret_t test_basic(duk_context *ctx, void *udata) {
+	duk_idx_t i, n;
+
+	(void) udata;
+
+	duk_push_string(ctx, "");
+	duk_push_string(ctx, "foo");
+	duk_push_string(ctx, "\x80" "bar");
+	duk_push_string(ctx, "\x81" "quux");
+	duk_push_string(ctx, "\x82" "baz");
+	duk_push_string(ctx, "\xc0" "quuux");
+	duk_push_string(ctx, "\xfe" "quuuux");
+	duk_push_string(ctx, "\xff" "quuuuux");
+
+	for (i = 0, n = duk_get_top(ctx) + 1; i < n; i++) {
+		printf("%ld: %ld %ld\n", (long) i, (long) duk_is_string(ctx, i), (long) duk_is_symbol(ctx, i));
+	}
+
+	printf("final top: %ld\n", (long) duk_get_top(ctx));
+	return 0;
+}
+
+void test(duk_context *ctx) {
+	TEST_SAFE_CALL(test_basic);
+}

website/api/duk_is_symbol.yaml

@@ -0,0 +1,25 @@
+name: duk_is_symbol
+
+proto: |
+  duk_bool_t duk_is_symbol(duk_context *ctx, duk_idx_t idx);
+
+stack: |
+  [ ... val! ... ]
+
+summary: |
+  <p>Returns 1 if value at <code>idx</code> is a symbol, otherwise
+  returns 0.  If <code>idx</code> is invalid, also returns 0.</p>
+
+  <div include="symbols-are-strings.html" />
+
+example: |
+  if (duk_is_symbol(ctx, -3)) {
+      /* ... */
+  }
+
+tags:
+  - stack
+  - string
+  - symbol
+
+introduced: 2.0.0

website/api/symbols-are-strings.html

@@ -1,7 +1,9 @@
 <div class="note">
-Symbol values are visible in the C API as strings, e.g. <code>duk_is_string()</code>
-is true (this behavior is similar to Duktape 1.x internal strings).  Symbols are
-still an experimental feature.  For now, you can distinguish Symbols from ordinary
-strings by looking at their initial byte, see
+Symbol values are visible in the C API as strings so that both
+<code>duk_is_symbol()</code> and <code>duk_is_string()</code> are true.
+This behavior is similar to Duktape 1.x internal strings.  Symbols are
+still an experimental feature; for now, you can distinguish Symbols from
+ordinary strings using <code><a href="#duk_is_symbol">duk_is_symbol()</a></code>.
+For the internal representation, see
 <a href="https://github.com/svaarala/duktape/blob/master/doc/symbols.rst">symbols.rst</a>.
 </div>