1.0.0[−][src]Enum std::option::Option
The Option
type. See the module level documentation for more.
Variants
None
No value
Some(T)
Some value T
Methods
impl<T> Option<T>
[src][−]
pub fn is_some(&self) -> bool
[src][−]
Returns true
if the option is a Some
value.
Examples
let x: Option<u32> = Some(2); assert_eq!(x.is_some(), true); let x: Option<u32> = None; assert_eq!(x.is_some(), false);Run
pub fn is_none(&self) -> bool
[src][−]
Returns true
if the option is a None
value.
Examples
let x: Option<u32> = Some(2); assert_eq!(x.is_none(), false); let x: Option<u32> = None; assert_eq!(x.is_none(), true);Run
pub fn as_ref(&self) -> Option<&T>
[src][−]
Converts from &Option<T>
to Option<&T>
.
Examples
Converts an Option<
String
>
into an Option<
usize
>
, preserving the original.
The map
method takes the self
argument by value, consuming the original,
so this technique uses as_ref
to first take an Option
to a reference
to the value inside the original.
let text: Option<String> = Some("Hello, world!".to_string()); // First, cast `Option<String>` to `Option<&String>` with `as_ref`, // then consume *that* with `map`, leaving `text` on the stack. let text_length: Option<usize> = text.as_ref().map(|s| s.len()); println!("still can print text: {:?}", text);Run
pub fn as_mut(&mut self) -> Option<&mut T>
[src][−]
Converts from &mut Option<T>
to Option<&mut T>
.
Examples
let mut x = Some(2); match x.as_mut() { Some(v) => *v = 42, None => {}, } assert_eq!(x, Some(42));Run
pub fn as_pin_ref(self: Pin<&'a Option<T>>) -> Option<Pin<&'a T>>
1.33.0[src][−]
Converts from Pin<&Option<T>>
to Option<Pin<&T>>
pub fn as_pin_mut(self: Pin<&'a mut Option<T>>) -> Option<Pin<&'a mut T>>
1.33.0[src][−]
Converts from Pin<&mut Option<T>>
to Option<Pin<&mut T>>
pub fn expect(self, msg: &str) -> T
[src][−]
Unwraps an option, yielding the content of a Some
.
Panics
Panics if the value is a None
with a custom panic message provided by
msg
.
Examples
let x = Some("value"); assert_eq!(x.expect("the world is ending"), "value");Run
let x: Option<&str> = None; x.expect("the world is ending"); // panics with `the world is ending`Run
pub fn unwrap(self) -> T
[src][−]
Moves the value v
out of the Option<T>
if it is Some(v)
.
In general, because this function may panic, its use is discouraged.
Instead, prefer to use pattern matching and handle the None
case explicitly.
Panics
Panics if the self value equals None
.
Examples
let x = Some("air"); assert_eq!(x.unwrap(), "air");Run
let x: Option<&str> = None; assert_eq!(x.unwrap(), "air"); // failsRun
pub fn unwrap_or(self, def: T) -> T
[src][−]
Returns the contained value or a default.
Arguments passed to unwrap_or
are eagerly evaluated; if you are passing
the result of a function call, it is recommended to use unwrap_or_else
,
which is lazily evaluated.
Examples
assert_eq!(Some("car").unwrap_or("bike"), "car"); assert_eq!(None.unwrap_or("bike"), "bike");Run
pub fn unwrap_or_else<F>(self, f: F) -> T where
F: FnOnce() -> T,
[src][−]
F: FnOnce() -> T,
Returns the contained value or computes it from a closure.
Examples
let k = 10; assert_eq!(Some(4).unwrap_or_else(|| 2 * k), 4); assert_eq!(None.unwrap_or_else(|| 2 * k), 20);Run
pub fn map<U, F>(self, f: F) -> Option<U> where
F: FnOnce(T) -> U,
[src][−]
F: FnOnce(T) -> U,
Maps an Option<T>
to Option<U>
by applying a function to a contained value.
Examples
Converts an Option<
String
>
into an Option<
usize
>
, consuming the original:
let maybe_some_string = Some(String::from("Hello, World!")); // `Option::map` takes self *by value*, consuming `maybe_some_string` let maybe_some_len = maybe_some_string.map(|s| s.len()); assert_eq!(maybe_some_len, Some(13));Run
pub fn map_or<U, F>(self, default: U, f: F) -> U where
F: FnOnce(T) -> U,
[src][−]
F: FnOnce(T) -> U,
Applies a function to the contained value (if any), or returns the provided default (if not).
Examples
let x = Some("foo"); assert_eq!(x.map_or(42, |v| v.len()), 3); let x: Option<&str> = None; assert_eq!(x.map_or(42, |v| v.len()), 42);Run
pub fn map_or_else<U, D, F>(self, default: D, f: F) -> U where
D: FnOnce() -> U,
F: FnOnce(T) -> U,
[src][−]
D: FnOnce() -> U,
F: FnOnce(T) -> U,
Applies a function to the contained value (if any), or computes a default (if not).
Examples
let k = 21; let x = Some("foo"); assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 3); let x: Option<&str> = None; assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 42);Run
pub fn ok_or<E>(self, err: E) -> Result<T, E>
[src][−]
Transforms the Option<T>
into a Result<T, E>
, mapping Some(v)
to
Ok(v)
and None
to Err(err)
.
Arguments passed to ok_or
are eagerly evaluated; if you are passing the
result of a function call, it is recommended to use ok_or_else
, which is
lazily evaluated.
Examples
let x = Some("foo"); assert_eq!(x.ok_or(0), Ok("foo")); let x: Option<&str> = None; assert_eq!(x.ok_or(0), Err(0));Run
pub fn ok_or_else<E, F>(self, err: F) -> Result<T, E> where
F: FnOnce() -> E,
[src][−]
F: FnOnce() -> E,
Transforms the Option<T>
into a Result<T, E>
, mapping Some(v)
to
Ok(v)
and None
to Err(err())
.
Examples
let x = Some("foo"); assert_eq!(x.ok_or_else(|| 0), Ok("foo")); let x: Option<&str> = None; assert_eq!(x.ok_or_else(|| 0), Err(0));Run
ⓘImportant traits for Iter<'a, A>pub fn iter(&self) -> Iter<T>
[src][−]
Returns an iterator over the possibly contained value.
Examples
let x = Some(4); assert_eq!(x.iter().next(), Some(&4)); let x: Option<u32> = None; assert_eq!(x.iter().next(), None);Run
ⓘImportant traits for IterMut<'a, A>pub fn iter_mut(&mut self) -> IterMut<T>
[src][−]
Returns a mutable iterator over the possibly contained value.
Examples
let mut x = Some(4); match x.iter_mut().next() { Some(v) => *v = 42, None => {}, } assert_eq!(x, Some(42)); let mut x: Option<u32> = None; assert_eq!(x.iter_mut().next(), None);Run
pub fn and<U>(self, optb: Option<U>) -> Option<U>
[src][−]
Returns None
if the option is None
, otherwise returns optb
.
Examples
let x = Some(2); let y: Option<&str> = None; assert_eq!(x.and(y), None); let x: Option<u32> = None; let y = Some("foo"); assert_eq!(x.and(y), None); let x = Some(2); let y = Some("foo"); assert_eq!(x.and(y), Some("foo")); let x: Option<u32> = None; let y: Option<&str> = None; assert_eq!(x.and(y), None);Run
pub fn and_then<U, F>(self, f: F) -> Option<U> where
F: FnOnce(T) -> Option<U>,
[src][−]
F: FnOnce(T) -> Option<U>,
Returns None
if the option is None
, otherwise calls f
with the
wrapped value and returns the result.
Some languages call this operation flatmap.
Examples
fn sq(x: u32) -> Option<u32> { Some(x * x) } fn nope(_: u32) -> Option<u32> { None } assert_eq!(Some(2).and_then(sq).and_then(sq), Some(16)); assert_eq!(Some(2).and_then(sq).and_then(nope), None); assert_eq!(Some(2).and_then(nope).and_then(sq), None); assert_eq!(None.and_then(sq).and_then(sq), None);Run
pub fn filter<P>(self, predicate: P) -> Option<T> where
P: FnOnce(&T) -> bool,
1.27.0[src][−]
P: FnOnce(&T) -> bool,
Returns None
if the option is None
, otherwise calls predicate
with the wrapped value and returns:
Some(t)
ifpredicate
returnstrue
(wheret
is the wrapped value), andNone
ifpredicate
returnsfalse
.
This function works similar to Iterator::filter()
. You can imagine
the Option<T>
being an iterator over one or zero elements. filter()
lets you decide which elements to keep.
Examples
fn is_even(n: &i32) -> bool { n % 2 == 0 } assert_eq!(None.filter(is_even), None); assert_eq!(Some(3).filter(is_even), None); assert_eq!(Some(4).filter(is_even), Some(4));Run
pub fn or(self, optb: Option<T>) -> Option<T>
[src][−]
Returns the option if it contains a value, otherwise returns optb
.
Arguments passed to or
are eagerly evaluated; if you are passing the
result of a function call, it is recommended to use or_else
, which is
lazily evaluated.
Examples
let x = Some(2); let y = None; assert_eq!(x.or(y), Some(2)); let x = None; let y = Some(100); assert_eq!(x.or(y), Some(100)); let x = Some(2); let y = Some(100); assert_eq!(x.or(y), Some(2)); let x: Option<u32> = None; let y = None; assert_eq!(x.or(y), None);Run
pub fn or_else<F>(self, f: F) -> Option<T> where
F: FnOnce() -> Option<T>,
[src][−]
F: FnOnce() -> Option<T>,
Returns the option if it contains a value, otherwise calls f
and
returns the result.
Examples
fn nobody() -> Option<&'static str> { None } fn vikings() -> Option<&'static str> { Some("vikings") } assert_eq!(Some("barbarians").or_else(vikings), Some("barbarians")); assert_eq!(None.or_else(vikings), Some("vikings")); assert_eq!(None.or_else(nobody), None);Run
pub fn xor(self, optb: Option<T>) -> Option<T>
[src][−]
Returns Some
if exactly one of self
, optb
is Some
, otherwise returns None
.
Examples
#![feature(option_xor)] let x = Some(2); let y: Option<u32> = None; assert_eq!(x.xor(y), Some(2)); let x: Option<u32> = None; let y = Some(2); assert_eq!(x.xor(y), Some(2)); let x = Some(2); let y = Some(2); assert_eq!(x.xor(y), None); let x: Option<u32> = None; let y: Option<u32> = None; assert_eq!(x.xor(y), None);Run
ⓘImportant traits for &'_ mut Fpub fn get_or_insert(&mut self, v: T) -> &mut T
1.20.0[src][−]
Inserts v
into the option if it is None
, then
returns a mutable reference to the contained value.
Examples
let mut x = None; { let y: &mut u32 = x.get_or_insert(5); assert_eq!(y, &5); *y = 7; } assert_eq!(x, Some(7));Run
ⓘImportant traits for &'_ mut Fpub fn get_or_insert_with<F>(&mut self, f: F) -> &mut T where
F: FnOnce() -> T,
1.20.0[src][−]
F: FnOnce() -> T,
Inserts a value computed from f
into the option if it is None
, then
returns a mutable reference to the contained value.
Examples
let mut x = None; { let y: &mut u32 = x.get_or_insert_with(|| 5); assert_eq!(y, &5); *y = 7; } assert_eq!(x, Some(7));Run
pub fn take(&mut self) -> Option<T>
[src][−]
Takes the value out of the option, leaving a None
in its place.
Examples
let mut x = Some(2); let y = x.take(); assert_eq!(x, None); assert_eq!(y, Some(2)); let mut x: Option<u32> = None; let y = x.take(); assert_eq!(x, None); assert_eq!(y, None);Run
pub fn replace(&mut self, value: T) -> Option<T>
1.31.0[src][−]
Replaces the actual value in the option by the value given in parameter,
returning the old value if present,
leaving a Some
in its place without deinitializing either one.
Examples
let mut x = Some(2); let old = x.replace(5); assert_eq!(x, Some(5)); assert_eq!(old, Some(2)); let mut x = None; let old = x.replace(3); assert_eq!(x, Some(3)); assert_eq!(old, None);Run
impl<'_, T> Option<&'_ T> where
T: Copy,
[src][−]
T: Copy,
impl<'_, T> Option<&'_ mut T> where
T: Copy,
[src][−]
T: Copy,
impl<'_, T> Option<&'_ T> where
T: Clone,
[src][−]
T: Clone,
impl<'_, T> Option<&'_ mut T> where
T: Clone,
[src][−]
T: Clone,
impl<T> Option<T> where
T: Default,
[src][−]
T: Default,
pub fn unwrap_or_default(self) -> T
[src][−]
Returns the contained value or a default
Consumes the self
argument then, if Some
, returns the contained
value, otherwise if None
, returns the default value for that
type.
Examples
Converts a string to an integer, turning poorly-formed strings
into 0 (the default value for integers). parse
converts
a string to any other type that implements FromStr
, returning
None
on error.
let good_year_from_input = "1909"; let bad_year_from_input = "190blarg"; let good_year = good_year_from_input.parse().ok().unwrap_or_default(); let bad_year = bad_year_from_input.parse().ok().unwrap_or_default(); assert_eq!(1909, good_year); assert_eq!(0, bad_year);Run
impl<T> Option<T> where
T: Deref,
[src][−]
T: Deref,
pub fn deref(&self) -> Option<&<T as Deref>::Target>
[src][−]
🔬 This is a nightly-only experimental API. (inner_deref
#50264)
newly added
Converts from &Option<T>
to Option<&T::Target>
.
Leaves the original Option in-place, creating a new one with a reference
to the original one, additionally coercing the contents via Deref
.
impl<T, E> Option<Result<T, E>>
[src][−]
pub fn transpose(self) -> Result<Option<T>, E>
1.33.0[src][−]
Transposes an Option
of a Result
into a Result
of an Option
.
None
will be mapped to Ok(None)
.
Some(Ok(_))
and Some(Err(_))
will be mapped to Ok(Some(_))
and Err(_)
.
Examples
#[derive(Debug, Eq, PartialEq)] struct SomeErr; let x: Result<Option<i32>, SomeErr> = Ok(Some(5)); let y: Option<Result<i32, SomeErr>> = Some(Ok(5)); assert_eq!(x, y.transpose());Run
impl<T> Option<Option<T>>
[src][−]
pub fn flatten(self) -> Option<T>
[src][−]
Converts from Option<Option<T>>
to Option<T>
Examples
Basic usage:
#![feature(option_flattening)] let x: Option<Option<u32>> = Some(Some(6)); assert_eq!(Some(6), x.flatten()); let x: Option<Option<u32>> = Some(None); assert_eq!(None, x.flatten()); let x: Option<Option<u32>> = None; assert_eq!(None, x.flatten());Run
Flattening once only removes one level of nesting:
#![feature(option_flattening)] let x: Option<Option<Option<u32>>> = Some(Some(Some(6))); assert_eq!(Some(Some(6)), x.flatten()); assert_eq!(Some(6), x.flatten().flatten());Run
Trait Implementations
impl<T> From<T> for Option<T>
1.12.0[src][+]
impl<'a, T> From<&'a Option<T>> for Option<&'a T>
1.30.0[src][+]
impl<'a, T> From<&'a mut Option<T>> for Option<&'a mut T>
1.30.0[src][+]
impl<T, U> Product<Option<U>> for Option<T> where
T: Product<U>,
1.37.0[src][+]
T: Product<U>,
impl<A, V> FromIterator<Option<A>> for Option<V> where
V: FromIterator<A>,
[src][+]
V: FromIterator<A>,
impl<T> PartialOrd<Option<T>> for Option<T> where
T: PartialOrd<T>,
[src][+]
T: PartialOrd<T>,
impl<T> Hash for Option<T> where
T: Hash,
[src][+]
T: Hash,
impl<T> Default for Option<T>
[src][+]
impl<T> Eq for Option<T> where
T: Eq,
[src]
T: Eq,
impl<T, U> Sum<Option<U>> for Option<T> where
T: Sum<U>,
1.37.0[src][+]
T: Sum<U>,
impl<T> Clone for Option<T> where
T: Clone,
[src][+]
T: Clone,
impl<T> Try for Option<T>
[src][+]
impl<T> Debug for Option<T> where
T: Debug,
[src][+]
T: Debug,
impl<T> Copy for Option<T> where
T: Copy,
[src]
T: Copy,
impl<T> Ord for Option<T> where
T: Ord,
[src][+]
T: Ord,
impl<T> PartialEq<Option<T>> for Option<T> where
T: PartialEq<T>,
[src][+]
T: PartialEq<T>,
impl<'a, T> IntoIterator for &'a mut Option<T>
1.4.0[src][+]
impl<'a, T> IntoIterator for &'a Option<T>
1.4.0[src][+]
impl<T> IntoIterator for Option<T>
[src][+]
Auto Trait Implementations
Blanket Implementations
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src][+]
U: Into<T>,
impl<I> IntoIterator for I where
I: Iterator,
[src][+]
I: Iterator,
impl<T, U> Into<U> for T where
U: From<T>,
[src][+]
U: From<T>,
impl<T> From<T> for T
[src][+]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src][+]
U: TryFrom<T>,
impl<T> Borrow<T> for T where
T: ?Sized,
[src][+]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src][+]
T: ?Sized,
impl<T> Any for T where
T: 'static + ?Sized,
[src][+]
T: 'static + ?Sized,
impl<T> ToOwned for T where
T: Clone,
[src][+]
T: Clone,