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:
| Cell | On 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:
| Width | Policies | Bare default |
|---|---|---|
i8 | trapping, wrapping, saturating | trapping |
i16 | trapping, wrapping, saturating | trapping |
i32 | trapping, wrapping, saturating | trapping |
i64 | trapping, wrapping, saturating | trapping |
u8 | trapping, wrapping, saturating | trapping |
u16 | trapping, wrapping, saturating | trapping |
u32 | trapping, wrapping, saturating | trapping |
u64 | trapping, wrapping, saturating | trapping |
d64 | trapping | trapping |
inf | trapping, wrapping, saturating — one type | unbounded |
f16 | trapping, saturating | saturating |
bf16 | trapping, saturating | saturating |
f32 | trapping, saturating | saturating |
f64 | trapping, saturating | saturating |
b8 b16 b32 b64 | none — raw bits, not numbers | none |
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.