Decision D038 · accepted
Decimal numbers
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-18)
Decision
A third kind of number, beside integers (with BigInt) and floats (D013), for money and exact decimal arithmetic: (+ 0.1 0.2) is 0.30000000000000004, (+ 0.1dec 0.2dec) is 0.3dec.
1.10dec -3dec 1_000.50dec ; literals
(+ 0.1dec 0.2dec) ; 0.3dec
(* 1.10dec 3) ; 3.30dec: integers mix, exactly
(/ 10dec 4) ; 2.5dec: an exact quotient
(/ 1dec 3) ; error: 1/3 has no exact decimal: use decimal.div with scale:
(decimal.div 1dec 3 scale: 2) ; 0.33dec
(decimal.round 2.345dec 2) ; 2.34dec: HalfEven by default
(decimal.round 2.345dec 2 round: Round.HalfUp) ; 2.35dec
(+ 1.5dec 0.5) ; error: + does not mix decimals and floats
(decimal.parse "0.1") ; 0.1dec, from text
(decimal.from-float 0.1) ; 0.1000000000000000055511151231257827021181583404541015625dec
(float 0.1dec) ; 0.1
(= 1.10dec 1.1dec) ; true
(str 1.10dec) ; "1.10": the scale is kept
f"{price:.2f}" ; formats a decimal exactly
- Arbitrary precision with a fast path. A decimal is a coefficient times 10 to the minus scale. The coefficient is an ordinary integer: an immediate while it fits 63 bits, a BigInt beyond, as integers already are, so small amounts cost little more than C#'s 128-bit decimal without its limit of 28 digits or its overflow errors.
- The literal is a number with the suffix
dec, with_separators as other literals (D034). +,-and*are exact. The scale of a sum is the larger scale, of a product the sum of the scales./gives the exact quotient or raises. A quotient with no finite decimal expansion is an error that namesdecimal.div;(decimal.div a b scale: n round: r)givesndigits after the point. No hidden context of precision, as Python's: the precision is visible at the call.- Rounding is an enum,
Round:HalfEven(the default, as IEEE 754, Python'sdecimal, C#'sMath.Round),HalfUp,HalfDown,Down,Up,Floor,Ceiling. The library does not know the domain, so its default is the unbiased rule; code about money states its rule (round: Round.HalfUp, as many invoices and tax rules require; a variant without fields is a value written by its name, D010 §3c), and the documentation ofdecimal.roundanddecimal.divsays so with an example. - Mixing: integers and BigInts mix exactly (
(+ 1 1.10dec)is2.10dec); floats do not: an operator given a decimal and a float raises "does not mix decimals and floats" (D022). Conversions are explicit:decimal.parsefrom text,decimal.from-float(the float's exact binary value),float. - Equality by value, printing by scale:
(= 1.10dec 1.1dec)is true and their hashes are equal, so they are one map key;1.10decprints as1.10dec, so a price keeps its two digits. Ordering compares values (D009). - A decimal is a number to
=(2026-11-18, the author's choice): D013's numbers are one kind compared by mathematical value, and decimals join them, exactly.(= 1dec 1)and(= 1dec 1.0)are true, so1,1.0and1decare one map key and one set element;(= 0.1dec 0.1)is false, since the float is 0.1000000000000000055511151231257827021181583404541015625.compare,<,sort,distinctand the total order of maps and sets order decimals with integers and floats by that exact value, consistently with=; NaN is placed and compared as with other numbers. A literal pattern matches what=says:(match 1.0dec 1 …)takes the clause, and a decimal literal in a pattern,(match x 2.5dec …), is(= 2.5dec). Arithmetic still refuses to mix decimals and floats: equality and order lose nothing, an operation would. A BigInt stays a kind of its own, as std.math.bigint has it:(= 1dec (bigint.of 1))is false. Replaced (2026-11-18) by D043, accepted and not implemented yet: a BigInt joins the numbers by the same rule, so(= 1dec 1big)is true and agrees withcompare, which gives 0 already.
(= 1dec 1) ; true
(= 1.50dec 1.5) ; true: 1.5 is exactly 1.5
(= 0.1dec 0.1) ; false: 0.1 is 0.1000000000000000055…
(get #{1 :one} 1.0dec) ; :one
(sort #[2 1.5dec 0.5 -1dec]) ; (-1dec 0.5 1.5dec 2)
(match 1.0dec 1 :one _ :other) ; :one
(+ 1dec 1.0) ; error: + does not mix decimals and floats
- No NaN or infinity: division by zero raises
DivisionByZero, as with integers. - Where it lives: the type and the literal in the core (the reader produces decimals; the operators know them); the operations in
std.decimal(div,round,parse,from-float,scale,to-string). - Format specs in f-strings format decimals exactly, rounding with
HalfEven. - JSON: decoding into a field of type Decimal reads the number from its text, never through a float (D010).
- Money is not a decimal: an amount has a currency, and amounts of different currencies do not add. A
Moneytype belongs to a library on top of decimals, designed later.
Rejected alternatives
| Alternative | Where | Why not |
|---|---|---|
| 128-bit fixed decimal | C#, rust_decimal |
a limit of 28 digits and overflow errors, for a speed the fast path gives anyway |
A default precision for / |
Python's context (28 digits), C# | the precision is chosen silently where it matters most |
1.10 ≠ 1.1 by scale |
Java's BigDecimal.equals |
a known trap: equal numbers are different map keys |
Decimals a kind of their own, (= 1dec 1) false |
BigInt's rule | 1 and 1dec as different map keys is the same trap; D013 already compares numbers by value |
| Decimals equal integers but not floats | not transitive with (= 1 1.0): 1dec = 1 = 1.0 ≠ 1dec has no total order, so map lookup would depend on what else is in the map |
|
Normalizing 1.10 to 1.1 |
some libraries | a price loses its format |
| Silent conversion to float | Clojure's (+ 0.1M 0.2) |
exactness is lost without a sign |
HalfUp by default |
Excel, cash registers | biased in sums; the domain decides, and the domain's code says so |
The suffix m |
C# | dec says what it is |