bits

Translation status: English reader-locale proof. Term names and code fences follow the en pack; supporting prose may still be English.

A list<b8> converts to string as UTF-8, a list<b16> as UTF-16 and a list<b32> as UTF-32; the decode can fail and the encode cannot.

Syntax: let string s ← bytes ↦ string ⊥ \"?\" | let list<b16> units ← s ↦ list<b16>

Category#

conversio

Examples#

radix/corpus/bits/bits-bulk-la.fab (canonical · conversio)#

A bits list converts to a wider list with a via Le or via Be clause, and a same-width list takes none.

# =============================================================================
# bits — Bulk list conversions: a via clause exactly when the width changes
# =============================================================================
#
# What this teaches:
#   • list<b8> ↦ list<u8> keeps the width, so it takes no via clause
#   • a width change names its byte order: ↦ list<u16> via Le or via Be
#   • the clause also encodes back: list<u16> ↦ list<b8> via Le
#   • list<b8> ↦ list<b16> via Be reads byte pairs without reading them as numbers
#
# Common mistakes:
#   • writing via on a same-width list — one spelling, no clause
#   • leaving via off a width change — the byte order is not guessed
#
# See also: bits-literals, bits-operations
# =============================================================================

# bits — width-preserving round trip, Le and Be decode, encode, b8 to b16
#
# EXPECTED stdout: see bits-bulk-la.expected

main {
    let list<b8> raw ← [1, 2, 3, 4]
    let list<u8> plain ← raw ↦ list<u8>
    let list<b8> back ← plain ↦ list<b8>
    print plain
    print back
    let list<u16> le ← raw ↦ list<u16> via Le
    let list<u16> be ← raw ↦ list<u16> via Be
    print le
    print be
    let list<b8> encoded ← le ↦ list<b8> via Le
    print encoded
    let list<b16> wide ← raw ↦ list<b16> via Be
    print wide
}

Expected output:

[1, 2, 3, 4]
[0x01, 0x02, 0x03, 0x04]
[513, 1027]
[258, 772]
[0x01, 0x02, 0x03, 0x04]
[0x0102, 0x0304]

radix/corpus/bits/bits-bulk.fab (canonical · conversio)#

A bits list converts to a wider list with a via Le or via Be clause, and a same-width list takes none.

# =============================================================================
# bits — Bulk list conversions: a via clause exactly when the width changes
# =============================================================================
#
# What this teaches:
#   • list<b8> ↦ list<u8> keeps the width, so it takes no via clause
#   • a width change names its byte order: ↦ list<u16> via Le or via Be
#   • the clause also encodes back: list<u16> ↦ list<b8> via Le
#   • list<b8> ↦ list<b16> via Be reads byte pairs without reading them as numbers
#
# Common mistakes:
#   • writing via on a same-width list — one spelling, no clause
#   • leaving via off a width change — the byte order is not guessed
#
# See also: bits-literals, bits-operations
# =============================================================================

# bits — width-preserving round trip, Le and Be decode, encode, b8 to b16
#
# EXPECTED stdout: see bits-bulk.expected

main {
    let list<b8> raw ← [0x01, 0x02, 0x03, 0x04]
    let list<u8> plain ← raw ↦ list<u8>
    let list<b8> back ← plain ↦ list<b8>
    print plain
    print back
    let list<u16> le ← raw ↦ list<u16> via Le
    let list<u16> be ← raw ↦ list<u16> via Be
    print le
    print be
    let list<b8> encoded ← le ↦ list<b8> via Le
    print encoded
    let list<b16> wide ← raw ↦ list<b16> via Be
    print wide
}

Expected output:

[1, 2, 3, 4]
[0x01, 0x02, 0x03, 0x04]
[513, 1027]
[258, 772]
[0x01, 0x02, 0x03, 0x04]
[0x0102, 0x0304]

radix/corpus/bits/bits-display-la.fab (canonical · display)#

print shows a bits value as hex at its full width, alone or inside a list.

# =============================================================================
# bits — Display is hex at full width
# =============================================================================
#
# What this teaches:
#   • a b8 prints as two hex digits, b16 as four, b32 as eight, b64 as sixteen
#   • leading zeros are kept: the display shows the whole width
#   • a list of bits prints each element the same way
#
# Common mistakes:
#   • expecting decimal output — bits are patterns, not quantities
#
# See also: bits-literals, bits-operations
# =============================================================================

# bits — hex print at full width
#
# EXPECTED stdout: see bits-display-la.expected

main {
    let b8 one8 ← 1
    let b16 one16 ← 1
    let b32 one32 ← 1
    let b64 one64 ← 1
    print one8
    print one16
    print one32
    print one64
    let list<b8> bytes ← [0, 15, 165, 255]
    print bytes
}

Expected output:

0x01
0x0001
0x00000001
0x0000000000000001
[0x00, 0x0f, 0xa5, 0xff]

radix/corpus/bits/bits-display-optional-la.fab (canonical · display)#

A bN inside an optional still prints as hex at full width; an absent optional prints none, and a nested list keeps its brackets.

# =============================================================================
# bits — Display of optional and nested bits values
# =============================================================================
#
# What this teaches:
#   • a present `b8 ∪ none` prints exactly as its b8: hex at full width
#   • an absent `b8 ∪ none` prints `none`
#   • a present `list<b8> ∪ none` prints in list shape, each element in hex
#   • an absent `list<b8> ∪ none` prints `none`
#   • a nested `list<list<b8>>` prints its inner lists in brackets
#
# Common mistakes:
#   • expecting an absent optional to print `0x00` or `[]` — absent is `none`
#   • expecting a nested list to flatten into one bracket level
#
# See also: bits-display, bits-literals, optionalis
# =============================================================================

# bits — optional and nested display
#
# EXPECTED stdout: see bits-display-optional-la.expected

main {
    # a present optional scalar prints as the b8 it holds
    let b8 sample ← 255
    let b8 ∪ none present ← sample
    print present

    # an absent optional scalar prints none
    let b8 ∪ none absent ← null
    print absent

    # a present optional list prints each element in hex
    let list<b8> raw ← [222, 173]
    let list<b8> ∪ none bytes ← raw
    print bytes

    # an absent optional list prints none
    let list<b8> ∪ none missing ← null
    print missing

    # a nested list keeps its inner brackets
    let list<list<b8>> rows ← [[1], [2, 255]]
    print rows
}

Expected output:

0xff
nihil
[0xde, 0xad]
nihil
[[0x01], [0x02, 0xff]]

radix/corpus/bits/bits-display-optional.fab (canonical · display)#

A bN inside an optional still prints as hex at full width; an absent optional prints none, and a nested list keeps its brackets.

# =============================================================================
# bits — Display of optional and nested bits values
# =============================================================================
#
# What this teaches:
#   • a present `b8 ∪ none` prints exactly as its b8: hex at full width
#   • an absent `b8 ∪ none` prints `none`
#   • a present `list<b8> ∪ none` prints in list shape, each element in hex
#   • an absent `list<b8> ∪ none` prints `none`
#   • a nested `list<list<b8>>` prints its inner lists in brackets
#
# Common mistakes:
#   • expecting an absent optional to print `0x00` or `[]` — absent is `none`
#   • expecting a nested list to flatten into one bracket level
#
# See also: bits-display, bits-literals, optionalis
# =============================================================================

# bits — optional and nested display
#
# EXPECTED stdout: see bits-display-optional.expected

main {
    # a present optional scalar prints as the b8 it holds
    let b8 sample ← 0xff
    let b8 ∪ none present ← sample
    print present

    # an absent optional scalar prints none
    let b8 ∪ none absent ← null
    print absent

    # a present optional list prints each element in hex
    let list<b8> raw ← [0xde, 0xad]
    let list<b8> ∪ none bytes ← raw
    print bytes

    # an absent optional list prints none
    let list<b8> ∪ none missing ← null
    print missing

    # a nested list keeps its inner brackets
    let list<list<b8>> rows ← [[0x01], [0x02, 0xff]]
    print rows
}

Expected output:

0xff
none
[0xde, 0xad]
none
[[0x01], [0x02, 0xff]]

radix/corpus/bits/bits-display.fab (canonical · display)#

print shows a bits value as hex at its full width, alone or inside a list.

# =============================================================================
# bits — Display is hex at full width
# =============================================================================
#
# What this teaches:
#   • a b8 prints as two hex digits, b16 as four, b32 as eight, b64 as sixteen
#   • leading zeros are kept: the display shows the whole width
#   • a list of bits prints each element the same way
#
# Common mistakes:
#   • expecting decimal output — bits are patterns, not quantities
#
# See also: bits-literals, bits-operations
# =============================================================================

# bits — hex print at full width
#
# EXPECTED stdout: see bits-display.expected

main {
    let b8 one8 ← 0x01
    let b16 one16 ← 0x0001
    let b32 one32 ← 0x00000001
    let b64 one64 ← 0x0000000000000001
    print one8
    print one16
    print one32
    print one64

    let list<b8> bytes ← [0x00, 0x0f, 0xa5, 0xff]
    print bytes
}

Expected output:

0x01
0x0001
0x00000001
0x0000000000000001
[0x00, 0x0f, 0xa5, 0xff]

radix/corpus/bits/bits-literals-la.fab (canonical · literal)#

A hex, binary or decimal integer literal in a bits cell takes the cell's type at all four widths.

# =============================================================================
# bits — Literals take the cell's type
# =============================================================================
#
# What this teaches:
#   • an integer literal in a bN cell is a bN value, not a number
#   • hex, binary and decimal spellings are all accepted
#   • the literal must fit the width: 0xff fits a b8, 0x1ff does not
#
# Common mistakes:
#   • writing a literal wider than the cell — that is a compile error
#
# See also: bits-display, bits-literal-range-reject
# =============================================================================

# bits — hex, binary and decimal literals at every width
#
# EXPECTED stdout: see bits-literals-la.expected

main {
    let b8 hex8 ← 255
    let b8 bin8 ← 165
    let b8 dec8 ← 255
    let b16 hex16 ← 65535
    let b16 bin16 ← 10
    let b16 dec16 ← 65535
    let b32 hex32 ← 4294967295
    let b32 bin32 ← 1
    let b32 dec32 ← 4294967295
    let b64 hex64 ← 18446744073709551615
    let b64 bin64 ← 8
    let b64 dec64 ← 255
    print hex8
    print bin8
    print dec8
    print hex16
    print bin16
    print dec16
    print hex32
    print bin32
    print dec32
    print hex64
    print bin64
    print dec64
}

Expected output:

0xff
0xa5
0xff
0xffff
0x000a
0xffff
0xffffffff
0x00000001
0xffffffff
0xffffffffffffffff
0x0000000000000008
0x00000000000000ff

radix/corpus/bits/bits-literals.fab (canonical · literal)#

A hex, binary or decimal integer literal in a bits cell takes the cell's type at all four widths.

# =============================================================================
# bits — Literals take the cell's type
# =============================================================================
#
# What this teaches:
#   • an integer literal in a bN cell is a bN value, not a number
#   • hex, binary and decimal spellings are all accepted
#   • the literal must fit the width: 0xff fits a b8, 0x1ff does not
#
# Common mistakes:
#   • writing a literal wider than the cell — that is a compile error
#
# See also: bits-display, bits-literal-range-reject
# =============================================================================

# bits — hex, binary and decimal literals at every width
#
# EXPECTED stdout: see bits-literals.expected

main {
    let b8 hex8 ← 0xff
    let b8 bin8 ← 0b10100101
    let b8 dec8 ← 255
    let b16 hex16 ← 0xffff
    let b16 bin16 ← 0b1010
    let b16 dec16 ← 65535
    let b32 hex32 ← 0xffffffff
    let b32 bin32 ← 0b1
    let b32 dec32 ← 4294967295
    let b64 hex64 ← 0xffffffffffffffff
    let b64 bin64 ← 0b1000
    let b64 dec64 ← 255
    print hex8
    print bin8
    print dec8
    print hex16
    print bin16
    print dec16
    print hex32
    print bin32
    print dec32
    print hex64
    print bin64
    print dec64
}

Expected output:

0xff
0xa5
0xff
0xffff
0x000a
0xffff
0xffffffff
0x00000001
0xffffffff
0xffffffffffffffff
0x0000000000000008
0x00000000000000ff

radix/corpus/bits/bits-operations-la.fab (canonical · operator-group)#

b8, b16, b32 and b64 are raw bits: ∧ ∨ ⊻ ¬ ⇐ ⇒ act at the type's own width, every time.

# =============================================================================
# bits — Bit operations act at the type's width
# =============================================================================
#
# What this teaches:
#   • A bN is exactly N bits; no wider value exists in the middle of an expression
#   • ∧ ∨ ⊻ combine two bits values of the same width; ¬ flips exactly N bits
#   • ⇐ shifts left and drops bits off the top; ⇒ shifts right and fills with zeros
#   • A shift by N or more gives all zeros; the count is not wrapped
#   • (b ⇐ 4) ⇒ 4 on a b8 clears the high nibble
#
# Common mistakes:
#   • expecting a left shift to widen the value — a b8 stays eight bits
#   • using + or - on bits — bits have no arithmetic; convert with ↦ first
#
# See also: bits-order, bits-literals, bits-display
# =============================================================================

# bits — operations at the type's own width
#
# WHY: an operation does what its own domain expects. Bit movement expects the
# container's edge, so bits have their width always.
#
# EXPECTED stdout: see bits-operations-la.expected

main {
    let b8 a ← 243
    let b8 mask ← 15
    print a ∧ mask
    print a ∨ mask
    print a ⊻ mask
    print ¬a
    print a ⇐ 4
    print a ⇒ 4
    let b8 cleared ← a ⇐ 4 ⇒ 4
    print cleared
    print a ⇐ 8
    print a ⇒ 8
    let b64 wide ← 17361641481138401520
    let b64 low ← 4294967295
    print wide ∧ low
    print wide ∨ low
    print wide ⊻ low
    print ¬wide
    print wide ⇐ 4
    print wide ⇒ 60
    print wide ⇐ 64
    print wide ⇒ 64
}

Expected output:

0x03
0xff
0xfc
0x0c
0x30
0x0f
0x03
0x00
0x00
0x00000000f0f0f0f0
0xf0f0f0f0ffffffff
0xf0f0f0f00f0f0f0f
0x0f0f0f0f0f0f0f0f
0x0f0f0f0f0f0f0f00
0x000000000000000f
0x0000000000000000
0x0000000000000000

radix/corpus/bits/bits-operations.fab (canonical · operator-group)#

b8, b16, b32 and b64 are raw bits: ∧ ∨ ⊻ ¬ ⇐ ⇒ act at the type's own width, every time.

# =============================================================================
# bits — Bit operations act at the type's width
# =============================================================================
#
# What this teaches:
#   • A bN is exactly N bits; no wider value exists in the middle of an expression
#   • ∧ ∨ ⊻ combine two bits values of the same width; ¬ flips exactly N bits
#   • ⇐ shifts left and drops bits off the top; ⇒ shifts right and fills with zeros
#   • A shift by N or more gives all zeros; the count is not wrapped
#   • (b ⇐ 4) ⇒ 4 on a b8 clears the high nibble
#
# Common mistakes:
#   • expecting a left shift to widen the value — a b8 stays eight bits
#   • using + or - on bits — bits have no arithmetic; convert with ↦ first
#
# See also: bits-order, bits-literals, bits-display
# =============================================================================

# bits — operations at the type's own width
#
# WHY: an operation does what its own domain expects. Bit movement expects the
# container's edge, so bits have their width always.
#
# EXPECTED stdout: see bits-operations.expected

main {
    let b8 a ← 0xf3
    let b8 mask ← 0x0f
    print a ∧ mask
    print a ∨ mask
    print a ⊻ mask
    print ¬ a
    print a ⇐ 4
    print a ⇒ 4
    let b8 cleared ← (a ⇐ 4) ⇒ 4
    print cleared
    print a ⇐ 8
    print a ⇒ 8

    let b64 wide ← 0xf0f0f0f0f0f0f0f0
    let b64 low ← 0x00000000ffffffff
    print wide ∧ low
    print wide ∨ low
    print wide ⊻ low
    print ¬ wide
    print wide ⇐ 4
    print wide ⇒ 60
    print wide ⇐ 64
    print wide ⇒ 64
}

Expected output:

0x03
0xff
0xfc
0x0c
0x30
0x0f
0x03
0x00
0x00
0x00000000f0f0f0f0
0xf0f0f0f0ffffffff
0xf0f0f0f00f0f0f0f
0x0f0f0f0f0f0f0f0f
0x0f0f0f0f0f0f0f00
0x000000000000000f
0x0000000000000000
0x0000000000000000

radix/corpus/bits/bits-order-la.fab (canonical · operator-group)#

bits values compare for equality and order by bit pattern read as unsigned.

# =============================================================================
# bits — Equality and unsigned ordering
# =============================================================================
#
# What this teaches:
#   • bits values have equality, and order by bit pattern read as unsigned
#   • 0x80 is greater than 0x7f on a b8: there is no sign bit
#   • an integer literal beside a bits operand takes the bits type
#
# Common mistakes:
#   • reading the top bit as a sign — a bN is never negative
#   • comparing a bN with a number — convert with ↦ first
#
# See also: bits-operations, bits-literals
# =============================================================================

# bits — ordering is unsigned
#
# EXPECTED stdout: see bits-order-la.expected

main {
    let b8 high ← 128
    let b8 low ← 127
    let b8 same ← 128
    print high ≻ low
    print high ≺ low
    print high ≥ same
    print high ≤ low
    print high ≡ same
    print high ≢ low
    print high ≡ 128
    print 127 ≺ high
    let b64 big ← 9223372036854775808
    let b64 small ← 9223372036854775807
    print big ≻ small
    print big ≡ small
}

Expected output:

verum
falsum
verum
falsum
verum
verum
verum
verum
verum
falsum

radix/corpus/bits/bits-order.fab (canonical · operator-group)#

bits values compare for equality and order by bit pattern read as unsigned.

# =============================================================================
# bits — Equality and unsigned ordering
# =============================================================================
#
# What this teaches:
#   • bits values have equality, and order by bit pattern read as unsigned
#   • 0x80 is greater than 0x7f on a b8: there is no sign bit
#   • an integer literal beside a bits operand takes the bits type
#
# Common mistakes:
#   • reading the top bit as a sign — a bN is never negative
#   • comparing a bN with a number — convert with ↦ first
#
# See also: bits-operations, bits-literals
# =============================================================================

# bits — ordering is unsigned
#
# EXPECTED stdout: see bits-order.expected

main {
    let b8 high ← 0x80
    let b8 low ← 0x7f
    let b8 same ← 0x80
    print high ≻ low
    print high ≺ low
    print high ≥ same
    print high ≤ low
    print high ≡ same
    print high ≢ low
    print high ≡ 0x80
    print 0x7f ≺ high

    let b64 big ← 0x8000000000000000
    let b64 small ← 0x7fffffffffffffff
    print big ≻ small
    print big ≡ small
}

Expected output:

true
false
true
false
true
true
true
true
true
false

radix/corpus/bits/bits-text-la.fab (canonical · conversio)#

A list<b8> converts to string as UTF-8, a list<b16> as UTF-16 and a list<b32> as UTF-32; the decode can fail and the encode cannot.

# =============================================================================
# bits — Text conversions at widths 8, 16 and 32
# =============================================================================
#
# What this teaches:
#   • list<b8> ↦ string is a UTF-8 decode, list<b16> UTF-16, list<b32> UTF-32
#   • string ↦ list<bN> is the encode and cannot fail
#   • a decode can fail on ill-formed input; recover with a ⊥ default
#   • the elements are the code units, so no byte order is involved
#
# Common mistakes:
#   • expecting a decode to succeed on any bits — ill-formed units fail
#   • reaching for b64 — it has no text conversion
#
# See also: bits-bulk, bits-display
# =============================================================================

# bits — UTF-8, UTF-16 and UTF-32 round trips and a failing decode
#
# EXPECTED stdout: see bits-text-la.expected

main {
    # UTF-8: "é" is two bytes
    let string word ← "héllo"
    let list<b8> utf8 ← word ↦ list<b8>
    print utf8
    print utf8 ↦ string ⊥ "?"

    # UTF-16: a character outside the basic plane is a surrogate pair
    let string face ← "a😀"
    let list<b16> utf16 ← face ↦ list<b16>
    print utf16
    print utf16 ↦ string ⊥ "?"

    # UTF-32: one unit per character
    let list<b32> utf32 ← face ↦ list<b32>
    print utf32
    print utf32 ↦ string ⊥ "?"

    # a failing decode: 0xff is never valid in UTF-8
    let list<b8> bad ← [104, 255]
    print bad ↦ string ⊥ "?"
}

Expected output:

[0x68, 0xc3, 0xa9, 0x6c, 0x6c, 0x6f]
héllo
[0x0061, 0xd83d, 0xde00]
a😀
[0x00000061, 0x0001f600]
a😀
?

radix/corpus/bits/bits-text.fab (canonical · conversio)#

A list<b8> converts to string as UTF-8, a list<b16> as UTF-16 and a list<b32> as UTF-32; the decode can fail and the encode cannot.

# =============================================================================
# bits — Text conversions at widths 8, 16 and 32
# =============================================================================
#
# What this teaches:
#   • list<b8> ↦ string is a UTF-8 decode, list<b16> UTF-16, list<b32> UTF-32
#   • string ↦ list<bN> is the encode and cannot fail
#   • a decode can fail on ill-formed input; recover with a ⊥ default
#   • the elements are the code units, so no byte order is involved
#
# Common mistakes:
#   • expecting a decode to succeed on any bits — ill-formed units fail
#   • reaching for b64 — it has no text conversion
#
# See also: bits-bulk, bits-display
# =============================================================================

# bits — UTF-8, UTF-16 and UTF-32 round trips and a failing decode
#
# EXPECTED stdout: see bits-text.expected

main {
    # UTF-8: "é" is two bytes
    let string word ← "héllo"
    let list<b8> utf8 ← word ↦ list<b8>
    print utf8
    print utf8 ↦ string ⊥ "?"

    # UTF-16: a character outside the basic plane is a surrogate pair
    let string face ← "a😀"
    let list<b16> utf16 ← face ↦ list<b16>
    print utf16
    print utf16 ↦ string ⊥ "?"

    # UTF-32: one unit per character
    let list<b32> utf32 ← face ↦ list<b32>
    print utf32
    print utf32 ↦ string ⊥ "?"

    # a failing decode: 0xff is never valid in UTF-8
    let list<b8> bad ← [0x68, 0xff]
    print bad ↦ string ⊥ "?"
}

Expected output:

[0x68, 0xc3, 0xa9, 0x6c, 0x6c, 0x6f]
héllo
[0x0061, 0xd83d, 0xde00]
a😀
[0x00000061, 0x0001f600]
a😀
?