---
title: "29.16 Decimal"
url: https://una-lang.org/en/docs/spec/29-numerics/16-decimal/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/29-numerics.md
---

# 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.

1. **The type.** `Decimal[s]`, with s an integer literal from 0 to 38, is a built-in type: an integer coefficient c, unbounded as `Int` is, with the value c × 10^-s. A scale above 38, and `Decimal` without its scale in brackets, is U2037. There is no negative zero: `-0.00` is `0.00`. A user kind, variant, capability or unit named `Decimal` is U1002; the prelude's variant `Json.Decimal` keeps its name, since a type is always written with brackets. `Decimal[s]` satisfies `Eq` and `Ord`, by value, and never `Integer`, so it is a map key and `sort` orders it.
2. **Literals.** A float literal where `Decimal[s]` is expected denotes its exact value at scale s, padded (`5.0` is `5.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: with `price: Decimal[2]`, `price + 0.005` is U2037, and `price * 1.1` is `price * 1.10`, a `Decimal[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.005` compares with `0.005` exactly. 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 in `let zero: Decimal[2] = 0.00`.
3. **Arithmetic** is exact, for operands of scales a and b:

   | Operation | Result |
   | --- | --- |
   | `x + y`, `x - y` | `Decimal[max(a, b)]`, the operand of smaller scale aligned by 10^\|a - b\| |
   | `-x` | `Decimal[a]` |
   | `x * y` | `Decimal[a + b]`; U2037 when a + b > 38 |
   | `==`, `!=`, `<`, `<=`, `>`, `>=` | `Bool`, by value across scales: `1.0 == 1.00` |
   | `x / y`, `x mod y` | U2001, with repairs to `divide` and `remainder` |
   | with an integer or an `F64` operand | U2001, with a repair to `n.to_decimal()` or `x.to_decimal(scale:, rounding:)` |

4. **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. `TowardZero` gives q; `AwayFromZero` gives q + 1 when f > 0; `TowardPositive` acts as `AwayFromZero` for v > 0 and as `TowardZero` for v < 0, `TowardNegative` the reverse; the three `Half` modes give q when f < 1/2 and q + 1 when f > 1/2, and at f = 1/2, `HalfEven` gives the even one, `HalfAwayFromZero` q + 1, and `HalfTowardZero` q. No operation has a default mode.
5. **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 `rescale` |
   | `x.rescale(scale: s, rounding: r)` | `Decimal[s]` | s below a, else U2037 with a repair to `widen`; rounded once by r |
   | `x.rescale_exact(scale: s)` | `Decimal[s]` | s below a; a `precondition` obligation that no nonzero digit is dropped |
   | `x.divide(by: y, scale: s, rounding: r)` | `Decimal[s]` | the exact quotient rounded once to scale s by r; a `division` obligation `y != 0` unless `y` is a nonzero literal |
   | `x.remainder(by: y, scale: s)` | `Decimal[max(a, b + s)]` | `x - y × q` with q `x.divide(by: y, scale: s, rounding: TowardZero)`, exact, so `x == y × q + remainder` and the remainder has the sign of x; a `division` obligation; U2037 when the scale is above 38 |
   | `x.to_int(rounding: r)` | `Int` | rounded once to an integer by r |
   | `x.to_f64()` | `F64` | the nearest binary64 value to the exact value, ties to even, an infinity beyond the range |
   | `x.abs()` | `Decimal[a]` | exact |
   | `x.coefficient()` | `Int` | c |
   | `n.to_decimal()` on `Int` and the fixed-width types | `Decimal[0]` | exact |
   | `x.to_decimal(scale: s, rounding: r)` on `F64` | `Option[Decimal[s]]` | `None` for NaN and the infinities; otherwise the float's exact binary value, rounded once |

   `divide` computes in integers, with no intermediate rounding: for `x: Decimal[2]` equal to `1.00`, `x.divide(by: 3.00, scale: 2, rounding: HalfEven)` is `0.33`. A package function named `to_decimal` whose first parameter has an integer type, `F64`, or a type parameter is U1002, since the built-in conversion resolves ahead of it.
6. **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)` gives `Decimal[s]` and fails with `ParseError`: 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, else `NotADigit(at: i)` at the first nonzero digit beyond it, which comes before any later position where no accepted text can continue; `Empty`, `NoDigits` and `NotADigit` otherwise as for `parse_f64`; and `TooLong` when 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) == x` for every x within the cap.
7. **JSON.** `as_decimal(j: Json, scale: s)` gives `Option[Decimal[s]]`: for `Number(n)`, n at scale s; for `Decimal(t)`, its exact value when it has one at scale s within the digit cap, the exponent read before any digit is built, so `1e1000000000` is `None` at once; `None` for every other `Json`. `json_decimal(x)` gives `Number(c)` at scale 0, and `Decimal(t)` with t the rendering of rule 6 otherwise.
8. **The prelude's functions with a scale.** The scale of `parse_decimal`'s and `as_decimal`'s result is the literal of each call: the argument that binds the parameter `scale`, 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, nor `json_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 the `Json` variant (ADR 0120 rule 3). A package declaration of one of these names, or of `Rounding` or its variants, is the package's own and keeps its meaning.
9. **Names** that edition `0.5` adds to the prelude: `Rounding` and its seven variants, `parse_decimal`, `as_decimal` and `json_decimal`.
10. **Labels.** A decimal carries labels as `Int` does (`spec/07`); the result of every operator, method and conversion joins the labels of all its operands, the rounding mode included, and `parse_decimal`, `as_decimal` and `json_decimal` carry their arguments' labels.
11. **Verification.** A decimal is its coefficient, an SMT `Int`, so its queries stay in `QF_UFLIA`. In the refinement language, decimal literals, `+`, `-`, unary `-`, the comparisons, `*` with a literal factor and `coefficient()` are terms, each operand aligned by a literal power of ten; the other methods are code only (U2014 in a clause). `rescale`, `to_int`, `divide` and `remainder` are encoded by the magnitude form of ADR 0120 V2: the quotient q and remainder r of the operands' magnitudes, by SMT-LIB `div` and `mod` when the divisor is a literal and by `i!div!Int` and `i!mod!Int` otherwise, 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.
12. **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 a `Decimal[2]` below 4.6 × 10^16 is one machine word. Both engines compute every operation with the same exact routines.
13. **Cost.** With d the limbs of a coefficient: `+`, `-`, comparisons and `widen` are O(d) beyond a multiplication by a constant power of ten; `*` is O(d²); `rescale`, `divide`, `remainder` and `to_int` are one division, O(d²); rendering is O(d²); `parse_decimal` is 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.
14. **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), and `in` with a decimal literal range is U2001; a refinement is written with `where`;
    - `to_f32()` of a decimal and `to_decimal` of an `F32` wait for a later step (§18 rule 15);
    - `to_f64()` and `to_decimal` on an `F64` are not compiled to native code until `F64` is (§9);
    - the `overflow` obligation of rule 19 on coefficient operations in a `systems` package waits for the `systems` profile;
    - U1002 for an imported `to_decimal` holds 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 >= 0` for `it >= 0.00`; a counterexample shows values.
15. **Diagnostics.** U2037, a decimal scale out of place: a scale that is not an integer literal from 0 to 38, the `scale` of `parse_decimal` and `as_decimal` included; a literal with a nonzero digit beyond its scale, also as an operator's operand or as `by:`, or whose coefficient passes the cap; a product or a remainder of scale above 38; `widen` to a smaller scale, or `rescale` or `rescale_exact` to a scale that is not smaller; a prelude function with a scale named as a value (ADR 0120, amendment of 2026-10-19).
16. **Units.** `Decimal[s] of` a 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 and `divide` divides them, and `convert()` multiplies the coefficient by an integer ratio, exactly (`spec/25 §9`).
