Skip to content

Commit d8a423b

Browse files
MarlyfleitasMarlyfleitas
committed
doc: ArrayBuffer and Buffer documentation
PR-URL: nodejs/node-addon-api#256 Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
1 parent 445f86b commit d8a423b

File tree

2 files changed

+264
-7
lines changed

2 files changed

+264
-7
lines changed

‎doc/array_buffer.md

Lines changed: 126 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,127 @@
1-
# Array buffer
1+
# ArrayBuffer
22

3-
You are reading a draft of the next documentation and it's in continuous update so
4-
if you don't find what you need please refer to:
5-
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
3+
The `ArrayBuffer` class corresponds to the JavaScript `ArrayBuffer` class.
4+
5+
## Methods
6+
7+
### New
8+
9+
Allocates a new `ArrayBuffer` object with a given length.
10+
11+
```cpp
12+
static ArrayBuffer New(napi_env env, size_t byteLength);
13+
```
14+
15+
- `[in] env`: The environment in which to create the ArrayBuffer object.
16+
- `[in] byteLength`: The length to be allocated, in bytes.
17+
18+
Returns a new `ArrayBuffer` object.
19+
20+
### New
21+
22+
Wraps the provided external data into a new `ArrayBuffer` object.
23+
24+
The `ArrayBuffer` object does not assume ownership for the data and expects it
25+
to be valid for the lifetime of the object. Since the `ArrayBuffer` is subject
26+
to garbage collection this overload is only suitable for data which is static
27+
and never needs to be freed.
28+
29+
```cpp
30+
static ArrayBuffer New(napi_env env, void* externalData, size_t byteLength);
31+
```
32+
33+
- `[in] env`: The environment in which to create the `ArrayBuffer` object.
34+
- `[in] externalData`: The pointer to the external data to wrap.
35+
- `[in] byteLength`: The length of the `externalData`, in bytes.
36+
37+
Returns a new `ArrayBuffer` object.
38+
39+
### New
40+
41+
Wraps the provided external data into a new `ArrayBuffer` object.
42+
43+
The `ArrayBuffer` object does not assume ownership for the data and expects it
44+
to be valid for the lifetime of the object. The data can only be freed once the
45+
`finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been
46+
released.
47+
48+
```cpp
49+
template <typename Finalizer>
50+
static ArrayBuffer New(napi_env env,
51+
void* externalData,
52+
size_t byteLength,
53+
Finalizer finalizeCallback);
54+
```
55+
56+
- `[in] env`: The environment in which to create the `ArrayBuffer` object.
57+
- `[in] externalData`: The pointer to the external data to wrap.
58+
- `[in] byteLength`: The length of the `externalData`, in bytes.
59+
- `[in] finalizeCallback`: A function to be called when the `ArrayBuffer` is
60+
destroyed. It must implement `operator()`, accept a `void*` (which is the
61+
`externalData` pointer), and return `void`.
62+
63+
Returns a new `ArrayBuffer` object.
64+
65+
### New
66+
67+
Wraps the provided external data into a new `ArrayBuffer` object.
68+
69+
The `ArrayBuffer` object does not assume ownership for the data and expects it
70+
to be valid for the lifetime of the object. The data can only be freed once the
71+
`finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been
72+
released.
73+
74+
```cpp
75+
template <typename Finalizer, typename Hint>
76+
static ArrayBuffer New(napi_env env,
77+
void* externalData,
78+
size_t byteLength,
79+
Finalizer finalizeCallback,
80+
Hint* finalizeHint);
81+
```
82+
83+
- `[in] env`: The environment in which to create the `ArrayBuffer` object.
84+
- `[in] externalData`: The pointer to the external data to wrap.
85+
- `[in] byteLength`: The length of the `externalData`, in bytes.
86+
- `[in] finalizeCallback`: The function to be called when the `ArrayBuffer` is
87+
destroyed. It must implement `operator()`, accept a `void*` (which is the
88+
`externalData` pointer) and `Hint*`, and return `void`.
89+
- `[in] finalizeHint`: The hint to be passed as the second parameter of the
90+
finalize callback.
91+
92+
Returns a new `ArrayBuffer` object.
93+
94+
### Constructor
95+
96+
Initializes an empty instance of the `ArrayBuffer` class.
97+
98+
```cpp
99+
ArrayBuffer();
100+
```
101+
102+
### Constructor
103+
104+
Initializes a wrapper instance of an existing `ArrayBuffer` object.
105+
106+
```cpp
107+
ArrayBuffer(napi_env env, napi_value value);
108+
```
109+
110+
- `[in] env`: The environment in which to create the `ArrayBuffer` object.
111+
- `[in] value`: The `ArrayBuffer` reference to wrap.
112+
113+
### ByteLength
114+
115+
```cpp
116+
size_t ByteLength() const;
117+
```
118+
119+
Returns the length of the wrapped data, in bytes.
120+
121+
### Data
122+
123+
```cpp
124+
T* Data() const;
125+
```
126+
127+
Returns a pointer the wrapped data.

‎doc/buffer.md

Lines changed: 138 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,140 @@
11
# Buffer
22

3-
You are reading a draft of the next documentation and it's in continuous update so
4-
if you don't find what you need please refer to:
5-
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
3+
The `Buffer` class creates a projection of raw data that can be consumed by
4+
script.
5+
6+
## Methods
7+
8+
### New
9+
10+
Allocates a new `Buffer` object with a given length.
11+
12+
```cpp
13+
static Buffer<T> New(napi_env env, size_t length);
14+
```
15+
16+
- `[in] env`: The environment in which to create the `Buffer` object.
17+
- `[in] length`: The number of `T` elements to allocate.
18+
19+
Returns a new `Buffer` object.
20+
21+
### New
22+
23+
Wraps the provided external data into a new `Buffer` object.
24+
25+
The `Buffer` object does not assume ownership for the data and expects it to be
26+
valid for the lifetime of the object. Since the `Buffer` is subject to garbage
27+
collection this overload is only suitable for data which is static and never
28+
needs to be freed.
29+
30+
```cpp
31+
static Buffer<T> New(napi_env env, T* data, size_t length);
32+
```
33+
34+
- `[in] env`: The environment in which to create the `Buffer` object.
35+
- `[in] data`: The pointer to the external data to expose.
36+
- `[in] length`: The number of `T` elements in the external data.
37+
38+
Returns a new `Buffer` object.
39+
40+
### New
41+
42+
Wraps the provided external data into a new `Buffer` object.
43+
44+
The `Buffer` object does not assume ownership for the data and expects it
45+
to be valid for the lifetime of the object. The data can only be freed once the
46+
`finalizeCallback` is invoked to indicate that the `Buffer` has been released.
47+
48+
```cpp
49+
template <typename Finalizer>
50+
static Buffer<T> New(napi_env env,
51+
T* data,
52+
size_t length,
53+
Finalizer finalizeCallback);
54+
```
55+
56+
- `[in] env`: The environment in which to create the `Buffer` object.
57+
- `[in] data`: The pointer to the external data to expose.
58+
- `[in] length`: The number of `T` elements in the external data.
59+
- `[in] finalizeCallback`: The function to be called when the `Buffer` is
60+
destroyed. It must implement `operator()`, accept a `T*` (which is the
61+
external data pointer), and return `void`.
62+
63+
Returns a new `Buffer` object.
64+
65+
### New
66+
67+
Wraps the provided external data into a new `Buffer` object.
68+
69+
The `Buffer` object does not assume ownership for the data and expects it to be
70+
valid for the lifetime of the object. The data can only be freed once the
71+
`finalizeCallback` is invoked to indicate that the `Buffer` has been released.
72+
73+
```cpp
74+
template <typename Finalizer, typename Hint>
75+
static Buffer<T> New(napi_env env,
76+
T* data,
77+
size_t length,
78+
Finalizer finalizeCallback,
79+
Hint* finalizeHint);
80+
```
81+
82+
- `[in] env`: The environment in which to create the `Buffer` object.
83+
- `[in] data`: The pointer to the external data to expose.
84+
- `[in] length`: The number of `T` elements in the external data.
85+
- `[in] finalizeCallback`: The function to be called when the `Buffer` is
86+
destroyed. It must implement `operator()`, accept a `T*` (which is the
87+
external data pointer) and `Hint*`, and return `void`.
88+
- `[in] finalizeHint`: The hint to be passed as the second parameter of the
89+
finalize callback.
90+
91+
Returns a new `Buffer` object.
92+
93+
### Copy
94+
95+
Allocates a new `Buffer` object and copies the provided external data into it.
96+
97+
```cpp
98+
static Buffer<T> Copy(napi_env env, const T* data, size_t length);
99+
```
100+
101+
- `[in] env`: The environment in which to create the `Buffer` object.
102+
- `[in] data`: The pointer to the external data to copy.
103+
- `[in] length`: The number of `T` elements in the external data.
104+
105+
Returns a new `Buffer` object containing a copy of the data.
106+
107+
### Constructor
108+
109+
Initializes an empty instance of the `Buffer` class.
110+
111+
```cpp
112+
Buffer();
113+
```
114+
115+
### Constructor
116+
117+
Initializes the `Buffer` object using an existing Uint8Array.
118+
119+
```cpp
120+
Buffer(napi_env env, napi_value value);
121+
```
122+
123+
- `[in] env`: The environment in which to create the `Buffer` object.
124+
- `[in] value`: The Uint8Array reference to wrap.
125+
126+
### Data
127+
128+
```cpp
129+
T* Data() const;
130+
```
131+
132+
Returns a pointer the external data.
133+
134+
### Length
135+
136+
```cpp
137+
size_t Length() const;
138+
```
139+
140+
Returns the number of `T` elements in the external data.

0 commit comments

Comments
 (0)