Returns the contained [Some] value, consuming the self value.

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("fruits are healthy"), "value");

let x = None;
x.expect("fruits are healthy"); // panics with `fruits are healthy`

Recommended Message Style

We recommend that expect messages are used to describe the reason you expect the Option should be Some.

let item = slice.get(0).expect("slice should not be empty");

Hint: If you're having trouble remembering how to phrase expect error messages remember to focus on the word "should" as in "env variable should be set by blah" or "the given binary should be available and executable by the current user".

For more detail on expect message styles and the reasoning behind our recommendation please refer to the section on "Common Message Styles" in the std::error module docs.

Returns the contained [Some] value, consuming the self value.

Because this function may panic, its use is generally discouraged. Instead, prefer to use pattern matching and handle the [None] case explicitly, or call unwrap_or, unwrap_or_else, or unwrap_or_default.

Panics

Panics if the self value equals [None].

Examples

let x = Some("air");
assert_eq!(x.unwrap(), "air");

let x = None;
assert_eq!(x.unwrap(), "air"); // fails

Returns the contained [Some] value or a provided 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");

Returns the contained [Some] 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);

Returns true if the option is a [Some] value.

Examples

let x = Some(2);
assert_eq!(x.is_some(), true);

let x = None;
assert_eq!(x.is_some(), false);

Returns true if the option is a [None] value.

Examples

let x = Some(2);
assert_eq!(x.is_none(), false);

let x = None;
assert_eq!(x.is_none(), true);

Construct an iterator over an optional value.

Examples

let value = Some(1);
let it = value.iter();

assert_eq!(Some(1), it.next());
assert_eq!(None, it.next());

let value = None;
let it = value.iter();

assert_eq!(None, it.next());

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_then_to_string(x) {
   x.checked_mul(x).map(|sq| sq.to_string())
}

assert_eq!(Some(2).and_then(sq_then_to_string), Some(4.to_string()));
assert_eq!(Some(1_000_000_000_000_000_000).and_then(sq_then_to_string), None); // overflowed!
assert_eq!(None.and_then(sq_then_to_string), None);

Often used to chain fallible operations that may return [None].

let arr_2d = [["A0", "A1"], ["B0", "B1"]];

let item_0_1 = arr_2d.get(0).and_then(|row| row.get(1));
assert_eq!(item_0_1, Some("A1"));

let item_2_0 = arr_2d.get(2).and_then(|row| row.get(0));
assert_eq!(item_2_0, None);

Maps an Option<T> to Option<U> by applying a function to a contained value (if Some) or returns None (if None).

Examples

Calculates the length of an Option<[String]> as 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));

let x = None;
assert_eq!(x.map(|s| s.len()), None);

Takes the value out of the option, leaving a [None] in its place.

Examples

let x = Some(2);
let y = x.take();
assert_eq!(x, None);
assert_eq!(y, Some(2));

let x = None;
let y = x.take();
assert_eq!(x, None);
assert_eq!(y, None);

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

let x = Ok(Some(5));
let y = Some(Ok(5));
assert_eq!(x, y.transpose());

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 = None;
assert_eq!(x.ok_or(0), Err(0));

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 = None;
assert_eq!(x.ok_or_else(|| 0), Err(0));

Construct an iterator over an optional value.

Examples

let value = Some(1);

let out = [];

for v in value {
   out.push(v);
}

assert_eq!(out, [1]);

Using Option with the try protocol.

Examples

fn maybe_add_one(value) {
   Some(value? + 1)
}

assert_eq!(maybe_add_one(Some(4)), Some(5));
assert_eq!(maybe_add_one(None), None);