Struct JsArrayBuffer

pub struct JsArrayBuffer(/* private fields */);

Implementations

impl JsArrayBuffer

pub fn new(env: NapiEnv, buffer: impl AsRef<[u8]>) -> NapiResult<JsArrayBuffer>

This API returns a Node-API value corresponding to a JavaScript ArrayBuffer. ArrayBuffers are used to represent fixed-length binary data buffers. They are normally used as a backing-buffer for TypedArray objects. The ArrayBuffer allocated will have an underlying byte buffer whose size is determined by the length parameter that’s passed in. The underlying buffer is optionally returned back to the caller in case the caller wants to directly manipulate the buffer. This buffer can only be written to directly from native code. To write to this buffer from JavaScript, a typed array or DataView object would need to be created. JavaScript ArrayBuffer objects are described in Section 24.1 of the ECMAScript Language Specification.

pub fn view(&self, offset: usize, length: usize) -> NapiResult<JsDataView>

This API creates a JavaScript DataView object over an existing ArrayBuffer. DataView objects provide an array-like view over an underlying data buffer, but one which allows items of different size and type in the ArrayBuffer.

It is required that byte_length + byte_offset is less than or equal to the size in bytes of the array passed in. If not, a RangeError exception is raised.

JavaScript DataView objects are described in Section 24.3 of the ECMAScript Language Specification.

pub fn typedarray( &self, typed: NapiTypedarrayType, offset: usize, length: usize, ) -> NapiResult<JsTypedArray>

This API creates a JavaScript TypedArray object over an existing ArrayBuffer. TypedArray objects provide an array-like view over an underlying data buffer where each element has the same underlying binary scalar datatype.

It’s required that (length * size_of_element) + byte_offset should be <= the size in bytes of the array passed in. If not, a RangeError exception is raised.

JavaScript TypedArray objects are described in Section 22.2 of the ECMAScript Language Specification.

pub fn buffer(&self) -> NapiResult<&[u8]>

This API is used to retrieve the underlying data buffer of an ArrayBuffer and its length.

WARNING: Use caution while using this API. The lifetime of the underlying data buffer is managed by the ArrayBuffer even after it’s returned. A possible safe way to use this API is in conjunction with napi_create_reference, which can be used to guarantee control over the lifetime of the ArrayBuffer. It’s also safe to use the returned data buffer within the same callback as long as there are no calls to other APIs that might trigger a GC.

pub fn get_arraybuffer_info(&self) -> NapiResult<&[u8]>

👎Deprecated: use JsArrayBuffer::buffer() instead

pub fn detach(&mut self) -> NapiResult<()>

If a non-detachable ArrayBuffer is passed in it returns napi_detachable_arraybuffer_expected.

Generally, an ArrayBuffer is non-detachable if it has been detached before. The engine may impose additional conditions on whether an ArrayBuffer is detachable. For example, V8 requires that the ArrayBuffer be external, that is, created with napi_create_external_arraybuffer.

This API represents the invocation of the ArrayBuffer detach operation as defined in Section 24.1.1.3 of the ECMAScript Language Specification.

pub fn is_detached(&self) -> NapiResult<bool>

The ArrayBuffer is considered detached if its internal data is null.

This API represents the invocation of the ArrayBuffer IsDetachedBuffer operation as defined in Section 24.1.1.2 of the ECMAScript Language Specification.

Trait Implementations

impl Clone for JsArrayBuffer

fn clone(&self) -> JsArrayBuffer

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for JsArrayBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl NapiValueCheck for JsArrayBuffer

fn check(&self) -> NapiResult<bool>

impl NapiValueT for JsArrayBuffer

fn from_raw(env: NapiEnv, raw: napi_value) -> JsArrayBuffer

construct value from raw pointer

fn value(&self) -> JsValue

inner value

unsafe fn cast<T: NapiValueT>(&self) -> T

napi_value type cast

fn cast_checked<T: NapiValueT>(&self) -> NapiResult<T>

Upcast to specified value

fn kind(&self) -> NapiResult<NapiValuetype>

Returns napi_ok if the API succeeded.

fn coerce_to_bool(&self) -> NapiResult<JsBoolean>

This API implements the abstract operation ToBoolean() as defined in Section 7.1.2 of the ECMAScript Language Specification.

fn coerce_coerce_to_number(&self) -> NapiResult<JsNumber>

This API implements the abstract operation ToNumber() as defined in Section 7.1.3 of the ECMAScript Language Specification. This function potentially runs JS code if the passed-in value is an object.

fn coerce_to_object(&self) -> NapiResult<JsObject>

This API implements the abstract operation ToObject() as defined in Section 7.1.13 of the ECMAScript Language Specification.

fn coerce_to_string(&self) -> NapiResult<JsString>

This API implements the abstract operation ToString() as defined in Section 7.1.13 of the ECMAScript Language Specification. This function potentially runs JS code if the passed-in value is an object.

fn instance_of(&self, constructor: JsFunction) -> NapiResult<bool>

This API represents invoking the instanceof Operator on the object as defined in Section 12.10.4 of the ECMAScript Language Specification.

fn equals(&self, rhs: impl NapiValueT) -> NapiResult<bool>

This API represents the invocation of the Strict Equality algorithm as defined in Section 7.2.14 of the ECMAScript Language Specification.

fn env(&self) -> NapiEnv

the NapiEnv of current value

fn raw(&self) -> napi_value

the raw-handle of current value

fn null(&self) -> NapiResult<JsNull>

get null singleton

fn undefined(&self) -> NapiResult<JsUndefined>

get undefined singleton

fn global(&self) -> NapiResult<JsGlobal>

get global singleton

fn throw(&self) -> NapiResult<()>

value is throwable

fn define_properties<P>(&self, properties: P) -> NapiResult<()>

where P: AsRef<[NapiPropertyDescriptor]>,

This method allows the efficient definition of multiple properties on a given object. The properties are defined using property descriptors (see napi_property_descriptor). Given an array of such property descriptors, this API will set the properties on the object one at a time, as defined by DefineOwnProperty() (described in Section 9.1.6 of the ECMA-262 specification).

fn gc<Finalizer>(&mut self, finalizer: Finalizer) -> NapiResult<NapiRef>

where Finalizer: FnOnce(NapiEnv) -> NapiResult<()>,

This is a hook which is fired when the value is gabage-collected. For napi >= 5, we use napi_add_finalizer, For napi < 5, we use napi_wrap.

fn finalizer<Finalizer>(&self, finalizer: Finalizer) -> NapiResult<NapiRef>

where Finalizer: FnOnce(NapiEnv) -> NapiResult<()>,

Adds a napi_finalize callback which will be called when the JavaScript object in js_object is ready for garbage collection. This API is similar to napi_wrap() except that:

fn wrap<T>( &mut self, data: T, finalizer: impl FnOnce(NapiEnv, T) -> NapiResult<()>, ) -> NapiResult<NapiRef>

Wraps a native instance in a JavaScript object. The native instance can be retrieved later using napi_unwrap().

fn unwrap<T>(&self) -> NapiResult<Option<&mut T>>

Retrieves a native instance that was previously wrapped in a JavaScript object using napi_wrap().

fn remove_wrap<T>(&mut self) -> NapiResult<T>

Retrieves a native instance that was previously wrapped in the JavaScript object js_object using napi_wrap() and removes the wrapping. If a finalize callback was associated with the wrapping, it will no longer be called when the JavaScript object becomes garbage-collected.

fn type_tag_object(&self, tag: &NapiTypeTag) -> NapiResult<()>

Associates the value of the type_tag pointer with the JavaScript object. napi_check_object_type_tag() can then be used to compare the tag that was attached to the object with one owned by the addon to ensure that the object has the right type. If the object already has an associated type tag, this API will return napi_invalid_arg.

fn check_object_type_tag(&self, tag: &NapiTypeTag) -> NapiResult<bool>

Compares the pointer given as type_tag with any that can be found on js_object. If no tag is found on js_object or, if a tag is found but it does not match type_tag, then result is set to false. If a tag is found and it matches type_tag, then result is set to true.

impl Copy for JsArrayBuffer