decimix
Fixed-point decimal arithmetic for trading systems: fast, exact, and hard to misuse.
Dec19 is a signed number with exactly 19 decimal places (not SQL
DECIMAL(19), which means 19 digits in total), stored as an i128: a range
of about ±1.7 × 10¹⁹ with up to 39 significant digits. UDec19 is the unsigned
version. There is one representation per value, so comparing and hashing are
plain integer operations, and adding costs the same as for an i128.
Usage
[]
= "0.1.2"
use ;
const TICK: Dec19 = dec!; // checked at compile time, never via f64
let bid = dec!;
let ask = dec!;
// Exact operations are operators.
let spread = ask - bid;
assert_eq!;
// Anything that can round is a method, and you say how to round.
let mid = .div_int;
assert_eq!;
let notional = bid.mul;
// Text in and out is exact, and fast enough for FIX.
let mut buf = ;
let n = mid.write_ascii.unwrap;
assert_eq!;
- No hidden rounding.
*between two decimals and/don't exist:mul,div,div_int,round_toand friends take a mandatoryRound(six modes). Overflow panics in operators;checked_*andsaturating_*don't. - Floats only at the edges. No
From<f64>oras_f64. Two loudly named methods,to_f64_lossyandfrom_f64_lossy(x, step, round), talk to systems that use doubles, and core crates can ban them with Clippy (see the crate docs for theclippy.tomlsnippet). - Exact slow path. With the
bigdecimalfeature,to_big()converts exactly for maths this crate doesn't do, andfrom_big(x, round)comes back. - Sums of products (
ProductSum) are kept exactly and rounded once. - Domain types.
newtype!defines types likePriceandQtythat can't be mixed by accident; thedecimix-financecrate has a set named after the FIX datatypes.
API documentation: https://docs.rs/decimix. The design decisions are in
docs/design-brief.md.
Performance
Rough figures on one machine (Apple Silicon); see crates/decimix/benches,
including compare.rs, which runs the same operations with
primitive_fixed_point_decimal, fpdec and f64.
| Operation | ns |
|---|---|
| add, compare | < 1 |
| price × quantity, rounded | 6.5–10 |
| price × whole quantity | 2–2.6 |
| divide | 30 (10 by a whole number) |
parse 113.725 |
8.7 |
format 113.725 (write_ascii) |
19 |
to_f64_lossy |
10 |
Testing
Arithmetic, parsing, formatting and conversions are checked against exact
big-integer oracles in every rounding mode (proptest), under Miri, and by
coverage-guided fuzzing (fuzz/, run in CI).
Minimum supported Rust version
1.98. Raising it is not considered a breaking change, but is noted in the changelog.
Releasing
decimix follows SemVer. While the crate is on
0.x, breaking changes bump the minor version (0.1.0 → 0.2.0) and
backward-compatible changes bump the patch version (0.1.0 → 0.1.1).
Releases are cut by the Release workflow,
which calls the shared one in
puremourning/rust-ci. To publish:
- Make sure
mainis green on CI and contains everything you want in the release. - From the GitHub Actions tab, run Release via Run workflow and
enter the new version (e.g.
0.2.0, novprefix) or a bump level (patch,minor,major). Tick dry-run to see what would happen.
The workflow runs the tests, then cargo release: it bumps the version in
Cargo.toml and the install snippet above, verifies with
cargo publish --dry-run, commits Release vX.Y.Z, tags vX.Y.Z, pushes,
publishes to crates.io and creates a GitHub release with generated notes.
Required setup
CARGO_REGISTRY_TOKENrepository secret — a crates.io API token from https://crates.io/me, scoped topublish-newfor the first release andpublish-updatefordecimixafterwards.- The default
GITHUB_TOKENis enough for the commit/tag push and release creation, providedmaindoesn't have branch protection that blocks pushes fromgithub-actions[bot].
License
Licensed under the MIT License.