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) -> Result<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) -> Result<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 a correctness check fails. See Quantity::from_raw_checked for more details.

pub fn from_raw_checked(raw: QuantityRaw, precision: u8) -> Result<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 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 rules follow the Sub implementation: the left-hand precision is retained unless zero.

Panics

Panics if the right-hand side has greater precision than the left-hand side (precision loss).

pub fn zero(precision: u8) -> Self

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

Panics

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

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) -> Result<Self>

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

This method provides more reliable parsing by using Decimal arithmetic to avoid floating-point precision issues during 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 cannot be converted to the raw representation.
• Overflow occurs during scaling.

pub fn from_decimal(decimal: Decimal) -> Result<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_u256(amount: U256, precision: u8) -> Result<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<T: Into<QuantityRaw>> AddAssign<T> for Quantity

fn add_assign(&mut self, other: T)

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 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 From<&Quantity> for Decimal

fn from(value: &Quantity) -> 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<&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 Decimal

fn from(value: Quantity) -> 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<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<'py> IntoPyObject<'py> for Quantity

type Target = Quantity

The Python output type

type Output = Bound<'py, <Quantity as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<Self as IntoPyObject<'_>>::Output, <Self as IntoPyObject<'_>>::Error>

Performs the conversion.

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

type Output = Quantity

The resulting type after applying the * operator.

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

Performs the * operation.

impl<T: Into<QuantityRaw>> MulAssign<T> for Quantity

fn mul_assign(&mut self, other: T)

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

type Frozen = True

Whether the pyclass is frozen.

impl PyClassImpl for Quantity

const IS_BASETYPE: bool = false

#[pyclass(subclass)]

const IS_SUBCLASS: bool = false

#[pyclass(extends=…)]

const IS_MAPPING: bool = false

#[pyclass(mapping)]

const IS_SEQUENCE: bool = false

#[pyclass(sequence)]

const IS_IMMUTABLE_TYPE: bool = false

#[pyclass(immutable_type)]

const RAW_DOC: &'static CStr = /// 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).

Docstring for the class provided on the struct or enum.

const DOC: &'static CStr

Fully rendered class doc, including the text_signature if a constructor is defined.

type BaseType = PyAny

Base class

type ThreadChecker = SendablePyClass<Quantity>

This handles following two situations:

type PyClassMutability = <<PyAny as PyClassBaseType>::PyClassMutability as PyClassMutability>::ImmutableChild

Immutable or mutable

type Dict = PyClassDummySlot

Specify this class has #[pyclass(dict)] or not.

type WeakRef = PyClassDummySlot

Specify this class has #[pyclass(weakref)] or not.

type BaseNativeType = PyAny

The closest native ancestor. This is PyAny by default, and when you declare #[pyclass(extends=PyDict)], it’s PyDict.

fn items_iter() -> PyClassItemsIter

fn lazy_type_object() -> &'static LazyTypeObject<Self>

fn dict_offset() -> Option<isize>

fn weaklist_offset() -> Option<isize>

impl PyClassNewTextSignature for Quantity

const TEXT_SIGNATURE: &'static str = "(value, precision)"

impl PyClass__add__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __add__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__floordiv__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __floordiv__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__mod__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __mod__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__mul__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __mul__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__radd__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __radd__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__rfloordiv__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __rfloordiv__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__rmod__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __rmod__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__rmul__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __rmul__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__rsub__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __rsub__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__rtruediv__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __rtruediv__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__sub__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __sub__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyClass__truediv__SlotFragment<Quantity> for PyClassImplCollector<Quantity>

unsafe fn __truediv__( self, py: Python<'_>, _raw_slf: *mut PyObject, arg0: *mut PyObject, ) -> PyResult<*mut PyObject>

Safety: _slf and _other must be valid non-null Python objects

impl PyMethods<Quantity> for PyClassImplCollector<Quantity>

fn py_methods(self) -> &'static PyClassItems

impl PyTypeInfo for Quantity

const NAME: &'static str = "Quantity"

Class name.

const MODULE: Option<&'static str>

Module name, if any.

fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

Returns the PyTypeObject instance for this type.

fn type_object(py: Python<'_>) -> Bound<'_, PyType>

Returns the safe abstraction over the type object.

fn is_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type or a subclass of this type.

fn is_exact_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type.

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<T: Into<QuantityRaw>> SubAssign<T> for Quantity

fn sub_assign(&mut self, other: T)

Performs the -= operation.

impl Copy for Quantity

impl DerefToPyAny for Quantity

impl Eq for Quantity

impl ExtractPyClassWithClone for Quantity