bão_hòa

Saturating integers: a store clamps at both ends of the width.

Syntax: saturating<W>

Category#

arithmetic

Related#

• số
• modulus<u32>

Examples#

radix/corpus/operatores/saturating-word.fab (canonical · operator-group)#

Saturating integers: a store clamps at both ends of the width.

# =============================================================================
# bão_hòa — Saturating integers: a store clamps at both ends of the width.
# =============================================================================
#
# What this teaches:
#   • Clamp contract — `saturating<W>` never traps or wraps on a store; a value
#     past either end of `W` lands at that end (pixels, audio, levels).
#   • Signed or unsigned — `saturating<i16>` clamps at −32768 and 32767.
#   • Exact arithmetic — `+ - * / %` on `saturating` operands is exact, like every
#     integer expression: `high + 10` is 260, `high * 2` is 500, `low - 10` is -5.
#     Nothing clamps until the value is stored into a `saturating` slot
#     (declaration, assignment, argument, return, `↑`/`↓`, …).
#   • Clamp once, at the store — a chain clamps where the value lands:
#     `high + 200 - 100` is 255 (exact 350), not 155, and `low - 300 + 100` is 0
#     (exact −190). An inferred slot (`_`) keeps the word and clamps the same way.
#
# Common mistakes:
#   • Mixing families — `saturating<u8> + u8` is an error; convert with `↦`.
#   • Expecting `↦` to fail — a chuyển into `saturating<W>` clamps and cannot
#     fail, so it takes no `⊥` recovery (`wrapping<W>` reduces mod 2^W the same way).
#
# See also: số, môđun
# =============================================================================

main {
    const saturating<u8> high ← 250
    const saturating<u8> low ← 5
    # Arithmetic is exact: nothing here is stored into a saturating slot.
    print high + 10
    print low - 10
    print high * 2
    print high / 2
    print high % 7
    const saturating<i16> big ← 30000
    const saturating<i16> neg ← -30000
    const saturating<i16> floor ← neg - 10000
    print big + 10000
    print floor
    print big * -2
    print -floor
    print floor / -1
    var saturating<u8> level ← 200
    # Each assignment is a store into a saturating slot: it clamps.
    level ← level + 100
    print level
    level ← level - 255
    print level
    const int n ← 200
    const saturating<u8> fromInt ← n ↦ saturating<u8>
    const int back ← high ↦ int
    print fromInt
    print back
    print high ≻ low
    # Chains clamp once, at the store.
    const saturating<u8> chainUp ← high + 200 - 100
    const saturating<u8> chainDown ← low - 300 + 100
    const saturating<u8> chainExact ← high * 2 / 4
    const saturating<u8> wide ← 200
    const saturating<u8> chainFits ← wide * 2 / 4
    const saturating<u8> chainRound ← low - wide - wide + wide + wide
    print chainUp
    print chainDown
    print chainExact
    print chainFits
    print chainRound
    var saturating<u8> acc ← 200
    acc ← acc + 100 - 50
    print acc
    # `↦` into saturating clamps the exact value; into wrapping it reduces mod 2^W.
    const int over ← 300
    const int under ← -5
    const saturating<u8> clampedHigh ← over ↦ saturating<u8>
    const saturating<u8> clampedLow ← under ↦ saturating<u8>
    const wrapping<u8> wrapped ← over ↦ wrapping<u8>
    print clampedHigh
    print clampedLow
    print wrapped
}

Expected output:

260
-5
500
125
5
40000
-32768
-60000
32768
32768
255
0
200
250
verum
255
0
125
100
5
250
255
0
44