Commit f9c2a3f
doc: clarify use of Uint8Array for n-api
`napi_get_buffer_info` always supported receiving `Uint8Array` as a
`value` argument because `node::Buffer` is a subclass of `Uint8Array`
and the underlying V8 APIs don't distinguish between two. With this
change we mark both types as supported by the API so that the user code
doesn't have to unknowingly use oficially unsupported type of the
`value` argument.
PR-URL: #48742
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Gabriel Schulhof <gabrielschulhof@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>1 parent 066d9d4 commit f9c2a3f
1 file changed
Lines changed: 15 additions & 6 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -3066,13 +3066,18 @@ napi_status napi_get_buffer_info(napi_env env, | |||
| 3066 | 3066 | ``` | |
| 3067 | 3067 | ||
| 3068 | 3068 | * `[in] env`: The environment that the API is invoked under. | |
| 3069 | - * `[in] value`: `napi_value` representing the `node::Buffer` being queried. | ||
| 3070 | - * `[out] data`: The underlying data buffer of the `node::Buffer`. | ||
| 3071 | - If length is `0`, this may be `NULL` or any other pointer value. | ||
| 3069 | + * `[in] value`: `napi_value` representing the `node::Buffer` or `Uint8Array` | ||
| 3070 | + being queried. | ||
| 3071 | + * `[out] data`: The underlying data buffer of the `node::Buffer` or | ||
| 3072 | + `Uint8Array`. If length is `0`, this may be `NULL` or any other pointer value. | ||
| 3072 | 3073 | * `[out] length`: Length in bytes of the underlying data buffer. | |
| 3073 | 3074 | ||
| 3074 | 3075 | Returns `napi_ok` if the API succeeded. | |
| 3075 | 3076 | ||
| 3077 | + This method returns the identical `data` and `byte_length` as | ||
| 3078 | + [`napi_get_typedarray_info`][]. And `napi_get_typedarray_info` accepts a | ||
| 3079 | + `node::Buffer` (a Uint8Array) as the value too. | ||
| 3080 | + | ||
| 3076 | 3081 | This API is used to retrieve the underlying data buffer of a `node::Buffer` | |
| 3077 | 3082 | and its length. | |
| 3078 | 3083 | ||
@@ -3823,12 +3828,14 @@ napi_status napi_is_buffer(napi_env env, napi_value value, bool* result) | |||
| 3823 | 3828 | ||
| 3824 | 3829 | * `[in] env`: The environment that the API is invoked under. | |
| 3825 | 3830 | * `[in] value`: The JavaScript value to check. | |
| 3826 | - * `[out] result`: Whether the given `napi_value` represents a `node::Buffer` | ||
| 3827 | - object. | ||
| 3831 | + * `[out] result`: Whether the given `napi_value` represents a `node::Buffer` or | ||
| 3832 | + `Uint8Array` object. | ||
| 3828 | 3833 | ||
| 3829 | 3834 | Returns `napi_ok` if the API succeeded. | |
| 3830 | 3835 | ||
| 3831 | - This API checks if the `Object` passed in is a buffer. | ||
| 3836 | + This API checks if the `Object` passed in is a buffer or Uint8Array. | ||
| 3837 | + [`napi_is_typedarray`][] should be preferred if the caller needs to check if the | ||
| 3838 | + value is a Uint8Array. | ||
| 3832 | 3839 | ||
| 3833 | 3840 | ### `napi_is_date` | |
| 3834 | 3841 | ||
@@ -6498,11 +6505,13 @@ the add-on's file name during loading. | |||
| 6498 | 6505 | [`napi_get_last_error_info`]: #napi_get_last_error_info | |
| 6499 | 6506 | [`napi_get_property`]: #napi_get_property | |
| 6500 | 6507 | [`napi_get_reference_value`]: #napi_get_reference_value | |
| 6508 | + [`napi_get_typedarray_info`]: #napi_get_typedarray_info | ||
| 6501 | 6509 | [`napi_get_value_external`]: #napi_get_value_external | |
| 6502 | 6510 | [`napi_has_property`]: #napi_has_property | |
| 6503 | 6511 | [`napi_instanceof`]: #napi_instanceof | |
| 6504 | 6512 | [`napi_is_error`]: #napi_is_error | |
| 6505 | 6513 | [`napi_is_exception_pending`]: #napi_is_exception_pending | |
| 6514 | + [`napi_is_typedarray`]: #napi_is_typedarray | ||
| 6506 | 6515 | [`napi_make_callback`]: #napi_make_callback | |
| 6507 | 6516 | [`napi_open_callback_scope`]: #napi_open_callback_scope | |
| 6508 | 6517 | [`napi_open_escapable_handle_scope`]: #napi_open_escapable_handle_scope | |
0 commit comments