pub trait JsCast: AsRef<JsValue> + Into<JsValue> {
// Required methods
fn instanceof(val: &JsValue) -> bool;
fn unchecked_from_js(val: JsValue) -> Self;
fn unchecked_from_js_ref(val: &JsValue) -> &Self;
// Provided methods
fn has_type<T>(&self) -> bool
where T: JsCast { ... }
fn dyn_into<T>(self) -> Result<T, Self>
where T: JsCast { ... }
fn dyn_ref<T>(&self) -> Option<&T>
where T: JsCast { ... }
fn unchecked_into<T>(self) -> T
where T: JsCast { ... }
fn unchecked_ref<T>(&self) -> &T
where T: JsCast { ... }
fn is_instance_of<T>(&self) -> bool
where T: JsCast { ... }
fn is_type_of(val: &JsValue) -> bool { ... }
}Expand description
A trait for checked and unchecked casting between JS types.
Specified in an RFC this trait is intended to provide support for casting JS values between different types of one another. In JS there aren’t many static types but we’ve ascribed JS values with static types in Rust, yet they often need to be switched to other types temporarily! This trait provides both checked and unchecked casting into various kinds of values.
This trait is automatically implemented for any type imported in a
#[wasm_bindgen] extern block.
Required Methods§
sourcefn instanceof(val: &JsValue) -> bool
fn instanceof(val: &JsValue) -> bool
Performs a dynamic instanceof check to see whether the JsValue
provided is an instance of this type.
This is intended to be an internal implementation detail, you likely
won’t need to call this. It’s generally called through the
is_instance_of method instead.
sourcefn unchecked_from_js(val: JsValue) -> Self
fn unchecked_from_js(val: JsValue) -> Self
Performs a zero-cost unchecked conversion from a JsValue into an
instance of Self
This is intended to be an internal implementation detail, you likely won’t need to call this.
sourcefn unchecked_from_js_ref(val: &JsValue) -> &Self
fn unchecked_from_js_ref(val: &JsValue) -> &Self
Performs a zero-cost unchecked conversion from a &JsValue into an
instance of &Self.
Note the safety of this method, which basically means that Self must
be a newtype wrapper around JsValue.
This is intended to be an internal implementation detail, you likely won’t need to call this.
Provided Methods§
sourcefn has_type<T>(&self) -> boolwhere
T: JsCast,
fn has_type<T>(&self) -> boolwhere
T: JsCast,
Test whether this JS value has a type T.
This method will dynamically check to see if this JS object can be
casted to the JS object of type T. Usually this uses the instanceof
operator. This also works with primitive types like
booleans/strings/numbers as well as cross-realm object like Array
which can originate from other iframes.
In general this is intended to be a more robust version of
is_instance_of, but if you want strictly the instanceof operator
it’s recommended to use that instead.
sourcefn dyn_into<T>(self) -> Result<T, Self>where
T: JsCast,
fn dyn_into<T>(self) -> Result<T, Self>where
T: JsCast,
Performs a dynamic cast (checked at runtime) of this value into the
target type T.
This method will return Err(self) if self.has_type::<T>()
returns false, and otherwise it will return Ok(T) manufactured with
an unchecked cast (verified correct via the has_type operation).
sourcefn dyn_ref<T>(&self) -> Option<&T>where
T: JsCast,
fn dyn_ref<T>(&self) -> Option<&T>where
T: JsCast,
Performs a dynamic cast (checked at runtime) of this value into the
target type T.
This method will return None if self.has_type::<T>()
returns false, and otherwise it will return Some(&T) manufactured
with an unchecked cast (verified correct via the has_type operation).
sourcefn unchecked_into<T>(self) -> Twhere
T: JsCast,
fn unchecked_into<T>(self) -> Twhere
T: JsCast,
Performs a zero-cost unchecked cast into the specified type.
This method will convert the self value to the type T, where both
self and T are simple wrappers around JsValue. This method does
not check whether self is an instance of T. If used incorrectly
then this method may cause runtime exceptions in both Rust and JS, this
should be used with caution.
sourcefn unchecked_ref<T>(&self) -> &Twhere
T: JsCast,
fn unchecked_ref<T>(&self) -> &Twhere
T: JsCast,
Performs a zero-cost unchecked cast into a reference to the specified type.
This method will convert the self value to the type T, where both
self and T are simple wrappers around JsValue. This method does
not check whether self is an instance of T. If used incorrectly
then this method may cause runtime exceptions in both Rust and JS, this
should be used with caution.
This method, unlike unchecked_into, does not consume ownership of
self and instead works over a shared reference.
sourcefn is_instance_of<T>(&self) -> boolwhere
T: JsCast,
fn is_instance_of<T>(&self) -> boolwhere
T: JsCast,
Test whether this JS value is an instance of the type T.
This method performs a dynamic check (at runtime) using the JS
instanceof operator. This method returns self instanceof T.
Note that instanceof does not always work with primitive values or
across different realms (e.g. iframes). If you’re not sure whether you
specifically need only instanceof it’s recommended to use has_type
instead.
sourcefn is_type_of(val: &JsValue) -> bool
fn is_type_of(val: &JsValue) -> bool
Performs a dynamic check to see whether the JsValue provided
is a value of this type.
Unlike instanceof, this can be specialised to use a custom check by
adding a #[wasm_bindgen(is_type_of = callback)] attribute to the
type import declaration.
Other than that, this is intended to be an internal implementation
detail of has_type and you likely won’t need to call this.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.