Expand description
Functions for handling fixed-point arithmetic.
This module provides constants and functions that enforce a fixed-point precision strategy, ensuring consistent precision and scaling across various types and calculations.
§Raw Value Requirements
For Price and Quantity, non-sentinel raw constructor inputs at precision p below
FIXED_PRECISION must be multiples of 10^(FIXED_PRECISION - p). The checked constructors
return an error for extra fractional digits; from_raw panics in both debug and release builds.
Arrow and SBE decoders use the checked constructors and reject these inputs without rounding.
Arithmetic does not implicitly increase precision. In particular, Quantity multiplication
can retain finer raw digits than its declared precision. Such a result requires an explicit
precision choice or rounding before reconstruction through a raw constructor.
§Legacy Catalog Data and Floating-Point Errors
Data written to catalogs using V2 wranglers before 16th December 2025 may contain raw values with floating-point precision errors. This occurred because the wranglers used:
int(value * FIXED_SCALAR) # Introduces floating-point errorsinstead of the correct precision-aware approach:
round(value * 10^precision) * scale # Correct§Raw Value Correction
Correction functions (correct_raw_i64, correct_raw_i128, etc.) explicitly round raw
values to the nearest valid multiple. Arrow decoding does not apply this correction.
Legacy catalog migration does not round raw digits. Built-in rows with extra digits fail
migration, including arithmetic results with finer digits than their declared precision.
Regenerate affected data or explicitly correct its precision or scaling before migration.
Constants§
- FIXED_
DECIMAL - The Arrow data type name for fixed-point value types.
- FIXED_
PRECISION - The maximum fixed-point precision.
- FIXED_
PRECISION_ STANDARD - The maximum fixed-point precision used by standard-precision catalog data.
- FIXED_
SCALAR - The scalar value corresponding to the maximum precision (10^16).
- MAX_
FLOAT_ PRECISION - The maximum precision that can be safely used with f64-based constructors.
- PRECISION_
BYTES - The width in bytes for fixed-point value types in high-precision mode (128-bit).
- PRECISION_
DIFF_ SCALAR - The scalar representing the difference between high-precision and standard-precision modes.
Statics§
- HIGH_
PRECISION_ MODE - Indicates if high-precision mode is enabled.
Functions§
- bankers_
round - Rounds a mantissa by removing
excessdecimal digits using banker’s rounding (half to even). - check_
fixed_ precision - Checks if a given
precisionvalue is within the allowed fixed-point precision range. - check_
fixed_ raw_ i64 - Checks that a raw signed fixed-point value (64-bit) has no spurious bits.
- check_
fixed_ raw_ i128 - Checks that a raw signed fixed-point value has no spurious bits beyond the precision scale.
- check_
fixed_ raw_ u64 - Checks that a raw unsigned fixed-point value (64-bit) has no spurious bits.
- check_
fixed_ raw_ u128 - Checks that a raw unsigned fixed-point value has no spurious bits beyond the precision scale.
- check_
float_ precision - Checks that a value with the given
precisioncan be converted tof64. - correct_
price_ raw - Rounds a raw price value to the nearest valid multiple of the scale for the given precision.
- correct_
quantity_ raw - Rounds a raw quantity value to the nearest valid multiple of the scale for the given precision.
- correct_
raw_ i64 - Rounds a raw
i64value to the nearest valid multiple of the scale for the given precision. - correct_
raw_ i128 - Rounds a raw
i128value to the nearest valid multiple of the scale for the given precision. - correct_
raw_ u64 - Rounds a raw
u64value to the nearest valid multiple of the scale for the given precision. - correct_
raw_ u128 - Rounds a raw
u128value to the nearest valid multiple of the scale for the given precision. - f64_
to_ fixed_ i64 - Converts an
f64value to a raw fixed-pointi64representation with a specified precision. - f64_
to_ fixed_ i128 - Converts an
f64value to a raw fixed-pointi128representation with a specified precision. - f64_
to_ fixed_ u64 - Converts an
f64value to a raw fixed-pointu64representation with a specified precision. - f64_
to_ fixed_ u128 - Converts an
f64value to a raw fixed-pointu128representation with a specified precision. - fixed_
i64_ to_ f64 - Converts a raw fixed-point
i64value back to anf64value. - fixed_
i128_ to_ f64 - Converts a raw fixed-point
i128value back to anf64value. - fixed_
u64_ to_ f64 - Converts a raw fixed-point
u64value back to anf64value. - fixed_
u128_ to_ f64 - Converts a raw fixed-point
u128value back to anf64value. - mantissa_
exponent_ to_ fixed_ i128 - Converts a mantissa/exponent pair to a raw fixed-point
i128value at the given precision. - raw_
scales_ match - Returns
truewhen two precisions encode theirrawvalues at the same scale.