1# ArrayBuffer
2
3Class `Napi::ArrayBuffer` inherits from class [`Napi::Object`][].
4
5The `Napi::ArrayBuffer` class corresponds to the
6[JavaScript `ArrayBuffer`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
7class.
8
9## Methods
10
11### New
12
13Allocates a new `Napi::ArrayBuffer` instance with a given length.
14
15```cpp
16static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, size_t byteLength);
17```
18
19- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
20- `[in] byteLength`: The length to be allocated, in bytes.
21
22Returns a new `Napi::ArrayBuffer` instance.
23
24### New
25
26> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
27> See [External Buffer][] for more information.
28
29Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
30
31The `Napi::ArrayBuffer` instance does not assume ownership for the data and
32expects it to be valid for the lifetime of the instance. Since the
33`Napi::ArrayBuffer` is subject to garbage collection this overload is only
34suitable for data which is static and never needs to be freed.
35This factory method will not provide the caller with an opportunity to free the
36data when the `Napi::ArrayBuffer` gets garbage-collected. If you need to free
37the data retained by the `Napi::ArrayBuffer` object please use other
38variants of the `Napi::ArrayBuffer::New` factory method that accept
39`Napi::Finalizer`, which is a function that will be invoked when the
40`Napi::ArrayBuffer` object has been destroyed.
41
42```cpp
43static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength);
44```
45
46- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
47- `[in] externalData`: The pointer to the external data to wrap.
48- `[in] byteLength`: The length of the `externalData`, in bytes.
49
50Returns a new `Napi::ArrayBuffer` instance.
51
52### New
53
54> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
55> See [External Buffer][] for more information.
56
57Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
58
59The `Napi::ArrayBuffer` instance does not assume ownership for the data and
60expects it to be valid for the lifetime of the instance. The data can only be
61freed once the `finalizeCallback` is invoked to indicate that the
62`Napi::ArrayBuffer` has been released.
63
64```cpp
65template <typename Finalizer>
66static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
67                       void* externalData,
68                       size_t byteLength,
69                       Finalizer finalizeCallback);
70```
71
72- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
73- `[in] externalData`: The pointer to the external data to wrap.
74- `[in] byteLength`: The length of the `externalData`, in bytes.
75- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
76  destroyed. It must implement `operator()`, accept an Napi::Env, a `void*` (which is the
77  `externalData` pointer), and return `void`.
78
79Returns a new `Napi::ArrayBuffer` instance.
80
81### New
82
83> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
84> See [External Buffer][] for more information.
85
86Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
87
88The `Napi::ArrayBuffer` instance does not assume ownership for the data and expects it
89to be valid for the lifetime of the instance. The data can only be freed once
90the `finalizeCallback` is invoked to indicate that the `Napi::ArrayBuffer` has been
91released.
92
93```cpp
94template <typename Finalizer, typename Hint>
95static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
96                       void* externalData,
97                       size_t byteLength,
98                       Finalizer finalizeCallback,
99                       Hint* finalizeHint);
100```
101
102- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
103- `[in] externalData`: The pointer to the external data to wrap.
104- `[in] byteLength`: The length of the `externalData`, in bytes.
105- `[in] finalizeCallback`: The function to be called when the `Napi::ArrayBuffer` is
106  destroyed. It must implement `operator()`, accept an Napi::Env, a `void*` (which is the
107  `externalData` pointer) and `Hint*`, and return `void`.
108- `[in] finalizeHint`: The hint to be passed as the second parameter of the
109  finalize callback.
110
111Returns a new `Napi::ArrayBuffer` instance.
112
113### Constructor
114
115Initializes an empty instance of the `Napi::ArrayBuffer` class.
116
117```cpp
118Napi::ArrayBuffer::ArrayBuffer();
119```
120
121### Constructor
122
123Initializes a wrapper instance of an existing `Napi::ArrayBuffer` object.
124
125```cpp
126Napi::ArrayBuffer::ArrayBuffer(napi_env env, napi_value value);
127```
128
129- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
130- `[in] value`: The `Napi::ArrayBuffer` reference to wrap.
131
132### ByteLength
133
134```cpp
135size_t Napi::ArrayBuffer::ByteLength() const;
136```
137
138Returns the length of the wrapped data, in bytes.
139
140### Data
141
142```cpp
143void* Napi::ArrayBuffer::Data() const;
144```
145
146Returns a pointer the wrapped data.
147
148### Detach
149
150```cpp
151void Napi::ArrayBuffer::Detach();
152```
153
154Invokes the `ArrayBuffer` detach operation on a detachable `ArrayBuffer`.
155
156### IsDetached
157
158```cpp
159bool Napi::ArrayBuffer::IsDetached() const;
160```
161
162Returns `true` if this `ArrayBuffer` has been detached.
163
164[`Napi::Object`]: ./object.md
165[External Buffer]: ./external_buffer.md
166