std::option::Option - Rust
Description: API documentation for the Rust `Option` enum in crate `std`.
Keywords: rust, rustlang, rust-lang, Option

# Enum std::option::Option 1.0.0[−][src]

    pub enum Option<T> {
        None,
        Some(T),
    }

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

Convert 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 `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_mut(self: PinMut<'a, Option<T>>) -> Option<PinMut<'a, T>>`

[src]

🔬 This is a nightly-only experimental API. (`pin` #49150)

Converts from `Option<T>` to `Option<PinMut<'_, 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]

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]

Maps an `Option<T>` to `Option<U>` by applying a function to a contained value.

# Examples

Convert 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]

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]

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]

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>

### Important traits for Iter<'a, A>

`impl<'a, A> Iterator for Iter<'a, A> type Item = &'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>

### Important traits for IterMut<'a, A>

`impl<'a, A> Iterator for IterMut<'a, A> type Item = &'a mut 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]

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]

Returns `None` if the option is `None`, otherwise calls `predicate` with the wrapped value and returns:

- `Some(t)` if `predicate` returns `true` (where `t` is the wrapped value), and
- `None` if `predicate` returns `false`.

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]

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]

🔬 This is a nightly-only experimental API. (`option_xor` #50512)

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 &'a mut I

### Important traits for &'a mut I

`impl<'a, I> Iterator for &'a mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'a, R: Read + ?Sized> Read for &'a mut Rimpl<'a, W: Write + ?Sized> Write for &'a mut W`

`pub 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 &'a mut I

### Important traits for &'a mut I

`impl<'a, I> Iterator for &'a mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'a, R: Read + ?Sized> Read for &'a mut Rimpl<'a, W: Write + ?Sized> Write for &'a mut W`

`pub fn get_or_insert_with<F>(&mut self, f: F) -> &mut T where F: FnOnce() -> T,`

1.20.0
[src]

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>`

[src]

🔬 This is a nightly-only experimental API. (`option_replace` #51998)

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

    #![feature(option_replace)]

    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<'a, T> Option<&'a T> where T: Clone,`

[src]

####

`pub fn cloned(self) -> Option<T>`

[src]

Maps an `Option<&T>` to an `Option<T>` by cloning the contents of the option.

# Examples

    let x = 12;
    let opt_x = Some(&x);
    assert_eq!(opt_x, Some(&12));
    let cloned = opt_x.cloned();
    assert_eq!(cloned, Some(12));Run

###

`impl<'a, T> Option<&'a mut T> where T: Clone,`

[src]

####

`pub fn cloned(self) -> Option<T>`

1.26.0
[src]

Maps an `Option<&mut T>` to an `Option<T>` by cloning the contents of the option.

# Examples

    let mut x = 12;
    let opt_x = Some(&mut x);
    assert_eq!(opt_x, Some(&mut 12));
    let cloned = opt_x.cloned();
    assert_eq!(cloned, Some(12));Run

###

`impl<T> Option<T> where T: Default,`

[src]

####

`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

Convert 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, E> Option<Result<T, E>>`

[src]

####

`pub fn transpose(self) -> Result<Option<T>, E>`

[src]

🔬 This is a nightly-only experimental API. (`transpose_result` #47338)

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

    #![feature(transpose_result)]

    #[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

## Trait Implementations

###

`impl<'a, T> IntoIterator for &'a mut Option<T>`

1.4.0
[src]

#### `type Item = &'a mut T`

The type of the elements being iterated over.

#### `type IntoIter = IterMut<'a, T>`

Which kind of iterator are we turning this into?

####
ⓘImportant traits for IterMut<'a, A>

### Important traits for IterMut<'a, A>

`impl<'a, A> Iterator for IterMut<'a, A> type Item = &'a mut A;`

`fn into_iter(self) -> IterMut<'a, T>`

[src]

Creates an iterator from a value. Read more

###

`impl<T> IntoIterator for Option<T>`

[src]

#### `type Item = T`

The type of the elements being iterated over.

#### `type IntoIter = IntoIter<T>`

Which kind of iterator are we turning this into?

####
ⓘImportant traits for IntoIter<A>

### Important traits for IntoIter<A>

`impl<A> Iterator for IntoIter<A> type Item = A;`

`fn into_iter(self) -> IntoIter<T>`

[src]

Returns a consuming iterator over the possibly contained value.

# Examples

    let x = Some("string");
    let v: Vec<&str> = x.into_iter().collect();
    assert_eq!(v, ["string"]);

    let x = None;
    let v: Vec<&str> = x.into_iter().collect();
    assert!(v.is_empty());Run

###

`impl<'a, T> IntoIterator for &'a Option<T>`

1.4.0
[src]

#### `type Item = &'a T`

The type of the elements being iterated over.

#### `type IntoIter = Iter<'a, T>`

Which kind of iterator are we turning this into?

####
ⓘImportant traits for Iter<'a, A>

### Important traits for Iter<'a, A>

`impl<'a, A> Iterator for Iter<'a, A> type Item = &'a A;`

`fn into_iter(self) -> Iter<'a, T>`

[src]

Creates an iterator from a value. Read more

###

`impl<T> Hash for Option<T> where T: Hash,`

[src]

####

`fn hash<__HT>(&self, state: &mut __HT) where __HT: Hasher,`

[src]

Feeds this value into the given [`Hasher`]. Read more

####

`fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher,`

1.3.0
[src]

Feeds a slice of this type into the given [`Hasher`]. Read more

###

`impl<T> From<T> for Option<T>`

1.12.0
[src]

####

`fn from(val: T) -> Option<T>`

[src]

Performs the conversion.

###

`impl<T> Clone for Option<T> where T: Clone,`

[src]

####

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

[src]

Returns a copy of the value. Read more

####

`fn clone_from(&mut self, source: &Self)`

[src]

Performs copy-assignment from `source`. Read more

###

`impl<T> Debug for Option<T> where T: Debug,`

[src]

####

`fn fmt(&self, f: &mut Formatter) -> Result<(), Error>`

[src]

Formats the value using the given formatter. Read more

###

`impl<T> PartialOrd<Option<T>> for Option<T> where T: PartialOrd<T>,`

[src]

####

`fn partial_cmp(&self, other: &Option<T>) -> Option<Ordering>`

[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

####

`fn lt(&self, other: &Option<T>) -> bool`

[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

####

`fn le(&self, other: &Option<T>) -> bool`

[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

####

`fn gt(&self, other: &Option<T>) -> bool`

[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

####

`fn ge(&self, other: &Option<T>) -> bool`

[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

###

`impl<T> Ord for Option<T> where T: Ord,`

[src]

####

`fn cmp(&self, other: &Option<T>) -> Ordering`

[src]

This method returns an `Ordering` between `self` and `other`. Read more

####

`fn max(self, other: Self) -> Self`

1.21.0
[src]

Compares and returns the maximum of two values. Read more

####

`fn min(self, other: Self) -> Self`

1.21.0
[src]

Compares and returns the minimum of two values. Read more

###

`impl<A, V> FromIterator<Option<A>> for Option<V> where V: FromIterator<A>,`

[src]

####

`fn from_iter<I>(iter: I) -> Option<V> where I: IntoIterator<Item = Option<A>>,`

[src]

Takes each element in the `Iterator`: if it is `None`, no further elements are taken, and the `None` is returned. Should no `None` occur, a container with the values of each `Option` is returned.

Here is an example which increments every integer in a vector, checking for overflow:

    use std::u16;

    let v = vec![1, 2];
    let res: Option<Vec<u16>> = v.iter().map(|&x: &u16|
        if x == u16::MAX { None }
        else { Some(x + 1) }
    ).collect();
    assert!(res == Some(vec![2, 3]));Run

###

`impl<T> Eq for Option<T> where T: Eq,`

[src]

###

`impl<T> PartialEq<Option<T>> for Option<T> where T: PartialEq<T>,`

[src]

####

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

[src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

####

`fn ne(&self, other: &Option<T>) -> bool`

[src]

This method tests for `!=`.

###

`impl<T> Copy for Option<T> where T: Copy,`

[src]

###

`impl<T> Try for Option<T>`

[src]

#### `type Ok = T`

🔬 This is a nightly-only experimental API. (`try_trait` #42327)

The type of this value when viewed as successful.

#### `type Error = NoneError`

🔬 This is a nightly-only experimental API. (`try_trait` #42327)

The type of this value when viewed as failed.

####

`fn into_result(self) -> Result<T, NoneError>`

[src]

🔬 This is a nightly-only experimental API. (`try_trait` #42327)

Applies the "?" operator. A return of `Ok(t)` means that the execution should continue normally, and the result of `?` is the value `t`. A return of `Err(e)` means that execution should branch to the innermost enclosing `catch`, or return from the function. Read more

####

`fn from_ok(v: T) -> Option<T>`

[src]

🔬 This is a nightly-only experimental API. (`try_trait` #42327)

Wrap an OK value to construct the composite result. For example, `Result::Ok(x)` and `Result::from_ok(x)` are equivalent. Read more

####

`fn from_error(NoneError) -> Option<T>`

[src]

🔬 This is a nightly-only experimental API. (`try_trait` #42327)

Wrap an error value to construct the composite result. For example, `Result::Err(x)` and `Result::from_error(x)` are equivalent. Read more

###

`impl<T> Default for Option<T>`

[src]

####

`fn default() -> Option<T>`

[src]

Returns `None`.

## Auto Trait Implementations

###

`impl<T> Send for Option<T> where T: Send,`

###

`impl<T> Sync for Option<T> where T: Sync,`

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g. `str,u8` or `String,struct:Vec,test`)