1# Buffer
2
3Class `Napi::Buffer` inherits from class [`Napi::Uint8Array`][].
4
5The `Napi::Buffer` class creates a projection of raw data that can be consumed by
6script.
7
8## Methods
9
10### New
11
12Allocates a new `Napi::Buffer` object with a given length.
13
14```cpp
15static Napi::Buffer<T> Napi::Buffer::New(napi_env env, size_t length);
16```
17
18- `[in] env`: The environment in which to create the `Napi::Buffer` object.
19- `[in] length`: The number of `T` elements to allocate.
20
21Returns a new `Napi::Buffer` object.
22
23### New
24
25> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
26> See [External Buffer][] for more information.
27
28Wraps the provided external data into a new `Napi::Buffer` object.
29
30The `Napi::Buffer` object does not assume ownership for the data and expects it to be
31valid for the lifetime of the object. Since the `Napi::Buffer` is subject to garbage
32collection this overload is only suitable for data which is static and never
33needs to be freed.
34This factory method will not provide the caller with an opportunity to free the
35data when the `Napi::Buffer` gets garbage-collected. If you need to free the
36data retained by the `Napi::Buffer` object please use other variants of the
37`Napi::Buffer::New` factory method that accept `Napi::Finalizer`, which is a
38function that will be invoked when the `Napi::Buffer` object has been
39destroyed.
40
41```cpp
42static Napi::Buffer<T> Napi::Buffer::New(napi_env env, T* data, size_t length);
43```
44
45- `[in] env`: The environment in which to create the `Napi::Buffer` object.
46- `[in] data`: The pointer to the external data to expose.
47- `[in] length`: The number of `T` elements in the external data.
48
49Returns a new `Napi::Buffer` object.
50
51### New
52
53> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
54> See [External Buffer][] for more information.
55
56Wraps the provided external data into a new `Napi::Buffer` object.
57
58The `Napi::Buffer` object does not assume ownership for the data and expects it
59to be valid for the lifetime of the object. The data can only be freed once the
60`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released.
61
62```cpp
63template <typename Finalizer>
64static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
65                     T* data,
66                     size_t length,
67                     Finalizer finalizeCallback);
68```
69
70- `[in] env`: The environment in which to create the `Napi::Buffer` object.
71- `[in] data`: The pointer to the external data to expose.
72- `[in] length`: The number of `T` elements in the external data.
73- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
74  destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
75  external data pointer), and return `void`.
76
77Returns a new `Napi::Buffer` object.
78
79### New
80
81> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
82> See [External Buffer][] for more information.
83
84Wraps the provided external data into a new `Napi::Buffer` object.
85
86The `Napi::Buffer` object does not assume ownership for the data and expects it to be
87valid for the lifetime of the object. The data can only be freed once the
88`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released.
89
90```cpp
91template <typename Finalizer, typename Hint>
92static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
93                     T* data,
94                     size_t length,
95                     Finalizer finalizeCallback,
96                     Hint* finalizeHint);
97```
98
99- `[in] env`: The environment in which to create the `Napi::Buffer` object.
100- `[in] data`: The pointer to the external data to expose.
101- `[in] length`: The number of `T` elements in the external data.
102- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
103  destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
104  external data pointer) and `Hint*`, and return `void`.
105- `[in] finalizeHint`: The hint to be passed as the second parameter of the
106  finalize callback.
107
108Returns a new `Napi::Buffer` object.
109
110### NewOrCopy
111
112Wraps the provided external data into a new `Napi::Buffer` object. When the
113[external buffer][] is not supported, allocates a new `Napi::Buffer` object and
114copies the provided external data into it.
115
116The `Napi::Buffer` object does not assume ownership for the data and expects it to be
117valid for the lifetime of the object. Since the `Napi::Buffer` is subject to garbage
118collection this overload is only suitable for data which is static and never
119needs to be freed.
120
121This factory method will not provide the caller with an opportunity to free the
122data when the `Napi::Buffer` gets garbage-collected. If you need to free the
123data retained by the `Napi::Buffer` object please use other variants of the
124`Napi::Buffer::New` factory method that accept `Napi::Finalizer`, which is a
125function that will be invoked when the `Napi::Buffer` object has been
126destroyed.
127
128```cpp
129static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env, T* data, size_t length);
130```
131
132- `[in] env`: The environment in which to create the `Napi::Buffer` object.
133- `[in] data`: The pointer to the external data to expose.
134- `[in] length`: The number of `T` elements in the external data.
135
136Returns a new `Napi::Buffer` object.
137
138### NewOrCopy
139
140Wraps the provided external data into a new `Napi::Buffer` object. When the
141[external buffer][] is not supported, allocates a new `Napi::Buffer` object and
142copies the provided external data into it and the `finalizeCallback` is invoked
143immediately.
144
145The `Napi::Buffer` object does not assume ownership for the data and expects it
146to be valid for the lifetime of the object. The data can only be freed once the
147`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released.
148
149```cpp
150template <typename Finalizer>
151static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env,
152                                               T* data,
153                                               size_t length,
154                                               Finalizer finalizeCallback);
155```
156
157- `[in] env`: The environment in which to create the `Napi::Buffer` object.
158- `[in] data`: The pointer to the external data to expose.
159- `[in] length`: The number of `T` elements in the external data.
160- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
161  destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
162  external data pointer), and return `void`.
163
164Returns a new `Napi::Buffer` object.
165
166### NewOrCopy
167
168Wraps the provided external data into a new `Napi::Buffer` object. When the
169[external buffer][] is not supported, allocates a new `Napi::Buffer` object and
170copies the provided external data into it and the `finalizeCallback` is invoked
171immediately.
172
173The `Napi::Buffer` object does not assume ownership for the data and expects it to be
174valid for the lifetime of the object. The data can only be freed once the
175`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released.
176
177```cpp
178template <typename Finalizer, typename Hint>
179static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env,
180                                               T* data,
181                                               size_t length,
182                                               Finalizer finalizeCallback,
183                                               Hint* finalizeHint);
184```
185
186- `[in] env`: The environment in which to create the `Napi::Buffer` object.
187- `[in] data`: The pointer to the external data to expose.
188- `[in] length`: The number of `T` elements in the external data.
189- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
190  destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
191  external data pointer) and `Hint*`, and return `void`.
192- `[in] finalizeHint`: The hint to be passed as the second parameter of the
193  finalize callback.
194
195Returns a new `Napi::Buffer` object.
196
197### Copy
198
199Allocates a new `Napi::Buffer` object and copies the provided external data into it.
200
201```cpp
202static Napi::Buffer<T> Napi::Buffer::Copy(napi_env env, const T* data, size_t length);
203```
204
205- `[in] env`: The environment in which to create the `Napi::Buffer` object.
206- `[in] data`: The pointer to the external data to copy.
207- `[in] length`: The number of `T` elements in the external data.
208
209Returns a new `Napi::Buffer` object containing a copy of the data.
210
211### Constructor
212
213Initializes an empty instance of the `Napi::Buffer` class.
214
215```cpp
216Napi::Buffer::Buffer();
217```
218
219### Constructor
220
221Initializes the `Napi::Buffer` object using an existing Uint8Array.
222
223```cpp
224Napi::Buffer::Buffer(napi_env env, napi_value value);
225```
226
227- `[in] env`: The environment in which to create the `Napi::Buffer` object.
228- `[in] value`: The Uint8Array reference to wrap.
229
230### Data
231
232```cpp
233T* Napi::Buffer::Data() const;
234```
235
236Returns a pointer the external data.
237
238### Length
239
240```cpp
241size_t Napi::Buffer::Length() const;
242```
243
244Returns the number of `T` elements in the external data.
245
246[`Napi::Uint8Array`]: ./typed_array_of.md
247[External Buffer]: ./external_buffer.md
248