1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
//! # decimix
//!
//! Fixed-point decimal numbers for trading systems: fast, exact, and hard to
//! misuse.
//!
//! The main type is [`Dec19`]: a signed number with exactly **19 decimal
//! places**, stored as an `i128`. [`UDec19`] is the unsigned version, for
//! values that must never be negative.
//!
//! ## What "19 decimal places" means
//!
//! Every value is stored as a whole number of 10⁻¹⁹ steps
//! (0.0000000000000000001). 113.725 is stored as the integer
//! 1,137,250,000,000,000,000,000. So:
//!
//! - There are 19 digits **after the decimal point**, always. This is *not*
//! SQL `DECIMAL(19)`, which means 19 digits in total.
//! - The range is about ±1.7 × 10¹⁹ whole units (0 to 3.4 × 10¹⁹ for
//! [`UDec19`]): every number below 10¹⁹ with up to 19 decimal places
//! fits (38 digits), and the largest values have 39. That is more than any
//! real price or tick needs, so nobody ever has to choose a scale or a
//! multiplier. Other systems reading these values need 39 digits of
//! precision: arbitrary-precision types (Java `BigDecimal`, Go `math/big`,
//! Postgres `NUMERIC`) are fine, but 38-digit column types (Arrow/Parquet
//! `Decimal128`) can't hold values of 10¹⁹ or more, and Python's `Decimal`
//! rounds arithmetic to 28 digits unless its context is widened.
//! - Every value has exactly one representation (`1.0` and `1.00` are the
//! same thing), so `==`, `<` and hashing are plain integer operations.
//! - Adding, subtracting and comparing cost the same as for `i128`.
//!
//! ## A quick tour
//!
//! ```
//! use decimix::{Dec19, Round, dec};
//!
//! // Literals are checked at compile time and never pass through f64.
//! const TICK: Dec19 = dec!(0.005);
//! let bid = dec!(113.725);
//! let ask = dec!(113.74);
//!
//! // Exact operations are operators.
//! let spread = ask - bid;
//! assert_eq!(spread, dec!(0.015));
//! assert_eq!(spread * 2, dec!(0.03));
//! assert!(bid < ask);
//!
//! // Anything that can round is a method, and you must say how to round.
//! let mid = (bid + ask).div_int(2, Round::HalfEven);
//! assert_eq!(mid.round_to(TICK, Round::Floor), dec!(113.73));
//!
//! // Text in and out is exact.
//! assert_eq!(mid.to_string(), "113.7325");
//! assert_eq!("113.7325".parse::<Dec19>(), Ok(mid));
//! ```
//!
//! ## Rounding
//!
//! Multiplying two decimals, and any division, can produce more than 19
//! decimal places, so these are methods that take a [`Round`]:
//! [`Dec19::mul`], [`Dec19::div`], [`Dec19::div_int`], [`Dec19::round_to`],
//! [`Dec19::round_dp`] and so on. There is no default rounding and no hidden
//! context. See [`Round`] for what each mode does, with examples.
//!
//! Exact divisions that don't round have their own methods, named as in std:
//! [`Dec19::div_euclid`] (how many whole lots or ticks fit) and
//! [`Dec19::rem_euclid`] (what's left over, never negative). With a positive
//! lot or tick size they count down for negative values too, unlike Rust's
//! `/` on integers, which rounds toward zero. The `%` operator is the other
//! remainder, matching Rust's integers and `f64`: it has the sign of the
//! value being divided, so −1.47 % 0.05 is −0.02 where `rem_euclid` gives
//! 0.03.
//!
//! To add up many products (notional, a VWAP numerator), use [`ProductSum`]:
//! it keeps every product exactly and rounds once at the end.
//!
//! ## Floating point: only at the edges
//!
//! There is no `From<f64>`, no `as_f64` and no `Into<f64>`. Doubles can't hold
//! most decimals exactly (0.1 has no exact binary form, just as 1/3 has no
//! exact decimal one), and every calculation on them can add error.
//!
//! Many systems and APIs do use doubles for prices, though, so two
//! deliberately loud methods cross the boundary:
//!
//! - [`Dec19::to_f64_lossy`]: the nearest double, for output.
//! - [`Dec19::from_f64_lossy`]: reads a double, rounding to a `step` you
//! choose: the finest precision you actually trust in it.
//!
//! They are for talking to other systems, **not for arithmetic**. If you need
//! maths this crate doesn't do, see below. Core crates can forbid them
//! entirely with Clippy, in their `clippy.toml`:
//!
//! ```toml
//! disallowed-methods = [
//! { path = "decimix::Dec19::to_f64_lossy", reason = "floats only at I/O edges; use to_big() for maths" },
//! { path = "decimix::Dec19::from_f64_lossy", reason = "floats only at I/O edges" },
//! { path = "decimix::UDec19::to_f64_lossy", reason = "floats only at I/O edges; use to_big() for maths" },
//! { path = "decimix::UDec19::from_f64_lossy", reason = "floats only at I/O edges" },
//! ]
//! ```
//!
//! Code at the edges (a gateway, an analytics crate) then opts in with
//! `#[allow(clippy::disallowed_methods)]`, which is easy to find in review.
//!
//! ## Maths this crate doesn't do, and what to use instead
//!
//! Square roots, logarithms, powers, statistics: turn on the `bigdecimal`
//! feature and convert with `to_big()`, which is always exact. Convert back
//! with `from_big(x, Round)`, which names its rounding, or `try_from`, which
//! refuses to round. Analytics code that genuinely wants doubles (e.g. for
//! `exp`) can use [`Dec19::to_f64_lossy`] under an explicit `#[allow]`.
//!
//! ## Domain types
//!
//! [`newtype!`] defines types like `Price` or `Qty` that wrap a `Dec19` or
//! `UDec19` and can't be mixed by accident. The `decimix-finance` crate
//! provides a standard set.
//!
//! ## What doesn't compile, on purpose
//!
//! No conversion from or to `f64`:
//!
//! ```compile_fail
//! let x = decimix::Dec19::from(1.5_f64);
//! ```
//!
//! ```compile_fail
//! let f: f64 = decimix::dec!(1.5).into();
//! ```
//!
//! The stored integer is not the value, so there is no `Into<i128>` (use
//! `to_raw` or `to_int`):
//!
//! ```compile_fail
//! let n: i128 = decimix::dec!(5).into();
//! ```
//!
//! Multiplying two decimals can round, so there is no `*` between them, and
//! no `/` at all (use `mul`, `div` or `div_euclid`):
//!
//! ```compile_fail
//! let (a, b) = (decimix::dec!(1.5), decimix::dec!(2));
//! let x = a * b;
//! ```
//!
//! ```compile_fail
//! let (a, b) = (decimix::dec!(1.5), decimix::dec!(2));
//! let x = a / b;
//! ```
//!
//! Unsigned values can't be negated:
//!
//! ```compile_fail
//! let x = -decimix::udec!(1.5);
//! ```
//!
//! (Multiplying by an integer is exact, so that *is* an operator:
//! `dec!(1.5) * 2`. So is the remainder, `%`, which works as on Rust's
//! integers: `dec!(-1.47) % dec!(0.05)` is −0.02.)
// One `unsafe` block, in `AsciiBuf::as_str`, allowed there explicitly; any
// other has to be allowed just as deliberately.
// Unit tests use std (proptest, formatting); the library itself does not.
extern crate std;
pub use crateProductSum;
pub use crateAsciiBuf;
pub use crateDec19;
pub use crateTryFromBigError;
pub use crate;
pub use crateRound;
pub use crateUDec19;
/// Any of this crate's 19-decimal-place types: [`Dec19`] or [`UDec19`].
///
/// Used where either can appear, e.g. `price.mul(qty, round)` with a
/// `UDec19` quantity. Sealed: it can't be implemented outside this crate.
/// Compiles and runs the README's examples as doc tests.
;
/// Low-level arithmetic kernels on raw scale-19 values.
///
/// Not part of the public API: public only so that the integration tests and
/// benchmarks can reach it.