Struct Quantity 

#[repr(C)]
pub struct Quantity {
    pub raw: QuantityRaw,
    pub precision: u8,
}

Represents a quantity with a non-negative value and specified precision.

Capable of storing either a whole number (no decimal places) of ‘contracts’ or ‘shares’ (instruments denominated in whole units) or a decimal value containing decimal places for instruments denominated in fractional units.

Handles up to FIXED_PRECISION decimals of precision.

• QUANTITY_MAX - Maximum representable quantity value.
• QUANTITY_MIN - 0 (non-negative values only).

Fields

raw: QuantityRaw

Represents the raw fixed-point value, with precision defining the number of decimal places.

precision: u8

The number of decimal places, with a maximum of FIXED_PRECISION.

Implementations

impl Quantity

pub fn new_checked(value: f64, precision: u8) -> CorrectnessResult<Self>

Creates a new Quantity instance with correctness checking.

Errors

Returns an error if:

• value is invalid outside the representable range [0, QUANTITY_MAX].
• precision is invalid outside the representable range [0, FIXED_PRECISION].

Notes

PyO3 requires a Result type for proper error handling and stacktrace printing in Python.

pub fn non_zero_checked(value: f64, precision: u8) -> CorrectnessResult<Self>

Creates a new Quantity instance with a guaranteed non zero value.

Errors

Returns an error if:

• value is zero.
• value becomes zero after rounding to precision.
• value is invalid outside the representable range [0, QUANTITY_MAX].
• precision is invalid outside the representable range [0, FIXED_PRECISION].

Notes

PyO3 requires a Result type for proper error handling and stacktrace printing in Python.

pub fn new(value: f64, precision: u8) -> Self

Creates a new Quantity instance.

Panics

Panics if a correctness check fails. See Quantity::new_checked for more details.

pub fn non_zero(value: f64, precision: u8) -> Self

Creates a new Quantity instance with a guaranteed non zero value.

Panics

Panics if a correctness check fails. See Quantity::non_zero_checked for more details.

pub fn from_raw(raw: QuantityRaw, precision: u8) -> Self

Creates a new Quantity instance from the given raw fixed-point value and precision.

Panics

Panics if raw exceeds QUANTITY_RAW_MAX and is not a sentinel value. Panics if precision exceeds FIXED_PRECISION.

pub fn from_raw_checked( raw: QuantityRaw, precision: u8, ) -> CorrectnessResult<Self>

Creates a new Quantity instance from the given raw fixed-point value and precision with correctness checking.

Errors

Returns an error if:

• precision exceeds the maximum fixed precision.
• precision is not 0 when raw is QUANTITY_UNDEF.
• raw exceeds QUANTITY_RAW_MAX and is not a sentinel value.

pub fn checked_add(self, rhs: Self) -> Option<Self>

Performs a checked addition, returning None on raw integer overflow, when the result exceeds QUANTITY_RAW_MAX, when either operand is QUANTITY_UNDEF, or when the operands have mixed raw scales (one at FIXED_PRECISION scale, the other at a defi WEI_PRECISION scale).

Precision follows the Add implementation: uses the maximum precision of both operands.

pub fn checked_sub(self, rhs: Self) -> Option<Self>

Performs a checked subtraction, returning None if rhs is greater than self, when either operand is QUANTITY_UNDEF, or when the operands have mixed raw scales (one at FIXED_PRECISION scale, the other at a defi WEI_PRECISION scale).

Precision follows the Sub implementation: uses the maximum precision of both operands.

pub fn saturating_sub(self, rhs: Self) -> Self

Computes a saturating subtraction between two quantities, logging when clamped.

When rhs is greater than self, the result is clamped to zero and a warning is logged. Precision follows the Sub implementation: uses the maximum precision of both operands.

pub fn zero(precision: u8) -> Self

Creates a new Quantity instance with a value of zero with the given precision.

Panics

Panics if precision exceeds the maximum allowed by check_fixed_precision.

pub fn is_undefined(&self) -> bool

Returns true if the value of this instance is undefined.

pub fn is_zero(&self) -> bool

Returns true if the value of this instance is zero.

pub fn is_positive(&self) -> bool

Returns true if the value of this instance is position (> 0).

pub fn as_f64(&self) -> f64

Returns the value of this instance as an f64.

Panics

Panics if precision is beyond MAX_FLOAT_PRECISION (16).

pub fn as_decimal(&self) -> Decimal

Returns the value of this instance as a Decimal.

pub fn to_formatted_string(&self) -> String

Returns a formatted string representation of this instance.

pub fn from_decimal_dp( decimal: Decimal, precision: u8, ) -> CorrectnessResult<Self>

Creates a new Quantity from a Decimal value with specified precision.

Uses pure integer arithmetic on the Decimal’s mantissa and scale for fast conversion. The value is rounded to the specified precision using banker’s rounding (round half to even).

Errors

Returns an error if:

• precision exceeds FIXED_PRECISION.
• The decimal value is negative.
• The decimal value cannot be converted to the raw representation.
• Overflow occurs during scaling.

pub fn from_decimal(decimal: Decimal) -> CorrectnessResult<Self>

Creates a new Quantity from a Decimal value with precision inferred from the decimal’s scale.

The precision is determined by the scale of the decimal (number of decimal places). The value is rounded to the inferred precision using banker’s rounding (round half to even).

Errors

Returns an error if:

• The inferred precision exceeds FIXED_PRECISION.
• The decimal value cannot be converted to the raw representation.
• Overflow occurs during scaling.

pub fn from_mantissa_exponent( mantissa: u64, exponent: i8, precision: u8, ) -> Self

Creates a new Quantity from a mantissa/exponent pair using pure integer arithmetic.

The value is mantissa * 10^exponent. This avoids all floating-point and Decimal operations, making it ideal for exchange data that arrives as mantissa/exponent pairs.

Panics

Panics if the resulting raw value exceeds QUANTITY_RAW_MAX.

pub fn from_mantissa_exponent_checked( mantissa: u64, exponent: i8, precision: u8, ) -> CorrectnessResult<Self>

Checked variant of Quantity::from_mantissa_exponent.

Errors

Returns an error if the precision is invalid or the resulting raw value exceeds QUANTITY_RAW_MAX.

pub fn from_u256(amount: U256, precision: u8) -> CorrectnessResult<Self>

Creates a new Quantity from a U256 amount with specified precision.

Errors

Returns an error if:

• Overflow occurs during scaling when precision is less than FIXED_PRECISION.
• The scaled U256 amount exceeds the QuantityRaw range.

impl Quantity

pub fn from_wei<U>(raw_wei: U) -> Self

where U: Into<U256>,

Constructs a Quantity from a raw amount expressed in wei (18-decimal fixed-point).

The resulting Quantity will always have precision equal to 18.

Panics

Panics if the supplied raw_wei cannot fit into an unsigned 128-bit integer (this would exceed the numeric range of the internal QuantityRaw representation).

pub fn as_wei(&self) -> U256

Converts this Quantity to a wei amount (U256).

Only valid for prices with precision 18. For other precisions convert to precision 18 first.

Panics

Panics if the quantity has precision other than 18.

Trait Implementations

impl Add for Quantity

type Output = Quantity

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Decimal> for Quantity

type Output = Decimal

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<f64> for Quantity

type Output = f64

The resulting type after applying the + operator.

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

Performs the + operation.

impl Clone for Quantity

fn clone(&self) -> Quantity

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Quantity

impl Debug for Quantity

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

Formats the value using the given formatter.

impl Default for Quantity

fn default() -> Quantity

Returns the “default value” for a type.

impl Deref for Quantity

type Target = u128

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'de> Deserialize<'de> for Quantity

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Quantity

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

Formats the value using the given formatter.

impl Div<Decimal> for Quantity

type Output = Decimal

The resulting type after applying the / operator.

fn div(self, rhs: Decimal) -> Self::Output

Performs the / operation.

impl Div<f64> for Quantity

type Output = f64

The resulting type after applying the / operator.

fn div(self, rhs: f64) -> Self::Output

Performs the / operation.

impl Eq for Quantity

impl From<&Quantity> for f64

fn from(qty: &Quantity) -> Self

Converts to this type from the input type.

impl From<&Quantity> for QuantityRaw

fn from(value: &Quantity) -> Self

Converts to this type from the input type.

impl From<&Quantity> for Decimal

fn from(value: &Quantity) -> Self

Converts to this type from the input type.

impl From<&String> for Quantity

fn from(value: &String) -> Self

Converts to this type from the input type.

impl From<&str> for Quantity

fn from(value: &str) -> Self

Converts to this type from the input type.

impl From<Quantity> for f64

fn from(qty: Quantity) -> Self

Converts to this type from the input type.

impl From<Quantity> for QuantityRaw

fn from(value: Quantity) -> Self

Converts to this type from the input type.

impl From<Quantity> for Decimal

fn from(value: Quantity) -> Self

Converts to this type from the input type.

impl From<String> for Quantity

fn from(value: String) -> Self

Converts to this type from the input type.

impl From<i32> for Quantity

fn from(value: i32) -> Self

Creates a Quantity from an i32 value.

Panics

Panics if value is negative. Use u32 for guaranteed non-negative values.

impl From<i64> for Quantity

fn from(value: i64) -> Self

Creates a Quantity from an i64 value.

Panics

Panics if value is negative. Use u64 for guaranteed non-negative values.

impl From<u32> for Quantity

fn from(value: u32) -> Self

Converts to this type from the input type.

impl From<u64> for Quantity

fn from(value: u64) -> Self

Converts to this type from the input type.

impl FromStr for Quantity

type Err = String

The associated error which can be returned from parsing.

fn from_str(value: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Quantity

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 Mul for Quantity

type Output = Quantity

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<Decimal> for Quantity

type Output = Decimal

The resulting type after applying the * operator.

fn mul(self, rhs: Decimal) -> Self::Output

Performs the * operation.

impl Mul<f64> for Quantity

type Output = f64

The resulting type after applying the * operator.

fn mul(self, rhs: f64) -> Self::Output

Performs the * operation.

impl Ord for Quantity

fn cmp(&self, other: &Self) -> 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 PartialEq for Quantity

fn eq(&self, other: &Self) -> 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 PartialOrd for Quantity

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

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

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

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

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

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

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

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

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

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

impl Serialize for Quantity

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub for Quantity

type Output = Quantity

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Decimal> for Quantity

type Output = Decimal

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<f64> for Quantity

type Output = f64

The resulting type after applying the - operator.

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

Performs the - operation.