Home / Docs / Specification / 29. Numerics
29.16 Decimal
(ADR 0120 rules 12 to 21.) An exact base-10 number for money, whose scale is part of its type and whose every rounding is written. This section applies only to packages of edition 0.5; in earlier editions Decimal is an ordinary name, Decimal[2] is a syntax error (U0101), and the prelude has none of the names of rule 9.
-
The type.
Decimal[s], with s an integer literal from 0 to 38, is a built-in type: an integer coefficient c, unbounded asIntis, with the value c × 10^-s. A scale above 38, andDecimalwithout its scale in brackets, is U2037. There is no negative zero:-0.00is0.00. A user kind, variant, capability or unit namedDecimalis U1002; the prelude's variantJson.Decimalkeeps its name, since a type is always written with brackets.Decimal[s]satisfiesEqandOrd, by value, and neverInteger, so it is a map key andsortorders it. -
Literals. A float literal where
Decimal[s]is expected denotes its exact value at scale s, padded (5.0is5.00), with the exponent form allowed (1.5e3). It is never rounded: a nonzero digit beyond the scale is U2037, and so is a coefficient of more than 4,300 digits, the language's digit cap, decided by counting digits before any number is built. An integer literal where a decimal is expected is U2001, with an edit that adds.0.- In an operator (
+,-,*), a float literal takes the other operand's scale and MUST fit it: withprice: Decimal[2],price + 0.005is U2037, andprice * 1.1isprice * 1.10, aDecimal[4]. A literal never widens the other operand's scale. With two literals,+and-give both the expected scale, and*gives each the scale of its own digits. - In a comparison (
==,!=,<,<=,>,>=) a float literal beside a decimal takes the scale of its own digits, the digits after its point less its exponent, since a comparison is exact across scales:price < 0.005compares with0.005exactly. An own scale above 38 is U2037. - A float literal where nothing expects a decimal is an
F64(§2), so a decimal from a literal needs its type written, as inlet zero: Decimal[2] = 0.00.
- In an operator (
-
Arithmetic is exact, for operands of scales a and b:
Operation Result x + y,x - yDecimal[max(a, b)], the operand of smaller scale aligned by 10^|a - b|-xDecimal[a]x * yDecimal[a + b]; U2037 when a + b > 38==,!=,<,<=,>,>=Bool, by value across scales:1.0 == 1.00x / y,x mod yU2001, with repairs to divideandremainderwith an integer or an F64operandU2001, with a repair to n.to_decimal()orx.to_decimal(scale:, rounding:) -
Rounding. The prelude declares
kind Rounding = HalfEven | HalfAwayFromZero | HalfTowardZero | TowardZero | AwayFromZero | TowardPositive | TowardNegative. Rounding an exact value v to an integer number of units of a scale works on the magnitude: with m = |v| in those units, q = ⌊m⌋ and f = m - q, the rounded magnitude is q or q + 1, and the sign of v is applied after.TowardZerogives q;AwayFromZerogives q + 1 when f > 0;TowardPositiveacts asAwayFromZerofor v > 0 and asTowardZerofor v < 0,TowardNegativethe reverse; the threeHalfmodes give q when f < 1/2 and q + 1 when f > 1/2, and at f = 1/2,HalfEvengives the even one,HalfAwayFromZeroq + 1, andHalfTowardZeroq. No operation has a default mode. -
Methods. Each
scale:is an integer literal from 0 to 38, else U2037; the arguments are written in the order shown, the first after the receiver unlabeled only when punned.Method Result Contract x.widen(scale: s)Decimal[s]exact; s at least a, else U2037 with a repair to rescalex.rescale(scale: s, rounding: r)Decimal[s]s below a, else U2037 with a repair to widen; rounded once by rx.rescale_exact(scale: s)Decimal[s]s below a; a preconditionobligation that no nonzero digit is droppedx.divide(by: y, scale: s, rounding: r)Decimal[s]the exact quotient rounded once to scale s by r; a divisionobligationy != 0unlessyis a nonzero literalx.remainder(by: y, scale: s)Decimal[max(a, b + s)]x - y × qwith qx.divide(by: y, scale: s, rounding: TowardZero), exact, sox == y × q + remainderand the remainder has the sign of x; adivisionobligation; U2037 when the scale is above 38x.to_int(rounding: r)Introunded once to an integer by r x.to_f64()F64the nearest binary64 value to the exact value, ties to even, an infinity beyond the range x.abs()Decimal[a]exact x.coefficient()Intc n.to_decimal()onIntand the fixed-width typesDecimal[0]exact x.to_decimal(scale: s, rounding: r)onF64Option[Decimal[s]]Nonefor NaN and the infinities; otherwise the float's exact binary value, rounded oncedividecomputes in integers, with no intermediate rounding: forx: Decimal[2]equal to1.00,x.divide(by: 3.00, scale: 2, rounding: HalfEven)is0.33. A package function namedto_decimalwhose first parameter has an integer type,F64, or a type parameter is U1002, since the built-in conversion resolves ahead of it. -
Text. A decimal renders as an optional
-, its integer part, and for s > 0 a point and exactly s digits:-12.50,0.05;Decimal[0]renders as an integer. Interpolation and the Una form of a value that holds a decimal write it so.parse_decimal(t, scale: s)givesDecimal[s]and fails withParseError: it reads-? (0 | [1-9][0-9]*) ("." [0-9]+)?, with no exponent and no space; fraction digits beyond the scale are accepted only when they are zeros, elseNotADigit(at: i)at the first nonzero digit beyond it, which comes before any later position where no accepted text can continue;Empty,NoDigitsandNotADigitotherwise as forparse_f64; andTooLongwhen the coefficient at the scale would have more than 4,300 digits, leading zeros not counted, decided in O(b) before any conversion.parse_decimal(to_text(x), scale: s) == xfor every x within the cap. -
JSON.
as_decimal(j: Json, scale: s)givesOption[Decimal[s]]: forNumber(n), n at scale s; forDecimal(t), its exact value when it has one at scale s within the digit cap, the exponent read before any digit is built, so1e1000000000isNoneat once;Nonefor every otherJson.json_decimal(x)givesNumber(c)at scale 0, andDecimal(t)with t the rendering of rule 6 otherwise. -
The prelude's functions with a scale. The scale of
parse_decimal's andas_decimal's result is the literal of each call: the argument that binds the parameterscale, labeled, punned or at its position, MUST be an integer literal from 0 to 38, else U2037, so no run-time value sets a scale. Neither function, norjson_decimal, is a function value: naming one as a value is U2037.Decimal(...)where a decimal is expected is U2001 with a repair that names theJsonvariant (ADR 0120 rule 3). A package declaration of one of these names, or ofRoundingor its variants, is the package's own and keeps its meaning. -
Names that edition
0.5adds to the prelude:Roundingand its seven variants,parse_decimal,as_decimalandjson_decimal. -
Labels. A decimal carries labels as
Intdoes (spec/07); the result of every operator, method and conversion joins the labels of all its operands, the rounding mode included, andparse_decimal,as_decimalandjson_decimalcarry their arguments' labels. -
Verification. A decimal is its coefficient, an SMT
Int, so its queries stay inQF_UFLIA. In the refinement language, decimal literals,+,-, unary-, the comparisons,*with a literal factor andcoefficient()are terms, each operand aligned by a literal power of ten; the other methods are code only (U2014 in a clause).rescale,to_int,divideandremainderare encoded by the magnitude form of ADR 0120 V2: the quotient q and remainder r of the operands' magnitudes, by SMT-LIBdivandmodwhen the divisor is a literal and byi!div!Intandi!mod!Intotherwise, q or q + 1 by rule 4's case on r, written linearly, and then the sign.rescale_exact's precondition is(= (mod c 10^k) 0). A counterexample shows a decimal by its value. -
Representation. The coefficient is an
Int: in native code a tagged word that promotes (spec/16 §4 rule 2), and the scale is static, so aDecimal[2]below 4.6 × 10^16 is one machine word. Both engines compute every operation with the same exact routines. -
Cost. With d the limbs of a coefficient:
+,-, comparisons andwidenare O(d) beyond a multiplication by a constant power of ten;*is O(d²);rescale,divide,remainderandto_intare one division, O(d²); rendering is O(d²);parse_decimalis O(b) to decide and O(d²) to convert at most 4,300 digits;to_f64()is O(1) when |c| < 2^53 and s ≤ 22, and O(d²) otherwise. A coefficient a program grows by its own*is bounded by the memory budget, not by the cap. -
Not yet. Each of these refuses what it does not implement, or is a later step's:
- range sugar with decimal bounds (
Decimal[2] in 0.00..100.00) is a syntax error until float bounds parse (§1), andinwith a decimal literal range is U2001; a refinement is written withwhere; to_f32()of a decimal andto_decimalof anF32wait for a later step (§18 rule 15);to_f64()andto_decimalon anF64are not compiled to native code untilF64is (§9);- the
overflowobligation of rule 19 on coefficient operations in asystemspackage waits for thesystemsprofile; - U1002 for an imported
to_decimalholds for a function of a module outside the package, which only dependencies will declare; the edition ledger test of ADR 0121 that pins it, and the other items of ADR 0120's table, waits for that record's test; - an obligation's goal text shows coefficients, such as
result >= 0forit >= 0.00; a counterexample shows values.
- range sugar with decimal bounds (
-
Diagnostics. U2037, a decimal scale out of place: a scale that is not an integer literal from 0 to 38, the
scaleofparse_decimalandas_decimalincluded; a literal with a nonzero digit beyond its scale, also as an operator's operand or asby:, or whose coefficient passes the cap; a product or a remainder of scale above 38;widento a smaller scale, orrescaleorrescale_exactto a scale that is not smaller; a prelude function with a scale named as a value (ADR 0120, amendment of 2026-10-19). -
Units.
Decimal[s] ofa unit is a measured decimal (ADR 0120 rule 63): a currency is a unit,+,-and the comparisons need one unit across scales,*multiplies the units anddividedivides them, andconvert()multiplies the coefficient by an integer ratio, exactly (spec/25 §9).