1# Symbol
2
3Class `Napi::Symbol` inherits from class [`Napi::Name`][].
4
5## Methods
6
7### Constructor
8
9Instantiates a new `Napi::Symbol` value.
10
11```cpp
12Napi::Symbol::Symbol();
13```
14
15Returns a new empty `Napi::Symbol`.
16
17### New
18```cpp
19Napi::Symbol::New(napi_env env, const std::string& description);
20Napi::Symbol::New(napi_env env, const char* description);
21Napi::Symbol::New(napi_env env, Napi::String description);
22Napi::Symbol::New(napi_env env, napi_value description);
23```
24
25- `[in] env`: The `napi_env` environment in which to construct the `Napi::Symbol` object.
26- `[in] value`: The C++ primitive which represents the description hint for the `Napi::Symbol`.
27  `description` may be any of:
28  - `std::string&` - UTF8 string description.
29  - `const char*` - represents a UTF8 string description.
30  - `String` - Node addon API String description.
31  - `napi_value` - Node-API `napi_value` description.
32
33If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
34being used, callers should check the result of `Napi::Env::IsExceptionPending` before
35attempting to use the returned value.
36
37### WellKnown
38```cpp
39static Napi::Symbol Napi::Symbol::WellKnown(napi_env env, const std::string& name);
40```
41
42- `[in] env`: The `napi_env` environment in which to construct the `Napi::Symbol` object.
43- `[in] name`: The C++ string representing the `Napi::Symbol` to retrieve.
44
45Returns a `Napi::Symbol` representing a well-known `Symbol` from the
46`Symbol` registry.
47
48### For
49```cpp
50static Napi::Symbol Napi::Symbol::For(napi_env env, const std::string& description);
51static Napi::Symbol Napi::Symbol::For(napi_env env, const char* description);
52static Napi::Symbol Napi::Symbol::For(napi_env env, String description);
53static Napi::Symbol Napi::Symbol::For(napi_env env, napi_value description);
54```
55
56- `[in] env`: The `napi_env` environment in which to construct the `Napi::Symbol` object.
57- `[in] description`: The C++ string representing the `Napi::Symbol` in the global registry to retrieve.
58
59Searches in the global registry for existing symbol with the given name. If the symbol already exist it will be returned, otherwise a new symbol will be created in the registry. It's equivalent to Symbol.for() called from JavaScript.
60
61[`Napi::Name`]: ./name.md