Struct Decimal32 

pub struct Decimal32<const PRECISION: u32>(/* private fields */);

Decimal32

This is a transparent wrapper over an i32. A const generic declares the number of places after the decimal point.

The motivation for such a type is providing lossless arithmetic guarantees like in the example below.

use high_roller::decimal::D9;
use num_traits::{CheckedAdd, WrappingAdd, WrappingSub};

const SMALL: f64 = 0.111000111;
const LARGE: f64 = 2.147483647;

const CHECKED_SMALL: D9 = D9::checked(SMALL).unwrap();
const CHECKED_LARGE: D9 = D9::checked(LARGE).unwrap();

// Parity with lossless operations
let sum = const { D9::checked(1.).unwrap() }.checked_add(&CHECKED_SMALL);
assert_eq!(sum.unwrap().get(), 1. + SMALL, "Result fits in f64");

// Checked operations prevent overflow
let lossy = CHECKED_LARGE.checked_add(&CHECKED_SMALL);
assert_eq!(lossy, None, "Result overflows i32");
assert_ne!(LARGE + SMALL - LARGE, SMALL);

// Wrapping operations enable loss recovery
let wrapped = CHECKED_LARGE.wrapping_add(&CHECKED_SMALL);
assert_eq!(wrapped.wrapping_sub(&CHECKED_LARGE), CHECKED_SMALL);

Design

There are different ways to represent a floating point number with wrapping and saturating semantics. This design basically takes the bounds of an i32 and sticks a decimal point somewhere. So the type itself serves primarily for self-documentation and convenience.

IEEE 754 floating point debauchery keeps the lossless range of an f32 in signed 2^24. So an equally valid design could lock the inner value within that range and use that bound for wrapping, saturating, and checked operations. The benefit is that get could return an f32 without loss of precision. The cost is hardware support for arithmetic. Since wrapping arithmetic is the primary motivation for Decimal32, this was not chosen.

A Decimal64 type is not (yet) exposed because at that point, the Decimal crate might be a better fit for your use case.

Implementations

impl<const PRECISION: u32> Decimal32<PRECISION>

pub const ZERO: Self

pub const MAX: Self

The greatest positive value this type can contain.

pub const MIN: Self

The most negative value this type can contain.

pub const MIN_UNIT: Self

The smallest positive value this type can contain.

pub const fn cast(value: f64) -> Self

Constructor that accepts any input. Truncates toward zero when the input has more decimal places than PRECISION. Use Self::checked to detect when precision is lost.

This function takes an f64 to prevent sneaky loss of precision. f32 only has a 24-bit mantissa, so values between 2^24 and and 2^31 require an f64 to be constructed.

use high_roller::decimal::D2;

let num = D2::cast(0.125_f64);
assert_eq!(num.get(), 0.12_f64);

If this f64 situation is annoying for your use case, you can still escape it entirely at compile time.

use high_roller::decimal::D3;

const MY_F32: f32 = D3::cast(0.321_f64).get() as f32;
assert_eq!(MY_F32, 0.321);

pub const fn checked(value: f64) -> Option<Self>

Const constructor that prevents loss of precision from the input value.

Succeeds

use high_roller::decimal::D5;

const GOOD: D5 = D5::checked(-100.12345).unwrap();

Fails

use high_roller::decimal::D9;

const BAD: D9 = D9::checked(-100.)
    .expect("There isn't space in 32 bits for 9 decimal places after -100");

pub const fn get(self) -> f64

Returns the inner value as an f64. This conversion is lossless because f64’s 53-bit mantissa can represent every i32 value exactly.

For f32 output use f32::try_from, which returns Err(Lossy) when the inner value exceeds f32’s 24-bit mantissa.

use high_roller::decimal::D1;

assert_eq!(D1::cast(1.0_f64).get(), 1.0_f64);

Trait Implementations

impl<const P: u32> Add for Decimal32<P>

fn add(self, rhs: Self) -> Self::Output

Uses wrapping addition.

type Output = Decimal32<P>

The resulting type after applying the + operator.

impl<const P: u32> CheckedAdd for Decimal32<P>

fn checked_add(&self, v: &Self) -> Option<Self>

Adds two numbers, checking for overflow. If overflow happens, None is returned.

impl<const P: u32> CheckedSub for Decimal32<P>

fn checked_sub(&self, v: &Self) -> Option<Self>

Subtracts two numbers, checking for underflow. If underflow happens, None is returned.

impl<const PRECISION: u32> Clone for Decimal32<PRECISION>

fn clone(&self) -> Decimal32<PRECISION>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const P: u32> Debug for Decimal32<P>

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

Formats the value using the given formatter.

impl<const P: u32> Default for Decimal32<P>

fn default() -> Self

Returns the “default value” for a type.

impl<const P: u32> Display for Decimal32<P>

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

Formats the value using the given formatter.

impl<const P: u32> From<Decimal32<P>> for f64

fn from(val: Decimal32<P>) -> Self

Converts to this type from the input type.

impl<const PRECISION: u32> Hash for Decimal32<PRECISION>

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

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<const P: u32> Neg for Decimal32<P>

fn neg(self) -> Self::Output

Uses wrapping negation.

type Output = Decimal32<P>

The resulting type after applying the - operator.

impl<const PRECISION: u32> Ord for Decimal32<PRECISION>

fn cmp(&self, other: &Decimal32<PRECISION>) -> 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.

impl<const PRECISION: u32> PartialEq for Decimal32<PRECISION>

fn eq(&self, other: &Decimal32<PRECISION>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const PRECISION: u32> PartialOrd for Decimal32<PRECISION>

fn partial_cmp(&self, other: &Decimal32<PRECISION>) -> 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<const P: u32> Sub for Decimal32<P>

fn sub(self, rhs: Self) -> Self::Output

Uses wrapping subtraction.

type Output = Decimal32<P>

The resulting type after applying the - operator.

impl<const P: u32> TryFrom<Decimal32<P>> for f32

fn try_from(value: Decimal32<P>) -> Result<Self, Self::Error>

Converts to f32. Returns Err(Lossy) when the inner value exceeds f32’s 24-bit mantissa. Use Decimal32::get if unchecked lossless output is required.

type Error = DecimalErr

The type returned in the event of a conversion error.

impl<const P: u32> TryFrom<f32> for Decimal32<P>

fn try_from(value: f32) -> Result<Self, Self::Error>

Constructs a Decimal32 from an f32 or returns Err(DecimalErr::Lossy) if the conversion would lose precision. This might occur if the input literal specifies more decimal places than the underlyingDecimal32 type.

use high_roller::decimal::D2;

D2::try_from(0.123).expect("resulting decimal is 0.12");

But take care not to lose precision when constructing the f32 input into this function. Since f32 has a 24-bit mantissa, it cannot represent some values that Decimal32 can.

In the example below, rustc abbreviates the float before this function even sees it. Decimal32::cast solves this case by using an f64 constructor.

use high_roller::decimal::D9;

const INPUT: f32 = 2.147483647;
let expected = D9::try_from(INPUT).unwrap();

assert_eq!(INPUT, f32::try_from(expected).unwrap());
assert_eq!(INPUT, 2.1474836, "two places were dropped");

type Error = DecimalErr

The type returned in the event of a conversion error.

impl<const P: u32> WrappingAdd for Decimal32<P>

fn wrapping_add(&self, v: &Self) -> Self

Wrapping (modular) addition. Computes self + other, wrapping around at the boundary of the type.

impl<const P: u32> WrappingSub for Decimal32<P>

fn wrapping_sub(&self, v: &Self) -> Self

Wrapping (modular) subtraction. Computes self - other, wrapping around at the boundary of the type.

impl<const PRECISION: u32> Copy for Decimal32<PRECISION>

impl<const PRECISION: u32> Eq for Decimal32<PRECISION>

impl<const PRECISION: u32> StructuralPartialEq for Decimal32<PRECISION>