Touch up descriptions of has_type

This commit is contained in:
Alex Crichton 2019-04-12 10:54:36 -07:00
parent 657b97b6d8
commit c4776becbb
2 changed files with 30 additions and 19 deletions

View File

@ -589,6 +589,7 @@ impl ToTokens for ast::ImportType {
}; };
let is_type_of = self.is_type_of.as_ref().map(|is_type_of| quote! { let is_type_of = self.is_type_of.as_ref().map(|is_type_of| quote! {
#[inline]
fn is_type_of(val: &JsValue) -> bool { fn is_type_of(val: &JsValue) -> bool {
let is_type_of: fn(&JsValue) -> bool = #is_type_of; let is_type_of: fn(&JsValue) -> bool = #is_type_of;
is_type_of(val) is_type_of(val)

View File

@ -16,24 +16,17 @@ pub trait JsCast
where where
Self: AsRef<JsValue> + Into<JsValue>, Self: AsRef<JsValue> + Into<JsValue>,
{ {
/// 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 work with primitive values or across
/// different realms (e.g. iframes). Prefer using `has_type` instead.
fn is_instance_of<T>(&self) -> bool
where
T: JsCast,
{
T::instanceof(self.as_ref())
}
/// Test whether this JS value has a type `T`. /// Test whether this JS value has a type `T`.
/// ///
/// Unlike `is_instance_of`, the type can override this to a specialised /// This method will dynamically check to see if this JS object can be
/// check that works reliably with primitives and across realms. /// 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.
fn has_type<T>(&self) -> bool fn has_type<T>(&self) -> bool
where where
T: JsCast, T: JsCast,
@ -46,7 +39,7 @@ where
/// ///
/// This method will return `Err(self)` if `self.has_type::<T>()` /// This method will return `Err(self)` if `self.has_type::<T>()`
/// returns `false`, and otherwise it will return `Ok(T)` manufactured with /// returns `false`, and otherwise it will return `Ok(T)` manufactured with
/// an unchecked cast (verified correct via the `instanceof` operation). /// an unchecked cast (verified correct via the `has_type` operation).
fn dyn_into<T>(self) -> Result<T, Self> fn dyn_into<T>(self) -> Result<T, Self>
where where
T: JsCast, T: JsCast,
@ -63,7 +56,7 @@ where
/// ///
/// This method will return `None` if `self.has_type::<T>()` /// This method will return `None` if `self.has_type::<T>()`
/// returns `false`, and otherwise it will return `Some(&T)` manufactured /// returns `false`, and otherwise it will return `Some(&T)` manufactured
/// with an unchecked cast (verified correct via the `instanceof` operation). /// with an unchecked cast (verified correct via the `has_type` operation).
fn dyn_ref<T>(&self) -> Option<&T> fn dyn_ref<T>(&self) -> Option<&T>
where where
T: JsCast, T: JsCast,
@ -107,11 +100,28 @@ where
T::unchecked_from_js_ref(self.as_ref()) T::unchecked_from_js_ref(self.as_ref())
} }
/// 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.
fn is_instance_of<T>(&self) -> bool
where
T: JsCast,
{
T::instanceof(self.as_ref())
}
/// Performs a dynamic `instanceof` check to see whether the `JsValue` /// Performs a dynamic `instanceof` check to see whether the `JsValue`
/// provided is an instance of this type. /// provided is an instance of this type.
/// ///
/// This is intended to be an internal implementation detail, you likely /// This is intended to be an internal implementation detail, you likely
/// won't need to call this. /// won't need to call this. It's generally called through the
/// `is_instance_of` method instead.
fn instanceof(val: &JsValue) -> bool; fn instanceof(val: &JsValue) -> bool;
/// Performs a dynamic check to see whether the `JsValue` provided /// Performs a dynamic check to see whether the `JsValue` provided