1# String
2
3Class `Napi::String` inherits from class [`Napi::Name`][].
4
5## Constructor
6
7```cpp
8Napi::String::String();
9```
10
11Returns a new **empty** `Napi::String` instance.
12
13If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
14being used, callers should check the result of `Env::IsExceptionPending` before
15attempting to use the returned value.
16
17```cpp
18Napi::String::String(napi_env env, napi_value value); ///< Wraps a Node-API value primitive.
19```
20- `[in] env` - The environment in which to create the string.
21- `[in] value` - The primitive to wrap.
22
23Returns a `Napi::String` wrapping a `napi_value`.
24
25If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
26being used, callers should check the result of `Env::IsExceptionPending` before
27attempting to use the returned value.
28
29## Operators
30
31### operator std::string
32
33```cpp
34Napi::String::operator std::string() const;
35```
36
37Returns a UTF-8 encoded C++ string.
38
39### operator std::u16string
40```cpp
41Napi::String::operator std::u16string() const;
42```
43
44Returns a UTF-16 encoded C++ string.
45
46## Methods
47
48### New
49```cpp
50Napi::String::New();
51```
52
53Returns a new empty `Napi::String`.
54
55### New
56```cpp
57Napi::String::New(napi_env env, const std::string& value);
58Napi::String::New(napi_env env, const std::u16::string& value);
59Napi::String::New(napi_env env, const char* value);
60Napi::String::New(napi_env env, const char16_t* value);
61Napi::String::New(napi_env env, const char* value, size_t length);
62Napi::String::New(napi_env env, const char16_t* value, size_t length);
63```
64
65- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object.
66- `[in] value`: The C++ primitive from which to instantiate the `Napi::Value`. `value` may be any of:
67  - `std::string&` - represents a UTF8 string.
68  - `std::u16string&` - represents a UTF16-LE string.
69  - `const char*` - represents a UTF8 string.
70  - `const char16_t*` - represents a UTF16-LE string.
71- `[in] length`: The length of the string (not necessarily null-terminated) in code units.
72
73Returns a new `Napi::String` that represents the passed in C++ string.
74
75If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
76being used, callers should check the result of `Env::IsExceptionPending` before
77attempting to use the returned value.
78
79### Utf8Value
80```cpp
81std::string Napi::String::Utf8Value() const;
82```
83
84Returns a UTF-8 encoded C++ string.
85
86### Utf16Value
87```cpp
88std::u16string Napi::String::Utf16Value() const;
89```
90
91Returns a UTF-16 encoded C++ string.
92
93[`Napi::Name`]: ./name.md
94