Struct nodex_api::value::JsExternal

pub struct JsExternal<T>(_, _);

Implementations

impl<T> JsExternal<T>

pub fn new(
    env: NapiEnv,
    value: T,
    finalizer: impl FnOnce(NapiEnv, T) -> NapiResult<()> + 'static
) -> NapiResult<JsExternal<T>>

This API allocates a JavaScript value with external data attached to it. This is used to pass external data through JavaScript code, so it can be retrieved later by native code using napi_get_value_external.

pub fn get(&self) -> NapiResult<&mut T>

Access the underlaying data.

pub fn arraybuffer<'a>(
    env: NapiEnv,
    value: impl AsRef<[T]>
) -> NapiResult<JsExternal<&'a [T]>>

This API returns a Node-API value corresponding to a JavaScript ArrayBuffer. The underlying byte buffer of the ArrayBuffer is externally allocated and managed. The caller must ensure that the byte buffer remains valid until the finalize callback is called. The API adds a napi_finalize callback which will be called when the JavaScript object just created is ready for garbage collection. It is similar to napi_wrap() except that:

• the native data cannot be retrieved later using napi_unwrap(),
• nor can it be removed later using napi_remove_wrap(), and
• the object created by the API can be used with napi_wrap(). JavaScript ArrayBuffers are described in Section 24.1 of the ECMAScript Language Specification.

pub fn buffer<'a>(
    env: NapiEnv,
    value: impl AsRef<[T]>
) -> NapiResult<JsExternal<&'a [T]>>

This API allocates a node::Buffer object and initializes it with data backed by the passed in buffer. While this is still a fully-supported data structure, in most cases using a TypedArray will suffice. The API adds a napi_finalize callback which will be called when the JavaScript object just created is ready for garbage collection. It is similar to napi_wrap() except that:

• the native data cannot be retrieved later using napi_unwrap(),
• nor can it be removed later using napi_remove_wrap(), and
• the object created by the API can be used with napi_wrap(). For Node.js >=4 Buffers are Uint8Arrays.

Trait Implementations

impl<T: Clone> Clone for JsExternal<T>

fn clone(&self) -> JsExternal<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for JsExternal<T>

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

Formats the value using the given formatter.

impl<T> NapiValueT for JsExternal<T>

fn from_raw(env: NapiEnv, raw: napi_value) -> JsExternal<T>

construct value from raw pointer

fn value(&self) -> JsValue

inner value

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

napi_value type cast

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 is_array(&self) -> NapiResult<bool>

This API represents invoking the IsArray operation on the object as defined in Section 7.2.2 of the ECMAScript Language Specification.

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

This API checks if the Object passed in is an array buffer.

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

This API checks if the Object passed in is a buffer.

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

This API checks if the Object passed in is a error.

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

This API checks if the Object passed in is a typed array.

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

This API checks if the Object passed in is a DataView.

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 kind(&self) -> NapiResult<NapiValuetype>

Returns napi_ok if the API succeeded.

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 wrap<T, Finalizer>(
    &mut self,
    data: T,
    finalizer: Finalizer
) -> NapiResult<NapiRef> where
    Finalizer: FnOnce(NapiEnv, T) -> NapiResult<()>, 

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

fn unwrap<T>(&self) -> NapiResult<Option<&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.

impl<T: Copy> Copy for JsExternal<T>