//! Optional values.

//!

//! Type [`Option`] represents an optional value: every [`Option`]

//! is either [`Some`] and contains a value, or [`None`], and

//! does not. [`Option`] types are very common in Rust code, as

//! they have a number of uses:

//!

//! * Initial values

//! * Return values for functions that are not defined

//!   over their entire input range (partial functions)

//! * Return value for otherwise reporting simple errors, where [`None`] is

//!   returned on error

//! * Optional struct fields

//! * Struct fields that can be loaned or "taken"

//! * Optional function arguments

//! * Nullable pointers

//! * Swapping things out of difficult situations

//!

//! [`Option`]s are commonly paired with pattern matching to query the presence

//! of a value and take action, always accounting for the [`None`] case.

//!

//! ```

//! fn divide(numerator: f64, denominator: f64) -> Option<f64> {

//!     if denominator == 0.0 {

//!         None

//!     } else {

//!         Some(numerator / denominator)

//!     }

//! }

//!

//! // The return value of the function is an option

//! let result = divide(2.0, 3.0);

//!

//! // Pattern match to retrieve the value

//! match result {

//!     // The division was valid

//!     Some(x) => println!("Result: {x}"),

//!     // The division was invalid

//!     None    => println!("Cannot divide by 0"),

//! }

//! ```

//!

//

// FIXME: Show how `Option` is used in practice, with lots of methods

//

//! # Options and pointers ("nullable" pointers)

//!

//! Rust's pointer types must always point to a valid location; there are

//! no "null" references. Instead, Rust has *optional* pointers, like

//! the optional owned box, <code>[Option]<[Box\<T>]></code>.

//!

//! [Box\<T>]: ../../std/boxed/struct.Box.html

//!

//! The following example uses [`Option`] to create an optional box of

//! [`i32`]. Notice that in order to use the inner [`i32`] value, the

//! `check_optional` function first needs to use pattern matching to

//! determine whether the box has a value (i.e., it is [`Some(...)`][`Some`]) or

//! not ([`None`]).

//!

//! ```

//! let optional = None;

//! check_optional(optional);

//!

//! let optional = Some(Box::new(9000));

//! check_optional(optional);

//!

//! fn check_optional(optional: Option<Box<i32>>) {

//!     match optional {

//!         Some(p) => println!("has value {p}"),

//!         None => println!("has no value"),

//!     }

//! }

//! ```

//!

//! # The question mark operator, `?`

//!

//! Similar to the [`Result`] type, when writing code that calls many functions that return the

//! [`Option`] type, handling `Some`/`None` can be tedious. The question mark

//! operator, [`?`], hides some of the boilerplate of propagating values

//! up the call stack.

//!

//! It replaces this:

//!

//! ```

//! # #![allow(dead_code)]

//! fn add_last_numbers(stack: &mut Vec<i32>) -> Option<i32> {

//!     let a = stack.pop();

//!     let b = stack.pop();

//!

//!     match (a, b) {

//!         (Some(x), Some(y)) => Some(x + y),

//!         _ => None,

//!     }

//! }

//!

//! ```

//!

//! With this:

//!

//! ```

//! # #![allow(dead_code)]

//! fn add_last_numbers(stack: &mut Vec<i32>) -> Option<i32> {

//!     Some(stack.pop()? + stack.pop()?)

//! }

//! ```

//!

//! *It's much nicer!*

//!

//! Ending the expression with [`?`] will result in the [`Some`]'s unwrapped value, unless the

//! result is [`None`], in which case [`None`] is returned early from the enclosing function.

//!

//! [`?`] can be used in functions that return [`Option`] because of the

//! early return of [`None`] that it provides.

//!

//! [`?`]: crate::ops::Try

//! [`Some`]: Some

//! [`None`]: None

//!

//! # Representation

//!

//! Rust guarantees to optimize the following types `T` such that

//! [`Option<T>`] has the same size, alignment, and [function call ABI] as `T`. In some

//! of these cases, Rust further guarantees the following:

//! - `transmute::<_, Option<T>>([0u8; size_of::<T>()])` is sound and produces

//!   `Option::<T>::None`

//! - `transmute::<_, [u8; size_of::<T>()]>(Option::<T>::None)` is sound and produces

//!   `[0u8; size_of::<T>()]`

//!

//! These cases are identified by the second column:

//!

//! | `T`                                                                 | Transmuting between `[0u8; size_of::<T>()]` and `Option::<T>::None` sound? |

//! |---------------------------------------------------------------------|----------------------------------------------------------------------------|

//! | [`Box<U>`] (specifically, only `Box<U, Global>`)                    | when `U: Sized`                                                            |

//! | `&U`                                                                | when `U: Sized`                                                            |

//! | `&mut U`                                                            | when `U: Sized`                                                            |

//! | `fn`, `extern "C" fn`[^extern_fn]                                   | always                                                                     |

//! | [`num::NonZero*`]                                                   | always                                                                     |

//! | [`ptr::NonNull<U>`]                                                 | when `U: Sized`                                                            |

//! | `#[repr(transparent)]` struct around one of the types in this list. | when it holds for the inner type                                           |

//!

//! [^extern_fn]: this remains true for `unsafe` variants, any argument/return types, and any other ABI: `[unsafe] extern "abi" fn` (_e.g._, `extern "system" fn`)

//!

//! Under some conditions the above types `T` are also null pointer optimized when wrapped in a [`Result`][result_repr].

//!

//! [`Box<U>`]: ../../std/boxed/struct.Box.html

//! [`num::NonZero*`]: crate::num

//! [`ptr::NonNull<U>`]: crate::ptr::NonNull

//! [function call ABI]: ../primitive.fn.html#abi-compatibility

//! [result_repr]: crate::result#representation

//!

//! This is called the "null pointer optimization" or NPO.

//!

//! It is further guaranteed that, for the cases above, one can

//! [`mem::transmute`] from all valid values of `T` to `Option<T>` and

//! from `Some::<T>(_)` to `T` (but transmuting `None::<T>` to `T`

//! is undefined behavior).

//!

//! # Method overview

//!

//! In addition to working with pattern matching, [`Option`] provides a wide

//! variety of different methods.

//!

//! ## Querying the variant

//!

//! The [`is_some`] and [`is_none`] methods return [`true`] if the [`Option`]

//! is [`Some`] or [`None`], respectively.

//!

//! The [`is_some_and`] and [`is_none_or`] methods apply the provided function

//! to the contents of the [`Option`] to produce a boolean value.

//! If this is [`None`] then a default result is returned instead without executing the function.

//!

//! [`is_none`]: Option::is_none

//! [`is_some`]: Option::is_some

//! [`is_some_and`]: Option::is_some_and

//! [`is_none_or`]: Option::is_none_or

//!

//! ## Adapters for working with references

//!

//! * [`as_ref`] converts from <code>[&][][Option]\<T></code> to <code>[Option]<[&]T></code>

//! * [`as_mut`] converts from <code>[&mut] [Option]\<T></code> to <code>[Option]<[&mut] T></code>

//! * [`as_deref`] converts from <code>[&][][Option]\<T></code> to

//!   <code>[Option]<[&]T::[Target]></code>

//! * [`as_deref_mut`] converts from <code>[&mut] [Option]\<T></code> to

//!   <code>[Option]<[&mut] T::[Target]></code>

//! * [`as_pin_ref`] converts from <code>[Pin]<[&][][Option]\<T>></code> to

//!   <code>[Option]<[Pin]<[&]T>></code>

//! * [`as_pin_mut`] converts from <code>[Pin]<[&mut] [Option]\<T>></code> to

//!   <code>[Option]<[Pin]<[&mut] T>></code>

//! * [`as_slice`] returns a one-element slice of the contained value, if any.

//!   If this is [`None`], an empty slice is returned.

//! * [`as_mut_slice`] returns a mutable one-element slice of the contained value, if any.

//!   If this is [`None`], an empty slice is returned.

//!

//! [&]: reference "shared reference"

//! [&mut]: reference "mutable reference"

//! [Target]: Deref::Target "ops::Deref::Target"

//! [`as_deref`]: Option::as_deref

//! [`as_deref_mut`]: Option::as_deref_mut

//! [`as_mut`]: Option::as_mut

//! [`as_pin_mut`]: Option::as_pin_mut

//! [`as_pin_ref`]: Option::as_pin_ref

//! [`as_ref`]: Option::as_ref

//! [`as_slice`]: Option::as_slice

//! [`as_mut_slice`]: Option::as_mut_slice

//!

//! ## Extracting the contained value

//!

//! These methods extract the contained value in an [`Option<T>`] when it

//! is the [`Some`] variant. If the [`Option`] is [`None`]:

//!

//! * [`expect`] panics with a provided custom message

//! * [`unwrap`] panics with a generic message

//! * [`unwrap_or`] returns the provided default value

//! * [`unwrap_or_default`] returns the default value of the type `T`

//!   (which must implement the [`Default`] trait)

//! * [`unwrap_or_else`] returns the result of evaluating the provided

//!   function

//! * [`unwrap_unchecked`] produces *[undefined behavior]*

//!

//! [`expect`]: Option::expect

//! [`unwrap`]: Option::unwrap

//! [`unwrap_or`]: Option::unwrap_or

//! [`unwrap_or_default`]: Option::unwrap_or_default

//! [`unwrap_or_else`]: Option::unwrap_or_else

//! [`unwrap_unchecked`]: Option::unwrap_unchecked

//! [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html

//!

//! ## Transforming contained values

//!

//! These methods transform [`Option`] to [`Result`]:

//!

//! * [`ok_or`] transforms [`Some(v)`] to [`Ok(v)`], and [`None`] to

//!   [`Err(err)`] using the provided default `err` value

//! * [`ok_or_else`] transforms [`Some(v)`] to [`Ok(v)`], and [`None`] to

//!   a value of [`Err`] using the provided function

//! * [`transpose`] transposes an [`Option`] of a [`Result`] into a

//!   [`Result`] of an [`Option`]

//!

//! [`Err(err)`]: Err

//! [`Ok(v)`]: Ok

//! [`Some(v)`]: Some

//! [`ok_or`]: Option::ok_or

//! [`ok_or_else`]: Option::ok_or_else

//! [`transpose`]: Option::transpose

//!

//! These methods transform the [`Some`] variant:

//!

//! * [`filter`] calls the provided predicate function on the contained

//!   value `t` if the [`Option`] is [`Some(t)`], and returns [`Some(t)`]

//!   if the function returns `true`; otherwise, returns [`None`]

//! * [`flatten`] removes one level of nesting from an [`Option<Option<T>>`]

//! * [`inspect`] method takes ownership of the [`Option`] and applies

//!   the provided function to the contained value by reference if [`Some`]

//! * [`map`] transforms [`Option<T>`] to [`Option<U>`] by applying the

//!   provided function to the contained value of [`Some`] and leaving

//!   [`None`] values unchanged

//!

//! [`Some(t)`]: Some

//! [`filter`]: Option::filter

//! [`flatten`]: Option::flatten

//! [`inspect`]: Option::inspect

//! [`map`]: Option::map

//!

//! These methods transform [`Option<T>`] to a value of a possibly

//! different type `U`:

//!

//! * [`map_or`] applies the provided function to the contained value of

//!   [`Some`], or returns the provided default value if the [`Option`] is

//!   [`None`]

//! * [`map_or_else`] applies the provided function to the contained value

//!   of [`Some`], or returns the result of evaluating the provided

//!   fallback function if the [`Option`] is [`None`]

//!

//! [`map_or`]: Option::map_or

//! [`map_or_else`]: Option::map_or_else

//!

//! These methods combine the [`Some`] variants of two [`Option`] values:

//!

//! * [`zip`] returns [`Some((s, o))`] if `self` is [`Some(s)`] and the

//!   provided [`Option`] value is [`Some(o)`]; otherwise, returns [`None`]

//! * [`zip_with`] calls the provided function `f` and returns

//!   [`Some(f(s, o))`] if `self` is [`Some(s)`] and the provided

//!   [`Option`] value is [`Some(o)`]; otherwise, returns [`None`]

//!

//! [`Some(f(s, o))`]: Some

//! [`Some(o)`]: Some

//! [`Some(s)`]: Some

//! [`Some((s, o))`]: Some

//! [`zip`]: Option::zip

//! [`zip_with`]: Option::zip_with

//!

//! ## Boolean operators

//!

//! These methods treat the [`Option`] as a boolean value, where [`Some`]

//! acts like [`true`] and [`None`] acts like [`false`]. There are two

//! categories of these methods: ones that take an [`Option`] as input, and

//! ones that take a function as input (to be lazily evaluated).

//!

//! The [`and`], [`or`], and [`xor`] methods take another [`Option`] as

//! input, and produce an [`Option`] as output. Only the [`and`] method can

//! produce an [`Option<U>`] value having a different inner type `U` than

//! [`Option<T>`].

//!

//! | method  | self      | input     | output    |

//! |---------|-----------|-----------|-----------|

//! | [`and`] | `None`    | (ignored) | `None`    |

//! | [`and`] | `Some(x)` | `None`    | `None`    |

//! | [`and`] | `Some(x)` | `Some(y)` | `Some(y)` |

//! | [`or`]  | `None`    | `None`    | `None`    |

//! | [`or`]  | `None`    | `Some(y)` | `Some(y)` |

//! | [`or`]  | `Some(x)` | (ignored) | `Some(x)` |

//! | [`xor`] | `None`    | `None`    | `None`    |

//! | [`xor`] | `None`    | `Some(y)` | `Some(y)` |

//! | [`xor`] | `Some(x)` | `None`    | `Some(x)` |

//! | [`xor`] | `Some(x)` | `Some(y)` | `None`    |

//!

//! [`and`]: Option::and

//! [`or`]: Option::or

//! [`xor`]: Option::xor

//!

//! The [`and_then`] and [`or_else`] methods take a function as input, and

//! only evaluate the function when they need to produce a new value. Only

//! the [`and_then`] method can produce an [`Option<U>`] value having a

//! different inner type `U` than [`Option<T>`].

//!

//! | method       | self      | function input | function result | output    |

//! |--------------|-----------|----------------|-----------------|-----------|

//! | [`and_then`] | `None`    | (not provided) | (not evaluated) | `None`    |

//! | [`and_then`] | `Some(x)` | `x`            | `None`          | `None`    |

//! | [`and_then`] | `Some(x)` | `x`            | `Some(y)`       | `Some(y)` |

//! | [`or_else`]  | `None`    | (not provided) | `None`          | `None`    |

//! | [`or_else`]  | `None`    | (not provided) | `Some(y)`       | `Some(y)` |

//! | [`or_else`]  | `Some(x)` | (not provided) | (not evaluated) | `Some(x)` |

//!

//! [`and_then`]: Option::and_then

//! [`or_else`]: Option::or_else

//!

//! This is an example of using methods like [`and_then`] and [`or`] in a

//! pipeline of method calls. Early stages of the pipeline pass failure

//! values ([`None`]) through unchanged, and continue processing on

//! success values ([`Some`]). Toward the end, [`or`] substitutes an error

//! message if it receives [`None`].

//!

//! ```

//! # use std::collections::BTreeMap;

//! let mut bt = BTreeMap::new();

//! bt.insert(20u8, "foo");

//! bt.insert(42u8, "bar");

//! let res = [0u8, 1, 11, 200, 22]

//!     .into_iter()

//!     .map(|x| {

//!         // `checked_sub()` returns `None` on error

//!         x.checked_sub(1)

//!             // same with `checked_mul()`

//!             .and_then(|x| x.checked_mul(2))

//!             // `BTreeMap::get` returns `None` on error

//!             .and_then(|x| bt.get(&x))

//!             // Substitute an error message if we have `None` so far

//!             .or(Some(&"error!"))

//!             .copied()

//!             // Won't panic because we unconditionally used `Some` above

//!             .unwrap()

//!     })

//!     .collect::<Vec<_>>();

//! assert_eq!(res, ["error!", "error!", "foo", "error!", "bar"]);

//! ```

//!

//! ## Comparison operators

//!

//! If `T` implements [`PartialOrd`] then [`Option<T>`] will derive its

//! [`PartialOrd`] implementation.  With this order, [`None`] compares as

//! less than any [`Some`], and two [`Some`] compare the same way as their

//! contained values would in `T`.  If `T` also implements

//! [`Ord`], then so does [`Option<T>`].

//!

//! ```

//! assert!(None < Some(0));

//! assert!(Some(0) < Some(1));

//! ```

//!

//! ## Iterating over `Option`

//!

//! An [`Option`] can be iterated over. This can be helpful if you need an

//! iterator that is conditionally empty. The iterator will either produce

//! a single value (when the [`Option`] is [`Some`]), or produce no values

//! (when the [`Option`] is [`None`]). For example, [`into_iter`] acts like

//! [`once(v)`] if the [`Option`] is [`Some(v)`], and like [`empty()`] if

//! the [`Option`] is [`None`].

//!

//! [`Some(v)`]: Some

//! [`empty()`]: crate::iter::empty

//! [`once(v)`]: crate::iter::once

//!

//! Iterators over [`Option<T>`] come in three types:

//!

//! * [`into_iter`] consumes the [`Option`] and produces the contained

//!   value

//! * [`iter`] produces an immutable reference of type `&T` to the

//!   contained value

//! * [`iter_mut`] produces a mutable reference of type `&mut T` to the

//!   contained value

//!

//! [`into_iter`]: Option::into_iter

//! [`iter`]: Option::iter

//! [`iter_mut`]: Option::iter_mut

//!

//! An iterator over [`Option`] can be useful when chaining iterators, for

//! example, to conditionally insert items. (It's not always necessary to

//! explicitly call an iterator constructor: many [`Iterator`] methods that

//! accept other iterators will also accept iterable types that implement

//! [`IntoIterator`], which includes [`Option`].)

//!

//! ```

//! let yep = Some(42);

//! let nope = None;

//! // chain() already calls into_iter(), so we don't have to do so

//! let nums: Vec<i32> = (0..4).chain(yep).chain(4..8).collect();

//! assert_eq!(nums, [0, 1, 2, 3, 42, 4, 5, 6, 7]);

//! let nums: Vec<i32> = (0..4).chain(nope).chain(4..8).collect();

//! assert_eq!(nums, [0, 1, 2, 3, 4, 5, 6, 7]);

//! ```

//!

//! One reason to chain iterators in this way is that a function returning

//! `impl Iterator` must have all possible return values be of the same

//! concrete type. Chaining an iterated [`Option`] can help with that.

//!

//! ```

//! fn make_iter(do_insert: bool) -> impl Iterator<Item = i32> {

//!     // Explicit returns to illustrate return types matching

//!     match do_insert {

//!         true => return (0..4).chain(Some(42)).chain(4..8),

//!         false => return (0..4).chain(None).chain(4..8),

//!     }

//! }

//! println!("{:?}", make_iter(true).collect::<Vec<_>>());

//! println!("{:?}", make_iter(false).collect::<Vec<_>>());

//! ```

//!

//! If we try to do the same thing, but using [`once()`] and [`empty()`],

//! we can't return `impl Iterator` anymore because the concrete types of

//! the return values differ.

//!

//! [`empty()`]: crate::iter::empty

//! [`once()`]: crate::iter::once

//!

//! ```compile_fail,E0308

//! # use std::iter::{empty, once};

//! // This won't compile because all possible returns from the function

//! // must have the same concrete type.

//! fn make_iter(do_insert: bool) -> impl Iterator<Item = i32> {

//!     // Explicit returns to illustrate return types not matching

//!     match do_insert {

//!         true => return (0..4).chain(once(42)).chain(4..8),

//!         false => return (0..4).chain(empty()).chain(4..8),

//!     }

//! }

//! ```

//!

//! ## Collecting into `Option`

//!

//! [`Option`] implements the [`FromIterator`][impl-FromIterator] trait,

//! which allows an iterator over [`Option`] values to be collected into an

//! [`Option`] of a collection of each contained value of the original

//! [`Option`] values, or [`None`] if any of the elements was [`None`].

//!

//! [impl-FromIterator]: Option#impl-FromIterator%3COption%3CA%3E%3E-for-Option%3CV%3E

//!

//! ```

//! let v = [Some(2), Some(4), None, Some(8)];

//! let res: Option<Vec<_>> = v.into_iter().collect();

//! assert_eq!(res, None);

//! let v = [Some(2), Some(4), Some(8)];

//! let res: Option<Vec<_>> = v.into_iter().collect();

//! assert_eq!(res, Some(vec![2, 4, 8]));

//! ```

//!

//! [`Option`] also implements the [`Product`][impl-Product] and

//! [`Sum`][impl-Sum] traits, allowing an iterator over [`Option`] values

//! to provide the [`product`][Iterator::product] and

//! [`sum`][Iterator::sum] methods.

//!

//! [impl-Product]: Option#impl-Product%3COption%3CU%3E%3E-for-Option%3CT%3E

//! [impl-Sum]: Option#impl-Sum%3COption%3CU%3E%3E-for-Option%3CT%3E

//!

//! ```

//! let v = [None, Some(1), Some(2), Some(3)];

//! let res: Option<i32> = v.into_iter().sum();

//! assert_eq!(res, None);

//! let v = [Some(1), Some(2), Some(21)];

//! let res: Option<i32> = v.into_iter().product();

//! assert_eq!(res, Some(42));

//! ```

//!

//! ## Modifying an [`Option`] in-place

//!

//! These methods return a mutable reference to the contained value of an

//! [`Option<T>`]:

//!

//! * [`insert`] inserts a value, dropping any old contents

//! * [`get_or_insert`] gets the current value, inserting a provided

//!   default value if it is [`None`]

//! * [`get_or_insert_default`] gets the current value, inserting the

//!   default value of type `T` (which must implement [`Default`]) if it is

//!   [`None`]

//! * [`get_or_insert_with`] gets the current value, inserting a default

//!   computed by the provided function if it is [`None`]

//!

//! [`get_or_insert`]: Option::get_or_insert

//! [`get_or_insert_default`]: Option::get_or_insert_default

//! [`get_or_insert_with`]: Option::get_or_insert_with

//! [`insert`]: Option::insert

//!

//! These methods transfer ownership of the contained value of an

//! [`Option`]:

//!

//! * [`take`] takes ownership of the contained value of an [`Option`], if

//!   any, replacing the [`Option`] with [`None`]

//! * [`replace`] takes ownership of the contained value of an [`Option`],

//!   if any, replacing the [`Option`] with a [`Some`] containing the

//!   provided value

//!

//! [`replace`]: Option::replace

//! [`take`]: Option::take

//!

//! # Examples

//!

//! Basic pattern matching on [`Option`]:

//!

//! ```

//! let msg = Some("howdy");

//!

//! // Take a reference to the contained string

//! if let Some(m) = &msg {

//!     println!("{}", *m);

//! }

//!

//! // Remove the contained string, destroying the Option

//! let unwrapped_msg = msg.unwrap_or("default message");

//! ```

//!

//! Initialize a result to [`None`] before a loop:

//!

//! ```

//! enum Kingdom { Plant(u32, &'static str), Animal(u32, &'static str) }

//!

//! // A list of data to search through.

//! let all_the_big_things = [

//!     Kingdom::Plant(250, "redwood"),

//!     Kingdom::Plant(230, "noble fir"),

//!     Kingdom::Plant(229, "sugar pine"),

//!     Kingdom::Animal(25, "blue whale"),

//!     Kingdom::Animal(19, "fin whale"),

//!     Kingdom::Animal(15, "north pacific right whale"),

//! ];

//!

//! // We're going to search for the name of the biggest animal,

//! // but to start with we've just got `None`.

//! let mut name_of_biggest_animal = None;

//! let mut size_of_biggest_animal = 0;

//! for big_thing in &all_the_big_things {

//!     match *big_thing {

//!         Kingdom::Animal(size, name) if size > size_of_biggest_animal => {

//!             // Now we've found the name of some big animal

//!             size_of_biggest_animal = size;

//!             name_of_biggest_animal = Some(name);

//!         }

//!         Kingdom::Animal(..) | Kingdom::Plant(..) => ()

//!     }

//! }

//!

//! match name_of_biggest_animal {

//!     Some(name) => println!("the biggest animal is {name}"),

//!     None => println!("there are no animals :("),

//! }

//! ```

#![stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

use crate::iter::{self, FusedIterator, TrustedLen};

use crate::marker::Destruct;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::ops::{self, ControlFlow, Deref, DerefMut};

#[cfg(feature = "ferrocene_certified")]

use crate::ops::{Deref, DerefMut};

#[cfg(not(feature = "ferrocene_certified"))]

use crate::panicking::{panic, panic_display};

#[cfg(not(feature = "ferrocene_certified"))]

use crate::pin::Pin;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::{cmp, convert, hint, mem, slice};

/// The `Option` type. See [the module level documentation](self) for more.

#[doc(search_unbox)]

#[cfg_attr(not(feature = "ferrocene_certified"), derive(Copy, Eq, Debug, Hash))]

#[rustc_diagnostic_item = "Option"]

#[lang = "Option"]

#[stable(feature = "rust1", since = "1.0.0")]

#[allow(clippy::derived_hash_with_manual_eq)] // PartialEq is manually implemented equivalently

pub enum Option<T> {

    /// No value.

    #[lang = "None"]

    #[stable(feature = "rust1", since = "1.0.0")]

    None,

    /// Some value of type `T`.

    #[lang = "Some"]

    #[stable(feature = "rust1", since = "1.0.0")]

    Some(#[stable(feature = "rust1", since = "1.0.0")] T),

}

/////////////////////////////////////////////////////////////////////////////

// Type implementation

/////////////////////////////////////////////////////////////////////////////

impl<T> Option<T> {

    /////////////////////////////////////////////////////////////////////////

    // Querying the contained values

    /////////////////////////////////////////////////////////////////////////

    /// 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);

    /// ```

    #[must_use = "if you intended to assert that this has a value, consider `.unwrap()` instead"]

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_stable(feature = "const_option_basics", since = "1.48.0")]

    /// Returns `true` if the option is a [`Some`] and the value inside of it matches a predicate.

    ///

    /// # Examples

    ///

    /// ```

    /// let x: Option<u32> = Some(2);

    /// assert_eq!(x.is_some_and(|x| x > 1), true);

    ///

    /// let x: Option<u32> = Some(0);

    /// assert_eq!(x.is_some_and(|x| x > 1), false);

    ///

    /// let x: Option<u32> = None;

    /// assert_eq!(x.is_some_and(|x| x > 1), false);

    ///

    /// let x: Option<String> = Some("ownership".to_string());

    /// assert_eq!(x.as_ref().is_some_and(|x| x.len() > 1), true);

    /// println!("still alive {:?}", x);

    /// ```

    #[must_use]

    #[inline]

    #[stable(feature = "is_some_and", since = "1.70.0")]

    #[rustc_const_unstable(feature = "const_option_ops", issue = "143956")]

        }

    /// 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);

    /// ```

    #[must_use = "if you intended to assert that this doesn't have a value, consider \

                  wrapping this in an `assert!()` instead"]

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_stable(feature = "const_option_basics", since = "1.48.0")]

    #[cfg(not(feature = "ferrocene_certified"))]

    pub const fn is_none(&self) -> bool {

        !self.is_some()

    }

    /// Returns `true` if the option is a [`None`] or the value inside of it matches a predicate.

    ///

    /// # Examples

    ///

    /// ```

    /// let x: Option<u32> = Some(2);

    /// assert_eq!(x.is_none_or(|x| x > 1), true);

    ///

    /// let x: Option<u32> = Some(0);

    /// assert_eq!(x.is_none_or(|x| x > 1), false);

    ///

    /// let x: Option<u32> = None;

    /// assert_eq!(x.is_none_or(|x| x > 1), true);

    ///

    /// let x: Option<String> = Some("ownership".to_string());

    /// assert_eq!(x.as_ref().is_none_or(|x| x.len() > 1), true);

    /// println!("still alive {:?}", x);

    /// ```

    #[must_use]

    #[inline]

    #[stable(feature = "is_none_or", since = "1.82.0")]

    #[rustc_const_unstable(feature = "const_option_ops", issue = "143956")]

        }

    /////////////////////////////////////////////////////////////////////////

    // Adapter for working with references

    /////////////////////////////////////////////////////////////////////////

    /// Converts from `&Option<T>` to `Option<&T>`.

    ///

    /// # Examples

    ///

    /// Calculates the length of an <code>Option<[String]></code> as an <code>Option<[usize]></code>

    /// without moving the [`String`]. 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.

    ///

    /// [`map`]: Option::map

    /// [String]: ../../std/string/struct.String.html "String"

    /// [`String`]: ../../std/string/struct.String.html "String"

    ///

    /// ```

    /// 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:?}");

    /// ```

    #[inline]

    #[rustc_const_stable(feature = "const_option_basics", since = "1.48.0")]

    #[stable(feature = "rust1", since = "1.0.0")]

        }

    /// 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));

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_stable(feature = "const_option", since = "1.83.0")]

        }

    /// Converts from <code>[Pin]<[&]Option\<T>></code> to <code>Option<[Pin]<[&]T>></code>.

    ///

    /// [&]: reference "shared reference"

    #[inline]

    #[must_use]

    #[stable(feature = "pin", since = "1.33.0")]

    #[rustc_const_stable(feature = "const_option_ext", since = "1.84.0")]

    #[cfg(not(feature = "ferrocene_certified"))]

    pub const fn as_pin_ref(self: Pin<&Self>) -> Option<Pin<&T>> {

        // FIXME(const-hack): use `map` once that is possible

        match Pin::get_ref(self).as_ref() {

            // SAFETY: `x` is guaranteed to be pinned because it comes from `self`

            // which is pinned.

            Some(x) => unsafe { Some(Pin::new_unchecked(x)) },

            None => None,

        }

    }

    /// Converts from <code>[Pin]<[&mut] Option\<T>></code> to <code>Option<[Pin]<[&mut] T>></code>.

    ///

    /// [&mut]: reference "mutable reference"

    #[inline]

    #[must_use]

    #[stable(feature = "pin", since = "1.33.0")]

    #[rustc_const_stable(feature = "const_option_ext", since = "1.84.0")]

    #[cfg(not(feature = "ferrocene_certified"))]

    pub const fn as_pin_mut(self: Pin<&mut Self>) -> Option<Pin<&mut T>> {

        // SAFETY: `get_unchecked_mut` is never used to move the `Option` inside `self`.

        // `x` is guaranteed to be pinned because it comes from `self` which is pinned.

        unsafe {

            // FIXME(const-hack): use `map` once that is possible

            match Pin::get_unchecked_mut(self).as_mut() {

                Some(x) => Some(Pin::new_unchecked(x)),

                None => None,

            }

        }

    }

    #[inline]

    #[cfg(not(feature = "ferrocene_certified"))]

    const fn len(&self) -> usize {

        // Using the intrinsic avoids emitting a branch to get the 0 or 1.

        let discriminant: isize = crate::intrinsics::discriminant_value(self);

        discriminant as usize

    }

    /// Returns a slice of the contained value, if any. If this is `None`, an

    /// empty slice is returned. This can be useful to have a single type of

    /// iterator over an `Option` or slice.

    ///

    /// Note: Should you have an `Option<&T>` and wish to get a slice of `T`,

    /// you can unpack it via `opt.map_or(&[], std::slice::from_ref)`.

    ///

    /// # Examples

    ///

    /// ```rust

    /// assert_eq!(

    ///     [Some(1234).as_slice(), None.as_slice()],

    ///     [&[1234][..], &[][..]],

    /// );

    /// ```

    ///

    /// The inverse of this function is (discounting

    /// borrowing) [`[_]::first`](slice::first):

    ///

    /// ```rust

    /// for i in [Some(1234_u16), None] {

    ///     assert_eq!(i.as_ref(), i.as_slice().first());

    /// }

    /// ```

    #[inline]

    #[must_use]

    #[stable(feature = "option_as_slice", since = "1.75.0")]

    #[rustc_const_stable(feature = "const_option_ext", since = "1.84.0")]

    #[cfg(not(feature = "ferrocene_certified"))]

    pub const fn as_slice(&self) -> &[T] {

        // SAFETY: When the `Option` is `Some`, we're using the actual pointer

        // to the payload, with a length of 1, so this is equivalent to

        // `slice::from_ref`, and thus is safe.

        // When the `Option` is `None`, the length used is 0, so to be safe it

        // just needs to be aligned, which it is because `&self` is aligned and

        // the offset used is a multiple of alignment.

        //

        // Here we assume that `offset_of!` always returns an offset to an

        // in-bounds and correctly aligned position for a `T` (even if in the

        // `None` case it's just padding).

        unsafe {

            slice::from_raw_parts(

                (self as *const Self).byte_add(core::mem::offset_of!(Self, Some.0)).cast(),

                self.len(),

            )

        }

    }

    /// Returns a mutable slice of the contained value, if any. If this is

    /// `None`, an empty slice is returned. This can be useful to have a

    /// single type of iterator over an `Option` or slice.

    ///

    /// Note: Should you have an `Option<&mut T>` instead of a

    /// `&mut Option<T>`, which this method takes, you can obtain a mutable

    /// slice via `opt.map_or(&mut [], std::slice::from_mut)`.

    ///

    /// # Examples

    ///

    /// ```rust

    /// assert_eq!(

    ///     [Some(1234).as_mut_slice(), None.as_mut_slice()],

    ///     [&mut [1234][..], &mut [][..]],

    /// );

    /// ```

    ///

    /// The result is a mutable slice of zero or one items that points into

    /// our original `Option`:

    ///

    /// ```rust

    /// let mut x = Some(1234);

    /// x.as_mut_slice()[0] += 1;

    /// assert_eq!(x, Some(1235));

    /// ```

    ///

    /// The inverse of this method (discounting borrowing)

    /// is [`[_]::first_mut`](slice::first_mut):

    ///

    /// ```rust

    /// assert_eq!(Some(123).as_mut_slice().first_mut(), Some(&mut 123))

    /// ```

    #[inline]

    #[must_use]

    #[stable(feature = "option_as_slice", since = "1.75.0")]

    #[rustc_const_stable(feature = "const_option_ext", since = "1.84.0")]

    #[cfg(not(feature = "ferrocene_certified"))]

    pub const fn as_mut_slice(&mut self) -> &mut [T] {

        // SAFETY: When the `Option` is `Some`, we're using the actual pointer

        // to the payload, with a length of 1, so this is equivalent to

        // `slice::from_mut`, and thus is safe.

        // When the `Option` is `None`, the length used is 0, so to be safe it

        // just needs to be aligned, which it is because `&self` is aligned and

        // the offset used is a multiple of alignment.

        //

        // In the new version, the intrinsic creates a `*const T` from a

        // mutable reference  so it is safe to cast back to a mutable pointer

        // here. As with `as_slice`, the intrinsic always returns a pointer to

        // an in-bounds and correctly aligned position for a `T` (even if in

        // the `None` case it's just padding).

        unsafe {

            slice::from_raw_parts_mut(

                (self as *mut Self).byte_add(core::mem::offset_of!(Self, Some.0)).cast(),

                self.len(),

            )

        }

    }

    /////////////////////////////////////////////////////////////////////////

    // Getting to contained values

    /////////////////////////////////////////////////////////////////////////

    /// 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");

    /// ```

    ///

    /// ```should_panic

    /// let x: Option<&str> = 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`.

    ///

    /// ```should_panic

    /// # let slice: &[u8] = &[];

    /// 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"](../../std/error/index.html#common-message-styles) in the [`std::error`](../../std/error/index.html) module docs.

    #[inline]

    #[track_caller]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_diagnostic_item = "option_expect"]

    #[rustc_allow_const_fn_unstable(const_precise_live_drops)]

    #[rustc_const_stable(feature = "const_option", since = "1.83.0")]

    #[cfg(not(feature = "ferrocene_certified"))]

    pub const fn expect(self, msg: &str) -> T {

        match self {

            Some(val) => val,

            None => expect_failed(msg),

        }

    }

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

    ///

    /// Because this function may panic, its use is generally discouraged.

    /// Panics are meant for unrecoverable errors, and

    /// [may abort the entire program][panic-abort].

    ///

    /// Instead, prefer to use pattern matching and handle the [`None`]

    /// case explicitly, or call [`unwrap_or`], [`unwrap_or_else`], or

    /// [`unwrap_or_default`]. In functions returning `Option`, you can use

    /// [the `?` (try) operator][try-option].

    ///

    /// [panic-abort]: https://doc.rust-lang.org/book/ch09-01-unrecoverable-errors-with-panic.html

    /// [try-option]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#where-the--operator-can-be-used

    /// [`unwrap_or`]: Option::unwrap_or

    /// [`unwrap_or_else`]: Option::unwrap_or_else

    /// [`unwrap_or_default`]: Option::unwrap_or_default

    ///

    /// # Panics

    ///

    /// Panics if the self value equals [`None`].

    ///

    /// # Examples

    ///

    /// ```

    /// let x = Some("air");

    /// assert_eq!(x.unwrap(), "air");

    /// ```

    ///

    /// ```should_panic

    /// let x: Option<&str> = None;

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

    /// ```

    #[inline(always)]

    #[track_caller]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_diagnostic_item = "option_unwrap"]

    #[rustc_allow_const_fn_unstable(const_precise_live_drops)]

    #[rustc_const_stable(feature = "const_option", since = "1.83.0")]

    #[cfg(not(feature = "ferrocene_certified"))]

    pub const fn unwrap(self) -> T {

        match self {

            Some(val) => val,

            None => unwrap_failed(),

        }

    }

    /// 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.

    ///

    /// [`unwrap_or_else`]: Option::unwrap_or_else

    ///

    /// # Examples

    ///

    /// ```

    /// assert_eq!(Some("car").unwrap_or("bike"), "car");

    /// assert_eq!(None.unwrap_or("bike"), "bike");

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_allow_const_fn_unstable(const_precise_live_drops)]

    #[rustc_const_unstable(feature = "const_option_ops", issue = "143956")]

    {

        }

    /// 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);

    /// ```

    #[inline]

    #[track_caller]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_unstable(feature = "const_option_ops", issue = "143956")]

    {

        }

    /// Returns the contained [`Some`] 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

    ///

    /// ```

    /// let x: Option<u32> = None;

    /// let y: Option<u32> = Some(12);

    ///

    /// assert_eq!(x.unwrap_or_default(), 0);

    /// assert_eq!(y.unwrap_or_default(), 12);

    /// ```

    ///

    /// [default value]: Default::default

    /// [`parse`]: str::parse

    /// [`FromStr`]: crate::str::FromStr

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_unstable(feature = "const_option_ops", issue = "143956")]

    {

        }

    /// Returns the contained [`Some`] value, consuming the `self` value,

    /// without checking that the value is not [`None`].

    ///

    /// # Safety

    ///

    /// Calling this method on [`None`] is *[undefined behavior]*.

    ///

    /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html

    ///

    /// # Examples

    ///

    /// ```

    /// let x = Some("air");

    /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air");

    /// ```

    ///

    /// ```no_run

    /// let x: Option<&str> = None;

    /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air"); // Undefined behavior!

    /// ```

    #[inline]

    #[track_caller]

    #[stable(feature = "option_result_unwrap_unchecked", since = "1.58.0")]

    #[rustc_allow_const_fn_unstable(const_precise_live_drops)]

    #[rustc_const_stable(feature = "const_option", since = "1.83.0")]

    #[cfg(not(feature = "ferrocene_certified"))]

    pub const unsafe fn unwrap_unchecked(self) -> T {

        match self {

            Some(val) => val,

            // SAFETY: the safety contract must be upheld by the caller.

            None => unsafe { hint::unreachable_unchecked() },

        }

    }

    /////////////////////////////////////////////////////////////////////////

    // Transforming contained values

    /////////////////////////////////////////////////////////////////////////

    /// 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 <code>Option<[String]></code> as an

    /// <code>Option<[usize]></code>, consuming the original:

    ///

    /// [String]: ../../std/string/struct.String.html "String"

    /// ```

    /// 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: Option<&str> = None;

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

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_unstable(feature = "const_option_ops", issue = "143956")]

    {

        }

    /// Calls a function with a reference to the contained value if [`Some`].

    ///

    /// Returns the original option.

    ///

    /// # Examples

    ///

    /// ```

    /// let list = vec![1, 2, 3];

    ///

    /// // prints "got: 2"

    /// let x = list

    ///     .get(1)

    ///     .inspect(|x| println!("got: {x}"))

    ///     .expect("list should be long enough");

    ///

    /// // prints nothing

    /// list.get(5).inspect(|x| println!("got: {x}"));

    /// ```

    #[inline]

    #[stable(feature = "result_option_inspect", since = "1.76.0")]

    #[rustc_const_unstable(feature = "const_option_ops", issue = "143956")]

    pub const fn inspect<F>(self, f: F) -> Self

    where

        F: [const] FnOnce(&T) + [const] Destruct,

    {

        if let Some(ref x) = self {

            f(x);

        }

        self

    }

    /// Returns the provided default result (if none),

    /// or applies a function to the contained value (if any).

    ///

    /// Arguments passed to `map_or` are eagerly evaluated; if you are passing

    /// the result of a function call, it is recommended to use [`map_or_else`],

    /// which is lazily evaluated.

    ///

    /// [`map_or_else`]: Option::map_or_else

    ///

    /// # 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);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[must_use = "if you don't need the returned value, use `if let` instead"]

    #[rustc_const_unstable(feature = "const_option_ops", issue = "143956")]

    {

        }

    /// Computes a default function result (if none), or

    /// applies a different function to the contained value (if any).

    ///

    /// # Basic 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);

    /// ```

    ///

    /// # Handling a Result-based fallback

    ///

    /// A somewhat common occurrence when dealing with optional values

    /// in combination with [`Result<T, E>`] is the case where one wants to invoke

    /// a fallible fallback if the option is not present.  This example

    /// parses a command line argument (if present), or the contents of a file to

    /// an integer.  However, unlike accessing the command line argument, reading

    /// the file is fallible, so it must be wrapped with `Ok`.

    ///

    /// ```no_run

    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {

    /// let v: u64 = std::env::args()

    ///    .nth(1)

    ///    .map_or_else(|| std::fs::read_to_string("/etc/someconfig.conf"), Ok)?

    ///    .parse()?;

    /// #   Ok(())

    /// # }

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_unstable(feature = "const_option_ops", issue = "143956")]

    {

        }

    /// Maps an `Option<T>` to a `U` by applying function `f` to the contained

    /// value if the option is [`Some`], otherwise if [`None`], returns the

    /// [default value] for the type `U`.

    ///

    /// # Examples

    ///

    /// ```

    /// #![feature(result_option_map_or_default)]

    ///

    /// let x: Option<&str> = Some("hi");

    /// let y: Option<&str> = None;

    ///

    /// assert_eq!(x.map_or_default(|x| x.len()), 2);

    /// assert_eq!(y.map_or_default(|y| y.len()), 0);

    /// ```

    ///

    /// [default value]: Default::default

    #[inline]

    #[unstable(feature = "result_option_map_or_default", issue = "138099")]

    #[rustc_const_unstable(feature = "const_option_ops", issue = "143956")]

    pub const fn map_or_default<U, F>(self, f: F) -> U

    where

        U: [const] Default,

        F: [const] FnOnce(T) -> U + [const] Destruct,

    {

        match self {

            Some(t) => f(t),

            None => U::default(),

        }

    }

    /// 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.

    ///

    /// [`Ok(v)`]: Ok

    /// [`Err(err)`]: Err

    /// [`Some(v)`]: Some

    /// [`ok_or_else`]: Option::ok_or_else