Struct optional::Optioned

pub struct Optioned<T: Noned + Copy> { /* fields omitted */ }

An Option<T>-like structure that takes only as much space as the enclosed value, at the cost of removing one particular None value from the value domain (see Noned)

Methods

impl<T: Noned + Copy> Optioned<T>

pub fn some(t: T) -> Self

Create an Optioned<T> that is some(t).

Panics

panics if the supplied value is the None value

Examples

Optioned::<i32>::some(1); // Optioned(1)

Optioned::<f64>::some(std::f64::NAN); // panic!s

pub fn none() -> Self

Create an Optioned<T> that is none().

Examples

Optioned::<u16>::none(); // Optioned(std::u16::MAX)

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

Convenience funtion to convert an Optioned into an Option.

Techinically this is possible with the Into<Option<T>> implementation in this crate. However, experience has shown that there are many cases where the compiler isn't able to infer the correct type for the generic parameter and issues an error. As a workaround you can use Into::<Option<T>>::into(...) or .map(|inner| inner) which will both work. The first is verbose and the second makes the intention less clear, so this method is provided as a convenience.

if let Some(val) = some(15).into_option() {
    println!("val = {}", val);
}

The following example will fail to compile because of type inference.

if let Some(val) = some(15).into() {
    println!("val = {}", val);
}

pub fn is_none(&self) -> bool

Returns true if this Optioned is None, false otherwise.

pub fn is_some(&self) -> bool

Returns true if this Optioned contains a value, false otherwise.

pub fn expect(&self, msg: &str) -> T

Unwraps the value, if any, else panics with the given message.

Panics

if self is None

Examples

For Some(_), the corresponding value is returned.

assert_eq!(42u8, Optioned::some(42u8).expect("FAIL"));

On None, it panics with the given message.

Optioned::<u8>::none().expect("FAIL"); // panics with FAIL

pub fn unwrap(&self) -> T

Unwraps the value, if any, else panics with "unwrap called on None".

Panics

if self is None

Examples

For Some(_), the corresponding value is returned.

assert_eq!(42u8, Optioned::some(42u8).unwrap());

On None, it panics with the given message.

Optioned::<u8>::none().unwrap(); // panics

pub fn unpack(&self) -> T

Returns the contained value, even if None.

Examples

assert_eq!(-128i8, none().unpack());
assert_eq!(1u32, some(1).unpack());

pub fn unwrap_or(&self, def: T) -> T

Returns the contained value or a default.

Examples

assert_eq!(-1i8, some(-1i8).unwrap_or(127i8));
assert_eq!(42u16, none().unwrap_or(42u16));

pub fn unwrap_or_else<F>(self, f: F) -> T where
    F: FnOnce() -> T, 

Returns the contained value or a calculated default.

Examples

assert_eq!(-1i8, some(-1i8).unwrap_or_else(|| panic!()));
assert_eq!(42u16, none().unwrap_or_else(|| 42u16));

pub fn map<U, F>(self, f: F) -> Option<U> where
    F: FnOnce(T) -> U, 

Maps the Optioned to an Option<U> by applying the function over the contained value, if any.

Examples

assert_eq!(Some(-42), some(42i8).map(|x| -x));
assert_eq!(None, none::<i8>().map(|x| -x));

pub fn map_t<U, F>(self, f: F) -> Optioned<U> where
    F: FnOnce(T) -> U,
    U: Noned + Copy, 

Maps the Optioned<T> to an Optioned<U> by applying the function over the contained value, if any. Requires that the result type of the function be Noned + Copy, as other types aren't compatible with Optioned.

Examples

assert_eq!(some(-42), some(42i8).map_t(|x| -x));
assert_eq!(none::<i8>(), none::<i8>().map_t(|x| -x));

pub fn map_or<U, F>(self, default: U, f: F) -> U where
    F: FnOnce(T) -> U, 

Maps the contained value to a U by applying the function or return a default.

Examples

assert_eq!("1", some(1usize).map_or("Unknown".to_string(), |b| b.to_string()));
assert_eq!("Unknown", none::<usize>().map_or("Unknown".to_string(), |b| b.to_string()));

pub fn map_or_else<U, D, F>(self, default: D, f: F) -> U where
    D: FnOnce() -> U,
    F: FnOnce(T) -> U, 

Maps a value to a U by applying the function or return a computed default.

Examples

assert_eq!("1", some(1usize).map_or_else(|| "Unknown".to_string(),
    |b| b.to_string()));
assert_eq!("Unknown", none::<usize>().map_or_else(
    || "Unknown".to_string(), |b| b.to_string()));

pub fn or(self, other: Optioned<T>) -> Optioned<T>

Returns this option if it contains a value, otherwise returns the other.

Arguments passed to or are eagerly evaluated; if you are passing the result of a function call, it is recommended to use or_else, which is lazily evaluated.

Examples

let x = some(2);
let y = none();
assert_eq!(x.or(y), some(2));

let x = none();
let y = some(100);
assert_eq!(x.or(y), some(100));

let x = some(2);
let y = some(100);
assert_eq!(x.or(y), some(2));

let x: Optioned<u32> = none();
let y = none();
assert_eq!(x.or(y), none());

pub fn or_else<F>(self, f: F) -> Optioned<T> where
    F: FnOnce() -> Optioned<T>, 

Returns this option if it contains a value, otherwise calls f and returns the result.

Examples

fn nothing() -> Optioned<u32> { none() }
fn something() -> Optioned<u32> { some(1) }

assert_eq!(some(2).or_else(something), some(2));
assert_eq!(none().or_else(something), some(1));
assert_eq!(none().or_else(nothing), none());

pub fn and<U>(self, other: Optioned<U>) -> Optioned<U> where
    U: Noned + Copy, 

Returns the None value for type U if this value or other contains their respective None values. Otherwise returns the other Optioned struct.

Examples

let the_other = some::<u32>(42);

assert_eq!(some('a').and(the_other), some(42));
assert_eq!(none::<char>().and(the_other), none::<u32>());
assert_eq!(some('a').and(none::<u32>()), none::<u32>());
assert_eq!(none::<char>().and(none::<u32>()), none::<u32>());

pub fn and_then<F, U>(self, f: F) -> Optioned<U> where
    F: FnOnce(T) -> Optioned<U>,
    U: Noned + Copy, 

Returns this Optioned if it contains the the None value, otherwise calls f with the contained value and returns the result as an Optioned<U>.

Examples

fn nothing() -> Optioned<u32> { none() }
fn something() -> Optioned<u32> { some(1) }
fn add_two(val: u32) -> Optioned<u32> {
  wrap( val + 2)
}

fn failed_function(val: u32) -> Optioned<u32> {
  none()
}

assert_eq!(some(2).and_then(add_two), some(4));
assert_eq!(none().and_then(add_two), none());
assert_eq!(some(2).and_then(failed_function), none());
assert_eq!(none().and_then(failed_function), none());

pub fn ok_or<E>(self, err: E) -> Result<T, E>

Transforms the Optioned<T> into a Result<T, E>, mapping some(v) to Ok(v) and none() to Err(err).

Examples

let x = some(42u32);
assert_eq!(x.ok_or("was none"), Ok(42u32));

let x: Optioned<u32> = none();
assert_eq!(x.ok_or("was none"), Err("was none"));

pub fn ok_or_else<E, F: FnOnce() -> E>(self, err: F) -> Result<T, E>

Transforms the Optioned<T> into a Result<T, E>, mapping some(v) to Ok(v) and none() to Err(err).

Examples

let x = some(42u32);
assert_eq!(x.ok_or_else(|| "was none"), Ok(42u32));

let x: Optioned<u32> = none();
assert_eq!(x.ok_or_else(|| "was none"), Err("was none"));

pub fn take(&mut self) -> Option<T>

Takes the value out of the Optioned and returns ist as Option<T>, changing self to None.

Examples

let mut x = some(1u8);
assert_eq!(Some(1u8), x.take());
assert!(x.is_none());

pub fn as_slice(&self) -> &[T]

Return a possibly empty slice over the contained value, if any.

Examples

assert_eq!(&[42], some(42u8).as_slice());
assert!(none::<i16>().as_slice().is_empty());

Important traits for OptionedIter<T>

impl<T: Noned + Copy> Iterator for OptionedIter<T> type Item = T;

pub fn iter(&self) -> OptionedIter<T>

return an iterator over all contained (that is zero or one) values.

Examples

assert_eq!(None, none::<u64>().iter().next());
assert_eq!(Some(42u64), some(42u64).iter().next());

Trait Implementations

impl<T: Clone + Noned + Copy> Clone for Optioned<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Copy + Noned> Copy for Optioned<T>

impl<T: Noned + Copy + Debug> Debug for Optioned<T>

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

Formats the value using the given formatter.

impl<T: Noned + Copy> Default for Optioned<T>

fn default() -> Optioned<T>

Returns the "default value" for a type.

impl<T> Eq for Optioned<T> where
    T: OptEq + Noned + Copy, 

impl<'a, T: Noned + Copy> From<&'a Option<T>> for Optioned<T>

fn from(o: &Option<T>) -> Optioned<T>

Performs the conversion.

impl<T: Noned + Copy> From<Option<T>> for Optioned<T>

fn from(o: Option<T>) -> Optioned<T>

Performs the conversion.

impl<T: Noned + Copy> From<T> for Optioned<T>

fn from(o: T) -> Optioned<T>

Performs the conversion.

impl<T> Hash for Optioned<T> where
    T: Noned + Copy + 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, 

Feeds a slice of this type into the given [Hasher].

impl<T: Noned + Copy> Into<Option<T>> for Optioned<T>

fn into(self) -> Option<T>

Performs the conversion.

impl<'a, T: Noned + Copy> Into<Option<T>> for &'a Optioned<T>

fn into(self) -> Option<T>

Performs the conversion.

impl<T> Ord for Optioned<T> where
    T: Eq + OptEq + OptOrd + Noned + Copy, 

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T> PartialEq<Optioned<T>> for Optioned<T> where
    T: OptEq + Noned + Copy, 

Equality works as usual.

Examples

assert_eq!(some(1u8), some(1u8));
assert_eq!(none::<u32>(), none::<u32>());

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialOrd<Optioned<T>> for Optioned<T> where
    T: PartialEq + OptEq + OptOrd + Noned + Copy, 

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

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

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

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