diff --git a/doc/array_buffer.md b/doc/array_buffer.md index d6a682a..7549836 100644 --- a/doc/array_buffer.md +++ b/doc/array_buffer.md @@ -1,28 +1,30 @@ # ArrayBuffer -The `ArrayBuffer` class corresponds to the JavaScript `ArrayBuffer` class. +The `ArrayBuffer` class corresponds to the +[JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) +class. ## Methods ### New -Allocates a new `ArrayBuffer` object with a given length. +Allocates a new `ArrayBuffer` instance with a given length. ```cpp static ArrayBuffer New(napi_env env, size_t byteLength); ``` -- `[in] env`: The environment in which to create the ArrayBuffer object. +- `[in] env`: The environment in which to create the `ArrayBuffer` instance. - `[in] byteLength`: The length to be allocated, in bytes. -Returns a new `ArrayBuffer` object. +Returns a new `ArrayBuffer` instance. ### New -Wraps the provided external data into a new `ArrayBuffer` object. +Wraps the provided external data into a new `ArrayBuffer` instance. -The `ArrayBuffer` object does not assume ownership for the data and expects it -to be valid for the lifetime of the object. Since the `ArrayBuffer` is subject +The `ArrayBuffer` instance does not assume ownership for the data and expects it +to be valid for the lifetime of the instance. Since the `ArrayBuffer` is subject to garbage collection this overload is only suitable for data which is static and never needs to be freed. @@ -30,19 +32,19 @@ and never needs to be freed. static ArrayBuffer New(napi_env env, void* externalData, size_t byteLength); ``` -- `[in] env`: The environment in which to create the `ArrayBuffer` object. +- `[in] env`: The environment in which to create the `ArrayBuffer` instance. - `[in] externalData`: The pointer to the external data to wrap. - `[in] byteLength`: The length of the `externalData`, in bytes. -Returns a new `ArrayBuffer` object. +Returns a new `ArrayBuffer` instance. ### New -Wraps the provided external data into a new `ArrayBuffer` object. +Wraps the provided external data into a new `ArrayBuffer` instance. -The `ArrayBuffer` object does not assume ownership for the data and expects it -to be valid for the lifetime of the object. The data can only be freed once the -`finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been +The `ArrayBuffer` instance does not assume ownership for the data and expects it +to be valid for the lifetime of the instance. The data can only be freed once +the `finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been released. ```cpp @@ -53,22 +55,22 @@ static ArrayBuffer New(napi_env env, Finalizer finalizeCallback); ``` -- `[in] env`: The environment in which to create the `ArrayBuffer` object. +- `[in] env`: The environment in which to create the `ArrayBuffer` instance. - `[in] externalData`: The pointer to the external data to wrap. - `[in] byteLength`: The length of the `externalData`, in bytes. - `[in] finalizeCallback`: A function to be called when the `ArrayBuffer` is destroyed. It must implement `operator()`, accept a `void*` (which is the `externalData` pointer), and return `void`. -Returns a new `ArrayBuffer` object. +Returns a new `ArrayBuffer` instance. ### New -Wraps the provided external data into a new `ArrayBuffer` object. +Wraps the provided external data into a new `ArrayBuffer` instance. -The `ArrayBuffer` object does not assume ownership for the data and expects it -to be valid for the lifetime of the object. The data can only be freed once the -`finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been +The `ArrayBuffer` instance does not assume ownership for the data and expects it +to be valid for the lifetime of the instance. The data can only be freed once +the `finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been released. ```cpp @@ -80,7 +82,7 @@ static ArrayBuffer New(napi_env env, Hint* finalizeHint); ``` -- `[in] env`: The environment in which to create the `ArrayBuffer` object. +- `[in] env`: The environment in which to create the `ArrayBuffer` instance. - `[in] externalData`: The pointer to the external data to wrap. - `[in] byteLength`: The length of the `externalData`, in bytes. - `[in] finalizeCallback`: The function to be called when the `ArrayBuffer` is @@ -89,7 +91,7 @@ static ArrayBuffer New(napi_env env, - `[in] finalizeHint`: The hint to be passed as the second parameter of the finalize callback. -Returns a new `ArrayBuffer` object. +Returns a new `ArrayBuffer` instance. ### Constructor @@ -107,7 +109,7 @@ Initializes a wrapper instance of an existing `ArrayBuffer` object. ArrayBuffer(napi_env env, napi_value value); ``` -- `[in] env`: The environment in which to create the `ArrayBuffer` object. +- `[in] env`: The environment in which to create the `ArrayBuffer` instance. - `[in] value`: The `ArrayBuffer` reference to wrap. ### ByteLength diff --git a/doc/typed_array.md b/doc/typed_array.md index 43f5bfe..f96d364 100644 --- a/doc/typed_array.md +++ b/doc/typed_array.md @@ -1,5 +1,74 @@ -# Typed array +# TypedArray -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) +The `TypedArray` class corresponds to the +[JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) +class. + +## Methods + +### Constructor + +Initializes an empty instance of the `TypedArray` class. + +```cpp +TypedArray(); +``` + +### Constructor + +Initializes a wrapper instance of an existing `TypedArray` instance. + +```cpp +TypedArray(napi_env env, napi_value value); +``` + +- `[in] env`: The environment in which to create the `TypedArray` instance. +- `[in] value`: The `TypedArray` reference to wrap. + +### TypedArrayType + +```cpp +napi_typedarray_type TypedArrayType() const; +``` + +Returns the type of this instance. + +### ArrayBuffer + +```cpp +Napi::ArrayBuffer ArrayBuffer() const; +``` + +Returns the backing array buffer. + +### ElementSize + +```cpp +uint8_t ElementSize() const; +``` + +Returns the size of one element, in bytes. + +### ElementLength + +```cpp +size_t ElementLength() const; +``` + +Returns the number of elements. + +### ByteOffset + +```cpp +size_t ByteOffset() const; +``` + +Returns the offset into the `ArrayBuffer` where the array starts, in bytes. + +### ByteLength + +```cpp +size_t ByteLength() const; +``` + +Returns the length of the array, in bytes. diff --git a/doc/typed_array_of.md b/doc/typed_array_of.md index 4ed6548..868e5ec 100644 --- a/doc/typed_array_of.md +++ b/doc/typed_array_of.md @@ -1,5 +1,133 @@ -# Typed array of +# TypedArrayOf -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) +The `TypedArrayOf` class corresponds to the various +[JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) +classes. + +## Typedefs + +The common JavaScript `TypedArray` types are pre-defined for each of use: + +```cpp +typedef TypedArrayOf Int8Array; +typedef TypedArrayOf Uint8Array; +typedef TypedArrayOf Int16Array; +typedef TypedArrayOf Uint16Array; +typedef TypedArrayOf Int32Array; +typedef TypedArrayOf Uint32Array; +typedef TypedArrayOf Float32Array; +typedef TypedArrayOf Float64Array; +``` + +The one exception is the `Uint8ClampedArray` which requires explicit +initialization: + +```cpp +Uint8Array::New(env, length, napi_uint8_clamped_array) +``` + +Note that while it's possible to create a "clamped" array the _clamping_ +behavior is only applied in JavaScript. + +## Methods + +### New + +Allocates a new `TypedArray` instance with a given length. The underlying +`ArrayBuffer` is allocated automatically to the desired number of elements. + +The array type parameter can normally be omitted (because it is inferred from +the template parameter T), except when creating a "clamped" array. + +```cpp +static TypedArrayOf New(napi_env env, + size_t elementLength, + napi_typedarray_type type); +``` + +- `[in] env`: The environment in which to create the `TypedArrayOf` instance. +- `[in] elementLength`: The length to be allocated, in elements. +- `[in] type`: The type of array to allocate (optional). + +Returns a new `TypedArrayOf` instance. + +### New + +Wraps the provided `ArrayBuffer` into a new `TypedArray` instance. + +The array `type` parameter can normally be omitted (because it is inferred from +the template parameter `T`), except when creating a "clamped" array. + +```cpp +static TypedArrayOf New(napi_env env, + size_t elementLength, + Napi::ArrayBuffer arrayBuffer, + size_t bufferOffset, + napi_typedarray_type type); +``` + +- `[in] env`: The environment in which to create the `TypedArrayOf` instance. +- `[in] elementLength`: The length to array, in elements. +- `[in] arrayBuffer`: The backing `ArrayBuffer` instance. +- `[in] bufferOffset`: The offset into the `ArrayBuffer` where the array starts, + in bytes. +- `[in] type`: The type of array to allocate (optional). + +Returns a new `TypedArrayOf` instance. + +### Constructor + +Initializes an empty instance of the `TypedArrayOf` class. + +```cpp +TypedArrayOf(); +``` + +### Constructor + +Initializes a wrapper instance of an existing `TypedArrayOf` object. + +```cpp +TypedArrayOf(napi_env env, napi_value value); +``` + +- `[in] env`: The environment in which to create the `TypedArrayOf` object. +- `[in] value`: The `TypedArrayOf` reference to wrap. + +### operator [] + +```cpp +T& operator [](size_t index); +``` + +- `[in] index: The element index into the array. + +Returns the element found at the given index. + +### operator [] + +```cpp +const T& operator [](size_t index) const; +``` + +- `[in] index: The element index into the array. + +Returns the element found at the given index. + +### Data + +```cpp +T* Data() const; +``` + +Returns a pointer into the backing `ArrayBuffer` which is offset to point to the +start of the array. + +### Data + +```cpp +const T* Data() const +``` + +Returns a pointer into the backing `ArrayBuffer` which is offset to point to the +start of the array.