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 move msg {
    Some(move m) => m,
    None => ~"default message"
};

Enum Option

The option type

Variants

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

Method eq

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

Method ne

fn ne(__other: &Option<T>) -> bool

Implementation for Option<T>

Method is_none

fn is_none() -> bool

Returns true if the option equals none

Method is_some

fn is_some() -> bool

Returns true if the option contains some value

Method chain_ref

fn chain_ref<U>(f: &fn(x: &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>(f: &fn(x: &T) -> U) -> Option<U>

Maps a some value from one type to another by reference

Method map_default

fn map_default<U>(def: U, f: &fn(x: &T) -> U) -> U

Applies a function to the contained value or returns a default

Method iter

fn iter(f: &fn(x: &T))

Performs an operation on the contained value by reference

Method get_ref

fn get_ref() -> &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 unwrap

fn unwrap() -> T

Gets the value out of an option without copying.

Failure

Fails if the value equals none

Method expect

fn expect(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>

Method get

fn get() -> 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_default

fn get_default(def: T) -> T

Method while_some

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

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

Function chain

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

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

Function chain_ref

fn chain_ref<T, U>(opt: &Option<T>, f: &fn(x: &T) -> Option<U>) -> Option<U>

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

Function expect

fn expect<T>(opt: Option<T>, reason: &str) -> T

As unwrap, but with a specified failure message.

Function get

fn get<T: Copy>(opt: Option<T>) -> 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.

Function get_default

fn get_default<T: Copy>(opt: Option<T>, def: T) -> T

Returns the contained value or a default

Function get_ref

fn get_ref<T>(opt: &r/Option<T>) -> &r/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.

Function is_none

fn is_none<T>(opt: &Option<T>) -> bool

Returns true if the option equals none

Function is_some

fn is_some<T>(opt: &Option<T>) -> bool

Returns true if the option contains some value

Function iter

fn iter<T>(opt: &Option<T>, f: &fn(x: &T))

Performs an operation on the contained value by reference

Function map

fn map<T, U>(opt: &Option<T>, f: &fn(x: &T) -> U) -> Option<U>

Maps a some value by reference from one type to another

Function map_consume

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

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

Function map_default

fn map_default<T, U>(opt: &Option<T>, def: U, f: &fn(x: &T) -> U) -> U

Applies a function to the contained value or returns a default

Function or

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

Returns the leftmost some() value, or none if both are none.

Function swap_unwrap

fn swap_unwrap<T>(opt: &mut Option<T>) -> 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.

Function unwrap

fn unwrap<T>(opt: Option<T>) -> 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.

Function while_some

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

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