Renderingen-US

Experimental through version 1. Version 0 was alpha. This is the first language release: the interface is relatively stable, not frozen. Nothing is promised stable until version 2.

Math in the ether

Faber treats a number's width the way measurement treats a value: it has no width until it is observed. A value is observed when it is stored into a cell or converted into one. Until then, no boundary applies to it.

So arithmetic runs unbounded — or as bare IEEE for floats — and a width limit is applied once, at the store or the conversion. Nothing clamps, traps, saturates or wraps per operation. In (100 + 200) / 2 the sum, 300, does not fit a u8, but nothing is checked there: the expression evaluates to 150, and only the store into a u8 cell is checked, where 150 fits.

The policy belongs to the cell, not to the arithmetic. An integer cell is one of three:

CellOn store or conversion
saturating<u8>clamps to the cell's range
wrapping<u8>reduces modulo the cell's width
trapping<u8>errors when the value does not fit

inf is the integer that stays unbounded after it is stored. A value that does not fit a fixed-width cell does not become inf by itself: the cell still applies its policy, and a bounded intermediate that leaves the 64-bit range traps. Write inf on a slot, or put an inf operand in the expression, and the unbounded width takes over — any integer width widens into it, and a store into an inf cell is never a size check.

Float cells follow the same rule: a bare f64 and a saturating<f64> both give ±infinity on overflow, because there is no maximum finite value to clamp to; only a trapping<f64> cell errors, and only when a non-finite value is stored or converted into it.

What it looks like#

The same unbounded sum is stored into cells with different policies:

main {
    let int a ← 200
    let int b ← 100
    let int exact ← (a + b) / 2
    print exact
    let saturating<u8> sat ← (a + b) ↦ saturating<u8>
    print sat
    let wrapping<u8> wrap ← (a + b) ↦ wrapping<u8>
    print wrap
}
$ faber run
150
255
44

(a + b) is 300 in the ether, and (a + b) / 2 is exactly 150 — the unbounded int keeps it. The limits appear only where the value becomes a u8: the sum saturates to 255 in a saturating cell, and reduces to 44 in a wrapping cell.

A trapping cell turns the same overflow into an error at the store:

main {
    let int big ← 300
    let trapping<u8> cell ← big ↦ u8
    print cell
}

The run stops at the store with an out-of-range error and a non-zero exit status.

Ranged cells#

A policy word can take a range as its second argument, so a cell holds exactly the values it names: saturating<W, lo ‥ hi>, trapping<W, lo ‥ hi> and wrapping<W, lo ‥ hi>. ‥ leaves the upper bound out, … includes it, and ∞ is no bound. The rule is the same as everywhere else: arithmetic stays exact, and only the store applies the range. A trapping cell errors on a value outside it, a saturating cell clamps, and a wrapping cell wraps into the range.

fn offset(trapping<i32, -2 ‥ 3> dy) → int {
    return dy
}

fn grow(trapping<u8, 0 ‥ 10> small) → trapping<u8, 0 ‥ 20> {
    return small
}

main {
    let i32 d ← 2
    let trapping<i32, -2 ‥ 3> dy ← d
    let i32 e ← -2
    let trapping<i32, -2 ‥ 3> dz ← e
    print dy
    print dz
    # Exact arithmetic: 4 is outside -2‥3 and prints as 4; nothing is stored.
    print dy + dy
    # A ranged cell reads as its width.
    let i32 back ← dy
    print back
    print offset(-2)
    # The inclusive glyph holds its high end.
    let trapping<u8, 1…5> top ← 5
    print top
    # Widening a range needs no check.
    let trapping<u8, 0 ‥ 20> larger ← grow(7)
    print larger
    # A ranged cell indexes a list: it can only name a slot inside its range.
    let list<int> xs ← [10, 20, 30, 40]
    let trapping<u8, 0 ‥ 4> ix ← 2
    print xs[ix]
    # The whole-width range is the bare type.
    let trapping<u8, 0…255> same ← 200
    let u8 plain ← same
    print plain
}

This prints 2, -2, 4, 2, -2, 5, 7, 30 and 200.

The spellings from the table above are whole-width ranges: saturating<u8> is saturating<u8, 0…255>, a bare u8 is trapping<u8, 0…255>, and inf is trapping<inf, -∞…∞>. Three mistakes are refused by name: a range outside the width (trapping<u8, 0 ‥ 300>, SEM008 ranged_policy_range_outside_width), an unsigned range that starts below zero (`SEM008 ranged_policy_unsigned_negative_bound`), and a range with no policy word (u8<0 ‥ 8>, SEM008 ranged_policy_word_required). faber run, the Rust target and the Faber emitter apply ranged cells; every other target stops at emission (most with ranged store policy in the message). A list length range is the same idea for a count: see bounded lists.

Why it works this way#

The rule buys predictability. A reader can look at an expression and reason about it as arithmetic, without carrying the widths of every operand in their head or wondering where an implicit reduction happens. The one place a boundary can bite is the one place the source names it: the store, or the ↦.

It also composes with the rest of the language. Because numeric families do not mix silently, an operation that crosses families (an integer and a float, say) is an explicit conversion — which is exactly the point where a policy would be applied. A saturating or wrapping cell cannot fail on conversion, so the conversion needs no default and no error channel; a trapping cell is where an out-of-range store is reported. See Types and values for the cell types themselves.

Every width, the overflow policies it accepts, and the policy a bare marker uses:

WidthPoliciesBare default
i8trapping, wrapping, saturatingtrapping
i16trapping, wrapping, saturatingtrapping
i32trapping, wrapping, saturatingtrapping
i64trapping, wrapping, saturatingtrapping
u8trapping, wrapping, saturatingtrapping
u16trapping, wrapping, saturatingtrapping
u32trapping, wrapping, saturatingtrapping
u64trapping, wrapping, saturatingtrapping
d64trappingtrapping
inftrapping, wrapping, saturating — one typeunbounded
f16trapping, saturatingsaturating
bf16trapping, saturatingsaturating
f32trapping, saturatingsaturating
f64trapping, saturatingsaturating
b8 b16 b32 b64none — raw bits, not numbersnone

The last row is the other domain. A b8, b16, b32 or b64 is exactly that many bits and no wider value exists in the middle of an expression. It takes bit operators (∧ ∨ ⊻ ¬ ⇐ ⇒), each acting at the type's own width every time, and has no arithmetic: x + x on a b8 is SEM011 bits_arithmetic_refused. Bits and numbers meet only at an explicit ↦ to the same-width type. This is not an exception to the store rule: an operation does what its own domain expects.