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.
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"
};
Option
- The option typeof core::cmp::Eq for Option<T>
for Option<T>
for Option<T>
chain
- Update an optional value by optionally running its content through a function that returns an option.chain_ref
- Update an optional value by optionally running its content by reference through a function that returns an option.expect
- As unwrap, but with a specified failure message.get
- Gets the value out of an optionget_default
- Returns the contained value or a defaultget_ref
- Gets an immutable reference to the value inside an option.is_none
- Returns true if the option equals none
is_some
- Returns true if the option contains some valueiter
- Performs an operation on the contained value by referencemap
- Maps a some
value by reference from one type to anothermap_consume
- As map
, but consumes the option and gives f
ownership to avoid copying.map_default
- Applies a function to the contained value or returns a defaultor
- Returns the leftmost some() value, or none if both are none.swap_unwrap
- The option danceunwrap
- Moves a value out of an option type and returns it.while_some
- Applies a function zero or more times until the result is none.Option
The option type
None
Some(T)
core::cmp::Eq
for Option<T>
eq
fn eq(__other: &Option<T>) -> bool
ne
fn ne(__other: &Option<T>) -> bool
Option<T>
is_none
fn is_none() -> bool
Returns true if the option equals none
is_some
fn is_some() -> bool
Returns true if the option contains some value
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.
map
fn map<U>(f: &fn(x: &T) -> U) -> Option<U>
Maps a some
value from one type to another by reference
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
iter
fn iter(f: &fn(x: &T))
Performs an operation on the contained value by reference
get_ref
fn get_ref() -> &self /T
Gets an immutable reference to the value inside an option.
Fails if the value equals None
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.
unwrap
fn unwrap() -> T
Gets the value out of an option without copying.
Fails if the value equals none
expect
fn expect(reason: &str) -> T
Gets the value out of an option, printing a specified message on failure
Fails if the value equals none
Option<T>
get
fn get() -> T
Gets the value out of an option
Fails if the value equals None
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.
get_default
fn get_default(def: T) -> T
while_some
fn while_some(blk: &fn(v: T) -> Option<T>)
Applies a function zero or more times until the result is none.
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.
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.
expect
fn expect<T>(opt: Option<T>, reason: &str) -> T
As unwrap, but with a specified failure message.
get
fn get<T: Copy>(opt: Option<T>) -> T
Gets the value out of an option
Fails if the value equals None
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.
get_default
fn get_default<T: Copy>(opt: Option<T>, def: T) -> T
Returns the contained value or a default
get_ref
fn get_ref<T>(opt: &r/Option<T>) -> &r/T
Gets an immutable reference to the value inside an option.
Fails if the value equals None
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.
is_none
fn is_none<T>(opt: &Option<T>) -> bool
Returns true if the option equals none
is_some
fn is_some<T>(opt: &Option<T>) -> bool
Returns true if the option contains some value
iter
fn iter<T>(opt: &Option<T>, f: &fn(x: &T))
Performs an operation on the contained value by reference
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
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.
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
or
fn or<T>(opta: Option<T>, optb: Option<T>) -> Option<T>
Returns the leftmost some() value, or none if both are none.
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
.
Fails if the value equals None
.
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.
Fails if the value equals None
.
In general, because this function may fail, its use is discouraged. Instead, prefer to use pattern matching and handle the None
case explicitly.
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.