Skip to the content
Diaspar

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 names decimal.div; (decimal.div a b scale: n round: r) gives n digits 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's decimal, C#'s Math.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 of decimal.round and decimal.div says so with an example.
  • Mixing: integers and BigInts mix exactly ((+ 1 1.10dec) is 2.10dec); floats do not: an operator given a decimal and a float raises "does not mix decimals and floats" (D022). Conversions are explicit: decimal.parse from 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.10dec prints as 1.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, so 1, 1.0 and 1dec are one map key and one set element; (= 0.1dec 0.1) is false, since the float is 0.1000000000000000055511151231257827021181583404541015625. compare, <, sort, distinct and 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 with compare, 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 Money type 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