Skip to main content

Module fixed

Module fixed 

Source
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 errors

instead 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 excess decimal digits using banker’s rounding (half to even).
check_fixed_precision
Checks if a given precision value 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 precision can be converted to f64.
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 i64 value to the nearest valid multiple of the scale for the given precision.
correct_raw_i128
Rounds a raw i128 value to the nearest valid multiple of the scale for the given precision.
correct_raw_u64
Rounds a raw u64 value to the nearest valid multiple of the scale for the given precision.
correct_raw_u128
Rounds a raw u128 value to the nearest valid multiple of the scale for the given precision.
f64_to_fixed_i64
Converts an f64 value to a raw fixed-point i64 representation with a specified precision.
f64_to_fixed_i128
Converts an f64 value to a raw fixed-point i128 representation with a specified precision.
f64_to_fixed_u64
Converts an f64 value to a raw fixed-point u64 representation with a specified precision.
f64_to_fixed_u128
Converts an f64 value to a raw fixed-point u128 representation with a specified precision.
fixed_i64_to_f64
Converts a raw fixed-point i64 value back to an f64 value.
fixed_i128_to_f64
Converts a raw fixed-point i128 value back to an f64 value.
fixed_u64_to_f64
Converts a raw fixed-point u64 value back to an f64 value.
fixed_u128_to_f64
Converts a raw fixed-point u128 value back to an f64 value.
mantissa_exponent_to_fixed_i128
Converts a mantissa/exponent pair to a raw fixed-point i128 value at the given precision.
raw_scales_match
Returns true when two precisions encode their raw values at the same scale.