Enum Nullable 

pub enum Nullable<T> {
    Null,
    NonNull(T),
}

A value that can be null in JavaScript, but not undefined.

This is used to distinguish between values in JavaScript that can be null (i.e. Nullable<T>) vs. those of which that can be undefined (i.e. Option<T>).

Nullable<T> tries to be close in API surface to the standard Option<T>, though with a much smaller API scope, and can be transformed into and from Option<T> for free.

Why a new type?

There are in the standard 2 different values that are “null coalescing”:

1. undefined, which is its own type (typeof void 0 == "undefined"),
2. null, which is different from undefined (undefined !== null) but is of type object (typeof null === "object") for legacy reasons.

Option<T> sets up the first case, so we needed to add a new type for the second case.

Would it be bad to use Option::<T>::None as both undefined or null?

Many values in the standard can be null but not undefined, or the other way around. Coalescing these two into Option::None means that any conversions using boa’s traits (such as TryFromJs) would result in indistinguishable values. The only way to respect the standard in this case would be to get JsValue and manually verify it’s not undefined/null, then do the conversion. This new type makes this process much simpler.

It also means that there is an asymmetry between JsValue to Option<T> then Option<T> back to JsValue, leading to unintuitive errors. Having a type Nullable<T> that acts like Option<T> but (de-)serialize to null clarifies all usage.

How can I do EitherNullOrUndefined<T>?

The best way is to use Nullable<Option<T>> and convert into Option<T> using Nullable::flatten(). Please note that the reverse (Nullable<Option<T>>) results in the same deserializing behaviour but does not implement flatten().

Please note that JavaScript cannot make a distinction between Option<T> and Option<Option<T>>. This cannot be resolved using this type, as it suffers from the same limitation. There is no way to distinguish between Null and NonNull(Null). Nullable<Nullable<T>> does not provide additional information.

Examples

let maybe_10: Nullable<u8> = JsValue::new(10).try_js_into(context).unwrap();
assert_eq!(maybe_10, Nullable::NonNull(10u8));

let maybe_not: Nullable<u8> = JsValue::null().try_js_into(context).unwrap();
assert_eq!(maybe_not, Nullable::Null);

let mut v: JsResult<Nullable<Option<u8>>> =
    JsValue::undefined().try_js_into(context);
assert_eq!(v, Ok(Nullable::NonNull(None)));

v = JsValue::null().try_js_into(context);
assert_eq!(v, Ok(Nullable::Null));

v = JsValue::from(42).try_js_into(context);
assert_eq!(v, Ok(Nullable::NonNull(Some(42))));
assert_eq!(v.unwrap().flatten(), Some(42));

Variants

Null

The value was not defined in JavaScript.

NonNull(T)

The value was defined in JavaScript.

Implementations

impl<T> Nullable<T>

pub const fn is_null(&self) -> bool

Returns true if this value is Nullable::Null.

pub const fn is_not_null(&self) -> bool

Returns true if this value is Nullable::NotNull.

pub fn iter(&self) -> Iter<'_, T>

Returns an iterator over the possibly contained value.

Examples

let x = Nullable::NonNull(4);
assert_eq!(x.iter().next(), Some(&4));

let x: Nullable<u32> = Nullable::Null;
assert_eq!(x.iter().next(), None);

pub const fn as_ref(&self) -> Nullable<&T>

Converts from &Nullable<T> to Nullable<&T>.

Examples

let text: Nullable<String> = Nullable::NonNull("Hello, world!".to_string());

// First, cast `Nullable<String>` to `Nullable<&String>` with `as_ref`,
// then consume *that* with `map`, leaving `text` on the stack.
let text_length: Nullable<usize> = text.as_ref().map(|s| s.len());
println!("still can print text: {text:?}");

pub fn map<U, F>(self, f: F) -> Nullable<U>

where F: FnOnce(T) -> U,

Maps a Nullable<T> to Nullable<U> by applying a function to a contained value.

Examples

let maybe_some_string = Nullable::NonNull(String::from("Hello, World!"));
// `Nullable::map` takes self *by value*, consuming `maybe_some_string`
let maybe_some_len = maybe_some_string.map(|s| s.len());
assert_eq!(maybe_some_len, Nullable::NonNull(13));

let x: Nullable<&str> = Nullable::Null;
assert_eq!(x.map(|s| s.len()), Nullable::Null);

pub fn unwrap_or_default(self) -> T

where T: Default,

Returns the contained Nullable::NonNull value or a default.

Consumes the self argument then, if Nullable::NonNull, returns the contained value, otherwise if Nullable::Null, returns the default value for that type.

Examples

let x: Nullable<u32> = Nullable::Null;
let y: Nullable<u32> = Nullable::NonNull(12);

assert_eq!(x.unwrap_or_default(), 0);
assert_eq!(y.unwrap_or_default(), 12);

impl<T> Nullable<Option<T>>

pub fn flatten(self) -> Option<T>

Converts from Nullable<Option<T>> to Option<T>.

Trait Implementations

impl<T> Clone for Nullable<T>

where T: Clone,

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Nullable<T>

where T: Debug,

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

Formats the value using the given formatter.

impl<T> From<Nullable<T>> for Option<T>

fn from(value: Nullable<T>) -> Option<T>

Converts to this type from the input type.

impl<T> From<Option<T>> for Nullable<T>

fn from(value: Option<T>) -> Nullable<T>

Converts to this type from the input type.

impl<T> Hash for Nullable<T>

where T: Hash,

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, T> IntoIterator for &'a Nullable<T>

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Iter<'a, T>

Creates an iterator from a value.

impl<T> IntoIterator for Nullable<T>

fn into_iter(self) -> IntoIter<T>

Returns a consuming iterator over the possibly contained value.

Examples

let x = Nullable::NonNull("string");
let v: Vec<&str> = x.into_iter().collect();
assert_eq!(v, ["string"]);

let x = Nullable::Null;
let v: Vec<&str> = x.into_iter().collect();
assert!(v.is_empty());

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

impl<T> Ord for Nullable<T>

where T: Ord,

fn cmp(&self, other: &Nullable<T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T> PartialEq for Nullable<T>

where T: PartialEq,

fn eq(&self, other: &Nullable<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd for Nullable<T>

where T: PartialOrd,

fn partial_cmp(&self, other: &Nullable<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> TryFromJs for Nullable<T>

where T: TryFromJs,

fn try_from_js( value: &JsValue, context: &mut Context, ) -> Result<Nullable<T>, JsError>

This function tries to convert a JavaScript value into Self.

impl<T> TryIntoJs for Nullable<T>

where T: TryIntoJs,

fn try_into_js(&self, context: &mut Context) -> Result<JsValue, JsError>

This function tries to convert a Self into JsValue.

impl<T> Copy for Nullable<T>

where T: Copy,

impl<T> Eq for Nullable<T>

where T: Eq,

impl<T> StructuralPartialEq for Nullable<T>