Struct Positive 

pub struct Positive(/* private fields */);

Positive, the non-negative decimal newtype, its error and the is_positive::<T>() type check. Defined by the standalone positive crate and re-exported unchanged: a value obtained through this path is a positive::Positive (see the crate-level “Foundational types” table). 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).

For values that must be strictly greater than zero, use StrictlyPositive.

Implementations

impl Positive

pub const ZERO: Positive = crate::constants::ZERO

A zero value represented as a Positive value.

pub const ONE: Positive = crate::constants::ONE

A value of one represented as a Positive value.

pub const TWO: Positive = crate::constants::TWO

A value of two represented as a Positive value.

pub const THREE: Positive = crate::constants::THREE

A value of three represented as a Positive value.

pub const FOUR: Positive = crate::constants::FOUR

A value of four represented as a Positive value.

pub const FIVE: Positive = crate::constants::FIVE

A value of five represented as a Positive value.

pub const SIX: Positive = crate::constants::SIX

A value of six represented as a Positive value.

pub const SEVEN: Positive = crate::constants::SEVEN

A value of seven represented as a Positive value.

pub const EIGHT: Positive = crate::constants::EIGHT

A value of eight represented as a Positive value.

pub const NINE: Positive = crate::constants::NINE

A value of nine represented as a Positive value.

pub const TEN: Positive = crate::constants::TEN

A value of ten represented as a Positive value.

pub const FIFTEEN: Positive = crate::constants::FIFTEEN

A value of fifteen represented as a Positive value.

pub const TWENTY: Positive = crate::constants::TWENTY

A value of twenty represented as a Positive value.

pub const TWENTY_FIVE: Positive = crate::constants::TWENTY_FIVE

A value of twenty-five represented as a Positive value.

pub const THIRTY: Positive = crate::constants::THIRTY

A value of thirty represented as a Positive value.

pub const THIRTY_FIVE: Positive = crate::constants::THIRTY_FIVE

A value of thirty-five represented as a Positive value.

pub const FORTY: Positive = crate::constants::FORTY

A value of forty represented as a Positive value.

pub const FORTY_FIVE: Positive = crate::constants::FORTY_FIVE

A value of forty-five represented as a Positive value.

pub const FIFTY: Positive = crate::constants::FIFTY

A value of fifty represented as a Positive value.

pub const FIFTY_FIVE: Positive = crate::constants::FIFTY_FIVE

A value of fifty-five represented as a Positive value.

pub const SIXTY: Positive = crate::constants::SIXTY

A value of sixty represented as a Positive value.

pub const SIXTY_FIVE: Positive = crate::constants::SIXTY_FIVE

A value of sixty-five represented as a Positive value.

pub const SEVENTY: Positive = crate::constants::SEVENTY

A value of seventy represented as a Positive value.

pub const SEVENTY_FIVE: Positive = crate::constants::SEVENTY_FIVE

A value of seventy-five represented as a Positive value.

pub const EIGHTY: Positive = crate::constants::EIGHTY

A value of eighty represented as a Positive value.

pub const EIGHTY_FIVE: Positive = crate::constants::EIGHTY_FIVE

A value of eighty-five represented as a Positive value.

pub const NINETY: Positive = crate::constants::NINETY

A value of ninety represented as a Positive value.

pub const NINETY_FIVE: Positive = crate::constants::NINETY_FIVE

A value of ninety-five represented as a Positive value.

pub const HUNDRED: Positive = crate::constants::HUNDRED

A value of one hundred represented as a Positive value.

pub const TWO_HUNDRED: Positive = crate::constants::TWO_HUNDRED

A value of two hundred represented as a Positive value.

pub const THREE_HUNDRED: Positive = crate::constants::THREE_HUNDRED

A value of three hundred represented as a Positive value.

pub const FOUR_HUNDRED: Positive = crate::constants::FOUR_HUNDRED

A value of four hundred represented as a Positive value.

pub const FIVE_HUNDRED: Positive = crate::constants::FIVE_HUNDRED

A value of five hundred represented as a Positive value.

pub const SIX_HUNDRED: Positive = crate::constants::SIX_HUNDRED

A value of six hundred represented as a Positive value.

pub const SEVEN_HUNDRED: Positive = crate::constants::SEVEN_HUNDRED

A value of seven hundred represented as a Positive value.

pub const EIGHT_HUNDRED: Positive = crate::constants::EIGHT_HUNDRED

A value of eight hundred represented as a Positive value.

pub const NINE_HUNDRED: Positive = crate::constants::NINE_HUNDRED

A value of nine hundred represented as a Positive value.

pub const THOUSAND: Positive = crate::constants::THOUSAND

A value of one thousand represented as a Positive value.

pub const TWO_THOUSAND: Positive = crate::constants::TWO_THOUSAND

A value of two thousand represented as a Positive value.

pub const THREE_THOUSAND: Positive = crate::constants::THREE_THOUSAND

A value of three thousand represented as a Positive value.

pub const FOUR_THOUSAND: Positive = crate::constants::FOUR_THOUSAND

A value of four thousand represented as a Positive value.

pub const FIVE_THOUSAND: Positive = crate::constants::FIVE_THOUSAND

A value of five thousand represented as a Positive value.

pub const SIX_THOUSAND: Positive = crate::constants::SIX_THOUSAND

A value of six thousand represented as a Positive value.

pub const SEVEN_THOUSAND: Positive = crate::constants::SEVEN_THOUSAND

A value of seven thousand represented as a Positive value.

pub const EIGHT_THOUSAND: Positive = crate::constants::EIGHT_THOUSAND

A value of eight thousand represented as a Positive value.

pub const NINE_THOUSAND: Positive = crate::constants::NINE_THOUSAND

A value of nine thousand represented as a Positive value.

pub const TEN_THOUSAND: Positive = crate::constants::TEN_THOUSAND

A value of ten thousand represented as a Positive value.

pub const PI: Positive = crate::constants::PI

The mathematical constant π (pi) represented as a Positive value.

pub const E: Positive = crate::constants::E

The mathematical constant e (Euler’s number) represented as a Positive value.

pub const MAX: Positive = crate::constants::MAX

The largest value a Positive can hold: Decimal::MAX (79,228,162,514,264,337,593,543,950,335).

Mirrors crate::constants::MAX. This is a real maximum, not an infinity — Decimal has no infinite value — and every operation treats it as the finite number it is.

pub const INFINITY: Positive = crate::constants::INFINITY

👎Deprecated since 0.6.0:

renamed to Positive::MAX: the value is Decimal::MAX, not an infinity

Represents the maximum positive value possible (effectively infinity).

Deprecated

Use Positive::MAX. Same value, accurate name; see the constant’s documentation for why the old one was misleading.

pub const DAYS_IN_A_YEAR: Positive = crate::constants::DAYS_IN_A_YEAR

Number of days in a year, in days (365, ignoring leap years).

Mirrors crate::constants::DAYS_IN_A_YEAR. Use this for day-count conventions that assume a fixed 365-day year, such as ACT/365.

pub fn new(value: f64) -> Result<Positive, PositiveError>

Creates a new Positive value from a 64-bit floating-point number.

Values >= 0 are accepted.

Errors

Returns PositiveError::InvalidValue when value is NaN or infinite, PositiveError::ConversionError when it is finite but outside the range Decimal can represent, and PositiveError::OutOfBounds when it converts cleanly but breaks the positivity invariant. The OutOfBounds bounds are exact Decimal values: 0 and Decimal::MAX.

Examples

use positive::{Positive, PositiveError};

assert!(Positive::new(1.5).is_ok());
assert!(matches!(
    Positive::new(-1.0).unwrap_err(),
    PositiveError::OutOfBounds { .. }
));
assert!(matches!(
    Positive::new(f64::NAN).unwrap_err(),
    PositiveError::InvalidValue { .. }
));

pub fn new_decimal(value: Decimal) -> Result<Positive, PositiveError>

Creates a new Positive value directly from a Decimal.

Values >= 0 are accepted.

Errors

Returns PositiveError::OutOfBounds when value breaks the positivity invariant. The reported value and both bounds are exact Decimals, so no precision is lost in the diagnostic.

Examples

use positive::{Positive, PositiveError};
use rust_decimal_macros::dec;

assert!(Positive::new_decimal(dec!(1.5)).is_ok());
assert!(matches!(
    Positive::new_decimal(dec!(-1)).unwrap_err(),
    PositiveError::OutOfBounds { .. }
));

pub fn value(&self) -> Decimal

Returns the inner Decimal value.

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

assert_eq!(pos_or_panic!(2.5).value(), dec!(2.5));

pub fn to_dec(&self) -> Decimal

Returns the inner Decimal value (alias for value()).

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

assert_eq!(pos_or_panic!(2.5).to_dec(), dec!(2.5));

pub fn to_dec_ref(&self) -> &Decimal

Returns the inner Decimal ref.

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

let value = pos_or_panic!(2.5);
assert_eq!(*value.to_dec_ref(), dec!(2.5));

pub fn to_f64(&self) -> f64

Converts the value to a 64-bit floating-point number.

This conversion is infallible. rust_decimal implements Decimal::to_f64 as Some(self.as_f64()), and as_f64 always produces a value; calling as_f64 directly encodes that fact in the signature instead of asserting it at runtime with an expect, which is what earlier versions did.

It is still lossy: f64 carries about 15 significant digits, so magnitudes beyond 2^53 and fractions beyond that precision are rounded. Use Positive::to_dec when precision matters.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(2.5).to_f64(), 2.5);

pub fn to_f64_checked(&self) -> Option<f64>

Converts the value to f64, returning None if conversion fails.

Retained for source compatibility; it always returns Some, because the conversion cannot fail. Prefer Positive::to_f64.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(2.5).to_f64_checked(), Some(2.5));

pub fn to_f64_lossy(&self) -> f64

👎Deprecated since 0.6.0:

to_f64 is infallible and returns the same value; this alias will be removed after 0.6.0

Converts the value to f64 with lossy conversion (returns 0.0 on failure).

Deprecated

There is no failure case to fall back from: Positive::to_f64 is infallible and returns the same value.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(2.5).to_f64_lossy(), 2.5);

pub fn to_i64(&self) -> i64

👎Deprecated since 0.6.0:

panics for valid values above i64::MAX; use i64::try_from(value) or to_i64_checked

Converts the value to a 64-bit signed integer, truncating any fraction.

Deprecated

This method panics for values that are perfectly valid Positives but exceed i64::MAX. Use i64::try_from(positive) for a typed error, or Positive::to_i64_checked for an Option.

Panics

Panics when the truncated value does not fit in an i64.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(42.9).to_i64(), 42);

pub fn to_i64_checked(&self) -> Option<i64>

Converts the value to i64, returning None if it does not fit.

Any fraction is truncated toward zero.

Examples

use positive::{Positive, pos_or_panic};
use rust_decimal::Decimal;

assert_eq!(pos_or_panic!(42.9).to_i64_checked(), Some(42));
assert_eq!(Positive::MAX.to_i64_checked(), None);

pub fn to_u64(&self) -> u64

👎Deprecated since 0.6.0:

panics for valid values above u64::MAX; use u64::try_from(value) or to_u64_checked

Converts the inner value to a u64, truncating any fraction.

Deprecated

This method panics for values that are perfectly valid Positives but exceed u64::MAX. Use u64::try_from(positive) for a typed error, or Positive::to_u64_checked for an Option.

Panics

Panics when the truncated value does not fit in a u64.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(42.9).to_u64(), 42);

pub fn to_u64_checked(&self) -> Option<u64>

Converts the value to u64, returning None if it does not fit.

Any fraction is truncated toward zero.

Examples

use positive::{Positive, pos_or_panic};

assert_eq!(pos_or_panic!(42.9).to_u64_checked(), Some(42));
assert_eq!(Positive::MAX.to_u64_checked(), None);

pub fn to_usize(&self) -> usize

👎Deprecated since 0.6.0:

panics for valid values above usize::MAX; use usize::try_from(value) or to_usize_checked

Converts the value to a usize, truncating any fraction.

Deprecated

This method panics for values that are perfectly valid Positives but exceed usize::MAX. Use usize::try_from(positive) for a typed error, or Positive::to_usize_checked for an Option.

Panics

Panics when the truncated value does not fit in a usize.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(42.9).to_usize(), 42);

pub fn to_usize_checked(&self) -> Option<usize>

Converts the value to usize, returning None if it does not fit.

Any fraction is truncated toward zero.

Examples

use positive::{Positive, pos_or_panic};

assert_eq!(pos_or_panic!(42.9).to_usize_checked(), Some(42));
assert_eq!(Positive::MAX.to_usize_checked(), None);

pub fn max(self, other: Positive) -> Positive

Returns the maximum of two Positive values.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(2.0).max(pos_or_panic!(5.0)), pos_or_panic!(5.0));

pub fn min(self, other: Positive) -> Positive

Returns the minimum of two Positive values.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(2.0).min(pos_or_panic!(5.0)), pos_or_panic!(2.0));

pub fn floor(&self) -> Positive

Rounds the value down to the nearest integer.

Panics

The floor of a non-negative value is non-negative, so this method cannot panic in practice. Positive::checked_floor is the Result-returning form.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(1.9).floor(), pos_or_panic!(1.0));

pub fn checked_floor(&self) -> Result<Positive, PositiveError>

Rounds the value down to the nearest integer, returning an error instead of panicking.

Errors

Returns PositiveError::OutOfBounds when the floored result would break the positivity invariant.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(1.9).checked_floor().unwrap(), pos_or_panic!(1.0));

pub fn powi(&self, n: i64) -> Positive

Raises this value to an integer power.

Panics

Panics when the power cannot be computed — for example a zero base with a negative exponent — or when the result would break the positivity invariant. Use Positive::checked_powi for the non-panicking form.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(2.0).powi(3), pos_or_panic!(8.0));

pub fn checked_powi(&self, n: i64) -> Result<Positive, PositiveError>

Raises this value to an integer power, returning an error instead of panicking.

Errors

Returns PositiveError::ArithmeticError when the power is outside the domain — a zero base with a negative exponent — or overflows, and PositiveError::OutOfBounds when the result would break the positivity invariant.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(2.0).checked_powi(3).unwrap(), pos_or_panic!(8.0));

pub fn pow(&self, n: Positive) -> Positive

Computes the result of raising the current value to the power of the given exponent.

Panics

Panics when the power cannot be computed or the result would break the positivity invariant. Use Positive::checked_pow for the non-panicking form.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(2.0).pow(pos_or_panic!(3.0)), pos_or_panic!(8.0));

pub fn checked_pow(&self, n: Positive) -> Result<Positive, PositiveError>

Raises this value to a Positive power, returning an error instead of panicking.

Errors

Returns PositiveError::ArithmeticError when the power is outside the domain or overflows, and PositiveError::OutOfBounds when the result would break the positivity invariant.

Examples

use positive::pos_or_panic;

let value = pos_or_panic!(2.0);
assert_eq!(value.checked_pow(pos_or_panic!(3.0)).unwrap(), pos_or_panic!(8.0));

pub fn powu(&self, n: u64) -> Positive

Raises the current value to the power of n using unsigned integer exponentiation.

Panics

Panics when the power overflows or the result would break the positivity invariant. Use Positive::checked_powu for the non-panicking form.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(2.0).powu(3), pos_or_panic!(8.0));

pub fn checked_powu(&self, n: u64) -> Result<Positive, PositiveError>

Raises this value to an unsigned integer power, returning an error instead of panicking.

Errors

Returns PositiveError::ArithmeticError when the power overflows and PositiveError::OutOfBounds when the result would break the positivity invariant, which cannot happen for a non-negative base.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(2.0).checked_powu(3).unwrap(), pos_or_panic!(8.0));

pub fn powd(&self, p0: Decimal) -> Positive

Raises this value to a decimal power.

Panics

Panics when the power cannot be computed or the result would break the positivity invariant. Use Positive::checked_powd for the non-panicking form.

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

assert_eq!(pos_or_panic!(2.0).powd(dec!(3)), pos_or_panic!(8.0));

pub fn checked_powd(&self, p0: Decimal) -> Result<Positive, PositiveError>

Raises this value to a decimal power, returning an error instead of panicking.

Errors

Returns PositiveError::ArithmeticError when the power is outside the domain or overflows, and PositiveError::OutOfBounds when the result would break the positivity invariant.

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

assert_eq!(pos_or_panic!(2.0).checked_powd(dec!(3)).unwrap(), pos_or_panic!(8.0));

pub fn round(&self) -> Positive

Rounds the value to the nearest integer.

Panics

Rounding a non-negative value yields a non-negative value, so this method cannot panic in practice. Positive::checked_round is the Result-returning form.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(1.6).round(), pos_or_panic!(2.0));

pub fn checked_round(&self) -> Result<Positive, PositiveError>

Rounds the value to the nearest integer, returning an error instead of panicking.

Errors

Returns PositiveError::OutOfBounds when the rounded result would break the positivity invariant.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(1.6).checked_round().unwrap(), pos_or_panic!(2.0));

pub fn round_to_nice_number(&self) -> Positive

Rounds the current value to a “nice” number, based on its magnitude.

The magnitude is computed entirely in Decimal. Routing it through Positive — as earlier versions did — meant the intermediate magnitude was clamped at zero for every input below ten, and that the final scaling went through magnitude.to_u64(), which cannot represent the negative magnitude of an input below one.

A zero input maps to zero: it is already the nicest number at its own magnitude, and log10(0) is undefined so there is nothing else to compute.

Panics

Panics when the scaled result overflows Decimal or breaks the positivity invariant. Use Positive::checked_round_to_nice_number for the non-panicking form.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(4.0).round_to_nice_number(), pos_or_panic!(5.0));
assert_eq!(pos_or_panic!(0.12).round_to_nice_number(), pos_or_panic!(0.1));

pub fn checked_round_to_nice_number(&self) -> Result<Positive, PositiveError>

Rounds to a “nice” number, returning an error instead of panicking.

Errors

Returns PositiveError::ArithmeticError when the magnitude cannot be computed or the scaled result overflows, and PositiveError::OutOfBounds when the result would break the positivity invariant.

Examples

use positive::pos_or_panic;

assert_eq!(
    pos_or_panic!(4.0).checked_round_to_nice_number().unwrap(),
    pos_or_panic!(5.0)
);
assert_eq!(
    pos_or_panic!(0.12).checked_round_to_nice_number().unwrap(),
    pos_or_panic!(0.1)
);

pub fn sqrt(&self) -> Positive

Calculates the square root of the value.

Panics

Panics when the square root cannot be computed, or when the result would break the positivity invariant. Use Positive::checked_sqrt for the non-panicking form.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(16.0).sqrt(), pos_or_panic!(4.0));

pub fn checked_sqrt(&self) -> Result<Positive, PositiveError>

Calculates the square root, returning an error instead of panicking.

Errors

Returns PositiveError::ArithmeticError when the square root cannot be computed, and PositiveError::OutOfBounds when the result would break the positivity invariant.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(16.0).checked_sqrt().unwrap(), pos_or_panic!(4.0));

pub fn sqrt_checked(&self) -> Result<Positive, PositiveError>

👎Deprecated since 0.6.0:

renamed to checked_sqrt for consistency with the rest of the checked API

Calculates the square root, returning an error if it fails.

Errors

See Positive::checked_sqrt.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(16.0).sqrt_checked().unwrap(), pos_or_panic!(4.0));

pub fn ln(&self) -> Decimal

Calculates the natural logarithm of the value.

Returns a Decimal, not a Positive: the logarithm of a positive number is not itself necessarily positive. ln(0.5) is -0.693…, and earlier versions returned that inside a Positive, silently breaking the type’s central guarantee.

Panics

Panics for a zero input, for which the natural logarithm is undefined. Use Positive::checked_ln for the non-panicking form.

Examples

use positive::pos_or_panic;
use rust_decimal::Decimal;

let half = pos_or_panic!(0.5);
assert!(half.ln() < Decimal::ZERO);

pub fn checked_ln(&self) -> Result<Decimal, PositiveError>

Calculates the natural logarithm, returning an error instead of panicking.

Errors

Returns PositiveError::ArithmeticError when the logarithm is undefined for the value — that is, for zero.

Examples

use positive::{Positive, PositiveError};

assert!(Positive::ONE.checked_ln().unwrap().is_zero());

pub fn log10(&self) -> Decimal

Computes the base-10 logarithm of the value.

Returns a Decimal, not a Positive, for the same reason as Positive::ln: log10(0.5) is -0.301….

Panics

Panics for a zero input, for which the logarithm is undefined. Use Positive::checked_log10 for the non-panicking form.

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

assert_eq!(pos_or_panic!(100.0).log10(), dec!(2));

pub fn checked_log10(&self) -> Result<Decimal, PositiveError>

Computes the base-10 logarithm, returning an error instead of panicking.

Errors

Returns PositiveError::ArithmeticError when the logarithm is undefined for the value — that is, for zero.

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

assert_eq!(pos_or_panic!(100.0).checked_log10().unwrap(), dec!(2));

pub fn round_to(&self, decimal_places: u32) -> Positive

Rounds the value to a specified number of decimal places.

Panics

Panics when decimal_places exceeds 28, the largest scale Decimal supports. Rounding a non-negative value always yields a non-negative value, so the invariant itself cannot fail. Use Positive::checked_round_to for the non-panicking form.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(1.2345).round_to(2), pos_or_panic!(1.23));

pub fn checked_round_to( &self, decimal_places: u32, ) -> Result<Positive, PositiveError>

Rounds to a specified number of decimal places, returning an error instead of panicking.

Errors

Returns PositiveError::OutOfBounds when the rounded result would break the positivity invariant.

Examples

use positive::pos_or_panic;

assert_eq!(
    pos_or_panic!(1.2345).checked_round_to(2).unwrap(),
    pos_or_panic!(1.23)
);

pub fn format_fixed_places(&self, decimal_places: u32) -> String

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.

Allocation

The returned String is at most a few dozen bytes, because decimal_places is validated against Decimal::MAX_SCALE (28) before any allocation happens. Earlier versions passed the argument straight through to format!, so format_fixed_places(u32::MAX) asked for a four-billion-character string and aborted the process on allocation failure — a denial of service reachable from user or config input.

Panics

Panics when decimal_places exceeds 28. Use Positive::checked_format_fixed_places for the non-panicking form.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(1.2345).format_fixed_places(2), "1.23");

pub fn checked_format_fixed_places( &self, decimal_places: u32, ) -> Result<String, PositiveError>

Formats the value with a fixed number of decimal places, returning an error instead of panicking.

Errors

Returns PositiveError::InvalidPrecision when decimal_places exceeds the 28 places Decimal supports. The check runs before any rounding or allocation, so an absurd precision costs nothing.

Examples

use positive::{PositiveError, pos_or_panic};

let value = pos_or_panic!(1.2345);
assert_eq!(value.checked_format_fixed_places(2).unwrap(), "1.23");
assert!(matches!(
    value.checked_format_fixed_places(u32::MAX).unwrap_err(),
    PositiveError::InvalidPrecision { .. }
));

pub fn exp(&self) -> Positive

Calculates the exponential function e^x for this value.

The result is always at least one, so it can never break the positivity invariant; only overflow can fail.

Panics

Panics when the result overflows Decimal. Use Positive::checked_exp for the non-panicking form.

Examples

use positive::Positive;

assert!(Positive::ONE.exp() > positive::pos_or_panic!(2.7));

pub fn checked_exp(&self) -> Result<Positive, PositiveError>

Calculates e^x, returning an error instead of panicking.

Errors

Returns PositiveError::ArithmeticError when the result overflows Decimal, which happens for inputs well below one hundred.

Examples

use positive::{Positive, PositiveError, pos_or_panic};

assert!(Positive::ONE.checked_exp().is_ok());
assert!(matches!(
    pos_or_panic!(1000.0).checked_exp().unwrap_err(),
    PositiveError::ArithmeticError { .. }
));

pub fn clamp(self, min: Positive, max: Positive) -> Positive

Clamps the value between a minimum and maximum.

Takes self by value. With a &self receiver — as earlier versions had — Rust’s method resolution preferred Ord::clamp for any owned Positive, because that one needs no autoref. The crate’s own clamp was therefore only reachable through a reference, and the two disagreed on inverted ranges: Ord::clamp asserted, this one silently returned a bound. Taking self makes the inherent method win uniformly, so there is one contract regardless of how the receiver is written.

Panics

Panics when min > max. The standard clamp contract treats an inverted range as a caller bug, and this method follows it. The reference path used to return whichever bound the if/else chain reached first, so the same impossible interval produced min for a low input and max for a high one, with nothing to tell the caller.

Use Positive::checked_clamp for the non-panicking form.

Examples

use positive::pos_or_panic;

let value = pos_or_panic!(7.0);
assert_eq!(value.clamp(pos_or_panic!(1.0), pos_or_panic!(5.0)), pos_or_panic!(5.0));
assert_eq!(value.clamp(pos_or_panic!(8.0), pos_or_panic!(10.0)), pos_or_panic!(8.0));
assert_eq!(value.clamp(pos_or_panic!(1.0), pos_or_panic!(10.0)), value);

pub fn checked_clamp( self, min: Positive, max: Positive, ) -> Result<Positive, PositiveError>

Clamps the value between a minimum and maximum, returning an error instead of panicking on an inverted range.

Equal bounds are valid and collapse the interval to a single value.

Errors

Returns PositiveError::OutOfBounds when min > max. The error carries the offending bounds as exact Decimals: value is the requested min, with min/max describing the range it had to fall within to be a valid lower bound.

Examples

use positive::{PositiveError, pos_or_panic};

let value = pos_or_panic!(7.0);
assert_eq!(
    value.checked_clamp(pos_or_panic!(1.0), pos_or_panic!(5.0)).unwrap(),
    pos_or_panic!(5.0)
);
assert!(matches!(
    value.checked_clamp(pos_or_panic!(10.0), pos_or_panic!(1.0)).unwrap_err(),
    PositiveError::OutOfBounds { .. }
));

pub fn is_zero(&self) -> bool

Checks if the value is exactly zero.

Examples

use positive::{Positive, pos_or_panic};

assert!(!pos_or_panic!(2.5).is_zero());

pub fn approx_eq_dec(&self, other: Decimal, epsilon: Decimal) -> bool

Compares this value with a Decimal within an absolute tolerance.

== against a Decimal is exact. This is the explicitly named approximate comparison that replaces the epsilon behaviour == used to have implicitly — implicitly, and asymmetrically, since the reverse comparison was exact.

The subtraction is checked, so operands at opposite extremes of Decimal’s range report “not close” instead of panicking.

For Positive-to-Positive approximate comparison use the approx traits (AbsDiffEq / RelativeEq), which this crate implements.

Examples

use positive::{constants::EPSILON_CMP, pos_or_panic};
use rust_decimal_macros::dec;

let value = pos_or_panic!(1.0);
assert!(value.approx_eq_dec(dec!(1.000000000000005), EPSILON_CMP));
assert!(!value.approx_eq_dec(dec!(1.1), EPSILON_CMP));
// exact equality disagrees, which is the point of having both
assert!(value != dec!(1.000000000000005));

pub fn ceiling(&self) -> Positive

Returns the smallest integer greater than or equal to the value.

Panics

Panics when the result would break the positivity invariant. For a value that already satisfies the invariant the ceiling always does too, so in practice this method does not panic; the check is present so no Positive-returning path can bypass validation. Use Positive::checked_ceiling for the non-panicking form.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(1.1).ceiling(), pos_or_panic!(2.0));

pub fn checked_ceiling(&self) -> Result<Positive, PositiveError>

Returns the ceiling, returning an error instead of panicking.

Errors

Returns PositiveError::OutOfBounds when the result would break the positivity invariant.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(1.1).checked_ceiling().unwrap(), pos_or_panic!(2.0));

pub fn sub_or_zero(&self, other: &Decimal) -> Positive

👎Deprecated since 0.5.1:

saturating arithmetic hides underflow and overflow; use checked_sub or checked_sub_dec and handle the error, or explicitly floor at zero with new_decimal(self.0.saturating_sub(*other)). Removal is scheduled for the release after 0.6.0

Subtracts a decimal value, returning zero if the result would be negative.

Panics

Panics when the subtraction overflows Decimal — a strictly positive difference too large to represent is an overflow, not a negative one, and flooring it at zero would silently corrupt the result. Use Positive::checked_sub_dec for the non-panicking form.

Examples

use positive::{Positive, pos_or_panic};
use rust_decimal_macros::dec;

assert_eq!(pos_or_panic!(5.0).sub_or_zero(&dec!(2)), pos_or_panic!(3.0));
assert_eq!(pos_or_panic!(5.0).sub_or_zero(&dec!(9)), Positive::ZERO);

pub fn sub_or_none(&self, other: &Decimal) -> Option<Positive>

Subtracts a decimal value, returning None if the result would be negative.

Also returns None when the subtraction would overflow Decimal, so this method cannot panic for any input.

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

assert_eq!(pos_or_panic!(5.0).sub_or_none(&dec!(2)), Some(pos_or_panic!(3.0)));
assert_eq!(pos_or_panic!(5.0).sub_or_none(&dec!(9)), None);

pub fn checked_add(&self, rhs: &Positive) -> Result<Positive, PositiveError>

Checked addition of two Positive values.

This is the non-panicking counterpart of the + operator.

Errors

Returns PositiveError::ArithmeticError when the sum overflows Decimal, and PositiveError::OutOfBounds when the result would break the positivity invariant.

Examples

use positive::{Positive, PositiveError, pos_or_panic};
use rust_decimal::Decimal;

let a = pos_or_panic!(2.0);
assert_eq!(a.checked_add(&pos_or_panic!(3.0)).unwrap(), pos_or_panic!(5.0));

let max = Positive::new_decimal(Decimal::MAX).unwrap();
assert!(matches!(
    max.checked_add(&Positive::ONE).unwrap_err(),
    PositiveError::ArithmeticError { .. }
));

pub fn checked_mul(&self, rhs: &Positive) -> Result<Positive, PositiveError>

Checked multiplication of two Positive values.

This is the non-panicking counterpart of the * operator.

Errors

Returns PositiveError::ArithmeticError when the product overflows Decimal, and PositiveError::OutOfBounds when the result would break the positivity invariant, which cannot happen for two non-negative operands.

Examples

use positive::{Positive, PositiveError, pos_or_panic};
use rust_decimal::Decimal;

let a = pos_or_panic!(4.0);
assert_eq!(a.checked_mul(&pos_or_panic!(2.5)).unwrap(), pos_or_panic!(10.0));

let max = Positive::new_decimal(Decimal::MAX).unwrap();
assert!(matches!(
    max.checked_mul(&Positive::TWO).unwrap_err(),
    PositiveError::ArithmeticError { .. }
));

pub fn checked_sub(&self, rhs: &Positive) -> Result<Positive, PositiveError>

Checked subtraction that returns a Result instead of panicking.

This is the non-panicking counterpart of the - operator.

Errors

Returns PositiveError::ArithmeticError when the difference overflows Decimal, and PositiveError::OutOfBounds when the result would be negative.

Examples

use positive::{PositiveError, pos_or_panic};

let a = pos_or_panic!(5.0);
assert_eq!(a.checked_sub(&pos_or_panic!(2.0)).unwrap(), pos_or_panic!(3.0));
assert!(matches!(
    a.checked_sub(&pos_or_panic!(9.0)).unwrap_err(),
    PositiveError::OutOfBounds { .. }
));

pub fn saturating_sub(&self, rhs: &Positive) -> Positive

👎Deprecated since 0.6.0:

saturating arithmetic hides underflow; use checked_sub and handle the error, or sub_or_zero to floor at zero explicitly. Removal is scheduled for the release after 0.6.0

Saturating subtraction that returns ZERO instead of negative.

Deprecated

rules/global_rules.md forbids saturating arithmetic: silently clamping an underflow to zero is indistinguishable from a genuine zero result, which in financial arithmetic is data corruption rather than a convenience. Use Positive::checked_sub and handle the error, or Positive::sub_or_zero if flooring at zero is genuinely what the caller wants and the intent should be visible at the call site.

Scheduled for removal in the release following 0.6.0.

Examples

use positive::{Positive, pos_or_panic};

assert_eq!(
    pos_or_panic!(5.0).saturating_sub(&pos_or_panic!(9.0)),
    Positive::ZERO
);

pub fn checked_div(&self, rhs: &Positive) -> Result<Positive, PositiveError>

Checked division that returns a 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.

Errors

Returns PositiveError::ArithmeticError on division by zero and on overflow — the latter is reachable, for example, when dividing Decimal::MAX by 1e-28. Returns PositiveError::OutOfBounds when the quotient would break the positivity invariant.

Examples

use positive::{Positive, PositiveError, pos_or_panic};
use rust_decimal::Decimal;

let a = pos_or_panic!(10.0);
assert_eq!(a.checked_div(&pos_or_panic!(4.0)).unwrap(), pos_or_panic!(2.5));

let max = Positive::new_decimal(Decimal::MAX).unwrap();
let tiny = Positive::new_decimal(Decimal::new(1, 28)).unwrap();
assert!(matches!(
    max.checked_div(&tiny).unwrap_err(),
    PositiveError::ArithmeticError { .. }
));

pub fn checked_div_with_strategy( &self, rhs: &Positive, strategy: RoundingStrategy, ) -> Result<Positive, PositiveError>

Checked division with an explicit rounding strategy.

Errors

Returns PositiveError::ArithmeticError on division by zero or overflow, and PositiveError::OutOfBounds when the quotient would break the positivity invariant.

Examples

use positive::pos_or_panic;
use rust_decimal::RoundingStrategy;

let a = pos_or_panic!(10.0);
let result = a
    .checked_div_with_strategy(&pos_or_panic!(3.0), RoundingStrategy::ToZero)
    .unwrap();
assert!(result < pos_or_panic!(3.34));

pub fn checked_add_dec(self, rhs: Decimal) -> Result<Positive, PositiveError>

Checked addition with a Decimal, returning a Result instead of panicking.

This is the non-panicking counterpart of Positive + Decimal.

Errors

Returns PositiveError::ArithmeticError on overflow and PositiveError::OutOfBounds when the result would break the positivity invariant — for example when rhs is negative and larger in magnitude than self.

Examples

use positive::{PositiveError, pos_or_panic};
use rust_decimal_macros::dec;

let a = pos_or_panic!(5.0);
assert_eq!(a.checked_add_dec(dec!(2.5)).unwrap(), pos_or_panic!(7.5));
assert!(matches!(
    a.checked_add_dec(dec!(-9)).unwrap_err(),
    PositiveError::OutOfBounds { .. }
));

pub fn checked_sub_dec(self, rhs: Decimal) -> Result<Positive, PositiveError>

Checked subtraction of a Decimal, returning a Result instead of panicking.

This is the non-panicking counterpart of Positive - Decimal.

Errors

Returns PositiveError::ArithmeticError on overflow and PositiveError::OutOfBounds when the result would break the positivity invariant.

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

let a = pos_or_panic!(5.0);
assert_eq!(a.checked_sub_dec(dec!(1.5)).unwrap(), pos_or_panic!(3.5));

pub fn checked_mul_dec(self, rhs: Decimal) -> Result<Positive, PositiveError>

Checked multiplication by a Decimal, returning a Result instead of panicking.

This is the non-panicking counterpart of Positive * Decimal.

Errors

Returns PositiveError::ArithmeticError on overflow and PositiveError::OutOfBounds when the result would break the positivity invariant — for example when rhs is negative.

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

let a = pos_or_panic!(4.0);
assert_eq!(a.checked_mul_dec(dec!(2.5)).unwrap(), pos_or_panic!(10.0));

pub fn checked_div_dec(self, rhs: Decimal) -> Result<Positive, PositiveError>

Checked division by a Decimal, returning a Result instead of panicking.

This is the non-panicking counterpart of Positive / Decimal, and uses DIV_ROUNDING_STRATEGY when rounding is required.

Errors

Returns PositiveError::ArithmeticError on division by zero and on overflow, and PositiveError::OutOfBounds when the quotient would break the positivity invariant.

Examples

use positive::{PositiveError, pos_or_panic};
use rust_decimal::Decimal;
use rust_decimal_macros::dec;

let a = pos_or_panic!(10.0);
assert_eq!(a.checked_div_dec(dec!(4)).unwrap(), pos_or_panic!(2.5));
assert!(matches!(
    a.checked_div_dec(Decimal::ZERO).unwrap_err(),
    PositiveError::ArithmeticError { .. }
));

pub fn checked_rem(&self, rhs: &Positive) -> Result<Positive, PositiveError>

Checked remainder of division by another Positive.

Errors

Returns PositiveError::ArithmeticError on division by zero or overflow, and PositiveError::OutOfBounds when the remainder would break the positivity invariant.

Examples

use positive::{PositiveError, pos_or_panic};

let a = pos_or_panic!(10.0);
assert_eq!(a.checked_rem(&pos_or_panic!(3.0)).unwrap(), pos_or_panic!(1.0));

pub fn checked_sum<I, T>(iter: I) -> Result<Positive, PositiveError>

where I: IntoIterator<Item = T>, T: Borrow<Positive>,

Sums an iterator of Positive values without ever panicking.

This is the aggregation counterpart of Positive::checked_add, and the non-panicking alternative to the Sum implementation. Sum cannot return a Result, so a fold that overflows has nowhere to report it; this function does.

Accepts both owned and borrowed iterators — anything whose item Borrows a Positive — so values.iter() and values.into_iter() both work.

Errors

Returns PositiveError::ArithmeticError as soon as the running total overflows Decimal, without consuming the rest of the iterator.

Returns PositiveError::OutOfBounds when the total breaks the positivity invariant, which cannot happen for non-negative terms. An empty iterator sums to Positive::ZERO.

Examples

use positive::{Positive, PositiveError, pos_or_panic};
use rust_decimal::Decimal;

let values = [pos_or_panic!(1.5), pos_or_panic!(2.5), pos_or_panic!(6.0)];

// borrowed
assert_eq!(Positive::checked_sum(values.iter()).unwrap(), pos_or_panic!(10.0));
// owned
assert_eq!(Positive::checked_sum(values).unwrap(), pos_or_panic!(10.0));

// overflow is reported, not panicked
let max = Positive::new_decimal(Decimal::MAX).unwrap();
assert!(matches!(
    Positive::checked_sum([max, Positive::ONE]).unwrap_err(),
    PositiveError::ArithmeticError { .. }
));

pub fn checked_add_f64(self, rhs: f64) -> Result<Positive, PositiveError>

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.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(5.0).checked_add_f64(2.5).unwrap(), pos_or_panic!(7.5));
assert!(pos_or_panic!(5.0).checked_add_f64(f64::NAN).is_err());

pub fn checked_sub_f64(self, rhs: f64) -> Result<Positive, PositiveError>

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.

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(5.0).checked_sub_f64(1.5).unwrap(), pos_or_panic!(3.5));
assert!(pos_or_panic!(5.0).checked_sub_f64(9.0).is_err());

pub fn checked_mul_f64(self, rhs: f64) -> Result<Positive, PositiveError>

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

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(4.0).checked_mul_f64(2.5).unwrap(), pos_or_panic!(10.0));
assert!(pos_or_panic!(4.0).checked_mul_f64(-1.0).is_err());

pub fn checked_div_f64(self, rhs: f64) -> Result<Positive, PositiveError>

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

Examples

use positive::pos_or_panic;

assert_eq!(pos_or_panic!(10.0).checked_div_f64(4.0).unwrap(), pos_or_panic!(2.5));
assert!(pos_or_panic!(10.0).checked_div_f64(0.0).is_err());

pub fn is_multiple(&self, other: f64) -> bool

👎Deprecated since 0.5.0:

use is_multiple_of_dec for Decimal-native precision; removal is scheduled for the release after 0.6.0

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 misclassifies values beyond the ~15 significant digits f64 can carry.

Edge cases

Until removal the contract is:

• a zero divisor returns false — nothing is a multiple of zero;
• a non-finite divisor (NaN, ±inf) returns false;
• a value that cannot be represented as a finite f64 returns false rather than panicking.

Deprecated

Scheduled for removal in the release following 0.6.0. Use Positive::is_multiple_of_dec or Positive::is_multiple_of, both of which are exact.

Examples

use positive::pos_or_panic;

assert!(pos_or_panic!(15.0).is_multiple(5.0));
assert!(!pos_or_panic!(15.0).is_multiple(0.0));

pub fn is_multiple_of_dec(&self, other: Decimal) -> bool

Checks whether the value is an exact multiple of a Decimal.

The remainder must be exactly zero. Returns false when other is zero, since nothing is a multiple of zero. Uses a checked remainder, so no input can panic.

Examples

use positive::pos_or_panic;
use rust_decimal_macros::dec;

assert!(pos_or_panic!(15.0).is_multiple_of_dec(dec!(5)));
assert!(!pos_or_panic!(15.0).is_multiple_of_dec(dec!(4)));
assert!(!pos_or_panic!(15.0).is_multiple_of_dec(dec!(0)));

pub fn is_multiple_of(&self, other: &Positive) -> bool

Checks whether the value is an exact multiple of another Positive.

The remainder must be exactly zero, matching Positive::is_multiple_of_dec for the same divisor. Earlier versions compared the remainder against EPSILON, so 1e-17 reported itself as a multiple of one — a false positive from a predicate that has an exact answer. Tolerance-based checking is available under the explicit name Positive::is_multiple_of_within.

Returns false when other is zero. Uses a checked remainder, so no input can panic.

Examples

use positive::{Positive, pos_or_panic};
use rust_decimal::Decimal;

assert!(pos_or_panic!(15.0).is_multiple_of(&pos_or_panic!(5.0)));

let tiny = Positive::new_decimal(Decimal::new(1, 17)).unwrap();
assert!(!tiny.is_multiple_of(&Positive::ONE));

pub fn is_multiple_of_within( &self, other: &Positive, tolerance: Decimal, ) -> bool

Checks whether the value is a multiple of another Positive within an explicit tolerance.

This is the tolerance-based counterpart of Positive::is_multiple_of, which is exact. The tolerance is supplied by the caller rather than baked in, because the right tolerance depends on the magnitudes involved and on what the caller is modelling.

A remainder is accepted when it is within tolerance of either zero or the divisor, so values just below an exact multiple count too.

Returns false when other is zero. Cannot panic.

Examples

use positive::{Positive, pos_or_panic};
use rust_decimal::Decimal;
use rust_decimal_macros::dec;

let tiny = Positive::new_decimal(Decimal::new(1, 17)).unwrap();
assert!(!tiny.is_multiple_of(&Positive::ONE));
assert!(tiny.is_multiple_of_within(&Positive::ONE, dec!(1e-16)));

Trait Implementations

impl AbsDiffEq for Positive

type Epsilon = Decimal

Used for specifying relative comparisons.

fn default_epsilon() -> <Positive as AbsDiffEq>::Epsilon

The default tolerance to use when testing values that are close together.

fn abs_diff_eq( &self, other: &Positive, epsilon: <Positive as AbsDiffEq>::Epsilon, ) -> bool

A test for equality that uses the absolute difference to compute the approximate equality of two numbers.

fn abs_diff_ne(&self, other: &Rhs, epsilon: Self::Epsilon) -> bool

The inverse of AbsDiffEq::abs_diff_eq.

impl Add for Positive

fn add(self, other: Positive) -> Positive

Panics

Panics on overflow. See Positive::checked_add for the non-panicking form.

type Output = Positive

The resulting type after applying the + operator.

impl Add<&Decimal> for Positive

fn add(self, rhs: &Decimal) -> <Positive as Add<&Decimal>>::Output

Panics

Same contract as Positive + Decimal.

type Output = Positive

The resulting type after applying the + operator.

impl Add<Decimal> for Positive

fn add(self, rhs: Decimal) -> Positive

Panics

Panics on overflow, or when the sum would break the positivity invariant. See Positive::checked_add_dec.

type Output = Positive

The resulting type after applying the + operator.

impl Add<StrictlyPositive> for Positive

fn add(self, rhs: StrictlyPositive) -> StrictlyPositive

Panics

Panics on overflow. See StrictlyPositive::checked_add_positive.

type Output = StrictlyPositive

The resulting type after applying the + operator.

impl Add<f64> for Positive

fn add(self, rhs: f64) -> <Positive as Add<f64>>::Output

Panics

Panics when rhs has no Decimal representation, on overflow, or when the sum would break the positivity invariant. See Positive::checked_add_f64.

type Output = Positive

The resulting type after applying the + operator.

impl AddAssign for Positive

fn add_assign(&mut self, other: Positive)

Panics

Panics on overflow, or when the result would break the positivity invariant.

impl AddAssign<Decimal> for Positive

fn add_assign(&mut self, rhs: Decimal)

Panics

Panics on overflow, or when the result would break the positivity invariant.

impl Clone for Positive

fn clone(&self) -> Positive

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Positive

impl Debug for Positive

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Positive

fn default() -> Positive

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Positive

fn deserialize<D>( deserializer: D, ) -> Result<Positive, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialises from the exact decimal string, or from a JSON number for compatibility with documents written by 0.5.x.

Errors

Fails when the input is not a valid decimal, or when the value breaks the positivity invariant (a negative value).

impl Display for Positive

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Renders the underlying Decimal exactly.

Earlier versions special-cased Positive::INFINITY and printed f64::MAX — a value roughly 10^279 times larger than the one the type actually held, and one that Positive::new rejects.

impl Div for Positive

fn div(self, other: Positive) -> <Positive as Div>::Output

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.

Panics

Panics on division by zero, on overflow, and when the quotient would break the positivity invariant.

type Output = Positive

The resulting type after applying the / operator.

impl Div for &Positive

fn div(self, other: &Positive) -> <&Positive as Div>::Output

Divides two &Positive values using DIV_ROUNDING_STRATEGY (banker’s rounding) when rounding is required.

Panics

Same contract as Positive / Positive; both delegate to Positive::checked_div.

type Output = Positive

The resulting type after applying the / operator.

impl Div<&Decimal> for Positive

fn div(self, rhs: &Decimal) -> <Positive as Div<&Decimal>>::Output

Divides by a &Decimal using DIV_ROUNDING_STRATEGY (banker’s rounding) when rounding is required.

Panics

Same contract as Positive / Decimal.

type Output = Positive

The resulting type after applying the / operator.

impl Div<Decimal> for Positive

fn div(self, rhs: Decimal) -> Positive

Divides by a Decimal using DIV_ROUNDING_STRATEGY (banker’s rounding) when rounding is required.

Panics

Panics on division by zero, on overflow, and when the quotient would break the positivity invariant. See Positive::checked_div_dec.

type Output = Positive

The resulting type after applying the / operator.

impl Div<StrictlyPositive> for Positive

fn div(self, rhs: StrictlyPositive) -> Positive

Rounds with crate::DIV_ROUNDING_STRATEGY (banker’s rounding). The divisor is never zero.

Panics

Same as Positive / Positive. See Positive::checked_div.

type Output = Positive

The resulting type after applying the / operator.

impl Div<f64> for Positive

fn div(self, rhs: f64) -> 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.

Panics

Panics when rhs has no Decimal representation, on division by zero, on overflow, or when the quotient would break the positivity invariant. See Positive::checked_div_f64.

type Output = Positive

The resulting type after applying the / operator.

impl Div<f64> for &Positive

fn div(self, rhs: f64) -> Positive

Divides a &Positive by an f64 using DIV_ROUNDING_STRATEGY (banker’s rounding) when rounding is required.

Panics

Same contract as Positive / f64.

type Output = Positive

The resulting type after applying the / operator.

impl Eq for Positive

impl From<&Positive> for Positive

fn from(value: &Positive) -> Positive

Copies an already-validated Positive, so the invariant holds by construction and no re-check is needed.

impl From<Positive> for DisplayMoney

Normalised, so a Positive printed without a precision keeps the trailing-zero-free rendering of Positive’s own Display.

fn from(value: Positive) -> Self

Converts to this type from the input type.

impl From<StrictlyPositive> for Positive

fn from(value: StrictlyPositive) -> Positive

Converts to this type from the input type.

impl FromStr for Positive

fn from_str(s: &str) -> Result<Positive, <Positive as FromStr>::Err>

Parses a Positive from its decimal text representation.

Errors

Returns PositiveError::InvalidValue when s is not a well-formed decimal, carrying the offending input verbatim, and PositiveError::OutOfBounds when it parses but breaks the positivity invariant.

Examples

use positive::{Positive, PositiveError};
use std::str::FromStr;

assert!(Positive::from_str("1.5").is_ok());

let err = Positive::from_str("not a number").unwrap_err();
assert!(matches!(err, PositiveError::InvalidValue { .. }));
assert!(err.to_string().contains("not a number"));

assert!(matches!(
    Positive::from_str("-1.5").unwrap_err(),
    PositiveError::OutOfBounds { .. }
));

type Err = PositiveError

The associated error which can be returned from parsing.

impl Hash for Positive

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Mul for Positive

fn mul(self, other: Positive) -> Positive

Panics

Panics on overflow. See Positive::checked_mul for the non-panicking form.

type Output = Positive

The resulting type after applying the * operator.

impl Mul<Decimal> for Positive

fn mul(self, rhs: Decimal) -> Positive

Panics

Panics on overflow, or when the product would break the positivity invariant — for example when rhs is negative. See Positive::checked_mul_dec.

type Output = Positive

The resulting type after applying the * operator.

impl Mul<StrictlyPositive> for Positive

fn mul(self, rhs: StrictlyPositive) -> Positive

Panics

Same as Positive * Positive. See Positive::checked_mul.

type Output = Positive

The resulting type after applying the * operator.

impl Mul<f64> for Positive

fn mul(self, rhs: f64) -> Positive

Panics

Panics when rhs has no Decimal representation, on overflow, or when the product would break the positivity invariant. See Positive::checked_mul_f64.

type Output = Positive

The resulting type after applying the * operator.

impl MulAssign<Decimal> for Positive

fn mul_assign(&mut self, rhs: Decimal)

Panics

Panics on overflow, or when the result would break the positivity invariant.

impl Ord for Positive

fn cmp(&self, other: &Positive) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for Positive

fn eq(&self, other: &Positive) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<&Positive> for Positive

fn eq(&self, other: &&Positive) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<Decimal> for Positive

fn eq(&self, other: &Decimal) -> bool

Exact equality, symmetric with Decimal == Positive.

Earlier versions compared |self - other| <= EPSILON_CMP here while the reverse impl compared exactly, so positive == decimal and decimal == positive could disagree — PartialEq requires them to agree. The subtraction also overflowed and panicked at the extremes of Decimal’s range.

Approximate comparison now lives exclusively in the approx impls and in Positive::approx_eq_dec.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<StrictlyPositive> for Positive

fn eq(&self, other: &StrictlyPositive) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<f64> for &Positive

fn eq(&self, other: &f64) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<f64> for Positive

fn eq(&self, other: &f64) -> bool

Exact equality against an f64, symmetric with f64 == Positive.

The previous implementation went through Positive::to_f64, which panics for values outside f64’s range, and collapsed distinct decimal integers above 2^53 onto the same float.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Positive

fn partial_cmp(&self, other: &Positive) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Decimal> for Positive

fn partial_cmp(&self, other: &Decimal) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<StrictlyPositive> for Positive

fn partial_cmp(&self, other: &StrictlyPositive) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<f64> for Positive

fn partial_cmp(&self, other: &f64) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<f64> for &Positive

fn partial_cmp(&self, other: &f64) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl RelativeEq for Positive

fn default_max_relative() -> <Positive as AbsDiffEq>::Epsilon

The default relative tolerance for testing values that are far-apart.

fn relative_eq( &self, other: &Positive, epsilon: <Positive as AbsDiffEq>::Epsilon, max_relative: <Positive as AbsDiffEq>::Epsilon, ) -> bool

A test for equality that uses a relative comparison if the values are far apart.

fn relative_ne( &self, other: &Rhs, epsilon: Self::Epsilon, max_relative: Self::Epsilon, ) -> bool

The inverse of RelativeEq::relative_eq.

impl Serialize for Positive

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialises the exact decimal representation as a string.

Errors

Propagates any error from the serializer. The conversion itself cannot fail: every Positive has an exact decimal representation.

impl StructuralPartialEq for Positive

impl Sub for Positive

fn sub(self, rhs: Positive) -> <Positive as Sub>::Output

Panics

Panics on overflow, or when the difference would be negative. See Positive::checked_sub.

type Output = Positive

The resulting type after applying the - operator.

impl Sub<&Decimal> for Positive

fn sub(self, rhs: &Decimal) -> <Positive as Sub<&Decimal>>::Output

Panics

Same contract as Positive - Decimal.

type Output = Positive

The resulting type after applying the - operator.

impl Sub<Decimal> for Positive

fn sub(self, rhs: Decimal) -> Positive

Panics

Panics on overflow, or when the difference would break the positivity invariant. See Positive::checked_sub_dec.

type Output = Positive

The resulting type after applying the - operator.

impl Sub<f64> for Positive

fn sub(self, rhs: f64) -> <Positive as Sub<f64>>::Output

Panics

Panics when rhs has no Decimal representation, on overflow, or when the difference would break the positivity invariant. See Positive::checked_sub_f64.

type Output = Positive

The resulting type after applying the - operator.

impl Sum for Positive

fn sum<I>(iter: I) -> Positive

where I: Iterator<Item = Positive>,

Sums an iterator of Positive values.

Panics

Panics when the total overflows Decimal. Use Positive::checked_sum for the non-panicking form; it reports the overflow as a PositiveError::ArithmeticError instead.

impl<'a> Sum<&'a Positive> for Positive

fn sum<I>(iter: I) -> Positive

where I: Iterator<Item = &'a Positive>,

Sums an iterator of &Positive values.

Panics

Panics when the total overflows Decimal. Use Positive::checked_sum for the non-panicking form.

impl ToRound for Positive

fn round(&self) -> Decimal

Rounds the number to the nearest integer.

fn round_to(&self, decimal_places: u32) -> Decimal

Rounds the number to a specified number of decimal places.

impl ToSchema for Positive

fn name() -> Cow<'static, str>

Return name of the schema.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implement reference utoipa::openapi::schema::Schemas for this type.

impl TryFrom<&Decimal> for Positive

fn try_from( value: &Decimal, ) -> Result<Positive, <Positive as TryFrom<&Decimal>>::Error>

Attempts to convert a &Decimal to a Positive value.

Errors

Returns PositiveError if the value is negative.

type Error = PositiveError

The type returned in the event of a conversion error.

impl TryFrom<Decimal> for Positive

fn try_from( value: Decimal, ) -> Result<Positive, <Positive as TryFrom<Decimal>>::Error>

Attempts to convert a Decimal to a Positive value.

Errors

Returns PositiveError if the value is negative.

type Error = PositiveError

The type returned in the event of a conversion error.

impl TryFrom<f64> for Positive

fn try_from(value: f64) -> Result<Positive, <Positive as TryFrom<f64>>::Error>

Attempts to convert an f64 to a Positive value.

Errors

Returns PositiveError if the value is negative, NaN, or cannot be converted to Decimal.

type Error = PositiveError

The type returned in the event of a conversion error.

impl TryFrom<i64> for Positive

fn try_from(value: i64) -> Result<Positive, <Positive as TryFrom<i64>>::Error>

Attempts to convert an i64 to a Positive value.

Errors

Returns PositiveError if the value is negative.

type Error = PositiveError

The type returned in the event of a conversion error.

impl TryFrom<u64> for Positive

fn try_from(value: u64) -> Result<Positive, <Positive as TryFrom<u64>>::Error>

Attempts to convert a u64 to a Positive value.

Errors

This conversion is infallible for u64 since all values are non-negative.

type Error = PositiveError

The type returned in the event of a conversion error.

impl TryFrom<usize> for Positive

fn try_from( value: usize, ) -> Result<Positive, <Positive as TryFrom<usize>>::Error>

Converts a usize to a Positive exactly.

The conversion goes straight to Decimal. Earlier versions went through f64, so on 64-bit targets every value above 2^53 was rounded — 9_007_199_254_740_993 became 9_007_199_254_740_992.

Errors

Every usize is non-negative and fits in Decimal, so this conversion never fails in practice; the Result is kept for API stability.

Examples

use positive::Positive;
use rust_decimal::Decimal;

let value = 9_007_199_254_740_993usize;
let positive = Positive::try_from(value).unwrap();
assert_eq!(positive.to_dec(), Decimal::from(value));

type Error = PositiveError

The type returned in the event of a conversion error.