feat(buffer): support C++20 std::span overloads

doc/array_buffer.md

@@ -109,6 +109,89 @@ static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
 
 Returns a new `Napi::ArrayBuffer` instance.
 
+### New
+
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined or when C++20 `std::span` is not available, this method is not available.
+> See [External Buffer][] for more information.
+
+Wraps the provided external data span into a new `Napi::ArrayBuffer` instance.
+
+The `Napi::ArrayBuffer` instance does not assume ownership for the data and
+expects it to be valid for the lifetime of the instance. Since the
+`Napi::ArrayBuffer` is subject to garbage collection this overload is only
+suitable for data which is static and never needs to be freed. This factory
+method will not provide the caller with an opportunity to free the data when the
+`Napi::ArrayBuffer` gets garbage-collected. If you need to free the data
+retained by the `Napi::ArrayBuffer` object please use other variants of the
+`Napi::ArrayBuffer::New` factory method that accept `Napi::Finalizer`.
+See [Finalization][] for more details.
+
+```cpp
+template <typename T, size_t Extent = std::dynamic_extent>
+static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, std::span<T, Extent> span);
+```
+
+- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
+- `[in] span`: The `std::span` referencing the external data to wrap.
+
+Returns a new `Napi::ArrayBuffer` instance.
+
+### New
+
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined or when C++20 `std::span` is not available, this method is not available.
+> See [External Buffer][] for more information.
+
+Wraps the provided external data span into a new `Napi::ArrayBuffer` instance.
+
+The `Napi::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
+`Napi::ArrayBuffer` has been released.
+
+```cpp
+template <typename T, size_t Extent, typename Finalizer>
+static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
+                       std::span<T, Extent> span,
+                       Finalizer finalizeCallback);
+```
+
+- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
+- `[in] span`: The `std::span` referencing the external data to wrap.
+- `[in] finalizeCallback`: A function called when the engine destroys the
+  `Napi::ArrayBuffer` object, implementing `operator()(Napi::BasicEnv, void*)`.
+  See [Finalization][] for more details.
+
+Returns a new `Napi::ArrayBuffer` instance.
+
+### New
+
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined or when C++20 `std::span` is not available, this method is not available.
+> See [External Buffer][] for more information.
+
+Wraps the provided external data span into a new `Napi::ArrayBuffer` instance.
+
+The `Napi::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 `Napi::ArrayBuffer` has been
+released.
+
+```cpp
+template <typename T, size_t Extent, typename Finalizer, typename Hint>
+static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
+                       std::span<T, Extent> span,
+                       Finalizer finalizeCallback,
+                       Hint* finalizeHint);
+```
+
+- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
+- `[in] span`: The `std::span` referencing the external data to wrap.
+- `[in] finalizeCallback`: A function called when the engine destroys the
+  `Napi::ArrayBuffer` object, implementing `operator()(Napi::BasicEnv, void*,
+  Hint*)`. See [Finalization][] for more details.
+- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
+
+Returns a new `Napi::ArrayBuffer` instance.
+
 ### Constructor
 
 Initializes an empty instance of the `Napi::ArrayBuffer` class.
@@ -144,6 +227,16 @@ void* Napi::ArrayBuffer::Data() const;
 
 Returns a pointer the wrapped data.
 
+### Span
+
+> When C++20 `std::span` is not available, this method is not available.
+
+```cpp
+std::span<uint8_t> Napi::ArrayBuffer::Span() const;
+```
+
+Returns a `std::span<uint8_t>` view over the raw byte data.
+
 ### Detach
 
 ```cpp

doc/buffer.md

@@ -105,6 +105,86 @@ static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
 
 Returns a new `Napi::Buffer` object.
 
+### New
+
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined or when C++20 `std::span` is not available, this method is not available.
+> See [External Buffer][] for more information.
+
+Wraps the provided external data span into a new `Napi::Buffer` object.
+
+The `Napi::Buffer` object does not assume ownership for the data and expects it
+to be valid for the lifetime of the object. Since the `Napi::Buffer` is subject
+to garbage collection this overload is only suitable for data which is static
+and never needs to be freed. This factory method will not provide the caller
+with an opportunity to free the data when the `Napi::Buffer` gets
+garbage-collected. If you need to free the data retained by the `Napi::Buffer`
+object please use other variants of the `Napi::Buffer::New` factory method that
+accept `Finalizer`. See [Finalization][] for more details.
+
+```cpp
+template <size_t Extent = std::dynamic_extent>
+static Napi::Buffer<T> Napi::Buffer::New(napi_env env, std::span<T, Extent> span);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] span`: The `std::span` referencing the external data to expose.
+
+Returns a new `Napi::Buffer` object.
+
+### New
+
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined or when C++20 `std::span` is not available, this method is not available.
+> See [External Buffer][] for more information.
+
+Wraps the provided external data span into a new `Napi::Buffer` object.
+
+The `Napi::Buffer` 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 `Napi::Buffer` has been released.
+
+```cpp
+template <size_t Extent, typename Finalizer>
+static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
+                     std::span<T, Extent> span,
+                     Finalizer finalizeCallback);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] span`: The `std::span` referencing the external data to expose.
+- `[in] finalizeCallback`: The function called when the engine destroys the
+  `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*)`. See
+  [Finalization][] for more details.
+
+Returns a new `Napi::Buffer` object.
+
+### New
+
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined or when C++20 `std::span` is not available, this method is not available.
+> See [External Buffer][] for more information.
+
+Wraps the provided external data span into a new `Napi::Buffer` object.
+
+The `Napi::Buffer` 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 `Napi::Buffer` has been released.
+
+```cpp
+template <size_t Extent, typename Finalizer, typename Hint>
+static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
+                     std::span<T, Extent> span,
+                     Finalizer finalizeCallback,
+                     Hint* finalizeHint);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] span`: The `std::span` referencing the external data to expose.
+- `[in] finalizeCallback`: The function called when the engine destroys the
+  `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`.
+  See [Finalization][] for more details.
+- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
+
+Returns a new `Napi::Buffer` object.
+
 ### NewOrCopy
 
 Wraps the provided external data into a new `Napi::Buffer` object. When the
@@ -191,6 +271,87 @@ static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env,
 
 Returns a new `Napi::Buffer` object.
 
+### NewOrCopy
+
+> When C++20 `std::span` is not available, this method is not available.
+
+Wraps the provided external data span into a new `Napi::Buffer` object. When the
+[external buffer][] is not supported, allocates a new `Napi::Buffer` object and
+copies the provided external data into it.
+
+The `Napi::Buffer` object does not assume ownership for the data and expects it to be
+valid for the lifetime of the object. Since the `Napi::Buffer` is subject to garbage
+collection this overload is only suitable for data which is static and never
+needs to be freed.
+
+```cpp
+template <size_t Extent = std::dynamic_extent>
+static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env, std::span<T, Extent> span);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] span`: The `std::span` referencing the external data to expose.
+
+Returns a new `Napi::Buffer` object.
+
+### NewOrCopy
+
+> When C++20 `std::span` is not available, this method is not available.
+
+Wraps the provided external data span into a new `Napi::Buffer` object. When the
+[external buffer][] is not supported, allocates a new `Napi::Buffer` object and
+copies the provided external data into it and the `finalizeCallback` is invoked
+immediately.
+
+The `Napi::Buffer` 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 `Napi::Buffer` has been released.
+
+```cpp
+template <size_t Extent, typename Finalizer>
+static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env,
+                                               std::span<T, Extent> span,
+                                               Finalizer finalizeCallback);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] span`: The `std::span` referencing the external data to expose.
+- `[in] finalizeCallback`: The function called when the engine destroys the
+  `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*)`. See
+  [Finalization][] for more details.
+
+Returns a new `Napi::Buffer` object.
+
+### NewOrCopy
+
+> When C++20 `std::span` is not available, this method is not available.
+
+Wraps the provided external data span into a new `Napi::Buffer` object. When the
+[external buffer][] is not supported, allocates a new `Napi::Buffer` object and
+copies the provided external data into it and the `finalizeCallback` is invoked
+immediately.
+
+The `Napi::Buffer` 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 `Napi::Buffer` has been released.
+
+```cpp
+template <size_t Extent, typename Finalizer, typename Hint>
+static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env,
+                                               std::span<T, Extent> span,
+                                               Finalizer finalizeCallback,
+                                               Hint* finalizeHint);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] span`: The `std::span` referencing the external data to expose.
+- `[in] finalizeCallback`: The function called when the engine destroys the
+  `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`.
+  See [Finalization][] for more details.
+- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
+
+Returns a new `Napi::Buffer` object.
+
 ### Copy
 
 Allocates a new `Napi::Buffer` object and copies the provided external data into it.
@@ -205,6 +366,25 @@ static Napi::Buffer<T> Napi::Buffer::Copy(napi_env env, const T* data, size_t le
 
 Returns a new `Napi::Buffer` object containing a copy of the data.
 
+### Copy
+
+> When C++20 `std::span` is not available, this method is not available.
+
+Allocates a new `Napi::Buffer` object and copies the provided external data span into it.
+
+```cpp
+template <size_t Extent = std::dynamic_extent>
+static Napi::Buffer<T> Napi::Buffer::Copy(napi_env env, std::span<const T, Extent> span);
+
+template <size_t Extent = std::dynamic_extent>
+static Napi::Buffer<T> Napi::Buffer::Copy(napi_env env, std::span<T, Extent> span);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] span`: The `std::span` referencing the external data to copy.
+
+Returns a new `Napi::Buffer` object containing a copy of the data.
+
 ### Constructor
 
 Initializes an empty instance of the `Napi::Buffer` class.
@@ -240,6 +420,16 @@ size_t Napi::Buffer::Length() const;
 
 Returns the number of `T` elements in the external data.
 
+### Span
+
+> When C++20 `std::span` is not available, this method is not available.
+
+```cpp
+std::span<T> Napi::Buffer::Span() const;
+```
+
+Returns a `std::span<T>` view over the buffer data.
+
 [`Napi::Uint8Array`]: ./typed_array_of.md
 [External Buffer]: ./external_buffer.md
 [Finalization]: ./finalization.md

doc/shared_array_buffer.md

@@ -62,4 +62,14 @@ void* Napi::SharedArrayBuffer::Data() const;
 
 Returns a pointer the wrapped data.
 
+### Span
+
+> When C++20 `std::span` is not available, this method is not available.
+
+```cpp
+std::span<uint8_t> Napi::SharedArrayBuffer::Span() const;
+```
+
+Returns a `std::span<uint8_t>` view over the raw byte data.
+
 [`Napi::Object`]: ./object.md

doc/typed_array_of.md

@@ -162,4 +162,15 @@ const T* Napi::TypedArrayOf::Data() const
 Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the
 start of the array.
 
+### Span
+
+> When C++20 `std::span` is not available, this method is not available.
+
+```cpp
+std::span<T> Napi::TypedArrayOf::Span();
+std::span<const T> Napi::TypedArrayOf::Span() const;
+```
+
+Returns a `std::span` view over the typed array data.
+
 [`Napi::TypedArray`]: ./typed_array.md