perhaps/

lib.rs

//! Optional values.
//!
//! Type [`Perhaps`] represents an optional value: every [`Perhaps`]
//! is either [`Certain`] and contains a value, or [`Dubious`], and
//! does not. [`Perhaps`] 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 [`Dubious`] 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
//!
//! [`Perhaps`]s are commonly paired with pattern matching to query the presence
//! of a value and take action, always accounting for the [`Dubious`] case.
//!
//! ```
//! fn divide(numerator: f64, denominator: f64) -> Perhaps<f64> {
//!     if denominator == 0.0 {
//!         Dubious
//!     } else {
//!         Certain(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
//!     Certain(x) => println!("Result: {x}"),
//!     // The division was invalid
//!     Dubious    => println!("Cannot divide by 0"),
//! }
//! ```
//!
//
// FIXME: Show how `Perhaps` 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>[Perhaps]<[Box\<T>]></code>.
//!
//! [Box\<T>]: ../../std/boxed/struct.Box.html
//!
//! The following example uses [`Perhaps`] 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 [`Self::Certain(...)`][`Certain`]) or
//! not ([`Dubious`]).
//!
//! ```
//! let optional = Dubious;
//! check_optional(optional);
//!
//! let optional = Certain(Box::new(9000));
//! check_optional(optional);
//!
//! fn check_optional(optional: Perhaps<Box<i32>>) {
//!     match optional {
//!         Certain(p) => println!("has value {p}"),
//!         Dubious => println!("has no value"),
//!     }
//! }
//! ```
//!
//! # The question mark operator, `?`
//!
//! Similar to the [`Result`] type, when writing code that calls many functions that return the
//! [`Perhaps`] type, handling `Certain`/`Dubious` 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>) -> Perhaps<i32> {
//!     let a = stack.pop();
//!     let b = stack.pop();
//!
//!     match (a, b) {
//!         (Self::Certain(x), Self::Certain(y)) => Certain(x + y),
//!         _ => Dubious,
//!     }
//! }
//!
//! ```
//!
//! With this:
//!
//! ```
//! # #![allow(dead_code)]
//! fn add_last_numbers(stack: &mut Vec<i32>) -> Perhaps<i32> {
//!     Certain(stack.pop()? + stack.pop()?)
//! }
//! ```
//!
//! *It's much nicer!*
//!
//! Ending the expression with [`?`] will result in the [`Certain`]'s unwrapped value, unless the
//! result is [`Self::Dubious`], in which case [`Dubious`] is returned early from the enclosing function.
//!
//! [`?`] can be used in functions that return [`Perhaps`] because of the
//! early return of [`Dubious`] that it provides.
//!
//! [`?`]: crate::ops::Try
//! [`Self::Certain`]: Certain
//! [`Self::Dubious`]: Dubious
//!
//! # Representation
//!
//! Rust guarantees to optimize the following types `T` such that
//! [`Perhaps<T>`] has the same size, alignment, and [function call ABI] as `T`. In some
//! of these cases, Rust further guarantees that
//! `transmute::<_, Perhaps<T>>([0u8; size_of::<T>()])` is sound and
//! produces `Perhaps::<T>::Dubious`. These cases are identified by the
//! second column:
//!
//! | `T`                                                                 | `transmute::<_, Perhaps<T>>([0u8; size_of::<T>()])` 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 any argument/return types and any other ABI: `extern "abi" fn` (_e.g._, `extern "system" fn`)
//!
//! [`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
//!
//! 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 `Perhaps<T>` and
//! from `Certain::<T>(_)` to `T` (but transmuting `Dubious::<T>` to `T`
//! is undefined behaviour).
//!
//! # Method overview
//!
//! In addition to working with pattern matching, [`Perhaps`] provides a wide
//! variety of different methods.
//!
//! ## Querying the variant
//!
//! The [`is_certain`] and [`is_dubious`] methods return [`true`] if the [`Perhaps`]
//! is [`Certain`] or [`Dubious`], respectively.
//!
//! [`is_dubious`]: Perhaps::is_dubious
//! [`is_certain`]: Perhaps::is_certain
//!
//! ## Adapters for working with references
//!
//! * [`as_ref`] converts from <code>[&][][Perhaps]\<T></code> to <code>[Perhaps]<[&]T></code>
//! * [`as_mut`] converts from <code>[&mut] [Perhaps]\<T></code> to <code>[Perhaps]<[&mut] T></code>
//! * [`as_deref`] converts from <code>[&][][Perhaps]\<T></code> to
//!   <code>[Perhaps]<[&]T::[Target]></code>
//! * [`as_deref_mut`] converts from <code>[&mut] [Perhaps]\<T></code> to
//!   <code>[Perhaps]<[&mut] T::[Target]></code>
//! * [`as_pin_ref`] converts from <code>[Pin]<[&][][Perhaps]\<T>></code> to
//!   <code>[Perhaps]<[Pin]<[&]T>></code>
//! * [`as_pin_mut`] converts from <code>[Pin]<[&mut] [Perhaps]\<T>></code> to
//!   <code>[Perhaps]<[Pin]<[&mut] T>></code>
//!
//! [&]: reference "shared reference"
//! [&mut]: reference "mutable reference"
//! [Target]: Deref::Target "ops::Deref::Target"
//! [`as_deref`]: Perhaps::as_deref
//! [`as_deref_mut`]: Perhaps::as_deref_mut
//! [`as_mut`]: Perhaps::as_mut
//! [`as_pin_mut`]: Perhaps::as_pin_mut
//! [`as_pin_ref`]: Perhaps::as_pin_ref
//! [`as_ref`]: Perhaps::as_ref
//!
//! ## Extracting the contained value
//!
//! These methods extract the contained value in an [`Perhaps<T>`] when it
//! is the [`Certain`] variant. If the [`Perhaps`] is [`Dubious`]:
//!
//! * [`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
//!
//! [`expect`]: Perhaps::expect
//! [`unwrap`]: Perhaps::unwrap
//! [`unwrap_or`]: Perhaps::unwrap_or
//! [`unwrap_or_default`]: Perhaps::unwrap_or_default
//! [`unwrap_or_else`]: Perhaps::unwrap_or_else
//!
//! ## Transforming contained values
//!
//! These methods transform [`Perhaps`] to [`Result`]:
//!
//! * [`ok_or`] transforms [`Certain(v)`] to [`Ok(v)`], and [`Dubious`] to
//!   [`Err(err)`] using the provided default `err` value
//! * [`ok_or_else`] transforms [`Certain(v)`] to [`Ok(v)`], and [`Dubious`] to
//!   a value of [`Err`] using the provided function
//! * [`transpose`] transposes an [`Perhaps`] of a [`Result`] into a
//!   [`Result`] of an [`Perhaps`]
//!
//! [`Err(err)`]: Err
//! [`Ok(v)`]: Ok
//! [`Self::Certain(v)`]: Certain
//! [`ok_or`]: Perhaps::ok_or
//! [`ok_or_else`]: Perhaps::ok_or_else
//! [`transpose`]: Perhaps::transpose
//!
//! These methods transform the [`Certain`] variant:
//!
//! * [`filter`] calls the provided predicate function on the contained
//!   value `t` if the [`Perhaps`] is [`Self::Certain(t)`], and returns [`Certain(t)`]
//!   if the function returns `true`; otherwise, returns [`Dubious`]
//! * [`flatten`] removes one level of nesting from an
//!   [`Perhaps<Perhaps<T>>`]
//! * [`map`] transforms [`Perhaps<T>`] to [`Perhaps<U>`] by applying the
//!   provided function to the contained value of [`Certain`] and leaving
//!   [`Dubious`] values unchanged
//!
//! [`Self::Certain(t)`]: Certain
//! [`filter`]: Perhaps::filter
//! [`flatten`]: Perhaps::flatten
//! [`map`]: Perhaps::map
//!
//! These methods transform [`Perhaps<T>`] to a value of a possibly
//! different type `U`:
//!
//! * [`map_or`] applies the provided function to the contained value of
//!   [`Certain`], or returns the provided default value if the [`Perhaps`] is
//!   [`Dubious`]
//! * [`map_or_else`] applies the provided function to the contained value
//!   of [`Certain`], or returns the result of evaluating the provided
//!   fallback function if the [`Perhaps`] is [`Dubious`]
//!
//! [`map_or`]: Perhaps::map_or
//! [`map_or_else`]: Perhaps::map_or_else
//!
//! These methods combine the [`Certain`] variants of two [`Perhaps`] values:
//!
//! * [`zip`] returns [`Self::Certain((s, o))`] if `self` is [`Certain(s)`] and the
//!   provided [`Perhaps`] value is [`Certain(o)`]; otherwise, returns [`Dubious`]
//! * [`zip_with`] calls the provided function `f` and returns
//!   [`Self::Certain(f(s, o))`] if `self` is [`Certain(s)`] and the provided
//!   [`Perhaps`] value is [`Certain(o)`]; otherwise, returns [`Dubious`]
//!
//! [`Self::Certain(f(s, o))`]: Certain
//! [`Self::Certain(o)`]: Certain
//! [`Self::Certain(s)`]: Certain
//! [`Self::Certain((s, o))`]: Certain
//! [`zip`]: Perhaps::zip
//! [`zip_with`]: Perhaps::zip_with
//!
//! ## Boolean operators
//!
//! These methods treat the [`Perhaps`] as a boolean value, where [`Certain`]
//! acts like [`true`] and [`Dubious`] acts like [`false`]. There are two
//! categories of these methods: ones that take an [`Perhaps`] as input, and
//! ones that take a function as input (to be lazily evaluated).
//!
//! The [`and`], [`or`], and [`xor`] methods take another [`Perhaps`] as
//! input, and produce an [`Perhaps`] as output. Only the [`and`] method can
//! produce an [`Perhaps<U>`] value having a different inner type `U` than
//! [`Perhaps<T>`].
//!
//! | method  | self      | input     | output    |
//! |---------|-----------|-----------|-----------|
//! | [`and`] | `Self::Dubious`    | (ignored) | `Dubious`    |
//! | [`and`] | `Certain(x)` | `Self::Dubious`    | `Dubious`    |
//! | [`and`] | `Self::Certain(x)` | `Self::Certain(y)` | `Certain(y)` |
//! | [`or`]  | `Self::Dubious`    | `Self::Dubious`    | `Dubious`    |
//! | [`or`]  | `Dubious`    | `Self::Certain(y)` | `Certain(y)` |
//! | [`or`]  | `Self::Certain(x)` | (ignored) | `Certain(x)` |
//! | [`xor`] | `Self::Dubious`    | `Self::Dubious`    | `Dubious`    |
//! | [`xor`] | `Dubious`    | `Self::Certain(y)` | `Certain(y)` |
//! | [`xor`] | `Self::Certain(x)` | `Dubious`    | `Certain(x)` |
//! | [`xor`] | `Self::Certain(x)` | `Certain(y)` | `Dubious`    |
//!
//! [`and`]: Perhaps::and
//! [`or`]: Perhaps::or
//! [`xor`]: Perhaps::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 [`Perhaps<U>`] value having a
//! different inner type `U` than [`Perhaps<T>`].
//!
//! | method       | self      | function input | function result | output    |
//! |--------------|-----------|----------------|-----------------|-----------|
//! | [`and_then`] | `Self::Dubious`    | (not provided) | (not evaluated) | `Dubious`    |
//! | [`and_then`] | `Certain(x)` | `x`            | `Self::Dubious`          | `Dubious`    |
//! | [`and_then`] | `Self::Certain(x)` | `x`            | `Self::Certain(y)`       | `Certain(y)` |
//! | [`or_else`]  | `Self::Dubious`    | (not provided) | `Self::Dubious`          | `Dubious`    |
//! | [`or_else`]  | `Dubious`    | (not provided) | `Self::Certain(y)`       | `Certain(y)` |
//! | [`or_else`]  | `Self::Certain(x)` | (not provided) | (not evaluated) | `Certain(x)` |
//!
//! [`and_then`]: Perhaps::and_then
//! [`or_else`]: Perhaps::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 ([`Dubious`]) through unchanged, and continue processing on
//! success values ([`Certain`]). Toward the end, [`or`] substitutes an error
//! message if it receives [`Dubious`].
//!
//! ```
//! # 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 `Dubious` on error
//!         x.checked_sub(1)
//!             // same with `checked_mul()`
//!             .and_then(|x| x.checked_mul(2))
//!             // `BTreeMap::get` returns `Dubious` on error
//!             .and_then(|x| bt.get(&x))
//!             // Substitute an error message if we have `Dubious` so far
//!             .or(Certain(&"error!"))
//!             .copied()
//!             // Won't panic because we unconditionally used `Certain` above
//!             .unwrap()
//!     })
//!     .collect::<Vec<_>>();
//! assert_eq!(res, ["error!", "error!", "foo", "error!", "bar"]);
//! ```
//!
//! ## Comparison operators
//!
//! If `T` implements [`PartialOrd`] then [`Perhaps<T>`] will derive its
//! [`PartialOrd`] implementation.  With this order, [`Dubious`] compares as
//! less than any [`Self::Certain`], and two [`Certain`] compare the same way as their
//! contained values would in `T`.  If `T` also implements
//! [`Ord`], then so does [`Perhaps<T>`].
//!
//! ```
//! assert!(Dubious < Certain(0));
//! assert!(Self::Certain(0) < Certain(1));
//! ```
//!
//! ## Iterating over `Perhaps`
//!
//! An [`Perhaps`] 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 [`Perhaps`] is [`Certain`]), or produce no values
//! (when the [`Perhaps`] is [`Dubious`]). For example, [`into_iter`] acts like
//! [`once(v)`] if the [`Perhaps`] is [`Certain(v)`], and like [`empty()`] if
//! the [`Perhaps`] is [`Dubious`].
//!
//! [`Self::Certain(v)`]: Certain
//! [`empty()`]: crate::iter::empty
//! [`once(v)`]: crate::iter::once
//!
//! Iterators over [`Perhaps<T>`] come in three types:
//!
//! * [`into_iter`] consumes the [`Perhaps`] 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`]: Perhaps::into_iter
//! [`iter`]: Perhaps::iter
//! [`iter_mut`]: Perhaps::iter_mut
//!
//! An iterator over [`Perhaps`] 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 [`Perhaps`].)
//!
//! ```
//! let yep = Certain(42);
//! let nope = Dubious;
//! // 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 [`Perhaps`] 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(Certain(42)).chain(4..8),
//!         false => return (0..4).chain(Dubious).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 `Perhaps`
//!
//! [`Perhaps`] implements the [`FromIterator`][impl-FromIterator] trait,
//! which allows an iterator over [`Perhaps`] values to be collected into an
//! [`Perhaps`] of a collection of each contained value of the original
//! [`Perhaps`] values, or [`Self::Dubious`] if any of the elements was [`Dubious`].
//!
//! [impl-FromIterator]: Perhaps#impl-FromIterator%3CPerhaps%3CA%3E%3E-for-Perhaps%3CV%3E
//!
//! ```
//! let v = [Self::Certain(2), Self::Certain(4), Dubious, Certain(8)];
//! let res: Perhaps<Vec<_>> = v.into_iter().collect();
//! assert_eq!(res, Dubious);
//! let v = [Self::Certain(2), Self::Certain(4), Certain(8)];
//! let res: Perhaps<Vec<_>> = v.into_iter().collect();
//! assert_eq!(res, Certain(vec![2, 4, 8]));
//! ```
//!
//! [`Perhaps`] also implements the [`Product`][impl-Product] and
//! [`Sum`][impl-Sum] traits, allowing an iterator over [`Perhaps`] values
//! to provide the [`product`][Iterator::product] and
//! [`sum`][Iterator::sum] methods.
//!
//! [impl-Product]: Perhaps#impl-Product%3CPerhaps%3CU%3E%3E-for-Perhaps%3CT%3E
//! [impl-Sum]: Perhaps#impl-Sum%3CPerhaps%3CU%3E%3E-for-Perhaps%3CT%3E
//!
//! ```
//! let v = [Dubious, Self::Certain(1), Self::Certain(2), Certain(3)];
//! let res: Perhaps<i32> = v.into_iter().sum();
//! assert_eq!(res, Dubious);
//! let v = [Self::Certain(1), Self::Certain(2), Certain(21)];
//! let res: Perhaps<i32> = v.into_iter().product();
//! assert_eq!(res, Certain(42));
//! ```
//!
//! ## Modifying an [`Perhaps`] in-place
//!
//! These methods return a mutable reference to the contained value of an
//! [`Perhaps<T>`]:
//!
//! * [`insert`] inserts a value, dropping any old contents
//! * [`get_or_insert`] gets the current value, inserting a provided
//!   default value if it is [`Dubious`]
//! * [`get_or_insert_default`] gets the current value, inserting the
//!   default value of type `T` (which must implement [`Default`]) if it is
//!   [`Dubious`]
//! * [`get_or_insert_with`] gets the current value, inserting a default
//!   computed by the provided function if it is [`Dubious`]
//!
//! [`get_or_insert`]: Perhaps::get_or_insert
//! [`get_or_insert_default`]: Perhaps::get_or_insert_default
//! [`get_or_insert_with`]: Perhaps::get_or_insert_with
//! [`insert`]: Perhaps::insert
//!
//! These methods transfer ownership of the contained value of an
//! [`Perhaps`]:
//!
//! * [`take`] takes ownership of the contained value of an [`Perhaps`], if
//!   any, replacing the [`Perhaps`] with [`Dubious`]
//! * [`replace`] takes ownership of the contained value of an [`Perhaps`],
//!   if any, replacing the [`Perhaps`] with a [`Certain`] containing the
//!   provided value
//!
//! [`replace`]: Perhaps::replace
//! [`take`]: Perhaps::take
//!
//! # Examples
//!
//! Basic pattern matching on [`Perhaps`]:
//!
//! ```
//! let msg = Certain("howdy");
//!
//! // Take a reference to the contained string
//! if let Certain(m) = &msg {
//!     println!("{}", *m);
//! }
//!
//! // Remove the contained string, destroying the Perhaps
//! let unwrapped_msg = msg.unwrap_or("default message");
//! ```
//!
//! Initialize a result to [`Dubious`] 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 `Dubious`.
//! let mut name_of_biggest_animal = Dubious;
//! 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 = Certain(name);
//!         }
//!         Kingdom::Animal(..) | Kingdom::Plant(..) => ()
//!     }
//! }
//!
//! match name_of_biggest_animal {
//!     Certain(name) => println!("the biggest animal is {name}"),
//!     Dubious => println!("there are no animals :("),
//! }
//! ```

use std::{
    hint, mem,
    ops::{Deref, DerefMut},
};

/// The `Perhaps` type. See [the module level documentation](self) for more.
#[derive(Copy, PartialEq, PartialOrd, Eq, Debug, Hash)]
pub enum Perhaps<T> {
    /// No value.
    Dubious,
    /// Certain value of type `T`.
    Certain(T),
}

/////////////////////////////////////////////////////////////////////////////
// Type implementation
/////////////////////////////////////////////////////////////////////////////

impl<T> Perhaps<T> {
    /////////////////////////////////////////////////////////////////////////
    // Querying the contained values
    /////////////////////////////////////////////////////////////////////////

    /// Returns `true` if the option is a [`Certain`] value.
    ///
    /// # Examples
    ///
    /// ```
    /// let x: Perhaps<u32> = Certain(2);
    /// assert_eq!(x.is_certain(), true);
    ///
    /// let x: Perhaps<u32> = Dubious;
    /// assert_eq!(x.is_certain(), false);
    /// ```
    #[must_use = "if you intended to assert that this has a value, consider `.unwrap()` instead"]
    #[inline]
    pub const fn is_certain(&self) -> bool {
        matches!(*self, Self::Certain(_))
    }

    /// Returns `true` if the option is a [`Certain`] and the value inside of it matches a predicate.
    ///
    /// # Examples
    ///
    /// ```
    /// let x: Perhaps<u32> = Certain(2);
    /// assert_eq!(x.is_certain_and(|x| x > 1), true);
    ///
    /// let x: Perhaps<u32> = Certain(0);
    /// assert_eq!(x.is_certain_and(|x| x > 1), false);
    ///
    /// let x: Perhaps<u32> = Dubious;
    /// assert_eq!(x.is_certain_and(|x| x > 1), false);
    /// ```
    #[must_use]
    #[inline]
    pub fn is_certain_and(self, f: impl FnOnce(T) -> bool) -> bool {
        match self {
            Self::Dubious => false,
            Self::Certain(x) => f(x),
        }
    }

    /// Returns `true` if the option is a [`Dubious`] value.
    ///
    /// # Examples
    ///
    /// ```
    /// let x: Perhaps<u32> = Certain(2);
    /// assert_eq!(x.is_dubious(), false);
    ///
    /// let x: Perhaps<u32> = Dubious;
    /// assert_eq!(x.is_dubious(), true);
    /// ```
    #[must_use = "if you intended to assert that this doesn't have a value, consider \
                  wrapping this in an `assert!()` instead"]
    #[inline]
    pub const fn is_dubious(&self) -> bool {
        !self.is_certain()
    }

    /////////////////////////////////////////////////////////////////////////
    // Adapter for working with references
    /////////////////////////////////////////////////////////////////////////

    /// Converts from `&Perhaps<T>` to `Perhaps<&T>`.
    ///
    /// # Examples
    ///
    /// Calculates the length of an <code>Perhaps<[String]></code> as an <code>Perhaps<[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 `Perhaps` to a
    /// reference to the value inside the original.
    ///
    /// [`map`]: Perhaps::map
    /// [String]: ../../std/string/struct.String.html "String"
    /// [`String`]: ../../std/string/struct.String.html "String"
    ///
    /// ```
    /// let text: Perhaps<String> = Certain("Hello, world!".to_string());
    /// // First, cast `Perhaps<String>` to `Perhaps<&String>` with `as_ref`,
    /// // then consume *that* with `map`, leaving `text` on the stack.
    /// let text_length: Perhaps<usize> = text.as_ref().map(|s| s.len());
    /// println!("still can print text: {text:?}");
    /// ```
    #[inline]
    pub const fn as_ref(&self) -> Perhaps<&T> {
        match *self {
            Self::Certain(ref x) => Perhaps::Certain(x),
            Self::Dubious => Perhaps::Dubious,
        }
    }

    /// Converts from `&mut Perhaps<T>` to `Perhaps<&mut T>`.
    ///
    /// # Examples
    ///
    /// ```
    /// let mut x = Certain(2);
    /// match x.as_mut() {
    ///     Certain(v) => *v = 42,
    ///     Dubious => {},
    /// }
    /// assert_eq!(x, Certain(42));
    /// ```
    #[inline]
    pub fn as_mut(&mut self) -> Perhaps<&mut T> {
        match *self {
            Self::Certain(ref mut x) => Perhaps::Certain(x),
            Self::Dubious => Perhaps::Dubious,
        }
    }

    /////////////////////////////////////////////////////////////////////////
    // Getting to contained values
    /////////////////////////////////////////////////////////////////////////

    /// Returns the contained [`Certain`] value, consuming the `self` value.
    ///
    /// # Panics
    ///
    /// Panics if the value is a [`Dubious`] with a custom panic message provided by
    /// `msg`.
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain("value");
    /// assert_eq!(x.expect("fruits are healthy"), "value");
    /// ```
    ///
    /// ```should_panic
    /// let x: Perhaps<&str> = Dubious;
    /// 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 `Perhaps` should be `Certain`.
    ///
    /// ```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]
    pub fn expect(self, msg: &str) -> T {
        match self {
            Self::Certain(val) => val,
            Self::Dubious => expect_failed(msg),
        }
    }

    /// Returns the contained [`Certain`] value, consuming the `self` value.
    ///
    /// Because this function may panic, its use is generally discouraged.
    /// Instead, prefer to use pattern matching and handle the [`Dubious`]
    /// case explicitly, or call [`unwrap_or`], [`unwrap_or_else`], or
    /// [`unwrap_or_default`].
    ///
    /// [`unwrap_or`]: Perhaps::unwrap_or
    /// [`unwrap_or_else`]: Perhaps::unwrap_or_else
    /// [`unwrap_or_default`]: Perhaps::unwrap_or_default
    ///
    /// # Panics
    ///
    /// Panics if the self value equals [`Dubious`].
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain("air");
    /// assert_eq!(x.unwrap(), "air");
    /// ```
    ///
    /// ```should_panic
    /// let x: Perhaps<&str> = Dubious;
    /// assert_eq!(x.unwrap(), "air"); // fails
    /// ```
    #[inline(always)]
    #[track_caller]
    pub fn unwrap(self) -> T {
        match self {
            Self::Certain(val) => val,
            Self::Dubious => unwrap_failed(),
        }
    }

    /// Returns the contained [`Certain`] 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`]: Perhaps::unwrap_or_else
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!(Certain("car").unwrap_or("bike"), "car");
    /// assert_eq!(Dubious.unwrap_or("bike"), "bike");
    /// ```
    #[inline]
    pub fn unwrap_or(self, default: T) -> T {
        match self {
            Self::Certain(x) => x,
            Self::Dubious => default,
        }
    }

    /// Returns the contained [`Certain`] value or computes it from a closure.
    ///
    /// # Examples
    ///
    /// ```
    /// let k = 10;
    /// assert_eq!(Certain(4).unwrap_or_else(|| 2 * k), 4);
    /// assert_eq!(Dubious.unwrap_or_else(|| 2 * k), 20);
    /// ```
    #[inline]
    #[track_caller]
    pub fn unwrap_or_else<F>(self, f: F) -> T
    where
        F: FnOnce() -> T,
    {
        match self {
            Self::Certain(x) => x,
            Self::Dubious => f(),
        }
    }

    /// Returns the contained [`Certain`] value or a default.
    ///
    /// Consumes the `self` argument then, if [`Certain`], returns the contained
    /// value, otherwise if [`Dubious`], returns the [default value] for that
    /// type.
    ///
    /// # Examples
    ///
    /// ```
    /// let x: Perhaps<u32> = Dubious;
    /// let y: Perhaps<u32> = Certain(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]
    pub fn unwrap_or_default(self) -> T
    where
        T: Default,
    {
        match self {
            Self::Certain(x) => x,
            Self::Dubious => T::default(),
        }
    }

    /// Returns the contained [`Certain`] value, consuming the `self` value,
    /// without checking that the value is not [`Dubious`].
    ///
    /// # Safety
    ///
    /// Calling this method on [`Dubious`] is *[undefined behavior]*.
    ///
    /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain("air");
    /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air");
    /// ```
    ///
    /// ```no_run
    /// let x: Perhaps<&str> = Dubious;
    /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air"); // Undefined behavior!
    /// ```
    #[inline]
    #[track_caller]
    pub unsafe fn unwrap_unchecked(self) -> T {
        match self {
            Self::Certain(val) => val,
            // SAFETY: the safety contract must be upheld by the caller.
            Self::Dubious => unsafe { hint::unreachable_unchecked() },
        }
    }

    /////////////////////////////////////////////////////////////////////////
    // Transforming contained values
    /////////////////////////////////////////////////////////////////////////

    /// Maps an `Perhaps<T>` to `Perhaps<U>` by applying a function to a contained value (if `Certain`) or returns `Self::Dubious` (if `Dubious`).
    ///
    /// # Examples
    ///
    /// Calculates the length of an <code>Perhaps<[String]></code> as an
    /// <code>Perhaps<[usize]></code>, consuming the original:
    ///
    /// [String]: ../../std/string/struct.String.html "String"
    /// ```
    /// let maybe_string = Certain(String::from("Hello, World!"));
    /// // `Perhaps::map` takes self *by value*, consuming `maybe_some_string`
    /// let maybe_len = maybe_string.map(|s| s.len());
    /// assert_eq!(maybe_len, Certain(13));
    ///
    /// let x: Perhaps<&str> = Dubious;
    /// assert_eq!(x.map(|s| s.len()), Dubious);
    /// ```
    #[inline]
    pub fn map<U, F>(self, f: F) -> Perhaps<U>
    where
        F: FnOnce(T) -> U,
    {
        match self {
            Self::Certain(x) => Perhaps::Certain(f(x)),
            Self::Dubious => Perhaps::Dubious,
        }
    }

    /// Calls a function with a reference to the contained value if [`Certain`].
    ///
    /// 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]
    pub fn inspect<F: FnOnce(&T)>(self, f: F) -> Self {
        if let Self::Certain(ref x) = self {
            f(x);
        }

        self
    }

    /// Returns the provided default result (if dubious),
    /// 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`]: Perhaps::map_or_else
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain("foo");
    /// assert_eq!(x.map_or(42, |v| v.len()), 3);
    ///
    /// let x: Perhaps<&str> = Dubious;
    /// assert_eq!(x.map_or(42, |v| v.len()), 42);
    /// ```
    #[inline]
    #[must_use = "if you don't need the returned value, use `if let` instead"]
    pub fn map_or<U, F>(self, default: U, f: F) -> U
    where
        F: FnOnce(T) -> U,
    {
        match self {
            Self::Certain(t) => f(t),
            Self::Dubious => default,
        }
    }

    /// Computes a default function result (if dubious), or
    /// applies a different function to the contained value (if any).
    ///
    /// # Basic examples
    ///
    /// ```
    /// let k = 21;
    ///
    /// let x = Certain("foo");
    /// assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 3);
    ///
    /// let x: Perhaps<&str> = Dubious;
    /// 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]
    pub fn map_or_else<U, D, F>(self, default: D, f: F) -> U
    where
        D: FnOnce() -> U,
        F: FnOnce(T) -> U,
    {
        match self {
            Self::Certain(t) => f(t),
            Self::Dubious => default(),
        }
    }

    /// Transforms the `Perhaps<T>` into a [`Result<T, E>`], mapping [`Certain(v)`] to
    /// [`Ok(v)`] and [`Dubious`] 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
    /// [`Self::Certain(v)`]: Certain
    /// [`ok_or_else`]: Perhaps::ok_or_else
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain("foo");
    /// assert_eq!(x.ok_or(0), Ok("foo"));
    ///
    /// let x: Perhaps<&str> = Dubious;
    /// assert_eq!(x.ok_or(0), Err(0));
    /// ```
    #[inline]
    pub fn ok_or<E>(self, err: E) -> Result<T, E> {
        match self {
            Self::Certain(v) => Ok(v),
            Self::Dubious => Err(err),
        }
    }

    /// Transforms the `Perhaps<T>` into a [`Result<T, E>`], mapping [`Certain(v)`] to
    /// [`Ok(v)`] and [`Dubious`] to [`Err(err())`].
    ///
    /// [`Ok(v)`]: Ok
    /// [`Err(err())`]: Err
    /// [`Self::Certain(v)`]: Certain
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain("foo");
    /// assert_eq!(x.ok_or_else(|| 0), Ok("foo"));
    ///
    /// let x: Perhaps<&str> = Dubious;
    /// assert_eq!(x.ok_or_else(|| 0), Err(0));
    /// ```
    #[inline]
    pub fn ok_or_else<E, F>(self, err: F) -> Result<T, E>
    where
        F: FnOnce() -> E,
    {
        match self {
            Self::Certain(v) => Ok(v),
            Self::Dubious => Err(err()),
        }
    }

    /// Converts from `Perhaps<T>` (or `&Perhaps<T>`) to `Perhaps<&T::Target>`.
    ///
    /// Leaves the original Perhaps in-place, creating a new one with a reference
    /// to the original one, additionally coercing the contents via [`Deref`].
    ///
    /// # Examples
    ///
    /// ```
    /// let x: Perhaps<String> = Certain("hey".to_owned());
    /// assert_eq!(x.as_deref(), Certain("hey"));
    ///
    /// let x: Perhaps<String> = Dubious;
    /// assert_eq!(x.as_deref(), Dubious);
    /// ```
    #[inline]
    pub fn as_deref(&self) -> Perhaps<&T::Target>
    where
        T: Deref,
    {
        match self.as_ref() {
            Perhaps::Certain(t) => Perhaps::Certain(t.deref()),
            Perhaps::Dubious => Perhaps::Dubious,
        }
    }

    /// Converts from `Perhaps<T>` (or `&mut Perhaps<T>`) to `Perhaps<&mut T::Target>`.
    ///
    /// Leaves the original `Perhaps` in-place, creating a new one containing a mutable reference to
    /// the inner type's [`Deref::Target`] type.
    ///
    /// # Examples
    ///
    /// ```
    /// let mut x: Perhaps<String> = Certain("hey".to_owned());
    /// assert_eq!(x.as_deref_mut().map(|x| {
    ///     x.make_ascii_uppercase();
    ///     x
    /// }), Certain("HEY".to_owned().as_mut_str()));
    /// ```
    #[inline]
    pub fn as_deref_mut(&mut self) -> Perhaps<&mut T::Target>
    where
        T: DerefMut,
    {
        match self.as_mut() {
            Perhaps::Certain(t) => Perhaps::Certain(t.deref_mut()),
            Perhaps::Dubious => Perhaps::Dubious,
        }
    }

    /////////////////////////////////////////////////////////////////////////
    // Iterator constructors
    /////////////////////////////////////////////////////////////////////////

    /////////////////////////////////////////////////////////////////////////
    // Boolean operations on the values, eager and lazy
    /////////////////////////////////////////////////////////////////////////

    /// Returns [`Self::Dubious`] if the option is [`Dubious`], otherwise returns `optb`.
    ///
    /// Arguments passed to `and` are eagerly evaluated; if you are passing the
    /// result of a function call, it is recommended to use [`and_then`], which is
    /// lazily evaluated.
    ///
    /// [`and_then`]: Perhaps::and_then
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain(2);
    /// let y: Perhaps<&str> = Dubious;
    /// assert_eq!(x.and(y), Dubious);
    ///
    /// let x: Perhaps<u32> = Dubious;
    /// let y = Certain("foo");
    /// assert_eq!(x.and(y), Dubious);
    ///
    /// let x = Certain(2);
    /// let y = Certain("foo");
    /// assert_eq!(x.and(y), Certain("foo"));
    ///
    /// let x: Perhaps<u32> = Dubious;
    /// let y: Perhaps<&str> = Dubious;
    /// assert_eq!(x.and(y), Dubious);
    /// ```
    #[inline]
    pub fn and<U>(self, optb: Perhaps<U>) -> Perhaps<U> {
        match self {
            Self::Certain(_) => optb,
            Self::Dubious => Perhaps::<U>::Dubious,
        }
    }

    /// Returns [`Self::Dubious`] if the option is [`Dubious`], otherwise calls `f` with the
    /// wrapped value and returns the result.
    ///
    /// Certain languages call this operation flatmap.
    ///
    /// # Examples
    ///
    /// ```
    /// fn sq_then_to_string(x: u32) -> Perhaps<String> {
    ///     x.checked_mul(x).map(|sq| sq.to_string())
    /// }
    ///
    /// assert_eq!(Self::Certain(2).and_then(sq_then_to_string), Certain(4.to_string()));
    /// assert_eq!(Certain(1_000_000).and_then(sq_then_to_string), Dubious); // overflowed!
    /// assert_eq!(Self::Dubious.and_then(sq_then_to_string), Dubious);
    /// ```
    ///
    /// Often used to chain fallible operations that may return [`Dubious`].
    ///
    /// ```
    /// 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, Certain(&"A1"));
    ///
    /// let item_2_0 = arr_2d.get(2).and_then(|row| row.get(0));
    /// assert_eq!(item_2_0, Dubious);
    /// ```
    #[doc(alias = "flatmap")]
    #[inline]
    pub fn and_then<U, F>(self, f: F) -> Perhaps<U>
    where
        F: FnOnce(T) -> Perhaps<U>,
    {
        match self {
            Self::Certain(x) => f(x),
            Self::Dubious => Perhaps::Dubious,
        }
    }

    /// Returns [`Self::Dubious`] if the option is [`Dubious`], otherwise calls `predicate`
    /// with the wrapped value and returns:
    ///
    /// - [`Certain(t)`] if `predicate` returns `true` (where `t` is the wrapped
    ///   value), and
    /// - [`Dubious`] if `predicate` returns `false`.
    ///
    /// This function works similar to [`Iterator::filter()`]. You can imagine
    /// the `Perhaps<T>` being an iterator over one or zero elements. `filter()`
    /// lets you decide which elements to keep.
    ///
    /// # Examples
    ///
    /// ```rust
    /// fn is_even(n: &i32) -> bool {
    ///     n % 2 == 0
    /// }
    ///
    /// assert_eq!(Self::Dubious.filter(is_even), Dubious);
    /// assert_eq!(Certain(3).filter(is_even), Dubious);
    /// assert_eq!(Self::Certain(4).filter(is_even), Certain(4));
    /// ```
    ///
    /// [`Self::Certain(t)`]: Certain
    #[inline]
    pub fn filter<P>(self, predicate: P) -> Self
    where
        P: FnOnce(&T) -> bool,
    {
        if let Self::Certain(x) = self {
            if predicate(&x) {
                return Self::Certain(x);
            }
        }
        Self::Dubious
    }

    /// 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.
    ///
    /// [`or_else`]: Perhaps::or_else
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain(2);
    /// let y = Dubious;
    /// assert_eq!(x.or(y), Certain(2));
    ///
    /// let x = Dubious;
    /// let y = Certain(100);
    /// assert_eq!(x.or(y), Certain(100));
    ///
    /// let x = Certain(2);
    /// let y = Certain(100);
    /// assert_eq!(x.or(y), Certain(2));
    ///
    /// let x: Perhaps<u32> = Dubious;
    /// let y = Dubious;
    /// assert_eq!(x.or(y), Dubious);
    /// ```
    #[inline]
    pub fn or(self, optb: Perhaps<T>) -> Perhaps<T> {
        match self {
            x @ Self::Certain(_) => x,
            Self::Dubious => optb,
        }
    }

    /// Returns the option if it contains a value, otherwise calls `f` and
    /// returns the result.
    ///
    /// # Examples
    ///
    /// ```
    /// fn nobody() -> Perhaps<&'static str> { Dubious }
    /// fn vikings() -> Perhaps<&'static str> { Certain("vikings") }
    ///
    /// assert_eq!(Self::Certain("barbarians").or_else(vikings), Certain("barbarians"));
    /// assert_eq!(Dubious.or_else(vikings), Certain("vikings"));
    /// assert_eq!(Self::Dubious.or_else(nobody), Dubious);
    /// ```
    #[inline]
    pub fn or_else<F>(self, f: F) -> Perhaps<T>
    where
        F: FnOnce() -> Perhaps<T>,
    {
        match self {
            x @ Self::Certain(_) => x,
            Self::Dubious => f(),
        }
    }

    /// Returns [`Self::Certain`] if exactly one of `self`, `optb` is [`Certain`], otherwise returns [`Dubious`].
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain(2);
    /// let y: Perhaps<u32> = Dubious;
    /// assert_eq!(x.xor(y), Certain(2));
    ///
    /// let x: Perhaps<u32> = Dubious;
    /// let y = Certain(2);
    /// assert_eq!(x.xor(y), Certain(2));
    ///
    /// let x = Certain(2);
    /// let y = Certain(2);
    /// assert_eq!(x.xor(y), Dubious);
    ///
    /// let x: Perhaps<u32> = Dubious;
    /// let y: Perhaps<u32> = Dubious;
    /// assert_eq!(x.xor(y), Dubious);
    /// ```
    #[inline]
    pub fn xor(self, optb: Perhaps<T>) -> Perhaps<T> {
        match (self, optb) {
            (a @ Self::Certain(_), Self::Dubious) => a,
            (Self::Dubious, b @ Self::Certain(_)) => b,
            _ => Self::Dubious,
        }
    }

    /////////////////////////////////////////////////////////////////////////
    // Entry-like operations to insert a value and return a reference
    /////////////////////////////////////////////////////////////////////////

    /// Inserts `value` into the option, then returns a mutable reference to it.
    ///
    /// If the option already contains a value, the old value is dropped.
    ///
    /// See also [`Perhaps::get_or_insert`], which doesn't update the value if
    /// the option already contains [`Certain`].
    ///
    /// # Example
    ///
    /// ```
    /// let mut opt = Dubious;
    /// let val = opt.insert(1);
    /// assert_eq!(*val, 1);
    /// assert_eq!(opt.unwrap(), 1);
    /// let val = opt.insert(2);
    /// assert_eq!(*val, 2);
    /// *val = 3;
    /// assert_eq!(opt.unwrap(), 3);
    /// ```
    #[must_use = "if you intended to set a value, consider assignment instead"]
    #[inline]
    pub fn insert(&mut self, value: T) -> &mut T {
        *self = Self::Certain(value);

        // SAFETY: the code above just filled the option
        unsafe { self.as_mut().unwrap_unchecked() }
    }

    /// Inserts `value` into the option if it is [`Dubious`], then
    /// returns a mutable reference to the contained value.
    ///
    /// See also [`Perhaps::insert`], which updates the value even if
    /// the option already contains [`Certain`].
    ///
    /// # Examples
    ///
    /// ```
    /// let mut x = Dubious;
    ///
    /// {
    ///     let y: &mut u32 = x.get_or_insert(5);
    ///     assert_eq!(y, &5);
    ///
    ///     *y = 7;
    /// }
    ///
    /// assert_eq!(x, Certain(7));
    /// ```
    #[inline]
    pub fn get_or_insert(&mut self, value: T) -> &mut T {
        if let Self::Dubious = *self {
            *self = Self::Certain(value);
        }

        // SAFETY: a `Self::Dubious` variant for `self` would have been replaced by a `Self::Certain`
        // variant in the code above.
        unsafe { self.as_mut().unwrap_unchecked() }
    }

    /// Inserts a value computed from `f` into the option if it is [`Dubious`],
    /// then returns a mutable reference to the contained value.
    ///
    /// # Examples
    ///
    /// ```
    /// let mut x = Dubious;
    ///
    /// {
    ///     let y: &mut u32 = x.get_or_insert_with(|| 5);
    ///     assert_eq!(y, &5);
    ///
    ///     *y = 7;
    /// }
    ///
    /// assert_eq!(x, Certain(7));
    /// ```
    #[inline]
    pub fn get_or_insert_with<F>(&mut self, f: F) -> &mut T
    where
        F: FnOnce() -> T,
    {
        if let Self::Dubious = self {
            *self = Self::Certain(f());
        }

        // SAFETY: a `Self::Dubious` variant for `self` would have been replaced by a `Self::Certain`
        // variant in the code above.
        unsafe { self.as_mut().unwrap_unchecked() }
    }

    /////////////////////////////////////////////////////////////////////////
    // Misc
    /////////////////////////////////////////////////////////////////////////

    /// Takes the value out of the option, leaving a [`Dubious`] in its place.
    ///
    /// # Examples
    ///
    /// ```
    /// let mut x = Certain(2);
    /// let y = x.take();
    /// assert_eq!(x, Dubious);
    /// assert_eq!(y, Certain(2));
    ///
    /// let mut x: Perhaps<u32> = Dubious;
    /// let y = x.take();
    /// assert_eq!(x, Dubious);
    /// assert_eq!(y, Dubious);
    /// ```
    #[inline]
    pub fn take(&mut self) -> Perhaps<T> {
        // FIXME replace `mem::replace` by `mem::take` when the latter is const ready
        mem::replace(self, Self::Dubious)
    }

    /// Replaces the actual value in the option by the value given in parameter,
    /// returning the old value if present,
    /// leaving a [`Certain`] in its place without deinitializing either one.
    ///
    /// # Examples
    ///
    /// ```
    /// let mut x = Certain(2);
    /// let old = x.replace(5);
    /// assert_eq!(x, Certain(5));
    /// assert_eq!(old, Certain(2));
    ///
    /// let mut x = Dubious;
    /// let old = x.replace(3);
    /// assert_eq!(x, Certain(3));
    /// assert_eq!(old, Dubious);
    /// ```
    #[inline]
    pub fn replace(&mut self, value: T) -> Perhaps<T> {
        mem::replace(self, Self::Certain(value))
    }

    /// Zips `self` with another `Perhaps`.
    ///
    /// If `self` is `Self::Certain(s)` and `other` is `Self::Certain(o)`, this method returns `Certain((s, o))`.
    /// Otherwise, `Dubious` is returned.
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain(1);
    /// let y = Certain("hi");
    /// let z = Dubious::<u8>;
    ///
    /// assert_eq!(x.zip(y), Certain((1, "hi")));
    /// assert_eq!(x.zip(z), Dubious);
    /// ```
    pub fn zip<U>(self, other: Perhaps<U>) -> Perhaps<(T, U)> {
        match (self, other) {
            (Self::Certain(a), Perhaps::Certain(b)) => Perhaps::Certain((a, b)),
            _ => Perhaps::Dubious,
        }
    }
}

impl<T, U> Perhaps<(T, U)> {
    /// Unzips an option containing a tuple of two options.
    ///
    /// If `self` is `Self::Certain((a, b))` this method returns `(Self::Certain(a), Certain(b))`.
    /// Otherwise, `(Self::Dubious, Dubious)` is returned.
    ///
    /// # Examples
    ///
    /// ```
    /// let x = Certain((1, "hi"));
    /// let y = Dubious::<(u8, u32)>;
    ///
    /// assert_eq!(x.unzip(), (Self::Certain(1), Certain("hi")));
    /// assert_eq!(y.unzip(), (Self::Dubious, Dubious));
    /// ```
    #[inline]
    pub fn unzip(self) -> (Perhaps<T>, Perhaps<U>) {
        match self {
            Self::Certain((a, b)) => (Perhaps::Certain(a), Perhaps::Certain(b)),
            Self::Dubious => (Perhaps::Dubious, Perhaps::Dubious),
        }
    }
}

impl<T> Perhaps<&T> {
    /// Maps an `Perhaps<&T>` to an `Perhaps<T>` by copying the contents of the
    /// option.
    ///
    /// # Examples
    ///
    /// ```
    /// let x = 12;
    /// let opt_x = Certain(&x);
    /// assert_eq!(opt_x, Certain(&12));
    /// let copied = opt_x.copied();
    /// assert_eq!(copied, Certain(12));
    /// ```
    #[must_use = "`self` will be dropped if the result is not used"]
    pub const fn copied(self) -> Perhaps<T>
    where
        T: Copy,
    {
        // FIXME: this implementation, which sidesteps using `Perhaps::map` since it's not const
        // ready yet, should be reverted when possible to avoid code repetition
        match self {
            Self::Certain(&v) => Perhaps::Certain(v),
            Self::Dubious => Perhaps::Dubious,
        }
    }

    /// Maps an `Perhaps<&T>` to an `Perhaps<T>` by cloning the contents of the
    /// option.
    ///
    /// # Examples
    ///
    /// ```
    /// let x = 12;
    /// let opt_x = Certain(&x);
    /// assert_eq!(opt_x, Certain(&12));
    /// let cloned = opt_x.cloned();
    /// assert_eq!(cloned, Certain(12));
    /// ```
    #[must_use = "`self` will be dropped if the result is not used"]
    pub fn cloned(self) -> Perhaps<T>
    where
        T: Clone,
    {
        match self {
            Self::Certain(t) => Perhaps::Certain(t.clone()),
            Self::Dubious => Perhaps::Dubious,
        }
    }
}

impl<T> Perhaps<&mut T> {
    /// Maps an `Perhaps<&mut T>` to an `Perhaps<T>` by copying the contents of the
    /// option.
    ///
    /// # Examples
    ///
    /// ```
    /// let mut x = 12;
    /// let opt_x = Certain(&mut x);
    /// assert_eq!(opt_x, Certain(&mut 12));
    /// let copied = opt_x.copied();
    /// assert_eq!(copied, Certain(12));
    /// ```
    #[must_use = "`self` will be dropped if the result is not used"]
    pub fn copied(self) -> Perhaps<T>
    where
        T: Copy,
    {
        match self {
            Self::Certain(&mut t) => Perhaps::Certain(t),
            Self::Dubious => Perhaps::Dubious,
        }
    }

    /// Maps an `Perhaps<&mut T>` to an `Perhaps<T>` by cloning the contents of the
    /// option.
    ///
    /// # Examples
    ///
    /// ```
    /// let mut x = 12;
    /// let opt_x = Certain(&mut x);
    /// assert_eq!(opt_x, Certain(&mut 12));
    /// let cloned = opt_x.cloned();
    /// assert_eq!(cloned, Certain(12));
    /// ```
    #[must_use = "`self` will be dropped if the result is not used"]
    pub fn cloned(self) -> Perhaps<T>
    where
        T: Clone,
    {
        match self {
            Self::Certain(t) => Perhaps::Certain(t.clone()),
            Self::Dubious => Perhaps::Dubious,
        }
    }
}

impl<T, E> Perhaps<Result<T, E>> {
    /// Transposes an `Perhaps` of a [`Result`] into a [`Result`] of an `Perhaps`.
    ///
    /// [`Self::Dubious`] will be mapped to <code>[Ok]\([Dubious])</code>.
    /// <code>[Self::Certain]\([Ok]\(\_))</code> and <code>[Certain]\([Err]\(\_))</code> will be mapped to
    /// <code>[Ok]\([Certain]\(\_))</code> and <code>[Err]\(\_)</code>.
    ///
    /// # Examples
    ///
    /// ```
    /// #[derive(Debug, Eq, PartialEq)]
    /// struct SomeErr;
    ///
    /// let x: Result<Perhaps<i32>, SomeErr> = Ok(Certain(5));
    /// let y: Perhaps<Result<i32, SomeErr>> = Certain(Ok(5));
    /// assert_eq!(x, y.transpose());
    /// ```
    #[inline]
    pub fn transpose(self) -> Result<Perhaps<T>, E> {
        match self {
            Self::Certain(Ok(x)) => Ok(Perhaps::Certain(x)),
            Self::Certain(Err(e)) => Err(e),
            Self::Dubious => Ok(Perhaps::Dubious),
        }
    }
}

#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))]
#[cfg_attr(feature = "panic_immediate_abort", inline)]
#[cold]
#[track_caller]
const fn unwrap_failed() -> ! {
    panic!("called `Perhaps::unwrap()` on a `Self::Dubious` value")
}

// This is a separate function to reduce the code size of .expect() itself.
#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))]
#[cfg_attr(feature = "panic_immediate_abort", inline)]
#[cold]
#[track_caller]
const fn expect_failed(msg: &str) -> ! {
    panic!("{}", msg);
}

/////////////////////////////////////////////////////////////////////////////
// Trait implementations
/////////////////////////////////////////////////////////////////////////////

impl<T> Clone for Perhaps<T>
where
    T: Clone,
{
    #[inline]
    fn clone(&self) -> Self {
        match self {
            Self::Certain(x) => Self::Certain(x.clone()),
            Self::Dubious => Self::Dubious,
        }
    }

    #[inline]
    fn clone_from(&mut self, source: &Self) {
        match (self, source) {
            (Self::Certain(to), Self::Certain(from)) => to.clone_from(from),
            (to, from) => *to = from.clone(),
        }
    }
}

impl<T> Default for Perhaps<T> {
    /// Returns [`Self::Dubious`][Perhaps::Dubious].
    ///
    /// # Examples
    ///
    /// ```
    /// let opt: Perhaps<u32> = Perhaps::default();
    /// assert!(opt.is_dubious());
    /// ```
    #[inline]
    fn default() -> Perhaps<T> {
        Self::Dubious
    }
}

impl<T> From<T> for Perhaps<T> {
    /// Moves `val` into a new [`Certain`].
    ///
    /// # Examples
    ///
    /// ```
    /// let o: Perhaps<u8> = Perhaps::from(67);
    ///
    /// assert_eq!(Certain(67), o);
    /// ```
    fn from(val: T) -> Perhaps<T> {
        Self::Certain(val)
    }
}

impl<'a, T> From<&'a Perhaps<T>> for Perhaps<&'a T> {
    /// Converts from `&Perhaps<T>` to `Perhaps<&T>`.
    ///
    /// # Examples
    ///
    /// Converts an <code>[Perhaps]<[String]></code> into an <code>[Perhaps]<[usize]></code>, preserving
    /// the original. The [`map`] method takes the `self` argument by value, consuming the original,
    /// so this technique uses `from` to first take an [`Perhaps`] to a reference
    /// to the value inside the original.
    ///
    /// [`map`]: Perhaps::map
    /// [String]: ../../std/string/struct.String.html "String"
    ///
    /// ```
    /// let s: Perhaps<String> = Certain(String::from("Hello, Rustaceans!"));
    /// let o: Perhaps<usize> = Perhaps::from(&s).map(|ss: &String| ss.len());
    ///
    /// println!("Can still print s: {s:?}");
    ///
    /// assert_eq!(o, Certain(18));
    /// ```
    fn from(o: &'a Perhaps<T>) -> Perhaps<&'a T> {
        o.as_ref()
    }
}

impl<'a, T> From<&'a mut Perhaps<T>> for Perhaps<&'a mut T> {
    /// Converts from `&mut Perhaps<T>` to `Perhaps<&mut T>`
    ///
    /// # Examples
    ///
    /// ```
    /// let mut s = Certain(String::from("Hello"));
    /// let o: Perhaps<&mut String> = Perhaps::from(&mut s);
    ///
    /// match o {
    ///     Certain(t) => *t = String::from("Hello, Rustaceans!"),
    ///     Dubious => (),
    /// }
    ///
    /// assert_eq!(s, Certain(String::from("Hello, Rustaceans!")));
    /// ```
    fn from(o: &'a mut Perhaps<T>) -> Perhaps<&'a mut T> {
        o.as_mut()
    }
}

impl<T> Perhaps<Perhaps<T>> {
    /// Converts from `Perhaps<Perhaps<T>>` to `Perhaps<T>`.
    ///
    /// # Examples
    ///
    /// Basic usage:
    ///
    /// ```
    /// let x: Perhaps<Perhaps<u32>> = Self::Certain(Certain(6));
    /// assert_eq!(Certain(6), x.flatten());
    ///
    /// let x: Perhaps<Perhaps<u32>> = Certain(Dubious);
    /// assert_eq!(Dubious, x.flatten());
    ///
    /// let x: Perhaps<Perhaps<u32>> = Dubious;
    /// assert_eq!(Dubious, x.flatten());
    /// ```
    ///
    /// Flattening only removes one level of nesting at a time:
    ///
    /// ```
    /// let x: Perhaps<Perhaps<Perhaps<u32>>> = Self::Certain(Self::Certain(Certain(6)));
    /// assert_eq!(Self::Certain(Certain(6)), x.flatten());
    /// assert_eq!(Certain(6), x.flatten().flatten());
    /// ```
    #[inline]
    pub fn flatten(self) -> Perhaps<T> {
        match self {
            Self::Certain(inner) => inner,
            Self::Dubious => Perhaps::Dubious,
        }
    }
}