Skip to content

doc: clarify use of Uint8Array for n-api #48742

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 21, 2023
Merged

doc: clarify use of Uint8Array for n-api #48742

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d664cf3
doc: clarify use of Uint8Array for n-api
indutny Jul 12, 2023
0bc66ea
Update doc/api/n-api.md
indutny Jul 28, 2023
2fbc2f1
update
indutny Jul 28, 2023
24b6365
format
indutny Aug 18, 2023
4ba8e6f
fix lint
indutny Aug 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 15 additions & 6 deletions doc/api/n-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3122,13 +3122,18 @@ napi_status napi_get_buffer_info(napi_env env,
```

* `[in] env`: The environment that the API is invoked under.
* `[in] value`: `napi_value` representing the `node::Buffer` being queried.
* `[out] data`: The underlying data buffer of the `node::Buffer`.
If length is `0`, this may be `NULL` or any other pointer value.
* `[in] value`: `napi_value` representing the `node::Buffer` or `Uint8Array`
being queried.
* `[out] data`: The underlying data buffer of the `node::Buffer` or
`Uint8Array`. If length is `0`, this may be `NULL` or any other pointer value.
* `[out] length`: Length in bytes of the underlying data buffer.

Returns `napi_ok` if the API succeeded.

This method returns the identical `data` and `byte_length` as
[`napi_get_typedarray_info`][]. And `napi_get_typedarray_info` accepts a
`node::Buffer` (a Uint8Array) as the value too.

This API is used to retrieve the underlying data buffer of a `node::Buffer`
and its length.

Expand Down Expand Up @@ -3879,12 +3884,14 @@ napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)

* `[in] env`: The environment that the API is invoked under.
* `[in] value`: The JavaScript value to check.
* `[out] result`: Whether the given `napi_value` represents a `node::Buffer`
object.
* `[out] result`: Whether the given `napi_value` represents a `node::Buffer` or
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

napi_is_typedarray should be preferred if the caller needs to check if the value is a Uint8Array.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Committed! Thanks!

`Uint8Array` object.

Returns `napi_ok` if the API succeeded.

This API checks if the `Object` passed in is a buffer.
This API checks if the `Object` passed in is a buffer or Uint8Array.
[`napi_is_typedarray`][] should be preferred if the caller needs to check if the
value is a Uint8Array.

### `napi_is_date`

Expand Down Expand Up @@ -6554,11 +6561,13 @@ the add-on's file name during loading.
[`napi_get_last_error_info`]: #napi_get_last_error_info
[`napi_get_property`]: #napi_get_property
[`napi_get_reference_value`]: #napi_get_reference_value
[`napi_get_typedarray_info`]: #napi_get_typedarray_info
[`napi_get_value_external`]: #napi_get_value_external
[`napi_has_property`]: #napi_has_property
[`napi_instanceof`]: #napi_instanceof
[`napi_is_error`]: #napi_is_error
[`napi_is_exception_pending`]: #napi_is_exception_pending
[`napi_is_typedarray`]: #napi_is_typedarray
[`napi_make_callback`]: #napi_make_callback
[`napi_open_callback_scope`]: #napi_open_callback_scope
[`napi_open_escapable_handle_scope`]: #napi_open_escapable_handle_scope
Expand Down