value_extra/

lib.rs

//! # value-extra
//!
//! A tri-state `Patch<T>` type for partial update semantics.
//!
//! ## The Problem
//!
//! When handling partial updates (PATCH requests, config merging, etc.),
//! `Option<T>` conflates two distinct states:
//!
//! - **Field is absent** → don't touch the existing value
//! - **Field is explicitly null** → clear/reset the value
//!
//! ## The Solution
//!
//! `Patch<T>` provides three states:
//!
//! - `Patch::Some(T)` — set the field to this value
//! - [`Patch::Empty`] — field was absent, leave unchanged
//! - [`Patch::None`] — field was explicitly null, clear it
//!
//! ## Quick Start
//!
//! ```
//! use value_extra::Patch;
//!
//! fn apply_name_patch(current: &mut Option<String>, patch: Patch<String>) {
//!     match patch {
//!         Patch::Some(new) => *current = Some(new),
//!         Patch::None => *current = None,
//!         Patch::Empty => {}
//!     }
//! }
//! ```
//!
//! ## Serde Usage
//!
//! With the `serde` feature enabled:
//!
//! ```ignore
//! #[derive(Deserialize, Serialize)]
//! struct UserPatch {
//!     #[serde(default, skip_serializing_if = "Patch::is_empty")]
//!     name: Patch<String>,
//! }
//! ```
//!
//! | JSON Input | Patch State | Meaning |
//! |------------|-------------|---------|
//! | `{ "name": "Alice" }` | `Patch::Some("Alice")` | Set to value |
//! | `{ "name": null }` | `Patch::None` | Explicitly clear |
//! | `{ }` | `Patch::Empty` | Leave unchanged |

#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg(not(feature = "std"))]
extern crate alloc;

use core::ops::Deref;

/// A tri-state type for partial update semantics.
///
/// `Patch<T>` distinguishes between three states:
///
/// - `Patch::Some(T)` — a value is present
/// - [`Patch::Empty`] — no value was provided (field absent)
/// - [`Patch::None`] — value was explicitly set to null
///
/// This is particularly useful for PATCH/UPDATE operations where you need
/// to distinguish between "don't change this field" and "clear this field".
///
/// # Examples
///
/// ```
/// use value_extra::Patch;
///
/// let some = Patch::Some(42);
/// let empty: Patch<i32> = Patch::Empty;
/// let none: Patch<i32> = Patch::None;
///
/// assert!(some.is_some());
/// assert!(empty.is_empty());
/// assert!(none.is_none());
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[must_use = "this `Patch` may contain a value that should be used"]
pub enum Patch<T> {
    /// A value is present.
    Some(T),
    /// No value was provided (field absent).
    Empty,
    /// Value was explicitly set to null.
    None,
}

impl<T: Copy> Copy for Patch<T> {}

impl<T> Patch<T> {
    /// Returns `true` if the patch contains a value.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert!(Patch::Some(42).is_some());
    /// assert!(!Patch::<i32>::Empty.is_some());
    /// assert!(!Patch::<i32>::None.is_some());
    /// ```
    #[inline]
    pub fn is_some(&self) -> bool {
        matches!(self, Patch::Some(_))
    }

    /// Returns `true` if the patch is empty (field absent).
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert!(Patch::<i32>::Empty.is_empty());
    /// assert!(!Patch::Some(42).is_empty());
    /// assert!(!Patch::<i32>::None.is_empty());
    /// ```
    #[inline]
    pub fn is_empty(&self) -> bool {
        matches!(self, Patch::Empty)
    }

    /// Returns `true` if the patch is explicitly null.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert!(Patch::<i32>::None.is_none());
    /// assert!(!Patch::Some(42).is_none());
    /// assert!(!Patch::<i32>::Empty.is_none());
    /// ```
    #[inline]
    pub fn is_none(&self) -> bool {
        matches!(self, Patch::None)
    }

    /// Alias for [`is_none`](Self::is_none). Returns `true` if explicitly null.
    ///
    /// This alias may be clearer in JSON/API contexts where "null" is the term used.
    #[inline]
    pub fn is_null(&self) -> bool {
        self.is_none()
    }

    /// Returns `true` if the patch contains the given value.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert!(Patch::Some(42).contains(&42));
    /// assert!(!Patch::Some(42).contains(&0));
    /// assert!(!Patch::<i32>::Empty.contains(&42));
    /// ```
    #[inline]
    pub fn contains<U>(&self, x: &U) -> bool
    where
        T: PartialEq<U>,
    {
        matches!(self, Patch::Some(v) if v == x)
    }
}

impl<T> Patch<T> {
    /// Converts from `&Patch<T>` to `Patch<&T>`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let patch = Patch::Some(String::from("hello"));
    /// assert_eq!(patch.as_ref(), Patch::Some(&String::from("hello")));
    /// ```
    #[inline]
    pub fn as_ref(&self) -> Patch<&T> {
        match *self {
            Patch::Some(ref x) => Patch::Some(x),
            Patch::Empty => Patch::Empty,
            Patch::None => Patch::None,
        }
    }

    /// Converts from `&mut Patch<T>` to `Patch<&mut T>`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let mut patch = Patch::Some(42);
    /// if let Patch::Some(v) = patch.as_mut() {
    ///     *v = 100;
    /// }
    /// assert_eq!(patch, Patch::Some(100));
    /// ```
    #[inline]
    pub fn as_mut(&mut self) -> Patch<&mut T> {
        match *self {
            Patch::Some(ref mut x) => Patch::Some(x),
            Patch::Empty => Patch::Empty,
            Patch::None => Patch::None,
        }
    }
}

impl<T: Deref> Patch<T> {
    /// Converts from `&Patch<T>` to `Patch<&T::Target>`.
    ///
    /// Useful for converting `Patch<String>` to `Patch<&str>`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let patch = Patch::Some(String::from("hello"));
    /// assert_eq!(patch.as_deref(), Patch::Some("hello"));
    /// ```
    #[inline]
    pub fn as_deref(&self) -> Patch<&<T as Deref>::Target> {
        self.as_ref().map(|t| t.deref())
    }
}

impl<T> Patch<T> {
    /// Maps a `Patch<T>` to `Patch<U>` by applying a function to the contained value.
    ///
    /// `Empty` and `None` are propagated unchanged.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let patch = Patch::Some(21);
    /// assert_eq!(patch.map(|x| x * 2), Patch::Some(42));
    ///
    /// let empty: Patch<i32> = Patch::Empty;
    /// assert_eq!(empty.map(|x| x * 2), Patch::Empty);
    /// ```
    #[inline]
    pub fn map<U, F: FnOnce(T) -> U>(self, f: F) -> Patch<U> {
        match self {
            Patch::Some(x) => Patch::Some(f(x)),
            Patch::Empty => Patch::Empty,
            Patch::None => Patch::None,
        }
    }

    /// Returns the provided default if `Empty` or `None`, otherwise applies `f` to the value.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(21).map_or(0, |x| x * 2), 42);
    /// assert_eq!(Patch::<i32>::Empty.map_or(0, |x| x * 2), 0);
    /// assert_eq!(Patch::<i32>::None.map_or(0, |x| x * 2), 0);
    /// ```
    #[inline]
    pub fn map_or<U, F: FnOnce(T) -> U>(self, default: U, f: F) -> U {
        match self {
            Patch::Some(x) => f(x),
            Patch::Empty | Patch::None => default,
        }
    }

    /// Computes a default from a closure if `Empty` or `None`, otherwise applies `f`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let result = Patch::Some(21).map_or_else(|| 0, |x| x * 2);
    /// assert_eq!(result, 42);
    /// ```
    #[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 {
            Patch::Some(x) => f(x),
            Patch::Empty | Patch::None => default(),
        }
    }

    /// Calls `f` with the value if `Some`, returning the result.
    ///
    /// `Empty` and `None` are propagated unchanged.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// fn parse_positive(s: String) -> Patch<u32> {
    ///     s.parse::<u32>().ok().filter(|&n| n > 0).into()
    /// }
    ///
    /// assert_eq!(Patch::Some("42".to_string()).and_then(parse_positive), Patch::Some(42));
    /// assert_eq!(Patch::Some("0".to_string()).and_then(parse_positive), Patch::None);
    /// assert_eq!(Patch::<String>::Empty.and_then(parse_positive), Patch::Empty);
    /// ```
    #[inline]
    pub fn and_then<U, F>(self, f: F) -> Patch<U>
    where
        F: FnOnce(T) -> Patch<U>,
    {
        match self {
            Patch::Some(x) => f(x),
            Patch::Empty => Patch::Empty,
            Patch::None => Patch::None,
        }
    }

    /// Returns `Patch::None` if the predicate returns `false`, otherwise returns `self`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(42).filter(|&x| x > 0), Patch::Some(42));
    /// assert_eq!(Patch::Some(-1).filter(|&x| x > 0), Patch::None);
    /// assert_eq!(Patch::<i32>::Empty.filter(|&x| x > 0), Patch::Empty);
    /// ```
    #[inline]
    pub fn filter<P>(self, predicate: P) -> Patch<T>
    where
        P: FnOnce(&T) -> bool,
    {
        match self {
            Patch::Some(x) if predicate(&x) => Patch::Some(x),
            Patch::Some(_) => Patch::None,
            Patch::Empty => Patch::Empty,
            Patch::None => Patch::None,
        }
    }
}

impl<T> Patch<T> {
    /// Returns the contained value, panicking with a custom message if not `Some`.
    ///
    /// # Panics
    ///
    /// Panics if the patch is `Empty` or `None`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(42).expect("should have value"), 42);
    /// ```
    #[inline]
    pub fn expect(self, msg: &str) -> T {
        match self {
            Patch::Some(x) => x,
            Patch::Empty => panic!("{msg}"),
            Patch::None => panic!("{msg}"),
        }
    }

    /// Returns the contained value, panicking if not `Some`.
    ///
    /// # Panics
    ///
    /// Panics if the patch is `Empty` or `None`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(42).unwrap(), 42);
    /// ```
    #[inline]
    pub fn unwrap(self) -> T {
        match self {
            Patch::Some(x) => x,
            Patch::Empty => panic!("called `Patch::unwrap()` on an `Empty` value"),
            Patch::None => panic!("called `Patch::unwrap()` on a `None` value"),
        }
    }

    /// Returns the contained value or a default.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(42).unwrap_or(0), 42);
    /// assert_eq!(Patch::<i32>::Empty.unwrap_or(0), 0);
    /// assert_eq!(Patch::<i32>::None.unwrap_or(0), 0);
    /// ```
    #[inline]
    pub fn unwrap_or(self, default: T) -> T {
        match self {
            Patch::Some(x) => x,
            Patch::Empty | Patch::None => default,
        }
    }

    /// Returns the contained value or computes it from a closure.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(42).unwrap_or_else(|| 0), 42);
    /// assert_eq!(Patch::<i32>::Empty.unwrap_or_else(|| 100), 100);
    /// ```
    #[inline]
    pub fn unwrap_or_else<F>(self, f: F) -> T
    where
        F: FnOnce() -> T,
    {
        match self {
            Patch::Some(x) => x,
            Patch::Empty | Patch::None => f(),
        }
    }
}

impl<T: Default> Patch<T> {
    /// Returns the contained value or the default for `T`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(42).unwrap_or_default(), 42);
    /// assert_eq!(Patch::<i32>::Empty.unwrap_or_default(), 0);
    /// ```
    #[inline]
    pub fn unwrap_or_default(self) -> T {
        self.unwrap_or(T::default())
    }
}

impl<T> Patch<T> {
    /// Returns `self` if it contains a value, otherwise returns `other`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(1).or(Patch::Some(2)), Patch::Some(1));
    /// assert_eq!(Patch::<i32>::Empty.or(Patch::Some(2)), Patch::Some(2));
    /// assert_eq!(Patch::<i32>::None.or(Patch::Some(2)), Patch::Some(2));
    /// ```
    #[inline]
    pub fn or(self, other: Patch<T>) -> Patch<T> {
        match self {
            Patch::Some(_) => self,
            Patch::Empty | Patch::None => other,
        }
    }

    /// Returns `self` if it contains a value, otherwise calls `f`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(1).or_else(|| Patch::Some(2)), Patch::Some(1));
    /// assert_eq!(Patch::<i32>::Empty.or_else(|| Patch::Some(2)), Patch::Some(2));
    /// ```
    #[inline]
    pub fn or_else<F>(self, f: F) -> Patch<T>
    where
        F: FnOnce() -> Patch<T>,
    {
        match self {
            Patch::Some(_) => self,
            Patch::Empty | Patch::None => f(),
        }
    }

    /// Returns `Some` if exactly one of `self` or `other` is `Some`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(1).xor(Patch::<i32>::Empty), Patch::Some(1));
    /// assert_eq!(Patch::<i32>::None.xor(Patch::Some(2)), Patch::Some(2));
    /// assert_eq!(Patch::Some(1).xor(Patch::Some(2)), Patch::None);
    /// assert_eq!(Patch::<i32>::Empty.xor(Patch::<i32>::None), Patch::Empty);
    /// assert_eq!(Patch::<i32>::None.xor(Patch::<i32>::None), Patch::None);
    /// ```
    #[inline]
    pub fn xor(self, other: Patch<T>) -> Patch<T> {
        match (self, other) {
            (Patch::Some(a), Patch::Empty | Patch::None) => Patch::Some(a),
            (Patch::Empty | Patch::None, Patch::Some(b)) => Patch::Some(b),
            (Patch::Empty, Patch::None) | (Patch::None, Patch::Empty) => Patch::Empty,
            _ => Patch::None,
        }
    }

    /// Zips `self` with another `Patch`.
    ///
    /// Returns `Some((a, b))` if both are `Some`, otherwise propagates `Empty` or `None`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(1).zip(Patch::Some("a")), Patch::Some((1, "a")));
    /// assert_eq!(Patch::Some(1).zip(Patch::<&str>::Empty), Patch::Empty);
    /// assert_eq!(Patch::<i32>::None.zip(Patch::Some("a")), Patch::None);
    /// ```
    #[inline]
    pub fn zip<U>(self, other: Patch<U>) -> Patch<(T, U)> {
        match (self, other) {
            (Patch::Some(a), Patch::Some(b)) => Patch::Some((a, b)),
            (Patch::Empty, _) | (_, Patch::Empty) => Patch::Empty,
            _ => Patch::None,
        }
    }

    /// Zips `self` with another `Patch` using a function.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(1).zip_with(Patch::Some(2), |a, b| a + b), Patch::Some(3));
    /// ```
    #[inline]
    pub fn zip_with<U, R, F>(self, other: Patch<U>, f: F) -> Patch<R>
    where
        F: FnOnce(T, U) -> R,
    {
        self.zip(other).map(|(a, b)| f(a, b))
    }
}

impl<T> Patch<T> {
    /// Inserts a value, returning a mutable reference to it.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let mut patch = Patch::<i32>::Empty;
    /// let v = patch.insert(42);
    /// assert_eq!(*v, 42);
    /// ```
    #[inline]
    pub fn insert(&mut self, value: T) -> &mut T {
        *self = Patch::Some(value);
        match self {
            Patch::Some(v) => v,
            _ => unreachable!(),
        }
    }

    /// Inserts a value if `Empty` or `None`, returning a mutable reference.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let mut patch = Patch::<i32>::Empty;
    /// assert_eq!(*patch.get_or_insert(42), 42);
    ///
    /// let mut patch = Patch::Some(1);
    /// assert_eq!(*patch.get_or_insert(42), 1);
    /// ```
    #[inline]
    pub fn get_or_insert(&mut self, value: T) -> &mut T {
        if !self.is_some() {
            *self = Patch::Some(value);
        }
        match self {
            Patch::Some(v) => v,
            _ => unreachable!(),
        }
    }

    /// Inserts a value computed from a closure if `Empty` or `None`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let mut patch = Patch::<i32>::Empty;
    /// assert_eq!(*patch.get_or_insert_with(|| 42), 42);
    /// ```
    #[inline]
    pub fn get_or_insert_with<F>(&mut self, f: F) -> &mut T
    where
        F: FnOnce() -> T,
    {
        if !self.is_some() {
            *self = Patch::Some(f());
        }
        match self {
            Patch::Some(v) => v,
            _ => unreachable!(),
        }
    }

    /// Takes the value out, leaving `Empty` in its place.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let mut patch = Patch::Some(42);
    /// let taken = patch.take();
    /// assert_eq!(taken, Patch::Some(42));
    /// assert_eq!(patch, Patch::Empty);
    /// ```
    #[inline]
    pub fn take(&mut self) -> Patch<T> {
        core::mem::replace(self, Patch::Empty)
    }

    /// Replaces the value, returning the old one.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let mut patch = Patch::Some(42);
    /// let old = patch.replace(100);
    /// assert_eq!(old, Patch::Some(42));
    /// assert_eq!(patch, Patch::Some(100));
    /// ```
    #[inline]
    pub fn replace(&mut self, value: T) -> Patch<T> {
        core::mem::replace(self, Patch::Some(value))
    }
}

impl<T: Default> Patch<T> {
    /// Inserts the default value if `Empty` or `None`, returning a mutable reference.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let mut patch = Patch::<i32>::Empty;
    /// assert_eq!(*patch.get_or_insert_default(), 0);
    /// ```
    #[inline]
    pub fn get_or_insert_default(&mut self) -> &mut T {
        self.get_or_insert_with(T::default)
    }
}

impl<T: Clone> Patch<&T> {
    /// Maps a `Patch<&T>` to a `Patch<T>` by cloning.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let value = String::from("hello");
    /// let patch = Patch::Some(&value);
    /// assert_eq!(patch.cloned(), Patch::Some(String::from("hello")));
    /// ```
    #[inline]
    pub fn cloned(self) -> Patch<T> {
        self.map(|t| t.clone())
    }
}

impl<T: Copy> Patch<&T> {
    /// Maps a `Patch<&T>` to a `Patch<T>` by copying.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// let value = 42;
    /// let patch = Patch::Some(&value);
    /// assert_eq!(patch.copied(), Patch::Some(42));
    /// ```
    #[inline]
    pub fn copied(self) -> Patch<T> {
        self.map(|&t| t)
    }
}

impl<T> Patch<T> {
    /// Converts the patch to an `Option`, treating `Empty` and `None` as `Option::None`.
    ///
    /// # Examples
    ///
    /// ```
    /// use value_extra::Patch;
    ///
    /// assert_eq!(Patch::Some(42).into_option(), Some(42));
    /// assert_eq!(Patch::<i32>::Empty.into_option(), None);
    /// assert_eq!(Patch::<i32>::None.into_option(), None);
    /// ```
    #[inline]
    pub fn into_option(self) -> Option<T> {
        match self {
            Patch::Some(v) => Some(v),
            Patch::Empty | Patch::None => None,
        }
    }
}

impl<T> Default for Patch<T> {
    /// Returns `Patch::Empty`.
    #[inline]
    fn default() -> Patch<T> {
        Patch::Empty
    }
}

impl<T> From<T> for Patch<T> {
    /// Creates a `Patch::Some` from a value.
    #[inline]
    fn from(value: T) -> Patch<T> {
        Patch::Some(value)
    }
}

impl<T> From<Option<T>> for Patch<T> {
    /// Converts `Option<T>` to `Patch<T>`.
    ///
    /// - `Some(v)` → `Patch::Some(v)`
    /// - `None` → `Patch::None`
    #[inline]
    fn from(opt: Option<T>) -> Patch<T> {
        match opt {
            Some(v) => Patch::Some(v),
            None => Patch::None,
        }
    }
}

impl<T> From<Patch<T>> for Option<T> {
    /// Converts `Patch<T>` to `Option<T>`.
    ///
    /// Both `Empty` and `None` become `Option::None`.
    #[inline]
    fn from(patch: Patch<T>) -> Option<T> {
        patch.into_option()
    }
}

impl<T> From<Option<Option<T>>> for Patch<T> {
    /// Converts `Option<Option<T>>` to `Patch<T>`.
    ///
    /// This is the canonical representation for serde:
    /// - `None` → `Patch::Empty` (field absent)
    /// - `Some(None)` → `Patch::None` (explicitly null)
    /// - `Some(Some(v))` → `Patch::Some(v)`
    #[inline]
    fn from(value: Option<Option<T>>) -> Patch<T> {
        match value {
            None => Patch::Empty,
            Some(None) => Patch::None,
            Some(Some(v)) => Patch::Some(v),
        }
    }
}

impl<T> From<Patch<T>> for Option<Option<T>> {
    /// Converts `Patch<T>` to `Option<Option<T>>`.
    ///
    /// - `Patch::Empty` → `None`
    /// - `Patch::None` → `Some(None)`
    /// - `Patch::Some(v)` → `Some(Some(v))`
    #[inline]
    fn from(patch: Patch<T>) -> Option<Option<T>> {
        match patch {
            Patch::Empty => None,
            Patch::None => Some(None),
            Patch::Some(v) => Some(Some(v)),
        }
    }
}

#[cfg(feature = "serde")]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
mod serde_impl {
    use super::Patch;
    use core::fmt;
    use core::marker::PhantomData;
    use serde::de::{self, Visitor};
    use serde::{Deserialize, Deserializer, Serialize, Serializer};

    impl<'de, T> Deserialize<'de> for Patch<T>
    where
        T: Deserialize<'de>,
    {
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: Deserializer<'de>,
        {
            struct PatchVisitor<T>(PhantomData<T>);

            impl<'de, T> Visitor<'de> for PatchVisitor<T>
            where
                T: Deserialize<'de>,
            {
                type Value = Patch<T>;

                fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
                    formatter.write_str("any value or null")
                }

                fn visit_none<E>(self) -> Result<Self::Value, E>
                where
                    E: de::Error,
                {
                    Ok(Patch::None)
                }

                fn visit_unit<E>(self) -> Result<Self::Value, E>
                where
                    E: de::Error,
                {
                    Ok(Patch::None)
                }

                fn visit_some<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
                where
                    D: Deserializer<'de>,
                {
                    T::deserialize(deserializer).map(Patch::Some)
                }
            }

            deserializer.deserialize_option(PatchVisitor(PhantomData))
        }
    }

    impl<T> Serialize for Patch<T>
    where
        T: Serialize,
    {
        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: Serializer,
        {
            match self {
                Patch::Some(v) => serializer.serialize_some(v),
                Patch::Empty | Patch::None => serializer.serialize_none(),
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[cfg(not(feature = "std"))]
    use alloc::string::String;
    #[cfg(feature = "std")]
    use std::string::String;

    #[test]
    fn test_queries() {
        assert!(Patch::Some(42).is_some());
        assert!(!Patch::<i32>::Empty.is_some());
        assert!(!Patch::<i32>::None.is_some());

        assert!(!Patch::Some(42).is_empty());
        assert!(Patch::<i32>::Empty.is_empty());
        assert!(!Patch::<i32>::None.is_empty());

        assert!(!Patch::Some(42).is_none());
        assert!(!Patch::<i32>::Empty.is_none());
        assert!(Patch::<i32>::None.is_none());

        assert!(Patch::<i32>::None.is_null());
    }

    #[test]
    fn test_contains() {
        assert!(Patch::Some(42).contains(&42));
        assert!(!Patch::Some(42).contains(&0));
        assert!(!Patch::<i32>::Empty.contains(&42));
        assert!(!Patch::<i32>::None.contains(&42));
    }

    #[test]
    fn test_as_ref_as_mut() {
        let patch = Patch::Some(42);
        assert_eq!(patch.as_ref(), Patch::Some(&42));

        let mut patch = Patch::Some(42);
        if let Patch::Some(v) = patch.as_mut() {
            *v = 100;
        }
        assert_eq!(patch, Patch::Some(100));
    }

    #[test]
    fn test_map() {
        assert_eq!(Patch::Some(21).map(|x| x * 2), Patch::Some(42));
        assert_eq!(Patch::<i32>::Empty.map(|x| x * 2), Patch::Empty);
        assert_eq!(Patch::<i32>::None.map(|x| x * 2), Patch::None);
    }

    #[test]
    fn test_map_or() {
        assert_eq!(Patch::Some(21).map_or(0, |x| x * 2), 42);
        assert_eq!(Patch::<i32>::Empty.map_or(0, |x| x * 2), 0);
        assert_eq!(Patch::<i32>::None.map_or(0, |x| x * 2), 0);
    }

    #[test]
    fn test_and_then() {
        let double = |x: i32| Patch::Some(x * 2);
        assert_eq!(Patch::Some(21).and_then(double), Patch::Some(42));
        assert_eq!(Patch::<i32>::Empty.and_then(double), Patch::Empty);
        assert_eq!(Patch::<i32>::None.and_then(double), Patch::None);
    }

    #[test]
    fn test_filter() {
        assert_eq!(Patch::Some(42).filter(|&x| x > 0), Patch::Some(42));
        assert_eq!(Patch::Some(-1).filter(|&x| x > 0), Patch::None);
        assert_eq!(Patch::<i32>::Empty.filter(|&x| x > 0), Patch::Empty);
    }

    #[test]
    fn test_unwrap_variants() {
        assert_eq!(Patch::Some(42).unwrap(), 42);
        assert_eq!(Patch::Some(42).unwrap_or(0), 42);
        assert_eq!(Patch::<i32>::Empty.unwrap_or(0), 0);
        assert_eq!(Patch::<i32>::None.unwrap_or(0), 0);
        assert_eq!(Patch::<i32>::Empty.unwrap_or_else(|| 100), 100);
        assert_eq!(Patch::<i32>::Empty.unwrap_or_default(), 0);
    }

    #[test]
    #[should_panic(expected = "called `Patch::unwrap()` on an `Empty` value")]
    fn test_unwrap_empty_panics() {
        Patch::<i32>::Empty.unwrap();
    }

    #[test]
    #[should_panic(expected = "called `Patch::unwrap()` on a `None` value")]
    fn test_unwrap_none_panics() {
        Patch::<i32>::None.unwrap();
    }

    #[test]
    fn test_or_combinators() {
        assert_eq!(Patch::Some(1).or(Patch::Some(2)), Patch::Some(1));
        assert_eq!(Patch::<i32>::Empty.or(Patch::Some(2)), Patch::Some(2));
        assert_eq!(Patch::<i32>::None.or(Patch::Some(2)), Patch::Some(2));

        assert_eq!(Patch::Some(1).or_else(|| Patch::Some(2)), Patch::Some(1));
        assert_eq!(
            Patch::<i32>::Empty.or_else(|| Patch::Some(2)),
            Patch::Some(2)
        );
    }

    #[test]
    fn test_xor() {
        assert_eq!(Patch::Some(1).xor(Patch::<i32>::Empty), Patch::Some(1));
        assert_eq!(Patch::<i32>::Empty.xor(Patch::Some(2)), Patch::Some(2));
        assert_eq!(Patch::<i32>::Empty.xor(Patch::<i32>::None), Patch::Empty);
        assert_eq!(Patch::Some(1).xor(Patch::Some(2)), Patch::None);
        assert_eq!(Patch::<i32>::Empty.xor(Patch::<i32>::Empty), Patch::None);
        assert_eq!(Patch::<i32>::None.xor(Patch::<i32>::None), Patch::None);
    }

    #[test]
    fn test_zip() {
        assert_eq!(Patch::Some(1).zip(Patch::Some("a")), Patch::Some((1, "a")));
        assert_eq!(Patch::Some(1).zip(Patch::<&str>::Empty), Patch::Empty);
        assert_eq!(Patch::<i32>::None.zip(Patch::Some("a")), Patch::None);
    }

    #[test]
    fn test_mutation_methods() {
        let mut patch = Patch::<i32>::Empty;
        assert_eq!(*patch.insert(42), 42);
        assert_eq!(patch, Patch::Some(42));

        let mut patch = Patch::<i32>::Empty;
        assert_eq!(*patch.get_or_insert(42), 42);

        let mut patch = Patch::Some(1);
        assert_eq!(*patch.get_or_insert(42), 1);

        let mut patch = Patch::Some(42);
        let taken = patch.take();
        assert_eq!(taken, Patch::Some(42));
        assert_eq!(patch, Patch::Empty);

        let mut patch = Patch::Some(42);
        let old = patch.replace(100);
        assert_eq!(old, Patch::Some(42));
        assert_eq!(patch, Patch::Some(100));
    }

    #[test]
    fn test_conversions() {
        // From<T>
        let patch: Patch<i32> = 42.into();
        assert_eq!(patch, Patch::Some(42));

        // From<Option<T>>
        let patch: Patch<i32> = Some(42).into();
        assert_eq!(patch, Patch::Some(42));
        let patch: Patch<i32> = Option::<i32>::None.into();
        assert_eq!(patch, Patch::None);

        // From<Patch<T>> for Option<T>
        let opt: Option<i32> = Patch::Some(42).into();
        assert_eq!(opt, Some(42));
        let opt: Option<i32> = Patch::<i32>::Empty.into();
        assert_eq!(opt, None);

        // Option<Option<T>> round-trip
        let patch: Patch<i32> = Option::<Option<i32>>::None.into();
        assert_eq!(patch, Patch::Empty);
        let patch: Patch<i32> = Some(None).into();
        assert_eq!(patch, Patch::None);
        let patch: Patch<i32> = Some(Some(42)).into();
        assert_eq!(patch, Patch::Some(42));

        let opt: Option<Option<i32>> = Patch::<i32>::Empty.into();
        assert_eq!(opt, None);
        let opt: Option<Option<i32>> = Patch::<i32>::None.into();
        assert_eq!(opt, Some(None));
        let opt: Option<Option<i32>> = Patch::<i32>::Some(42).into();
        assert_eq!(opt, Some(Some(42)));
    }

    #[test]
    fn test_default() {
        let patch: Patch<i32> = Patch::default();
        assert_eq!(patch, Patch::Empty);
    }

    #[test]
    fn test_clone_copy() {
        let patch = Patch::Some(String::from("hello"));
        let cloned = patch.clone();
        assert_eq!(patch, cloned);

        let patch = Patch::Some(42);
        let copied = patch;
        assert_eq!(patch, copied);
    }

    #[test]
    fn test_cloned_copied() {
        let value = 42;
        let patch = Patch::Some(&value);
        assert_eq!(patch.copied(), Patch::Some(42));

        let s = String::from("hello");
        let patch = Patch::Some(&s);
        assert_eq!(patch.cloned(), Patch::Some(String::from("hello")));
    }

    #[test]
    fn test_as_deref() {
        let patch = Patch::Some(String::from("hello"));
        assert_eq!(patch.as_deref(), Patch::Some("hello"));

        let empty: Patch<String> = Patch::Empty;
        assert_eq!(empty.as_deref(), Patch::Empty);
    }

    #[test]
    fn test_ord() {
        assert!(Patch::Some(1) < Patch::Some(2));
        assert!(Patch::<i32>::Empty < Patch::<i32>::None);
        assert!(Patch::Some(1) < Patch::<i32>::Empty);
    }

    #[test]
    #[cfg(feature = "std")]
    fn test_hash() {
        use core::hash::{Hash, Hasher};
        use std::collections::hash_map::DefaultHasher;

        fn hash<T: Hash>(t: &T) -> u64 {
            let mut s = DefaultHasher::new();
            t.hash(&mut s);
            s.finish()
        }

        assert_eq!(hash(&Patch::Some(42)), hash(&Patch::Some(42)));
        assert_ne!(hash(&Patch::Some(42)), hash(&Patch::Some(0)));
        assert_ne!(hash(&Patch::<i32>::Empty), hash(&Patch::<i32>::None));
    }
}

#[cfg(all(test, feature = "serde"))]
mod serde_tests {
    use super::*;
    use serde::{Deserialize, Serialize};

    #[derive(Debug, Deserialize, Serialize, PartialEq)]
    struct TestStruct {
        #[serde(default, skip_serializing_if = "Patch::is_empty")]
        value: Patch<i32>,
    }

    #[test]
    fn test_deserialize_some() {
        let json = r#"{"value": 42}"#;
        let s: TestStruct = serde_json::from_str(json).unwrap();
        assert_eq!(s.value, Patch::Some(42));
    }

    #[test]
    fn test_deserialize_null() {
        let json = r#"{"value": null}"#;
        let s: TestStruct = serde_json::from_str(json).unwrap();
        assert_eq!(s.value, Patch::None);
    }

    #[test]
    fn test_deserialize_missing() {
        let json = r#"{}"#;
        let s: TestStruct = serde_json::from_str(json).unwrap();
        assert_eq!(s.value, Patch::Empty);
    }

    #[test]
    fn test_serialize_some() {
        let s = TestStruct {
            value: Patch::Some(42),
        };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(json, r#"{"value":42}"#);
    }

    #[test]
    fn test_serialize_none() {
        let s = TestStruct { value: Patch::None };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(json, r#"{"value":null}"#);
    }

    #[test]
    fn test_serialize_empty() {
        let s = TestStruct {
            value: Patch::Empty,
        };
        let json = serde_json::to_string(&s).unwrap();
        assert_eq!(json, r#"{}"#);
    }

    #[test]
    fn test_roundtrip() {
        let original = TestStruct {
            value: Patch::Some(42),
        };
        let json = serde_json::to_string(&original).unwrap();
        let parsed: TestStruct = serde_json::from_str(&json).unwrap();
        assert_eq!(original, parsed);
    }
}