Operations on the ubiquitous Option type.

Type Option represents an optional value.

Every Option<T> value can either be Some(T) or None. Where in other languages you might use a nullable type, in Rust you would use an option type.

Options are most commonly used with pattern matching to query the presence of a value and take action, always accounting for the None case.

Example

let msg = Some(~"howdy");

// Take a reference to the contained string
match msg {
    Some(ref m) => io::println(m),
    None => ()
}

// Remove the contained string, destroying the Option
let unwrapped_msg = match msg {
    Some(m) => m,
    None => ~"default message"
};

Enum Option

The option type

Variants

Struct OptionIterator

pub struct OptionIterator<'self, A> {
    priv opt: Option<&'self A>,
}

Immutable iterator over an Option<A>

Struct OptionMutIterator

pub struct OptionMutIterator<'self, A> {
    priv opt: Option<&'self mut A>,
}

Mutable iterator over an Option<A>

Implementation of ::std::clone::Clone for Option<T> where <T: ::std::clone::Clone>

Automatically derived.

Method clone

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

Implementation of ::std::clone::DeepClone for Option<T> where <T: ::std::clone::DeepClone>

Automatically derived.

Method deep_clone

fn deep_clone(&self) -> Option<T>

Implementation of ::std::cmp::Eq for Option<T> where <T: ::std::cmp::Eq>

Automatically derived.

Method eq

fn eq(&self, __arg_0: &Option<T>) -> ::bool

Method ne

fn ne(&self, __arg_0: &Option<T>) -> ::bool

Implementation of Ord for Option<T> where <T: Ord>

Method lt

fn lt(&self, other: &Option<T>) -> bool

Method le

fn le(&self, other: &Option<T>) -> bool

Method ge

fn ge(&self, other: &Option<T>) -> bool

Method gt

fn gt(&self, other: &Option<T>) -> bool

Implementation of Add<Option<T>, Option<T>> for Option<T> where <T: Copy + Add<T, T>>

Method add

fn add(&self, other: &Option<T>) -> Option<T>

Implementation for Option<T> where <T>

Method iter

fn iter<'r>(&'r self) -> OptionIterator<'r, T>

Return an iterator over the possibly contained value

Method mut_iter

fn mut_iter<'r>(&'r mut self) -> OptionMutIterator<'r, T>

Return a mutable iterator over the possibly contained value

Method is_none

fn is_none(&self) -> bool

Returns true if the option equals none

Method is_some

fn is_some(&self) -> bool

Returns true if the option contains some value

Method chain

fn chain<U>(self, f: &fn(t: T) -> Option<U>) -> Option<U>

Update an optional value by optionally running its content through a function that returns an option.

Method or

fn or(self, optb: Option<T>) -> Option<T>

Returns the leftmost Some() value, or None if both are None.

Method chain_ref

fn chain_ref<'a, U>(&'a self, f: &fn(x: &'a T) -> Option<U>) -> Option<U>

Update an optional value by optionally running its content by reference through a function that returns an option.

Method filtered

fn filtered<'a>(self, f: &fn(t: &'a T) -> bool) -> Option<T>

Filters an optional value using given function.

Method map

fn map<'a, U>(&self, f: &fn(&'a T) -> U) -> Option<U>

Maps a some value from one type to another by reference

Method map_consume

fn map_consume<U>(self, f: &fn(v: T) -> U) -> Option<U>

As map, but consumes the option and gives f ownership to avoid copying.

Method map_default

fn map_default<'a, U>(&'a self, def: U, f: &fn(&'a T) -> U) -> U

Applies a function to the contained value or returns a default

Method map_consume_default

fn map_consume_default<U>(self, def: U, f: &fn(v: T) -> U) -> U

As map_default, but consumes the option and gives f ownership to avoid copying.

Method mutate

fn mutate(&mut self, f: &fn(T) -> T)

Apply a function to the contained value or do nothing

Method mutate_default

fn mutate_default(&mut self, def: T, f: &fn(T) -> T)

Apply a function to the contained value or set it to a default

Method get_ref

fn get_ref<'a>(&'a self) -> &'a T

Gets an immutable reference to the value inside an option.

Failure

Fails if the value equals None

Safety note

In general, because this function may fail, its use is discouraged (calling get on None is akin to dereferencing a null pointer). Instead, prefer to use pattern matching and handle the None case explicitly.

Method get_mut_ref

fn get_mut_ref<'a>(&'a mut self) -> &'a mut T

Gets a mutable reference to the value inside an option.

Failure

Fails if the value equals None

Safety note

In general, because this function may fail, its use is discouraged (calling get on None is akin to dereferencing a null pointer). Instead, prefer to use pattern matching and handle the None case explicitly.

Method unwrap

fn unwrap(self) -> T

Moves a value out of an option type and returns it.

Useful primarily for getting strings, vectors and unique pointers out of option types without copying them.

Failure

Fails if the value equals None.

Safety note

In general, because this function may fail, its use is discouraged. Instead, prefer to use pattern matching and handle the None case explicitly.

Method swap_unwrap

fn swap_unwrap(&mut self) -> T

The option dance. Moves a value out of an option type and returns it, replacing the original with None.

Failure

Fails if the value equals None.

Method expect

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

Gets the value out of an option, printing a specified message on failure

Failure

Fails if the value equals none

Implementation for Option<T> where <T: Copy>

Method get

fn get(self) -> T

Gets the value out of an option

Failure

Fails if the value equals None

Safety note

In general, because this function may fail, its use is discouraged (calling get on None is akin to dereferencing a null pointer). Instead, prefer to use pattern matching and handle the None case explicitly.

Method get_or_default

fn get_or_default(self, def: T) -> T

Returns the contained value or a default

Method while_some

fn while_some(self, blk: &fn(v: T) -> Option<T>)

Applies a function zero or more times until the result is none.

Implementation for Option<T> where <T: Copy + Zero>

Method get_or_zero

fn get_or_zero(self) -> T

Returns the contained value or zero (for this type)

Implementation of Zero for Option<T> where <T>

Method zero

fn zero() -> Option<T>

Method is_zero

fn is_zero(&self) -> bool

Implementation of Iterator<&'self A> for OptionIterator<'self, A> where <'self, A>

Method next

fn next(&mut self) -> Option<&'self A>

Implementation of Iterator<&'self mut A> for OptionMutIterator<'self, A> where <'self, A>

Method next

fn next(&mut self) -> Option<&'self mut A>