js/public/Symbol.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /* Symbols. */
   7
   8 #ifndef js_Symbol_h
   9 #define js_Symbol_h
  10
  11 #include "js/shadow/Symbol.h"  // JS::shadow::Symbol::WellKnownAPILimit
  12
  13 #include <stddef.h>  // size_t
  14 #include <stdint.h>  // uintptr_t, uint32_t
  15
  16 #include "jstypes.h"  // JS_PUBLIC_API
  17
  18 #include "js/TypeDecls.h"
  19
  20 namespace JS {
  21
  22 class JS_PUBLIC_API Symbol;
  23
  24 /**
  25  * Create a new Symbol with the given description. This function never returns
  26  * a Symbol that is in the Runtime-wide symbol registry.
  27  *
  28  * If description is null, the new Symbol's [[Description]] attribute is
  29  * undefined.
  30  */
  31 extern JS_PUBLIC_API Symbol* NewSymbol(JSContext* cx,
  32                                        Handle<JSString*> description);
  33
  34 /**
  35  * Symbol.for as specified in ES6.
  36  *
  37  * Get a Symbol with the description 'key' from the Runtime-wide symbol
  38  * registry. If there is not already a Symbol with that description in the
  39  * registry, a new Symbol is created and registered. 'key' must not be null.
  40  */
  41 extern JS_PUBLIC_API Symbol* GetSymbolFor(JSContext* cx, Handle<JSString*> key);
  42
  43 /**
  44  * Get the [[Description]] attribute of the given symbol.
  45  *
  46  * This function is infallible. If it returns null, that means the symbol's
  47  * [[Description]] is undefined.
  48  */
  49 extern JS_PUBLIC_API JSString* GetSymbolDescription(Handle<Symbol*> symbol);
  50
  51 /* Well-known symbols. */
  52 #define JS_FOR_EACH_WELL_KNOWN_SYMBOL(MACRO) \
  53   MACRO(isConcatSpreadable)                  \
  54   MACRO(iterator)                            \
  55   MACRO(match)                               \
  56   MACRO(replace)                             \
  57   MACRO(search)                              \
  58   MACRO(species)                             \
  59   MACRO(hasInstance)                         \
  60   MACRO(split)                               \
  61   MACRO(toPrimitive)                         \
  62   MACRO(toStringTag)                         \
  63   MACRO(unscopables)                         \
  64   MACRO(asyncIterator)                       \
  65   MACRO(matchAll)                            \
  66   IF_EXPLICIT_RESOURCE_MANAGEMENT(MACRO(dispose))
  67
  68 enum class SymbolCode : uint32_t {
  69 // There is one SymbolCode for each well-known symbol.
  70 #define JS_DEFINE_SYMBOL_ENUM(name) name,
  71   JS_FOR_EACH_WELL_KNOWN_SYMBOL(
  72       JS_DEFINE_SYMBOL_ENUM)  // SymbolCode::iterator, etc.
  73 #undef JS_DEFINE_SYMBOL_ENUM
  74   Limit,
  75   WellKnownAPILimit = JS::shadow::Symbol::WellKnownAPILimit,
  76   PrivateNameSymbol = 0xfffffffd,  // created by the #PrivateName syntax.
  77   InSymbolRegistry =
  78       0xfffffffe,            // created by Symbol.for() or JS::GetSymbolFor()
  79   UniqueSymbol = 0xffffffff  // created by Symbol() or JS::NewSymbol()
  80 };
  81
  82 /* For use in loops that iterate over the well-known symbols. */
  83 const size_t WellKnownSymbolLimit = size_t(SymbolCode::Limit);
  84
  85 /**
  86  * Return the SymbolCode telling what sort of symbol `symbol` is.
  87  *
  88  * A symbol's SymbolCode never changes once it is created.
  89  */
  90 extern JS_PUBLIC_API SymbolCode GetSymbolCode(Handle<Symbol*> symbol);
  91
  92 /**
  93  * Get one of the well-known symbols defined by ES6. A single set of well-known
  94  * symbols is shared by all compartments in a JSRuntime.
  95  *
  96  * `which` must be in the range [0, WellKnownSymbolLimit).
  97  */
  98 extern JS_PUBLIC_API Symbol* GetWellKnownSymbol(JSContext* cx,
  99                                                 SymbolCode which);
 100
 101 /**
 102  * Return true if the given JSPropertySpec::name or JSFunctionSpec::name value
 103  * is actually a symbol code and not a string. See JS_SYM_FN.
 104  */
 105 inline bool PropertySpecNameIsSymbol(uintptr_t name) {
 106   return name != 0 && name - 1 < WellKnownSymbolLimit;
 107 }
 108
 109 }  // namespace JS
 110
 111 #endif /* js_Symbol_h */