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

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

Method clone

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

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

Method eq

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

Method ne

fn ne(&self, __other: &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 of BaseIter<T> for Option<T> where <T>

Method each

fn each(&self, f: &fn(x: &'self T) -> bool)

Performs an operation on the contained value by reference

Method size_hint

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

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

Method each_mut

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

Implementation for Option<T> where <T>

Method is_none

fn is_none(&const self) -> bool

Returns true if the option equals none

Method is_some

fn is_some(&const 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<U>(&self, f: &fn(x: &'self T) -> Option<U>) -> Option<U>

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

Method map

fn map<U>(&self, f: &fn(&'self 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<U>(&self, def: U, f: &fn(&'self 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(&self) -> &'self 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(&mut self) -> &'self 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)