any_of 1.3.1

//! # any_of
//!
//! `any_of` is a flexible and lightweight Rust crate designed to handle scenarios
//! where a variable may have one out of several possible values, or none at all.
//! It provides the `AnyOf` enum with variants to represent these possibilities.
//!
//! ## Features
//! - **Enum Variants**:
//!   - `Neither` to represent the absence of values.
//!   - `Either` to represent a single value (`Left` or `Right`).
//!   - `Both` to represent a combination of values (`Left` and `Right`).
//! - **Convenient Methods**: Create, transform, and check the state of `AnyOf` values
//!   easily with utility functions like `new`, `is_neither`, `is_both`, `map_left`, etc.
//! - **Extensible with Type Parameters**: Allows customization of the `Left` and `Right` types.
//!
//! ## Example Usage
//!
//! ```rust
//! use any_of::{AnyOf, Both, Either, LeftOrRight, Map};
//!
//! let neither: AnyOf<i32, &str> = AnyOf::Neither;
//! let neither: AnyOf<i32, &str> = AnyOf::new(None, None);
//! let left: AnyOf<i32, &str> = AnyOf::Either(Either::Left(42));
//! let left: AnyOf<i32, &str> = AnyOf::new(Some(42), None);
//! let both: AnyOf<i32, &str> = AnyOf::Both(Both { left: 42, right: "Hello" });
//! let both: AnyOf<i32, &str> = AnyOf::new(Some(42), Some("Hello"));
//!
//! assert!(neither.is_neither());
//! assert!(left.is_left());
//! assert!(both.is_both());
//!
//! assert!(neither.map_right(|r| r).is_neither());
//! assert!(left.map_right(|r| r).is_left());
//! assert!(left.map_left(|l| l).is_left());
//! assert!(both.map_left(|l| l).is_both());
//! ```
//!
//! ## Use Cases
//! - Representing optional or branching data in a concise manner.
//! - Handling dynamic states with variants like `Neither`, `Either`, and `Both`.
//! - Reducing boilerplate for mapping and transforming multiple optional values.
//!
//! ## Notable methods :
//! - [AnyOf::new]
//! - [AnyOf::combine]
//! - [AnyOf::unwrap_left] and [AnyOf::left]
//! - [AnyOf::unwrap_right] and [AnyOf::right]
//! - [AnyOf::unwrap_both] and [AnyOf::both_or_none]
//!
#![no_std]

pub mod concepts;

pub mod either;

pub mod both;

use core::ops::{BitAnd, BitOr, Not};

pub use crate::{
    any_of_x::{AnyOf16, AnyOf4, AnyOf8},
    both::Both,
    concepts::{Any, Couple, LeftOrRight, Map, Pair, Swap, Unwrap},
    either::Either,
};

/// Represents a type that can hold one of several variants: `Neither`, `Either` (with `Left` or `Right`),
/// or `Both` (containing both `Left` and `Right` values).
///
/// This enum allows for representing a flexible combination of values, or the absence of any values.
///
/// # Variants
///
/// - `Neither`: Represents the absence of both `Left` and `Right` values.
/// - `Either`: Represents a value that is either `Left` or `Right`.
/// - `Both`: Represents a combination of both `Left` and `Right` values.
///
/// # Type Parameters
///
/// - `L`: The type of the `Left` value.
/// - `R`: The type of the `Right` value. Defaults to the same type as `L` if not specified.
///
/// # Examples
///
/// ```rust
/// use any_of::{AnyOf, Either, Both, LeftOrRight, Map};
///
/// let neither: AnyOf<i32, &str> = AnyOf::Neither;
/// let neither: AnyOf<i32, &str> = AnyOf::new(None, None);
/// let left: AnyOf<i32, &str> = AnyOf::Either(Either::Left(42));
/// let left: AnyOf<i32, &str> = AnyOf::new(Some(42), None);
/// let both: AnyOf<i32, &str> = AnyOf::Both(Both { left: 42, right: "Hello" });
/// let both: AnyOf<i32, &str> = AnyOf::new(Some(42), Some("Hello"));
///
/// assert!(neither.is_neither());
/// assert!(left.is_left());
/// assert!(both.is_both());
///
/// assert!(neither.map_right(|r| r).is_neither());
/// assert!(left.map_right(|r| r).is_left());
/// assert!(left.map_left(|l| l).is_left());
/// assert!(both.map_left(|l| l).is_both());
///
/// ```
#[derive(Copy, Clone, Eq, PartialEq, Debug, Hash)]
pub enum AnyOf<L, R = L> {
    Neither,
    Either(Either<L, R>),
    Both(Both<L, R>),
}

impl<L, R> AnyOf<L, R> {
    /// Creates a new `AnyOf` instance based on the presence of `left` and `right` values.
    ///
    /// # Parameters
    ///
    /// - `left`: An `Option` containing the left value of type `L`, or `None` if absent.
    /// - `right`: An `Option` containing the right value of type `R`, or `None` if absent.
    ///
    /// # Returns
    ///
    /// - Returns `AnyOf::Neither` if both `left` and `right` are `None`.
    /// - Returns `AnyOf::Either(Either::Left)` if `left` has a value and `right` is `None`.
    /// - Returns `AnyOf::Either(Either::Right)` if `right` has a value and `left` is `None`.
    /// - Returns `AnyOf::Both` if both `left` and `right` have values.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::{AnyOf, Either, Both, LeftOrRight};
    ///
    /// let neither: AnyOf<i32, &str> = AnyOf::new(None, None);
    /// assert!(neither.is_neither());
    ///
    /// let left: AnyOf<i32, &str> = AnyOf::new(Some(42), None);
    /// assert!(left.is_left());
    ///
    /// let right: AnyOf<i32, &str> = AnyOf::new(None, Some("Hello"));
    /// assert!(right.is_right());
    ///
    /// let both: AnyOf<i32, &str> = AnyOf::new(Some(42), Some("Hello"));
    /// assert!(both.is_both());
    /// ```
    pub fn new(left: Option<L>, right: Option<R>) -> Self {
        match (left, right) {
            (None, None) => Self::Neither,
            (Some(l), None) => Self::Either(Either::Left(l)),
            (None, Some(r)) => Self::Either(Either::Right(r)),
            (Some(l), Some(r)) => Self::Both(Both { left: l, right: r }),
        }
    }

    /// Creates an `AnyOf::Neither` variant.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::AnyOf;
    ///
    /// let neither: AnyOf<i32, &str> = AnyOf::new_neither();
    /// assert!(neither.is_neither());
    /// ```
    pub fn new_neither() -> Self {
        Self::new(None, None)
    }

    /// Creates an `AnyOf::Either` variant containing a `Left` value.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::{AnyOf, LeftOrRight};
    ///
    /// let left: AnyOf<i32, &str> = AnyOf::new_left(42);
    /// assert!(left.is_left());
    /// ```
    pub fn new_left(left: L) -> Self {
        Self::new(Some(left), None)
    }

    /// Creates an `AnyOf::Either` variant containing a `Right` value.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::{AnyOf, LeftOrRight};
    ///
    /// let right: AnyOf<i32, &str> = AnyOf::new_right("Hello");
    /// assert!(right.is_right());
    /// ```
    pub fn new_right(right: R) -> Self {
        Self::new(None, Some(right))
    }

    /// Creates an `AnyOf::Both` variant containing both a `Left` and `Right` value.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::AnyOf;
    ///
    /// let both: AnyOf<i32, &str> = AnyOf::new_both(42, "Hello");
    /// assert!(both.is_both());
    /// ```
    pub fn new_both(l: L, r: R) -> Self {
        Self::new(Some(l), Some(r))
    }

    /// Creates an `AnyOf::Both` variant from a `Both` struct.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::{AnyOf, Both};
    ///
    /// let both_struct = Both { left: 42, right: "Hello" };
    /// let both = AnyOf::from_both(both_struct);
    /// assert!(both.is_both());
    /// ```
    pub fn from_both(both: Both<L, R>) -> Self {
        Self::new(Some(both.left), Some(both.right))
    }

    /// Creates a new `AnyOf` instance based on the presence of `left` and `right` values.
    ///
    /// See [Self::new].
    pub fn from_any(any: Any<L, R>) -> Self {
        Self::new(any.0, any.1)
    }

    /// Creates an `AnyOf` variant from an `Either` struct.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::{AnyOf, Either, LeftOrRight};
    ///
    /// let either: Either<i32, ()> = Either::Left(42);
    /// let any_of: AnyOf<i32, ()> = AnyOf::from_either(either);
    /// assert!(any_of.is_left());
    /// ```
    pub fn from_either(either: Either<L, R>) -> Self {
        Self::Either(either)
    }

    /// Converts the `AnyOf` variant to a `Both` struct.
    ///
    /// # Panics
    ///
    /// This function will panic if `self` is not an `AnyOf::Both` variant.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::AnyOf;
    ///
    /// let both = AnyOf::new_both(42, "Hello").into_both();
    /// assert_eq!(both.left, 42);
    /// assert_eq!(both.right, "Hello");
    /// ```
    pub fn into_both(self) -> Both<L, R> {
        match self {
            AnyOf::Both(b) => b,
            _ => panic!("Can only convert Either::Both to Both"),
        }
    }

    /// Converts the `AnyOf` variant to an `Either` struct.
    ///
    /// # Panics
    ///
    /// This function will panic if `self` is not an `AnyOf::Either` variant.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::{AnyOf, Either};
    ///
    /// let either: Either<i32, ()> = AnyOf::new_left(42).into_either();
    /// assert_eq!(either, Either::Left(42));
    /// ```
    pub fn into_either(self) -> Either<L, R> {
        if let AnyOf::Either(e) = self {
            e
        } else {
            panic!("Can only convert Either::Either to Either");
        }
    }

    /// Converts the current `AnyOf` variant into a pair of options containing `Either` variants.
    ///
    /// # Returns
    ///
    /// - `(Some(Left), None)` for `AnyOf::Either(Either::Left)`.
    /// - `(None, Some(Right))` for `AnyOf::Either(Either::Right)`.
    /// - `(Some(Left), Some(Right))` for `AnyOf::Both`.
    /// - `(None, None)` for `AnyOf::Neither`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::{AnyOf, Either};
    ///
    /// let any_of = AnyOf::new_both(42, "Hello");
    /// let (left, right) = any_of.to_either_pair();
    /// assert_eq!(left, Some(Either::Left(42)));
    /// assert_eq!(right, Some(Either::Right("Hello")));
    /// ```
    pub fn to_either_pair(&self) -> Pair<Option<Either<L, R>>>
    where
        L: Clone,
        R: Clone,
    {
        let both = self.any();
        let left = both.0.map(|l| Either::Left(l.clone()));
        let right = both.1.map(|r| Either::Right(r.clone()));
        (left, right)
    }

    /// True if [Either::Left] or [AnyOf::Both].
    pub fn has_left(&self) -> bool {
        matches!(self, Self::Either(Either::Left(_)) | Self::Both(_))
    }
    
    /// True if [Either::Right] or [AnyOf::Both].0
    pub fn has_right(&self) -> bool {
        matches!(self, Self::Either(Either::Right(_)) | Self::Both(_))
    }
    
    /// True if not [AnyOf::Neither].
    pub fn is_any(&self) -> bool {
        matches!(
            self,
            Self::Either(Either::Left(_)) | Self::Either(Either::Right(_)) | Self::Both(_)
        )
    }

    // todo(2.0.0) : remove
    /// True if [AnyOf::Either].
    #[deprecated(since = "1.3.1", note = "Use `is_either` instead. Will be removed in 2.0.0.")]
    pub fn is_one(&self) -> bool {
        self.is_either()
    }

    /// True if [AnyOf::Either].
    pub fn is_either(&self) -> bool {
        matches!(self, Self::Either(_))
    }
    
    /// True if [AnyOf::Both]
    pub fn is_both(&self) -> bool {
        matches!(self, Self::Both(_))
    }
    
    /// True if [AnyOf::Neither]
    pub fn is_neither(&self) -> bool {
        matches!(self, Self::Neither)
    }
    
    /// True if not [AnyOf::Either]
    pub fn is_neither_or_both(&self) -> bool {
        matches!(self, Self::Neither | Self::Both(_))
    }

    /// Returns `Some((&L, &R))` if `self.is_both()` is true, or `None`.
    pub fn both_or_none(&self) -> Option<Couple<&L, &R>> {
        Some((self.left()?, self.right()?))
    }

    /// Returns both values if present, or computes them with the provided function.
    pub fn both_or_else(self, f: impl FnOnce() -> Both<L, R>) -> Both<L, R> {
        match self {
            Self::Neither => f(),
            Self::Either(Either::Left(l)) => Both::new(l, f().right),
            Self::Either(Either::Right(r)) => Both::new(f().left, r),
            Self::Both(b) => b,
        }
    }

    /// Returns both values if present, or the provided default values.
    pub fn both_or(self, other: Both<L, R>) -> Both<L, R> {
        self.both_or_else(|| other)
    }

    /// Unwraps and returns both values, panicking if not available.
    pub fn unwrap_both(self) -> Both<L, R> {
        self.both_or_else(|| panic!("Can only unwrap both of Either::Both"))
    }

    /// Filters to keep only the left value if present, otherwise returns Self::Neither.
    pub fn filter_left(self) -> Self {
        match self {
            Self::Neither => Self::Neither,
            Self::Either(Either::Left(l)) => Self::Either(Either::Left(l)),
            Self::Either(Either::Right(_)) => Self::Neither,
            Self::Both(Both { left: l, .. }) => Self::Either(Either::Left(l)),
        }
    }

    /// Filters to keep only the right value if present, otherwise returns Self::Neither.
    pub fn filter_right(self) -> Self {
        match self {
            Self::Neither => Self::Neither,
            Self::Either(Either::Left(_)) => Self::Neither,
            Self::Either(Either::Right(r)) => Self::Either(Either::Right(r)),
            Self::Both(Both { right: r, .. }) => Self::Either(Either::Right(r)),
        }
    }

    /// Adds or replaces the right value, keeping or constructing the instance accordingly.
    pub fn with_right(self, right: R) -> Self {
        match self {
            Self::Neither => Self::Either(Either::Right(right)),
            Self::Either(Either::Left(l)) => Self::Both(Both { left: l, right }),
            Self::Either(Either::Right(_)) => Self::Either(Either::Right(right)),
            Self::Both(Both { left: l, .. }) => Self::Both(Both { left: l, right }),
        }
    }

    /// Adds or replaces the left value, keeping or constructing the instance accordingly.
    pub fn with_left(self, left: L) -> Self {
        match self {
            Self::Neither => Self::Either(Either::Left(left)),
            Self::Either(Either::Left(_)) => Self::Either(Either::Left(left)),
            Self::Either(Either::Right(r)) => Self::Both(Both { left, right: r }),
            Self::Both(Both { right: r, .. }) => Self::Both(Both { left, right: r }),
        }
    }

    /// Combines (`&` operator) two `Either` values into a single one.
    ///
    /// ## General rules
    ///
    /// * `Neither` is always substituted by the other operand,
    /// * `Both` :
    ///     * as left operand : substitutes the other operand,
    ///     * as right operand : completes the other operand,
    /// * `Left` or `Right` :
    ///     * `L & R` or `R & L` combines to an instance of `Both`,
    ///     * `L & l` or `r & R` selects the operand placed on the correct side of the operator :
    ///         * left**Left** + right**Left** = left**Left**
    ///         * left**Right** + right**Right** = right**Right**
    ///
    /// ## All cases
    ///
    /// * Neither cases :
    ///     * Neither & Neither = Neither
    ///     * Neither & **other** = other
    ///     * **self** & Neither = self
    /// * Trivial cases :
    ///     * **Left(x)** & Left(y) = Left(x)
    ///     * Right(x) & **Right(y)** = Right(y)
    ///     * **Both(x, y)** & other = Both(x, y)
    /// * Combined cases :
    ///     * Left(x) & Right(y) = Both(x, y)
    ///     * Right(x) & Left(y) = Both(y, x)
    ///     * Left(x) & Both(_, y) = Both(x, y)
    ///     * Right(x) & Both(y, _) = Both(y, x)
    pub fn combine(self, other: Self) -> Self {
        match self {
            Self::Neither => other,
            Self::Either(Either::Left(l)) => match other {
                AnyOf::Neither => Self::Either(Either::Left(l)),
                AnyOf::Either(Either::Left(_)) => Self::Either(Either::Left(l)),
                AnyOf::Either(Either::Right(r)) => Self::Both(Both { left: l, right: r }),
                AnyOf::Both(Both { right: r, .. }) => Self::Both(Both { left: l, right: r }),
            },
            Self::Either(Either::Right(r)) => match other {
                AnyOf::Neither => Self::Either(Either::Right(r)),
                AnyOf::Either(Either::Left(l)) => Self::Both(Both { left: l, right: r }),
                AnyOf::Either(Either::Right(r2)) => Self::Either(Either::Right(r2)),
                AnyOf::Both(Both { left: l, .. }) => Self::Both(Both { left: l, right: r }),
            },
            Self::Both(b) => Self::Both(b),
        }
    }

    /// Filters (`|` operator) the current `AnyOf` instance using another `AnyOf` instance.
    ///
    /// ## General rules
    ///
    /// The filtering behavior depends on the specific variants of `self` and `other`:
    ///
    /// * `other == Neither` filters nothing (self is returned),
    /// * `other == Both` filters all (`Neither` is returned),
    /// * `Left` and `Right` as `other` filters the corresponding side of `self`.
    ///
    /// ## All cases
    ///
    /// - **Neither cases**:
    ///     * `Neither | other = Neither`
    ///     * `Left(x) | Left(y) = Neither`
    ///     * `Right(x) | Right(y) = Neither`
    ///     * `other | Both(x, y) = Neither`
    /// - **Trivial case**:
    ///     * `other | Neither = other`
    /// - **Filtered cases**:
    ///     * `Left(x) | Right(y) = Left(x)`
    ///     * `Right(x) | Left(y) = Right(x)`
    ///     * `Both(x, y) | Right(y) = Left(x)`
    ///     * `Both(x, y) | Left(y) = Right(y)`
    ///
    /// # Examples
    ///
    /// ```rust
    /// use any_of::{AnyOf, Both};
    /// use any_of::either::Either;
    ///
    /// let both = AnyOf::Both(Both { left: 5, right: 10 });
    /// let left_only = AnyOf::Either(Either::Left(5));
    /// let right_only = AnyOf::Either(Either::Right(10));
    /// let neither: AnyOf<i32, i32> = AnyOf::Neither;
    ///
    /// // Filtering Both with Right results in Left
    /// assert_eq!(both | right_only, left_only);
    ///
    /// // Filtering Both with Left results in Right
    /// assert_eq!(both | left_only, right_only);
    ///
    /// // Filtering with Neither doesn't affect the original value
    /// assert_eq!(both | neither, both);
    /// assert_eq!(left_only | neither, left_only);
    /// assert_eq!(right_only | neither, right_only);
    ///
    /// // Filtering with Both always results in Neither
    /// assert_eq!(both | both, neither);
    /// assert_eq!(left_only | both, neither);
    /// assert_eq!(right_only | both, neither);
    /// ```
    pub fn filter(self, other: Self) -> Self {
        match other {
            AnyOf::Neither => self,
            AnyOf::Either(Either::Left(_)) => match self {
                AnyOf::Either(Either::Left(_)) => AnyOf::Neither,
                AnyOf::Either(Either::Right(r)) => AnyOf::Either(Either::Right(r)),
                AnyOf::Both(Both { right: r, .. }) => AnyOf::Either(Either::Right(r)),
                _ => self,
            },
            AnyOf::Either(Either::Right(_)) => match self {
                AnyOf::Either(Either::Left(l)) => AnyOf::Either(Either::Left(l)),
                AnyOf::Either(Either::Right(_)) => AnyOf::Neither,
                AnyOf::Both(Both { left: l, .. }) => AnyOf::Either(Either::Left(l)),
                _ => self,
            },
            AnyOf::Both(_) => AnyOf::Neither,
        }
    }
}

impl<L, R> BitAnd for AnyOf<L, R> {
    type Output = Self;

    /// See : [Self::combine].
    fn bitand(self, rhs: Self) -> Self::Output {
        self.combine(rhs)
    }
}

impl<L, R> BitOr for AnyOf<L, R> {
    type Output = Self;

    /// See : [Self::filter].
    fn bitor(self, rhs: Self) -> Self::Output {
        self.filter(rhs)
    }
}

impl<L, R> Not for AnyOf<L, R> {
    type Output = AnyOf<R, L>;

    /// See : [Self::swap].
    fn not(self) -> Self::Output {
        self.swap()
    }
}

impl<L, R> LeftOrRight<L, R> for AnyOf<L, R> {
    /// Returns `Some(&L)` if `self.has_left()` is true, or `None`.
    fn left(&self) -> Option<&L> {
        match self {
            Self::Neither => None,
            Self::Either(e) => e.left(),
            Self::Both(b) => b.left(),
        }
    }

    /// Returns `Some(&R)` if `self.has_right()` is true, or `None`.
    fn right(&self) -> Option<&R> {
        match self {
            Self::Neither => None,
            Self::Either(e) => e.right(),
            Self::Both(b) => b.right(),
        }
    }
}

impl<L, R> Swap<L, R> for AnyOf<L, R> {
    type Output = AnyOf<R, L>;

    /// Swaps (! operator) the left and right components, creating a new `AnyOf` with reversed types.
    ///
    /// # Returns
    ///
    /// A new `AnyOf<R, L>` instance where the left and right components have been swapped.
    ///
    /// - If `self` is `Neither`, the result will also be `Neither`.
    /// - If `self` is an `Either::Left`, the result will contain the value as an `Either::Right`.
    /// - If `self` is an `Either::Right`, the result will contain the value as an `Either::Left`.
    /// - If `self` is a `Both`, the left and right values are swapped in the result.
    fn swap(self) -> Self::Output {
        match self {
            Self::Neither => AnyOf::<R, L>::Neither,
            Self::Either(e) => AnyOf::<R, L>::Either(e.swap()),
            Self::Both(b) => AnyOf::<R, L>::Both(b.swap()),
        }
    }
}

impl<L, R> Map<L, R> for AnyOf<L, R> {
    type Output<L2, R2> = AnyOf<L2, R2>;

    /// Transforms the `Left` and `Right` value using separate functions, depending
    /// on the variant.
    ///
    /// ## Arguments
    ///
    /// * `fl` - A function to transform the left value.
    /// * `fr` - A function to transform the right value.
    ///
    /// ## Returns
    ///
    /// An `AnyOf` where the `Left` and `Right` value has been transformed
    /// by the corresponding function. If self is `Neither`, this function returns `Neither`.
    fn map<FL, FR, L2, R2>(self, fl: FL, fr: FR) -> Self::Output<L2, R2>
    where
        FL: FnOnce(L) -> L2,
        FR: FnOnce(R) -> R2,
    {
        match self {
            Self::Neither => AnyOf::<L2, R2>::Neither,
            Self::Either(e) => AnyOf::<L2, R2>::Either(e.map(fl, fr)),
            Self::Both(b) => AnyOf::<L2, R2>::Both(b.map(fl, fr)),
        }
    }
}

impl<L, R> Unwrap<L, R> for AnyOf<L, R> {
    /// Returns the left value if present, or computes it with the provided function.
    fn left_or_else(self, f: impl FnOnce() -> L) -> L {
        match self {
            Self::Neither => f(),
            Self::Either(Either::Left(l)) => l,
            Self::Either(Either::Right(_)) => f(),
            Self::Both(Both { left: l, .. }) => l,
        }
    }

    /// Returns the right value if present, or computes it with the provided function.
    fn right_or_else(self, f: impl FnOnce() -> R) -> R {
        match self {
            Self::Neither => f(),
            Self::Either(Either::Left(_)) => f(),
            Self::Either(Either::Right(r)) => r,
            Self::Both(Both { right: r, .. }) => r,
        }
    }
}

pub mod any_of_x;

#[cfg(test)]
mod tests;