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<A> {
    priv opt: Option<A>,
}

An iterator that yields either one or zero elements

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: Eq + 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 ToStr for Option<T> where <T: ToStr>

Method to_str

fn to_str(&self) -> ~str

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) -> OptionIterator<&'r mut T>

Return a mutable iterator over the possibly contained value

Method move_iter

fn move_iter(self) -> OptionIterator<T>

Return a consuming 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 a 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 chain_mut_ref

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

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

Method filtered

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

Filters an optional value using given function.

Method map

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

Maps a Some value from one type to another by reference

Method map_mut

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

Maps a Some value from one type to another by a mutable reference

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_mut_default

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

Maps a Some value from one type to another by a mutable reference, or returns a default value.

Method map_move

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

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

Method map_move_default

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

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

Method take

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

Take the value out of the option, leaving a None in its place.

Method mutate

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

Apply a function to the contained value or do nothing. Returns true if the contained value was mutated.

Method mutate_default

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

Apply a function to the contained value or set it to a default. Returns true if the contained value was mutated, or false if set to the 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 take_unwrap

fn take_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

Method unwrap_or_default

fn unwrap_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: Zero>

Method unwrap_or_zero

fn unwrap_or_zero(self) -> T

Returns the contained value or zero (for this type)

Method or_zero

fn or_zero(self) -> Option<T>

Returns self or Some-wrapped zero value

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

Method zero

fn zero() -> Option<T>

Method is_zero

fn is_zero(&self) -> bool

Implementation of ::std::clone::Clone for OptionIterator<A> where <A: ::std::clone::Clone>

Automatically derived.

Method clone

fn clone(&self) -> OptionIterator<A>

Implementation of ::std::clone::DeepClone for OptionIterator<A> where <A: ::std::clone::DeepClone>

Automatically derived.

Method deep_clone

fn deep_clone(&self) -> OptionIterator<A>

Implementation of Iterator<A> for OptionIterator<A> where <A>

Method next

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

Method size_hint

fn size_hint(&self) -> (uint, Option<uint>)

Implementation of DoubleEndedIterator<A> for OptionIterator<A> where <A>

Method next_back

fn next_back(&mut self) -> Option<A>

Implementation of ExactSize<A> for OptionIterator<A> where <A>