positive 0.5.0

/******************************************************************************
   Author: Joaquín Béjar García
   Email: jb@taunais.com
   Date: 25/12/25
******************************************************************************/

//! Core implementation of the Positive type.

use crate::constants::{EPSILON, EPSILON_CMP};
use crate::error::PositiveError;
use approx::{AbsDiffEq, RelativeEq};
use num_traits::{FromPrimitive, Pow, ToPrimitive};
use rust_decimal::{Decimal, MathematicalOps, RoundingStrategy};
use rust_decimal_macros::dec;
use serde::de::Visitor;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use std::cmp::{Ordering, PartialEq};
use std::fmt;
use std::fmt::Display;
#[cfg(not(feature = "non-zero"))]
use std::iter::Sum;
use std::ops::{Add, AddAssign, Div, Mul, MulAssign, Sub};
use std::str::FromStr;

/// A wrapper type that represents a guaranteed positive decimal value.
///
/// This type encapsulates a `Decimal` value and ensures through its API that
/// the contained value is always positive (greater than or equal to zero).
///
/// When the `non-zero` feature is enabled, the value must be strictly
/// greater than zero.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(transparent)]
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
pub struct Positive(Decimal);

/// Returns whether the given decimal value satisfies the positivity constraint.
///
/// Without the `non-zero` feature, values >= 0 are accepted.
/// With the `non-zero` feature, only values > 0 are accepted.
#[inline]
#[must_use]
pub fn is_valid_positive_value(value: Decimal) -> bool {
    #[cfg(feature = "non-zero")]
    {
        value > Decimal::ZERO
    }
    #[cfg(not(feature = "non-zero"))]
    {
        value >= Decimal::ZERO
    }
}

/// Returns the minimum bound for error messages.
///
/// Without the `non-zero` feature, the minimum is 0.0.
/// With the `non-zero` feature, the minimum is the smallest representable
/// positive f64 value.
#[inline]
#[must_use]
fn min_bound() -> f64 {
    #[cfg(feature = "non-zero")]
    {
        f64::MIN_POSITIVE
    }
    #[cfg(not(feature = "non-zero"))]
    {
        0.0
    }
}

/// Determines if the given type parameter `T` is the `Positive` type.
#[must_use]
pub fn is_positive<T: 'static>() -> bool {
    std::any::TypeId::of::<T>() == std::any::TypeId::of::<Positive>()
}

/// Default rounding strategy used by every `Div` operator on `Positive`.
///
/// `Decimal` division is exact when the result fits in its 28-digit
/// mantissa, but when it does not the operation must round. We pick
/// banker's rounding (`MidpointNearestEven`) as the canonical strategy
/// because it is statistically unbiased and matches IEEE-754 default
/// behaviour for financial calculations. Callers needing a different
/// strategy should use [`Positive::checked_div_with_strategy`].
pub const DIV_ROUNDING_STRATEGY: RoundingStrategy = RoundingStrategy::MidpointNearestEven;

/// Maximum decimal places preserved by division results.
///
/// `rust_decimal::Decimal` carries up to 28 digits of precision; rounding
/// at that scale is effectively "keep full precision". This constant is
/// used by every `Div` operator and by
/// [`Positive::checked_div_with_strategy`].
pub(crate) const DIV_SCALE: u32 = 28;

/// Applies [`DIV_ROUNDING_STRATEGY`] to the result of a division.
///
/// Kept as a crate-private helper so every `Div` / `checked_div*`
/// operator on `Positive` rounds through the same point.
#[inline]
pub(crate) fn round_div(result: Decimal) -> Decimal {
    result.round_dp_with_strategy(DIV_SCALE, DIV_ROUNDING_STRATEGY)
}

/// Panics with a uniform message when a `Positive` arithmetic operation
/// overflows the underlying `Decimal` range.
///
/// Marked `#[cold]` and `#[inline(never)]` so the happy path stays lean.
#[cold]
#[inline(never)]
pub(crate) fn overflow_panic(op: &'static str) -> ! {
    panic!("Positive arithmetic overflow in {op}")
}

/// Panics with a uniform message when the result of a `Positive`
/// arithmetic operation would violate the positivity invariant
/// (negative, or zero under the `non-zero` feature).
///
/// Marked `#[cold]` and `#[inline(never)]` so the happy path stays lean.
#[cold]
#[inline(never)]
pub(crate) fn invariant_panic(op: &'static str) -> ! {
    panic!("Positive invariant broken in {op}: result would be non-positive")
}

impl Positive {
    // Re-export constants from the constants module for backward compatibility
    /// A zero value represented as a `Positive` value.
    ///
    /// This constant is not available when the `non-zero` feature is enabled.
    #[cfg(not(feature = "non-zero"))]
    pub const ZERO: Positive = crate::constants::ZERO;
    /// A value of one represented as a `Positive` value.
    pub const ONE: Positive = crate::constants::ONE;
    /// A value of two represented as a `Positive` value.
    pub const TWO: Positive = crate::constants::TWO;
    /// A value of three represented as a `Positive` value.
    pub const THREE: Positive = crate::constants::THREE;
    /// A value of four represented as a `Positive` value.
    pub const FOUR: Positive = crate::constants::FOUR;
    /// A value of five represented as a `Positive` value.
    pub const FIVE: Positive = crate::constants::FIVE;
    /// A value of six represented as a `Positive` value.
    pub const SIX: Positive = crate::constants::SIX;
    /// A value of seven represented as a `Positive` value.
    pub const SEVEN: Positive = crate::constants::SEVEN;
    /// A value of eight represented as a `Positive` value.
    pub const EIGHT: Positive = crate::constants::EIGHT;
    /// A value of nine represented as a `Positive` value.
    pub const NINE: Positive = crate::constants::NINE;
    /// A value of ten represented as a `Positive` value.
    pub const TEN: Positive = crate::constants::TEN;
    /// A value of fifteen represented as a `Positive` value.
    pub const FIFTEEN: Positive = crate::constants::FIFTEEN;
    /// A value of twenty represented as a `Positive` value.
    pub const TWENTY: Positive = crate::constants::TWENTY;
    /// A value of twenty-five represented as a `Positive` value.
    pub const TWENTY_FIVE: Positive = crate::constants::TWENTY_FIVE;
    /// A value of thirty represented as a `Positive` value.
    pub const THIRTY: Positive = crate::constants::THIRTY;
    /// A value of thirty-five represented as a `Positive` value.
    pub const THIRTY_FIVE: Positive = crate::constants::THIRTY_FIVE;
    /// A value of forty represented as a `Positive` value.
    pub const FORTY: Positive = crate::constants::FORTY;
    /// A value of forty-five represented as a `Positive` value.
    pub const FORTY_FIVE: Positive = crate::constants::FORTY_FIVE;
    /// A value of fifty represented as a `Positive` value.
    pub const FIFTY: Positive = crate::constants::FIFTY;
    /// A value of fifty-five represented as a `Positive` value.
    pub const FIFTY_FIVE: Positive = crate::constants::FIFTY_FIVE;
    /// A value of sixty represented as a `Positive` value.
    pub const SIXTY: Positive = crate::constants::SIXTY;
    /// A value of sixty-five represented as a `Positive` value.
    pub const SIXTY_FIVE: Positive = crate::constants::SIXTY_FIVE;
    /// A value of seventy represented as a `Positive` value.
    pub const SEVENTY: Positive = crate::constants::SEVENTY;
    /// A value of seventy-five represented as a `Positive` value.
    pub const SEVENTY_FIVE: Positive = crate::constants::SEVENTY_FIVE;
    /// A value of eighty represented as a `Positive` value.
    pub const EIGHTY: Positive = crate::constants::EIGHTY;
    /// A value of eighty-five represented as a `Positive` value.
    pub const EIGHTY_FIVE: Positive = crate::constants::EIGHTY_FIVE;
    /// A value of ninety represented as a `Positive` value.
    pub const NINETY: Positive = crate::constants::NINETY;
    /// A value of ninety-five represented as a `Positive` value.
    pub const NINETY_FIVE: Positive = crate::constants::NINETY_FIVE;
    /// A value of one hundred represented as a `Positive` value.
    pub const HUNDRED: Positive = crate::constants::HUNDRED;
    /// A value of two hundred represented as a `Positive` value.
    pub const TWO_HUNDRED: Positive = crate::constants::TWO_HUNDRED;
    /// A value of three hundred represented as a `Positive` value.
    pub const THREE_HUNDRED: Positive = crate::constants::THREE_HUNDRED;
    /// A value of four hundred represented as a `Positive` value.
    pub const FOUR_HUNDRED: Positive = crate::constants::FOUR_HUNDRED;
    /// A value of five hundred represented as a `Positive` value.
    pub const FIVE_HUNDRED: Positive = crate::constants::FIVE_HUNDRED;
    /// A value of six hundred represented as a `Positive` value.
    pub const SIX_HUNDRED: Positive = crate::constants::SIX_HUNDRED;
    /// A value of seven hundred represented as a `Positive` value.
    pub const SEVEN_HUNDRED: Positive = crate::constants::SEVEN_HUNDRED;
    /// A value of eight hundred represented as a `Positive` value.
    pub const EIGHT_HUNDRED: Positive = crate::constants::EIGHT_HUNDRED;
    /// A value of nine hundred represented as a `Positive` value.
    pub const NINE_HUNDRED: Positive = crate::constants::NINE_HUNDRED;
    /// A value of one thousand represented as a `Positive` value.
    pub const THOUSAND: Positive = crate::constants::THOUSAND;
    /// A value of two thousand represented as a `Positive` value.
    pub const TWO_THOUSAND: Positive = crate::constants::TWO_THOUSAND;
    /// A value of three thousand represented as a `Positive` value.
    pub const THREE_THOUSAND: Positive = crate::constants::THREE_THOUSAND;
    /// A value of four thousand represented as a `Positive` value.
    pub const FOUR_THOUSAND: Positive = crate::constants::FOUR_THOUSAND;
    /// A value of five thousand represented as a `Positive` value.
    pub const FIVE_THOUSAND: Positive = crate::constants::FIVE_THOUSAND;
    /// A value of six thousand represented as a `Positive` value.
    pub const SIX_THOUSAND: Positive = crate::constants::SIX_THOUSAND;
    /// A value of seven thousand represented as a `Positive` value.
    pub const SEVEN_THOUSAND: Positive = crate::constants::SEVEN_THOUSAND;
    /// A value of eight thousand represented as a `Positive` value.
    pub const EIGHT_THOUSAND: Positive = crate::constants::EIGHT_THOUSAND;
    /// A value of nine thousand represented as a `Positive` value.
    pub const NINE_THOUSAND: Positive = crate::constants::NINE_THOUSAND;
    /// A value of ten thousand represented as a `Positive` value.
    pub const TEN_THOUSAND: Positive = crate::constants::TEN_THOUSAND;
    /// The mathematical constant π (pi) represented as a `Positive` value.
    pub const PI: Positive = crate::constants::PI;
    /// The mathematical constant e (Euler's number) represented as a `Positive` value.
    pub const E: Positive = crate::constants::E;
    /// Represents the maximum positive value possible (effectively infinity).
    pub const INFINITY: Positive = crate::constants::INFINITY;

    /// Creates a new `Positive` value from a 64-bit floating-point number.
    ///
    /// Without the `non-zero` feature, values >= 0 are accepted.
    /// With the `non-zero` feature, only values > 0 are accepted.
    #[must_use = "constructor returns a Result; ignoring the Positive discards a validated invariant"]
    pub fn new(value: f64) -> Result<Self, PositiveError> {
        let dec = Decimal::from_f64(value);
        match dec {
            Some(value) if is_valid_positive_value(value) => Ok(Positive(value)),
            Some(value) => Err(PositiveError::OutOfBounds {
                value: value.to_f64().unwrap_or(0.0),
                min: min_bound(),
                max: f64::MAX,
            }),
            None => Err(PositiveError::ConversionError {
                from_type: "f64".to_string(),
                to_type: "Positive".to_string(),
                reason: "failed to parse Decimal".to_string(),
            }),
        }
    }

    /// Creates a new `Positive` value directly from a `Decimal`.
    ///
    /// Without the `non-zero` feature, values >= 0 are accepted.
    /// With the `non-zero` feature, only values > 0 are accepted.
    #[must_use = "constructor returns a Result; ignoring the Positive discards a validated invariant"]
    pub fn new_decimal(value: Decimal) -> Result<Self, PositiveError> {
        if is_valid_positive_value(value) {
            Ok(Positive(value))
        } else {
            Err(PositiveError::OutOfBounds {
                value: value.to_f64().unwrap_or(0.0),
                min: min_bound(),
                max: f64::INFINITY,
            })
        }
    }

    /// Returns the inner `Decimal` value.
    #[inline]
    #[must_use]
    pub fn value(&self) -> Decimal {
        self.0
    }

    /// Returns the inner `Decimal` value (alias for `value()`).
    #[inline]
    #[must_use]
    pub fn to_dec(&self) -> Decimal {
        self.0
    }

    /// Returns the inner `Decimal` ref.
    #[inline]
    #[must_use]
    pub fn to_dec_ref(&self) -> &Decimal {
        &self.0
    }

    /// Converts the value to a 64-bit floating-point number.
    ///
    /// # Panics
    ///
    /// This method will panic if the conversion fails. Use `to_f64_checked()`
    /// or `to_f64_lossy()` for non-panicking alternatives.
    #[must_use]
    pub fn to_f64(&self) -> f64 {
        self.0
            .to_f64()
            .expect("Decimal to f64 conversion failed - value out of range")
    }

    /// Converts the value to f64, returning None if conversion fails.
    #[inline]
    #[must_use]
    pub fn to_f64_checked(&self) -> Option<f64> {
        self.0.to_f64()
    }

    /// Converts the value to f64 with lossy conversion (returns 0.0 on failure).
    #[inline]
    #[must_use]
    pub fn to_f64_lossy(&self) -> f64 {
        self.0.to_f64().unwrap_or(0.0)
    }

    /// Converts the value to a 64-bit signed integer.
    ///
    /// # Panics
    ///
    /// This method will panic if the conversion fails. Use `to_i64_checked()`
    /// for a non-panicking alternative.
    #[must_use]
    pub fn to_i64(&self) -> i64 {
        self.0
            .to_i64()
            .expect("Decimal to i64 conversion failed - value out of range")
    }

    /// Converts the value to i64, returning None if conversion fails.
    #[must_use]
    pub fn to_i64_checked(&self) -> Option<i64> {
        self.0.to_i64()
    }

    /// Converts the inner value to a `u64`.
    ///
    /// # Panics
    ///
    /// This method will panic if the conversion fails. Use `to_u64_checked()`
    /// for a non-panicking alternative.
    #[must_use]
    pub fn to_u64(&self) -> u64 {
        self.0
            .to_u64()
            .expect("Decimal to u64 conversion failed - value out of range")
    }

    /// Converts the value to u64, returning None if conversion fails.
    #[must_use]
    pub fn to_u64_checked(&self) -> Option<u64> {
        self.0.to_u64()
    }

    /// Converts the value to a usize.
    ///
    /// # Panics
    ///
    /// This method will panic if the conversion fails. Use `to_usize_checked()`
    /// for a non-panicking alternative.
    #[must_use]
    pub fn to_usize(&self) -> usize {
        self.0
            .to_usize()
            .expect("Decimal to usize conversion failed - value out of range")
    }

    /// Converts the value to usize, returning None if conversion fails.
    #[must_use]
    pub fn to_usize_checked(&self) -> Option<usize> {
        self.0.to_usize()
    }

    /// Returns the maximum of two `Positive` values.
    #[must_use]
    pub fn max(self, other: Positive) -> Positive {
        if self.0 > other.0 { self } else { other }
    }

    /// Returns the minimum of two `Positive` values.
    #[must_use]
    pub fn min(self, other: Positive) -> Positive {
        if self.0 < other.0 { self } else { other }
    }

    /// Rounds the value down to the nearest integer.
    #[must_use]
    pub fn floor(&self) -> Positive {
        Positive(self.0.floor())
    }

    /// Raises this value to an integer power.
    #[must_use]
    pub fn powi(&self, n: i64) -> Positive {
        Positive(self.0.powi(n))
    }

    /// Computes the result of raising the current value to the power of the given exponent.
    #[must_use]
    pub fn pow(&self, n: Positive) -> Positive {
        Positive(self.0.pow(n.to_dec()))
    }

    /// Raises the current value to the power of `n` using unsigned integer exponentiation.
    #[must_use]
    pub fn powu(&self, n: u64) -> Positive {
        Positive(self.0.powu(n))
    }

    /// Raises this value to a decimal power.
    #[must_use]
    pub fn powd(&self, p0: Decimal) -> Positive {
        Positive(self.0.powd(p0))
    }

    /// Rounds the value to the nearest integer.
    #[must_use]
    pub fn round(&self) -> Positive {
        Positive(self.0.round())
    }

    /// Rounds the current value to a "nice" number, based on its magnitude.
    #[must_use]
    pub fn round_to_nice_number(&self) -> Positive {
        let magnitude = self.log10().floor();
        let ten_pow = Positive::TEN.pow(magnitude);
        let normalized = self / &ten_pow;
        let nice_number = if normalized < dec!(1.5) {
            Positive::ONE
        } else if normalized < pos_or_panic!(3.0) {
            Positive::TWO
        } else if normalized < pos_or_panic!(7.0) {
            pos_or_panic!(5.0)
        } else {
            Positive::TEN
        };
        nice_number * pos_or_panic!(10.0).powu(magnitude.to_u64())
    }

    /// Calculates the square root of the value.
    ///
    /// # Panics
    ///
    /// This method will panic if the square root calculation fails.
    /// Use `sqrt_checked()` for a non-panicking alternative.
    #[must_use]
    pub fn sqrt(&self) -> Positive {
        Positive(self.0.sqrt().expect("Square root calculation failed"))
    }

    /// Calculates the square root, returning an error if it fails.
    pub fn sqrt_checked(&self) -> Result<Positive, PositiveError> {
        self.0.sqrt().map(Positive).ok_or_else(|| {
            PositiveError::arithmetic_error("sqrt", "square root calculation failed")
        })
    }

    /// Calculates the natural logarithm of the value.
    #[inline]
    #[must_use]
    pub fn ln(&self) -> Positive {
        Positive(self.0.ln())
    }

    /// Rounds the value to a specified number of decimal places.
    #[inline]
    #[must_use]
    pub fn round_to(&self, decimal_places: u32) -> Positive {
        Positive(self.0.round_dp(decimal_places))
    }

    /// Formats the value with a fixed number of decimal places.
    ///
    /// Rounds the underlying `Decimal` at `decimal_places` using its
    /// default rounding strategy and formats the result. No
    /// `f64` round-trip, so precision is preserved beyond the ~15 digits
    /// of `f64`.
    #[inline]
    #[must_use]
    pub fn format_fixed_places(&self, decimal_places: u32) -> String {
        format!(
            "{:.1$}",
            self.0.round_dp(decimal_places),
            decimal_places as usize
        )
    }

    /// Calculates the exponential function e^x for this value.
    #[inline]
    #[must_use]
    pub fn exp(&self) -> Positive {
        Positive(self.0.exp())
    }

    /// Clamps the value between a minimum and maximum.
    #[must_use]
    pub fn clamp(&self, min: Positive, max: Positive) -> Positive {
        if self < &min {
            min
        } else if self > &max {
            max
        } else {
            *self
        }
    }

    /// Checks if the value is exactly zero.
    #[inline]
    #[must_use]
    pub fn is_zero(&self) -> bool {
        self.0.is_zero()
    }

    /// Returns the smallest integer greater than or equal to the value.
    #[inline]
    #[must_use]
    pub fn ceiling(&self) -> Positive {
        Positive(self.to_dec().ceil())
    }

    /// Computes the base-10 logarithm of the value.
    #[inline]
    #[must_use]
    pub fn log10(&self) -> Positive {
        Positive(self.0.log10())
    }

    /// Subtracts a decimal value, returning zero if the result would be negative.
    ///
    /// This method is not available when the `non-zero` feature is enabled
    /// because the result could be zero.
    #[cfg(not(feature = "non-zero"))]
    #[must_use]
    pub fn sub_or_zero(&self, other: &Decimal) -> Positive {
        if &self.0 > other {
            Positive(self.0 - other)
        } else {
            Positive(Decimal::ZERO)
        }
    }

    /// Subtracts a decimal value, returning None if the result would be negative.
    #[must_use]
    pub fn sub_or_none(&self, other: &Decimal) -> Option<Positive> {
        if &self.0 >= other {
            Some(Positive(self.0 - other))
        } else {
            None
        }
    }

    /// Checked subtraction that returns Result instead of panicking.
    #[must_use = "checked arithmetic returns a Result; ignoring it silences the overflow/underflow error"]
    pub fn checked_sub(&self, rhs: &Self) -> Result<Self, PositiveError> {
        Positive::new_decimal(self.0 - rhs.0)
    }

    /// Saturating subtraction that returns ZERO instead of negative.
    ///
    /// This method is not available when the `non-zero` feature is enabled
    /// because the result could be zero.
    #[cfg(not(feature = "non-zero"))]
    #[must_use]
    pub fn saturating_sub(&self, rhs: &Self) -> Self {
        if self.0 > rhs.0 {
            Positive(self.0 - rhs.0)
        } else {
            Positive::ZERO
        }
    }

    /// Checked division that returns Result instead of panicking.
    ///
    /// Uses [`DIV_ROUNDING_STRATEGY`] (banker's rounding) for any
    /// rounding required by the result. Use
    /// [`Positive::checked_div_with_strategy`] to select a different
    /// strategy.
    #[must_use = "checked arithmetic returns a Result; ignoring it silences the division-by-zero error"]
    pub fn checked_div(&self, rhs: &Self) -> Result<Self, PositiveError> {
        if rhs.is_zero() {
            Err(PositiveError::arithmetic_error(
                "division",
                "division by zero",
            ))
        } else {
            Ok(Positive(round_div(self.0 / rhs.0)))
        }
    }

    /// Checked division with an explicit rounding strategy.
    ///
    /// # Errors
    ///
    /// Returns an `ArithmeticError` on division by zero or overflow.
    #[must_use = "checked arithmetic returns a Result; ignoring it silences the error"]
    pub fn checked_div_with_strategy(
        &self,
        rhs: &Self,
        strategy: RoundingStrategy,
    ) -> Result<Self, PositiveError> {
        if rhs.is_zero() {
            return Err(PositiveError::arithmetic_error(
                "division",
                "division by zero",
            ));
        }
        let result = self
            .0
            .checked_div(rhs.0)
            .ok_or_else(|| PositiveError::arithmetic_error("division", "overflow"))?;
        Ok(Positive(result.round_dp_with_strategy(DIV_SCALE, strategy)))
    }

    /// Checked addition with an `f64`, returning a `Result` instead of panicking.
    ///
    /// # Errors
    ///
    /// Returns a `ConversionError` if `rhs` cannot be represented as a
    /// `Decimal` (e.g. NaN, `±inf`), an `ArithmeticError` on overflow, or
    /// an `OutOfBounds` if the result would violate the positivity
    /// invariant.
    #[must_use = "checked arithmetic returns a Result; ignoring it silences the error"]
    pub fn checked_add_f64(self, rhs: f64) -> Result<Positive, PositiveError> {
        let rhs_dec = Decimal::from_f64(rhs).ok_or_else(|| {
            PositiveError::conversion_error("f64", "Decimal", "value not representable as Decimal")
        })?;
        let result = self
            .0
            .checked_add(rhs_dec)
            .ok_or_else(|| PositiveError::arithmetic_error("add_f64", "overflow"))?;
        Positive::new_decimal(result)
    }

    /// Checked subtraction with an `f64`, returning a `Result` instead of panicking.
    ///
    /// # Errors
    ///
    /// Returns a `ConversionError` if `rhs` cannot be represented as a
    /// `Decimal`, an `ArithmeticError` on overflow, or an `OutOfBounds`
    /// if the result would violate the positivity invariant.
    #[must_use = "checked arithmetic returns a Result; ignoring it silences the error"]
    pub fn checked_sub_f64(self, rhs: f64) -> Result<Positive, PositiveError> {
        let rhs_dec = Decimal::from_f64(rhs).ok_or_else(|| {
            PositiveError::conversion_error("f64", "Decimal", "value not representable as Decimal")
        })?;
        let result = self
            .0
            .checked_sub(rhs_dec)
            .ok_or_else(|| PositiveError::arithmetic_error("sub_f64", "overflow"))?;
        Positive::new_decimal(result)
    }

    /// Checked multiplication with an `f64`, returning a `Result` instead of panicking.
    ///
    /// # Errors
    ///
    /// Returns a `ConversionError` if `rhs` cannot be represented as a
    /// `Decimal`, an `ArithmeticError` on overflow, or an `OutOfBounds`
    /// if the result would violate the positivity invariant (for example
    /// when `rhs` is negative).
    #[must_use = "checked arithmetic returns a Result; ignoring it silences the error"]
    pub fn checked_mul_f64(self, rhs: f64) -> Result<Positive, PositiveError> {
        let rhs_dec = Decimal::from_f64(rhs).ok_or_else(|| {
            PositiveError::conversion_error("f64", "Decimal", "value not representable as Decimal")
        })?;
        let result = self
            .0
            .checked_mul(rhs_dec)
            .ok_or_else(|| PositiveError::arithmetic_error("mul_f64", "overflow"))?;
        Positive::new_decimal(result)
    }

    /// Checked division by an `f64`, returning a `Result` instead of panicking.
    ///
    /// # Errors
    ///
    /// Returns a `ConversionError` if `rhs` cannot be represented as a
    /// `Decimal`, an `ArithmeticError` on overflow or division by zero,
    /// or an `OutOfBounds` if the result would violate the positivity
    /// invariant (for example when `rhs` is negative).
    #[must_use = "checked arithmetic returns a Result; ignoring it silences the error"]
    pub fn checked_div_f64(self, rhs: f64) -> Result<Positive, PositiveError> {
        let rhs_dec = Decimal::from_f64(rhs).ok_or_else(|| {
            PositiveError::conversion_error("f64", "Decimal", "value not representable as Decimal")
        })?;
        if rhs_dec.is_zero() {
            return Err(PositiveError::arithmetic_error(
                "div_f64",
                "division by zero",
            ));
        }
        let result = self
            .0
            .checked_div(rhs_dec)
            .ok_or_else(|| PositiveError::arithmetic_error("div_f64", "overflow"))?;
        Positive::new_decimal(round_div(result))
    }

    /// Checks whether the value is a multiple of another `f64` value.
    ///
    /// Prefer [`Positive::is_multiple_of_dec`] for full `Decimal`
    /// precision — this variant lifts the value to `f64` and compares
    /// against `f64::EPSILON`, which can misclassify values beyond the
    /// ~15-digit precision of `f64`.
    #[deprecated(
        since = "0.5.0",
        note = "use `is_multiple_of_dec` for Decimal-native precision"
    )]
    #[must_use]
    pub fn is_multiple(&self, other: f64) -> bool {
        let value = self.to_f64();
        if !value.is_finite() {
            return false;
        }
        let remainder = value % other;
        remainder.abs() < f64::EPSILON || (other - remainder.abs()).abs() < f64::EPSILON
    }

    /// Checks whether the value is a multiple of a `Decimal` without
    /// lifting to `f64`.
    ///
    /// Returns `false` when `other` is zero. Uses
    /// [`Decimal::checked_rem`] so pathological inputs cannot panic.
    #[inline]
    #[must_use]
    pub fn is_multiple_of_dec(&self, other: Decimal) -> bool {
        if other.is_zero() {
            return false;
        }
        self.0
            .checked_rem(other)
            .map(|r| r.is_zero())
            .unwrap_or(false)
    }

    /// Checks whether the value is a multiple of another `Positive`
    /// value.
    ///
    /// Returns `false` when `other` is zero. Uses
    /// [`Decimal::checked_rem`] so pathological inputs cannot panic
    /// (rule 50). The remainder is compared against [`EPSILON`] to
    /// tolerate the tiny rounding artefacts `Decimal` can introduce at
    /// the edge of its 28-digit mantissa.
    #[inline]
    #[must_use]
    pub fn is_multiple_of(&self, other: &Positive) -> bool {
        if other.is_zero() {
            return false;
        }
        self.0
            .checked_rem(other.0)
            .map(|r| r.abs() < EPSILON)
            .unwrap_or(false)
    }

    /// Creates a new `Positive` value without validating the positivity
    /// invariant.
    ///
    /// This is the crate's **only** public `unsafe` constructor and the
    /// only escape hatch out of [`Positive::new`] /
    /// [`Positive::new_decimal`]. Prefer the validated constructors in
    /// every normal code path; `new_unchecked` is reserved for contexts
    /// where the caller has already proven the invariant at compile time
    /// (for example when reading back a previously validated
    /// [`Decimal`]) and wants to skip the re-check.
    ///
    /// # Safety
    ///
    /// The caller must uphold the [`Positive`] invariant for `value`:
    ///
    /// - Without the `non-zero` feature, `value >= Decimal::ZERO`.
    /// - With the `non-zero` feature, `value > Decimal::ZERO`.
    ///
    /// Violating this invariant is **undefined behaviour** through the
    /// rest of the crate: arithmetic, comparisons, serialisation, and
    /// conversions all assume a `Positive` holds a non-negative (or
    /// strictly positive under `non-zero`) `Decimal`. Downstream code
    /// that relies on the positivity guarantee to skip range checks may
    /// miscompute, infinite-loop, or return nonsensical results if that
    /// assumption is broken.
    ///
    /// `new_unchecked` performs **no** validation, **no** conversion,
    /// **no** rounding: the returned value wraps exactly the `Decimal`
    /// you pass in.
    ///
    /// # When to use
    ///
    /// Genuine use cases are rare. In order of preference:
    ///
    /// 1. [`Positive::new_decimal`] — fallible, validates once,
    ///    returns `Result<Self, PositiveError>`.
    /// 2. [`Positive::new`] — same, but takes an `f64`.
    /// 3. The [`pos!`](crate::pos) / [`spos!`](crate::spos) /
    ///    [`pos_or_panic!`](crate::pos_or_panic) macros for ergonomic
    ///    literal construction.
    /// 4. `new_unchecked` — only if none of the above work, for
    ///    example inside your own `const fn` paths where the input is
    ///    a literal `Decimal` already known to be non-negative.
    ///
    /// Every call site must be accompanied by a `// SAFETY:` comment
    /// that documents *why* the invariant holds for the specific input.
    ///
    /// # Examples
    ///
    /// Valid usage — the input literal is clearly non-negative:
    ///
    /// ```rust
    /// use positive::Positive;
    /// use rust_decimal_macros::dec;
    ///
    /// // SAFETY: the literal `5.0` is strictly greater than zero, so
    /// // the Positive invariant is preserved under both the default
    /// // and `non-zero` features.
    /// let value = unsafe { Positive::new_unchecked(dec!(5.0)) };
    /// assert_eq!(value.to_f64(), 5.0);
    /// ```
    ///
    /// Invalid usage (**undefined behaviour** — do **not** do this):
    ///
    /// ```ignore
    /// use positive::Positive;
    /// use rust_decimal_macros::dec;
    ///
    /// // UB: the input is negative; every downstream operation on
    /// // `broken` is now unsound.
    /// let broken = unsafe { Positive::new_unchecked(dec!(-1)) };
    /// ```
    #[inline]
    #[must_use]
    pub const unsafe fn new_unchecked(value: Decimal) -> Self {
        Positive(value)
    }

    /// Crate-private const constructor used exclusively by `crate::constants`
    /// to define `Positive` constants in `const` context. The invariant is
    /// enforced by the callers: every constant in `crate::constants` is a
    /// strictly non-negative literal (or `>0` under the `non-zero` feature).
    #[inline]
    #[must_use]
    pub(crate) const fn from_decimal_const(value: Decimal) -> Self {
        Positive(value)
    }
}

impl From<Positive> for Decimal {
    #[inline]
    fn from(value: Positive) -> Self {
        value.0
    }
}

impl PartialEq<&Positive> for Positive {
    #[inline]
    fn eq(&self, other: &&Positive) -> bool {
        self == *other
    }
}

impl From<Positive> for u64 {
    #[inline]
    fn from(pos_u64: Positive) -> Self {
        pos_u64.0.to_u64().unwrap_or(0)
    }
}

impl From<&Positive> for f64 {
    #[inline]
    fn from(value: &Positive) -> Self {
        value.0.to_f64().unwrap_or(0.0)
    }
}

impl From<Positive> for f64 {
    #[inline]
    fn from(value: Positive) -> Self {
        value.0.to_f64().unwrap_or(0.0)
    }
}

impl From<Positive> for usize {
    /// Converts the underlying `Decimal` to `usize` via `to_u64`.
    ///
    /// Returns `0` on overflow or when the value is not representable as
    /// `u64`. For fallible, non-lossy conversion callers should prefer
    /// matching on `Positive::to_u64_checked()`.
    #[inline]
    fn from(value: Positive) -> Self {
        value.to_dec().to_u64().unwrap_or(0) as usize
    }
}

impl PartialEq<&Positive> for f64 {
    #[inline]
    fn eq(&self, other: &&Positive) -> bool {
        self == &other.0.to_f64().unwrap_or(0.0)
    }
}

impl PartialOrd<&Positive> for f64 {
    #[inline]
    fn partial_cmp(&self, other: &&Positive) -> Option<Ordering> {
        self.partial_cmp(&other.0.to_f64().unwrap_or(0.0))
    }
}

impl PartialEq<Positive> for f64 {
    #[inline]
    fn eq(&self, other: &Positive) -> bool {
        self == &other.0.to_f64().unwrap_or(0.0)
    }
}

impl PartialOrd<Positive> for f64 {
    #[inline]
    fn partial_cmp(&self, other: &Positive) -> Option<Ordering> {
        self.partial_cmp(&other.0.to_f64().unwrap_or(0.0))
    }
}

impl Mul<Positive> for f64 {
    type Output = f64;
    #[inline]
    fn mul(self, rhs: Positive) -> Self::Output {
        self * rhs.to_f64()
    }
}

impl Div<Positive> for f64 {
    type Output = f64;
    #[inline]
    fn div(self, rhs: Positive) -> Self::Output {
        self / rhs.to_f64()
    }
}

impl Sub<Positive> for f64 {
    type Output = f64;
    #[inline]
    fn sub(self, rhs: Positive) -> Self::Output {
        self - rhs.to_f64()
    }
}

impl Add<Positive> for f64 {
    type Output = f64;
    #[inline]
    fn add(self, rhs: Positive) -> Self::Output {
        self + rhs.to_f64()
    }
}

impl FromStr for Positive {
    type Err = String;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.parse::<Decimal>() {
            Ok(value) if is_valid_positive_value(value) => Ok(Positive(value)),
            Ok(value) => Err(format!("Value must be positive, got {value}")),
            Err(e) => Err(format!("Failed to parse as Decimal: {e}")),
        }
    }
}

impl TryFrom<f64> for Positive {
    type Error = PositiveError;

    /// Attempts to convert an f64 to a Positive value.
    ///
    /// # Errors
    ///
    /// Returns `PositiveError` if the value is negative, NaN, or cannot be converted to Decimal.
    fn try_from(value: f64) -> Result<Self, Self::Error> {
        Positive::new(value)
    }
}

impl TryFrom<usize> for Positive {
    type Error = PositiveError;

    /// Attempts to convert a usize to a Positive value.
    ///
    /// # Errors
    ///
    /// Returns `PositiveError` if the value cannot be converted to Decimal.
    fn try_from(value: usize) -> Result<Self, Self::Error> {
        Positive::new(value as f64)
    }
}

impl TryFrom<Decimal> for Positive {
    type Error = PositiveError;

    /// Attempts to convert a Decimal to a Positive value.
    ///
    /// # Errors
    ///
    /// Returns `PositiveError` if the value is negative.
    fn try_from(value: Decimal) -> Result<Self, Self::Error> {
        Positive::new_decimal(value)
    }
}

impl TryFrom<&Decimal> for Positive {
    type Error = PositiveError;

    /// Attempts to convert a &Decimal to a Positive value.
    ///
    /// # Errors
    ///
    /// Returns `PositiveError` if the value is negative.
    fn try_from(value: &Decimal) -> Result<Self, Self::Error> {
        Positive::new_decimal(*value)
    }
}

impl TryFrom<i64> for Positive {
    type Error = PositiveError;

    /// Attempts to convert an i64 to a Positive value.
    ///
    /// # Errors
    ///
    /// Returns `PositiveError` if the value is negative.
    fn try_from(value: i64) -> Result<Self, Self::Error> {
        Positive::new_decimal(Decimal::from(value))
    }
}

impl TryFrom<u64> for Positive {
    type Error = PositiveError;

    /// Attempts to convert a u64 to a Positive value.
    ///
    /// # Errors
    ///
    /// This conversion is infallible for u64 since all values are non-negative.
    fn try_from(value: u64) -> Result<Self, Self::Error> {
        Positive::new_decimal(Decimal::from(value))
    }
}

impl From<&Positive> for Positive {
    #[inline]
    fn from(value: &Positive) -> Self {
        Positive(value.0)
    }
}

impl Mul<f64> for Positive {
    type Output = Positive;
    #[inline]
    fn mul(self, rhs: f64) -> Positive {
        let rhs_dec = Decimal::from_f64(rhs).unwrap_or_else(|| invariant_panic("mul_f64"));
        let result = match self.0.checked_mul(rhs_dec) {
            Some(v) => v,
            None => overflow_panic("mul_f64"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("mul_f64")
        }
    }
}

impl Div<f64> for Positive {
    type Output = Positive;
    /// Divides by an `f64` using [`DIV_ROUNDING_STRATEGY`] (banker's
    /// rounding) when rounding is required. For a different strategy
    /// use [`Positive::checked_div_with_strategy`] on the lifted
    /// `Decimal`.
    #[inline]
    fn div(self, rhs: f64) -> Positive {
        let rhs_dec = Decimal::from_f64(rhs).unwrap_or_else(|| invariant_panic("div_f64"));
        if rhs_dec.is_zero() {
            invariant_panic("div_f64");
        }
        let result = match self.0.checked_div(rhs_dec) {
            Some(v) => round_div(v),
            None => overflow_panic("div_f64"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("div_f64")
        }
    }
}

impl Div<f64> for &Positive {
    type Output = Positive;
    /// Divides a `&Positive` by an `f64` using [`DIV_ROUNDING_STRATEGY`]
    /// (banker's rounding) when rounding is required.
    #[inline]
    fn div(self, rhs: f64) -> Positive {
        let rhs_dec = Decimal::from_f64(rhs).unwrap_or_else(|| invariant_panic("div_f64"));
        if rhs_dec.is_zero() {
            invariant_panic("div_f64");
        }
        let result = match self.0.checked_div(rhs_dec) {
            Some(v) => round_div(v),
            None => overflow_panic("div_f64"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("div_f64")
        }
    }
}

impl Sub<f64> for Positive {
    type Output = Positive;
    #[inline]
    fn sub(self, rhs: f64) -> Self::Output {
        let rhs_dec = Decimal::from_f64(rhs).unwrap_or_else(|| invariant_panic("sub_f64"));
        let result = match self.0.checked_sub(rhs_dec) {
            Some(v) => v,
            None => overflow_panic("sub_f64"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("sub_f64")
        }
    }
}

impl Add<f64> for Positive {
    type Output = Positive;
    #[inline]
    fn add(self, rhs: f64) -> Self::Output {
        let rhs_dec = Decimal::from_f64(rhs).unwrap_or_else(|| invariant_panic("add_f64"));
        let result = match self.0.checked_add(rhs_dec) {
            Some(v) => v,
            None => overflow_panic("add_f64"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("add_f64")
        }
    }
}

impl PartialOrd<f64> for Positive {
    #[inline]
    fn partial_cmp(&self, other: &f64) -> Option<Ordering> {
        self.0.to_f64().unwrap_or(0.0).partial_cmp(other)
    }
}

impl PartialEq<f64> for &Positive {
    #[inline]
    fn eq(&self, other: &f64) -> bool {
        self.0.to_f64().unwrap_or(0.0) == *other
    }
}

impl PartialOrd<f64> for &Positive {
    #[inline]
    fn partial_cmp(&self, other: &f64) -> Option<Ordering> {
        self.0.to_f64().unwrap_or(0.0).partial_cmp(other)
    }
}

impl PartialEq<f64> for Positive {
    #[inline]
    fn eq(&self, other: &f64) -> bool {
        self.to_f64() == *other
    }
}

impl Display for Positive {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if *self == Positive::INFINITY {
            return write!(f, "{}", f64::MAX);
        }
        if let Some(precision) = f.precision() {
            return write!(f, "{:.1$}", self.0, precision);
        }
        // `Decimal::normalize` strips trailing zeros past the decimal
        // point (e.g. `1.500` -> `1.5`, `5.00` -> `5`), which matches
        // the previous `to_string() + trim_end_matches('0')` approach
        // without allocating an intermediate `String`.
        write!(f, "{}", self.0.normalize())
    }
}

impl fmt::Debug for Positive {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if *self == Positive::INFINITY {
            return write!(f, "{}", f64::MAX);
        }
        // Same normalisation as `Display` so integer-valued decimals
        // render without trailing `.0` and fractional ones without
        // trailing zeros.
        write!(f, "{}", self.0.normalize())
    }
}

impl PartialEq<Decimal> for Positive {
    #[inline]
    fn eq(&self, other: &Decimal) -> bool {
        (self.0 - *other).abs() <= EPSILON_CMP
    }
}

// NOTE (#26): `#[serde(transparent)]` would delegate to `Decimal`'s
// default `Serialize`/`Deserialize`, which emits a JSON string (e.g.
// `"12.345"`). The manual impls below preserve a long-standing,
// downstream-visible JSON contract:
//   - `Positive::INFINITY` serialises to the literal `f64::MAX`.
//   - integer-valued `Positive`s serialise as JSON integers (`42`).
//   - fractional `Positive`s serialise as JSON numbers (`12.345`).
// Switching to `#[serde(transparent)]` would change the wire format
// and is therefore deferred. Duplicated validation inside the
// deserialiser is removed separately in #27.
impl Serialize for Positive {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        if *self == Positive::INFINITY {
            return serializer.serialize_f64(f64::MAX);
        }
        if self.0.scale() == 0 {
            serializer.serialize_i64(
                self.0
                    .to_i64()
                    .ok_or_else(|| serde::ser::Error::custom("Failed to convert to i64"))?,
            )
        } else {
            serializer.serialize_f64(
                self.0
                    .to_f64()
                    .ok_or_else(|| serde::ser::Error::custom("Failed to convert to f64"))?,
            )
        }
    }
}

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

        impl Visitor<'_> for PositiveVisitor {
            type Value = Positive;

            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
                formatter.write_str("a positive number")
            }

            fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
            where
                E: serde::de::Error,
            {
                Err(serde::de::Error::custom(format!(
                    "Invalid string: '{value}'. Expected a positive number."
                )))
            }

            fn visit_i64<E>(self, value: i64) -> Result<Self::Value, E>
            where
                E: serde::de::Error,
            {
                Positive::new_decimal(Decimal::from(value)).map_err(serde::de::Error::custom)
            }

            fn visit_u64<E>(self, value: u64) -> Result<Self::Value, E>
            where
                E: serde::de::Error,
            {
                Positive::new_decimal(Decimal::from(value)).map_err(serde::de::Error::custom)
            }

            fn visit_f64<E>(self, value: f64) -> Result<Self::Value, E>
            where
                E: serde::de::Error,
            {
                if value.is_infinite() && value.is_sign_positive() {
                    return Ok(Positive::INFINITY);
                }
                if value == f64::MAX {
                    return Ok(Positive::INFINITY);
                }
                let decimal = Decimal::from_f64(value)
                    .ok_or_else(|| serde::de::Error::custom("Failed to convert f64 to Decimal"))?;
                Positive::new_decimal(decimal).map_err(serde::de::Error::custom)
            }
        }

        deserializer.deserialize_any(PositiveVisitor)
    }
}

impl Add for Positive {
    type Output = Positive;
    #[inline]
    fn add(self, other: Positive) -> Positive {
        match self.0.checked_add(other.0) {
            Some(v) => Positive(v),
            None => overflow_panic("add"),
        }
    }
}

impl Sub for Positive {
    type Output = Positive;
    #[inline]
    fn sub(self, rhs: Self) -> Self::Output {
        let result = match self.0.checked_sub(rhs.0) {
            Some(v) => v,
            None => overflow_panic("sub"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("sub")
        }
    }
}

impl Div for Positive {
    type Output = Positive;
    /// Divides two `Positive` values using [`DIV_ROUNDING_STRATEGY`]
    /// (banker's rounding) when rounding is required. For a different
    /// strategy use [`Positive::checked_div_with_strategy`].
    #[inline]
    fn div(self, other: Positive) -> Self::Output {
        if other.0.is_zero() {
            invariant_panic("div");
        }
        match self.0.checked_div(other.0) {
            Some(v) => Positive(round_div(v)),
            None => overflow_panic("div"),
        }
    }
}

impl Div for &Positive {
    type Output = Positive;
    /// Divides two `&Positive` values using [`DIV_ROUNDING_STRATEGY`]
    /// (banker's rounding) when rounding is required.
    #[inline]
    fn div(self, other: &Positive) -> Self::Output {
        if other.0.is_zero() {
            invariant_panic("div");
        }
        match self.0.checked_div(other.0) {
            Some(v) => Positive(round_div(v)),
            None => overflow_panic("div"),
        }
    }
}

impl Add<Decimal> for Positive {
    type Output = Positive;
    #[inline]
    fn add(self, rhs: Decimal) -> Positive {
        let result = match self.0.checked_add(rhs) {
            Some(v) => v,
            None => overflow_panic("add_decimal"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("add_decimal")
        }
    }
}

impl Add<&Decimal> for Positive {
    type Output = Positive;
    #[inline]
    fn add(self, rhs: &Decimal) -> Self::Output {
        let result = match self.0.checked_add(*rhs) {
            Some(v) => v,
            None => overflow_panic("add_decimal"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("add_decimal")
        }
    }
}

impl Sub<Decimal> for Positive {
    type Output = Positive;
    #[inline]
    fn sub(self, rhs: Decimal) -> Positive {
        let result = match self.0.checked_sub(rhs) {
            Some(v) => v,
            None => overflow_panic("sub_decimal"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("sub_decimal")
        }
    }
}

impl Sub<&Decimal> for Positive {
    type Output = Positive;
    #[inline]
    fn sub(self, rhs: &Decimal) -> Self::Output {
        let result = match self.0.checked_sub(*rhs) {
            Some(v) => v,
            None => overflow_panic("sub_decimal"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("sub_decimal")
        }
    }
}

impl AddAssign for Positive {
    #[inline]
    fn add_assign(&mut self, other: Positive) {
        match self.0.checked_add(other.0) {
            Some(v) => self.0 = v,
            None => overflow_panic("add_assign"),
        }
    }
}

impl AddAssign<Decimal> for Positive {
    #[inline]
    fn add_assign(&mut self, rhs: Decimal) {
        let result = match self.0.checked_add(rhs) {
            Some(v) => v,
            None => overflow_panic("add_assign_decimal"),
        };
        if is_valid_positive_value(result) {
            self.0 = result;
        } else {
            invariant_panic("add_assign_decimal");
        }
    }
}

impl MulAssign<Decimal> for Positive {
    #[inline]
    fn mul_assign(&mut self, rhs: Decimal) {
        let result = match self.0.checked_mul(rhs) {
            Some(v) => v,
            None => overflow_panic("mul_assign_decimal"),
        };
        if is_valid_positive_value(result) {
            self.0 = result;
        } else {
            invariant_panic("mul_assign_decimal");
        }
    }
}

impl Div<Decimal> for Positive {
    type Output = Positive;
    /// Divides by a `Decimal` using [`DIV_ROUNDING_STRATEGY`] (banker's
    /// rounding) when rounding is required.
    #[inline]
    fn div(self, rhs: Decimal) -> Positive {
        if rhs.is_zero() {
            invariant_panic("div_decimal");
        }
        let result = match self.0.checked_div(rhs) {
            Some(v) => round_div(v),
            None => overflow_panic("div_decimal"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("div_decimal")
        }
    }
}

impl Div<&Decimal> for Positive {
    type Output = Positive;
    /// Divides by a `&Decimal` using [`DIV_ROUNDING_STRATEGY`] (banker's
    /// rounding) when rounding is required.
    #[inline]
    fn div(self, rhs: &Decimal) -> Self::Output {
        if rhs.is_zero() {
            invariant_panic("div_decimal");
        }
        let result = match self.0.checked_div(*rhs) {
            Some(v) => round_div(v),
            None => overflow_panic("div_decimal"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("div_decimal")
        }
    }
}

impl PartialOrd<Decimal> for Positive {
    #[inline]
    fn partial_cmp(&self, other: &Decimal) -> Option<Ordering> {
        self.0.partial_cmp(other)
    }
}

impl Mul for Positive {
    type Output = Positive;
    #[inline]
    fn mul(self, other: Positive) -> Positive {
        match self.0.checked_mul(other.0) {
            Some(v) => Positive(v),
            None => overflow_panic("mul"),
        }
    }
}

impl Mul<Decimal> for Positive {
    type Output = Positive;
    #[inline]
    fn mul(self, rhs: Decimal) -> Positive {
        let result = match self.0.checked_mul(rhs) {
            Some(v) => v,
            None => overflow_panic("mul_decimal"),
        };
        if is_valid_positive_value(result) {
            Positive(result)
        } else {
            invariant_panic("mul_decimal")
        }
    }
}

impl Mul<Positive> for Decimal {
    type Output = Decimal;
    #[inline]
    fn mul(self, rhs: Positive) -> Decimal {
        match self.checked_mul(rhs.0) {
            Some(v) => v,
            None => overflow_panic("mul_decimal_by_positive"),
        }
    }
}

impl Div<Positive> for Decimal {
    type Output = Decimal;
    #[inline]
    fn div(self, rhs: Positive) -> Decimal {
        if rhs.0.is_zero() {
            invariant_panic("div_decimal_by_positive");
        }
        match self.checked_div(rhs.0) {
            Some(v) => v,
            None => overflow_panic("div_decimal_by_positive"),
        }
    }
}

impl Sub<Positive> for Decimal {
    type Output = Decimal;
    #[inline]
    fn sub(self, rhs: Positive) -> Decimal {
        match self.checked_sub(rhs.0) {
            Some(v) => v,
            None => overflow_panic("sub_decimal_by_positive"),
        }
    }
}

impl Sub<&Positive> for Decimal {
    type Output = Decimal;
    #[inline]
    fn sub(self, rhs: &Positive) -> Decimal {
        match self.checked_sub(rhs.0) {
            Some(v) => v,
            None => overflow_panic("sub_decimal_by_positive"),
        }
    }
}

impl Add<Positive> for Decimal {
    type Output = Decimal;
    #[inline]
    fn add(self, rhs: Positive) -> Decimal {
        match self.checked_add(rhs.0) {
            Some(v) => v,
            None => overflow_panic("add_decimal_by_positive"),
        }
    }
}

impl Add<&Positive> for Decimal {
    type Output = Decimal;
    #[inline]
    fn add(self, rhs: &Positive) -> Decimal {
        match self.checked_add(rhs.0) {
            Some(v) => v,
            None => overflow_panic("add_decimal_by_positive"),
        }
    }
}

impl std::ops::AddAssign<Positive> for Decimal {
    #[inline]
    fn add_assign(&mut self, rhs: Positive) {
        match self.checked_add(rhs.0) {
            Some(v) => *self = v,
            None => overflow_panic("add_assign_decimal_by_positive"),
        }
    }
}

impl std::ops::AddAssign<&Positive> for Decimal {
    #[inline]
    fn add_assign(&mut self, rhs: &Positive) {
        match self.checked_add(rhs.0) {
            Some(v) => *self = v,
            None => overflow_panic("add_assign_decimal_by_positive"),
        }
    }
}

impl std::ops::MulAssign<Positive> for Decimal {
    #[inline]
    fn mul_assign(&mut self, rhs: Positive) {
        match self.checked_mul(rhs.0) {
            Some(v) => *self = v,
            None => overflow_panic("mul_assign_decimal_by_positive"),
        }
    }
}

impl std::ops::MulAssign<&Positive> for Decimal {
    #[inline]
    fn mul_assign(&mut self, rhs: &Positive) {
        match self.checked_mul(rhs.0) {
            Some(v) => *self = v,
            None => overflow_panic("mul_assign_decimal_by_positive"),
        }
    }
}

impl PartialEq<Positive> for Decimal {
    #[inline]
    fn eq(&self, other: &Positive) -> bool {
        *self == other.0
    }
}

impl From<&Positive> for Decimal {
    #[inline]
    fn from(pos: &Positive) -> Self {
        pos.0
    }
}

#[cfg(not(feature = "non-zero"))]
impl Default for Positive {
    fn default() -> Self {
        Positive::ZERO
    }
}

#[cfg(feature = "non-zero")]
impl Default for Positive {
    fn default() -> Self {
        Positive::ONE
    }
}

impl AbsDiffEq for Positive {
    type Epsilon = Decimal;

    fn default_epsilon() -> Self::Epsilon {
        EPSILON
    }

    fn abs_diff_eq(&self, other: &Self, epsilon: Self::Epsilon) -> bool {
        (self.0 - other.0).abs() <= epsilon
    }
}

impl RelativeEq for Positive {
    fn default_max_relative() -> Self::Epsilon {
        EPSILON_CMP
    }

    fn relative_eq(
        &self,
        other: &Self,
        epsilon: Self::Epsilon,
        max_relative: Self::Epsilon,
    ) -> bool {
        let abs_diff = (self.0 - other.0).abs();
        let largest = self.0.abs().max(other.0.abs());
        abs_diff <= epsilon || abs_diff <= max_relative * largest
    }
}

#[cfg(not(feature = "non-zero"))]
impl Sum for Positive {
    fn sum<I: Iterator<Item = Self>>(iter: I) -> Self {
        let sum = iter.fold(Decimal::ZERO, |acc, x| acc + x.value());
        Positive::new_decimal(sum).unwrap_or(Positive::ZERO)
    }
}

#[cfg(not(feature = "non-zero"))]
impl<'a> Sum<&'a Positive> for Positive {
    fn sum<I: Iterator<Item = &'a Positive>>(iter: I) -> Self {
        let sum = iter.fold(Decimal::ZERO, |acc, x| acc + x.value());
        Positive::new_decimal(sum).unwrap_or(Positive::ZERO)
    }
}