Skip to content

Commit 908cdc3

Browse files
kfarnungmhdawson
kfarnung
authored and
mhdawson
committed
doc: add TypedArray and TypedArrayOf
* Added documentation for `TypedArray` and `TypedArrayOf` * Tweaked the documentation for `ArrayBuffer` PR-URL: #305 Reviewed-By: Michael Dawson <[email protected]>
1 parent 2ff776f commit 908cdc3

File tree

3 files changed

+229
-30
lines changed

3 files changed

+229
-30
lines changed

‎doc/array_buffer.md

Lines changed: 24 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,50 @@
11
# ArrayBuffer
22

3-
The `ArrayBuffer` class corresponds to the JavaScript `ArrayBuffer` class.
3+
The `ArrayBuffer` class corresponds to the
4+
[JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
5+
class.
46

57
## Methods
68

79
### New
810

9-
Allocates a new `ArrayBuffer` object with a given length.
11+
Allocates a new `ArrayBuffer` instance with a given length.
1012

1113
```cpp
1214
static ArrayBuffer New(napi_env env, size_t byteLength);
1315
```
1416
15-
- `[in] env`: The environment in which to create the ArrayBuffer object.
17+
- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
1618
- `[in] byteLength`: The length to be allocated, in bytes.
1719
18-
Returns a new `ArrayBuffer` object.
20+
Returns a new `ArrayBuffer` instance.
1921
2022
### New
2123
22-
Wraps the provided external data into a new `ArrayBuffer` object.
24+
Wraps the provided external data into a new `ArrayBuffer` instance.
2325
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+
The `ArrayBuffer` instance does not assume ownership for the data and expects it
27+
to be valid for the lifetime of the instance. Since the `ArrayBuffer` is subject
2628
to garbage collection this overload is only suitable for data which is static
2729
and never needs to be freed.
2830
2931
```cpp
3032
static ArrayBuffer New(napi_env env, void* externalData, size_t byteLength);
3133
```
3234

33-
- `[in] env`: The environment in which to create the `ArrayBuffer` object.
35+
- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
3436
- `[in] externalData`: The pointer to the external data to wrap.
3537
- `[in] byteLength`: The length of the `externalData`, in bytes.
3638

37-
Returns a new `ArrayBuffer` object.
39+
Returns a new `ArrayBuffer` instance.
3840

3941
### New
4042

41-
Wraps the provided external data into a new `ArrayBuffer` object.
43+
Wraps the provided external data into a new `ArrayBuffer` instance.
4244

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
45+
The `ArrayBuffer` instance does not assume ownership for the data and expects it
46+
to be valid for the lifetime of the instance. The data can only be freed once
47+
the `finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been
4648
released.
4749

4850
```cpp
@@ -53,22 +55,22 @@ static ArrayBuffer New(napi_env env,
5355
Finalizer finalizeCallback);
5456
```
5557
56-
- `[in] env`: The environment in which to create the `ArrayBuffer` object.
58+
- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
5759
- `[in] externalData`: The pointer to the external data to wrap.
5860
- `[in] byteLength`: The length of the `externalData`, in bytes.
5961
- `[in] finalizeCallback`: A function to be called when the `ArrayBuffer` is
6062
destroyed. It must implement `operator()`, accept a `void*` (which is the
6163
`externalData` pointer), and return `void`.
6264
63-
Returns a new `ArrayBuffer` object.
65+
Returns a new `ArrayBuffer` instance.
6466
6567
### New
6668
67-
Wraps the provided external data into a new `ArrayBuffer` object.
69+
Wraps the provided external data into a new `ArrayBuffer` instance.
6870
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
71+
The `ArrayBuffer` instance does not assume ownership for the data and expects it
72+
to be valid for the lifetime of the instance. The data can only be freed once
73+
the `finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been
7274
released.
7375
7476
```cpp
@@ -80,7 +82,7 @@ static ArrayBuffer New(napi_env env,
8082
Hint* finalizeHint);
8183
```
8284

83-
- `[in] env`: The environment in which to create the `ArrayBuffer` object.
85+
- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
8486
- `[in] externalData`: The pointer to the external data to wrap.
8587
- `[in] byteLength`: The length of the `externalData`, in bytes.
8688
- `[in] finalizeCallback`: The function to be called when the `ArrayBuffer` is
@@ -89,7 +91,7 @@ static ArrayBuffer New(napi_env env,
8991
- `[in] finalizeHint`: The hint to be passed as the second parameter of the
9092
finalize callback.
9193

92-
Returns a new `ArrayBuffer` object.
94+
Returns a new `ArrayBuffer` instance.
9395

9496
### Constructor
9597

@@ -107,7 +109,7 @@ Initializes a wrapper instance of an existing `ArrayBuffer` object.
107109
ArrayBuffer(napi_env env, napi_value value);
108110
```
109111
110-
- `[in] env`: The environment in which to create the `ArrayBuffer` object.
112+
- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
111113
- `[in] value`: The `ArrayBuffer` reference to wrap.
112114
113115
### ByteLength

‎doc/typed_array.md

Lines changed: 73 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,74 @@
1-
# Typed array
1+
# TypedArray
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 `TypedArray` class corresponds to the
4+
[JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
5+
class.
6+
7+
## Methods
8+
9+
### Constructor
10+
11+
Initializes an empty instance of the `TypedArray` class.
12+
13+
```cpp
14+
TypedArray();
15+
```
16+
17+
### Constructor
18+
19+
Initializes a wrapper instance of an existing `TypedArray` instance.
20+
21+
```cpp
22+
TypedArray(napi_env env, napi_value value);
23+
```
24+
25+
- `[in] env`: The environment in which to create the `TypedArray` instance.
26+
- `[in] value`: The `TypedArray` reference to wrap.
27+
28+
### TypedArrayType
29+
30+
```cpp
31+
napi_typedarray_type TypedArrayType() const;
32+
```
33+
34+
Returns the type of this instance.
35+
36+
### ArrayBuffer
37+
38+
```cpp
39+
Napi::ArrayBuffer ArrayBuffer() const;
40+
```
41+
42+
Returns the backing array buffer.
43+
44+
### ElementSize
45+
46+
```cpp
47+
uint8_t ElementSize() const;
48+
```
49+
50+
Returns the size of one element, in bytes.
51+
52+
### ElementLength
53+
54+
```cpp
55+
size_t ElementLength() const;
56+
```
57+
58+
Returns the number of elements.
59+
60+
### ByteOffset
61+
62+
```cpp
63+
size_t ByteOffset() const;
64+
```
65+
66+
Returns the offset into the `ArrayBuffer` where the array starts, in bytes.
67+
68+
### ByteLength
69+
70+
```cpp
71+
size_t ByteLength() const;
72+
```
73+
74+
Returns the length of the array, in bytes.

‎doc/typed_array_of.md

Lines changed: 132 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,133 @@
1-
# Typed array of
1+
# TypedArrayOf
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 `TypedArrayOf` class corresponds to the various
4+
[JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
5+
classes.
6+
7+
## Typedefs
8+
9+
The common JavaScript `TypedArray` types are pre-defined for each of use:
10+
11+
```cpp
12+
typedef TypedArrayOf<int8_t> Int8Array;
13+
typedef TypedArrayOf<uint8_t> Uint8Array;
14+
typedef TypedArrayOf<int16_t> Int16Array;
15+
typedef TypedArrayOf<uint16_t> Uint16Array;
16+
typedef TypedArrayOf<int32_t> Int32Array;
17+
typedef TypedArrayOf<uint32_t> Uint32Array;
18+
typedef TypedArrayOf<float> Float32Array;
19+
typedef TypedArrayOf<double> Float64Array;
20+
```
21+
22+
The one exception is the `Uint8ClampedArray` which requires explicit
23+
initialization:
24+
25+
```cpp
26+
Uint8Array::New(env, length, napi_uint8_clamped_array)
27+
```
28+
29+
Note that while it's possible to create a "clamped" array the _clamping_
30+
behavior is only applied in JavaScript.
31+
32+
## Methods
33+
34+
### New
35+
36+
Allocates a new `TypedArray` instance with a given length. The underlying
37+
`ArrayBuffer` is allocated automatically to the desired number of elements.
38+
39+
The array type parameter can normally be omitted (because it is inferred from
40+
the template parameter T), except when creating a "clamped" array.
41+
42+
```cpp
43+
static TypedArrayOf New(napi_env env,
44+
size_t elementLength,
45+
napi_typedarray_type type);
46+
```
47+
48+
- `[in] env`: The environment in which to create the `TypedArrayOf` instance.
49+
- `[in] elementLength`: The length to be allocated, in elements.
50+
- `[in] type`: The type of array to allocate (optional).
51+
52+
Returns a new `TypedArrayOf` instance.
53+
54+
### New
55+
56+
Wraps the provided `ArrayBuffer` into a new `TypedArray` instance.
57+
58+
The array `type` parameter can normally be omitted (because it is inferred from
59+
the template parameter `T`), except when creating a "clamped" array.
60+
61+
```cpp
62+
static TypedArrayOf New(napi_env env,
63+
size_t elementLength,
64+
Napi::ArrayBuffer arrayBuffer,
65+
size_t bufferOffset,
66+
napi_typedarray_type type);
67+
```
68+
69+
- `[in] env`: The environment in which to create the `TypedArrayOf` instance.
70+
- `[in] elementLength`: The length to array, in elements.
71+
- `[in] arrayBuffer`: The backing `ArrayBuffer` instance.
72+
- `[in] bufferOffset`: The offset into the `ArrayBuffer` where the array starts,
73+
in bytes.
74+
- `[in] type`: The type of array to allocate (optional).
75+
76+
Returns a new `TypedArrayOf` instance.
77+
78+
### Constructor
79+
80+
Initializes an empty instance of the `TypedArrayOf` class.
81+
82+
```cpp
83+
TypedArrayOf();
84+
```
85+
86+
### Constructor
87+
88+
Initializes a wrapper instance of an existing `TypedArrayOf` object.
89+
90+
```cpp
91+
TypedArrayOf(napi_env env, napi_value value);
92+
```
93+
94+
- `[in] env`: The environment in which to create the `TypedArrayOf` object.
95+
- `[in] value`: The `TypedArrayOf` reference to wrap.
96+
97+
### operator []
98+
99+
```cpp
100+
T& operator [](size_t index);
101+
```
102+
103+
- `[in] index: The element index into the array.
104+
105+
Returns the element found at the given index.
106+
107+
### operator []
108+
109+
```cpp
110+
const T& operator [](size_t index) const;
111+
```
112+
113+
- `[in] index: The element index into the array.
114+
115+
Returns the element found at the given index.
116+
117+
### Data
118+
119+
```cpp
120+
T* Data() const;
121+
```
122+
123+
Returns a pointer into the backing `ArrayBuffer` which is offset to point to the
124+
start of the array.
125+
126+
### Data
127+
128+
```cpp
129+
const T* Data() const
130+
```
131+
132+
Returns a pointer into the backing `ArrayBuffer` which is offset to point to the
133+
start of the array.

0 commit comments

Comments
 (0)