18 Sized Numbers and Bits
Firmware talks to hardware, and hardware works in bits: a status register where each bit is a flag, a byte in a frame from a sensor, a 16-bit value split over two registers. This chapter is about the operators that work on bits, and the six whole-number types that say how many bits a number fits in.
18.1 Writing bits
A whole number can be written in hexadecimal after 0x,
in binary after 0b and in octal after 0o, and
_ can split the digits into groups. A format shows a number
the same ways (Text):
let status = 0b1010_0101
print(status, 0xA5, 0o245)
print(f"{status:08b} {status:02X} {status:x}")165 165 165
10100101 A5 a5
18.2 The bit operators
| Operator | Means | Example |
|---|---|---|
& |
and: a bit set in both | 0b1100 & 0b1010 is
0b1000 |
| |
or: a bit set in either | 0b1100 | 0b1010 is
0b1110 |
^ |
exclusive or: set in one, not both | 0b1100 ^ 0b1010 is
0b0110 |
~ |
every bit turned over | ~0 is -1 |
<< |
shift left: times two, n
times |
1 << 4 is
16 |
>> |
shift right: halve, rounding down | 0xF0 >> 4 is
15 |
Each has an = form: &=,
|=, ^=, <<=,
>>=. They are the everyday tools of a register:
let READY = 1 << 0
let ERROR = 1 << 3
var flags = 0
flags |= READY # set a bit
flags |= ERROR
print(f"{flags:08b}")
flags &= ~ERROR # clear a bit
print(f"{flags:08b}", flags & READY != 0)
flags ^= READY # turn a bit over
print(f"{flags:08b}")
let reading = 0x3A7
print((reading >> 8) & 0xFF, reading & 0xFF) # high byte, low byte00001001
00000001 true
00000000
3 167
An int is 64 bits in two’s complement, so
~x is -x - 1 and -1 & 0xFF is
255.
Zeno spells and, or and not as
words, and still uses symbols for bits. status & MASK
is how every datasheet, every C header and every Python script writes
it, and a firmware engineer reads it faster than any word. The words
left & and | free for exactly this.
(Decision 2.7.)
The C slip, & on two bools, is caught,
and so is &&:
let ready = true
let safe = false
print(ready & safe)error: `&` works on the bits of whole numbers, and these are bool and bool. For two bools Zeno spells this `and`
--> main.zeno:3:7
|
3 | print(ready & safe)
| ^
1 error found. Nothing was run.
Bits come before comparisons
flags & MASK == 0 means
(flags & MASK) == 0, as it looks. The bit operators
bind tighter than the comparisons, as in Python:
let flags = 0x81
print(flags & 0x80 == 0x80, flags & 0x02 == 0)true true
In C, flags & MASK == 0 means
flags & (MASK == 0), which is almost never what was
meant and compiles without a word. C’s own authors called it a mistake
that was too late to fix. (Decision 2.7a.)
Shifts are checked
A shift left that would push set bits off the top is an
OverflowError, as * would be, and a shift by a
count outside 0 to 63 is a ValueError:
print(1 << 64)error: uncaught ValueError: cannot shift by 64. An int has 64 bits, so a shift is 0 to 63
--> main.zeno:1:7
|
1 | print(1 << 64)
| ^
In C, a shift by 64 or by a negative count is undefined, and
1 << 40 on a 32-bit int is a wrong number. Each is a
quiet wrong answer. To throw away the top bits on purpose, say so with
wrap, below. (Decision 2.7b.)
18.3 Sized whole numbers
An int is 64 bits. Six more types say that a whole
number fits in fewer:
| Type | Bits | Holds |
|---|---|---|
u8 |
8 | 0 to 255 |
u16 |
16 | 0 to 65 535 |
u32 |
32 | 0 to 4 294 967 295 |
i8 |
8 | − 128 to 127 |
i16 |
16 | − 32 768 to 32 767 |
i32 |
32 | − 2 147 483 648 to 2 147 483 647 |
They are for where the size is real: a byte in a frame, a field of an
object on a board with 2 KB of memory, a register. With the size in the
type, the checker knows that a u8 is never handed 300, and
a compiled program stores it in one byte.
let level: u8 = 200
let offset: i16 = -300
let frame: list[u8] = [0x02, 0x41, 0xFF]
print(level, offset, frame)200 -300 [2, 65, 255]
A number written out takes the size of where it goes, and one that does not fit is refused before the program runs:
let level: u8 = 300error: 300 does not fit in a u8 (0 to 255)
--> main.zeno:1:17
|
1 | let level: u8 = 300
| ^
1 error found. Nothing was run.
The names are Rust’s, and close to C’s uint8_t with the
noise taken off. byte and short say less: how
long is a short? (Decision 2.8.)
Arithmetic gives an int
Sums, products, shifts and the rest on sized numbers give an
int, so the middle of a calculation never overflows at
255:
let a: u8 = 200
let b: u8 = 100
print(a + b, (a + b) // 2)300 150
The one place a number may not fit is where it is stored, and there the program says what it wants.
Wrapping at the size, as C does, makes 200 + 100 into
44, quietly. Checking at the size, as Rust does when
debugging, makes (a + b) // 2 fail for two numbers whose
average fits. Refusing to mix sizes needs a conversion on every line,
and people stop reading them. Working in ints and checking where the
answer is stored is C’s integer promotion without the silent cut at the
end. (Decision 2.8a.)
18.4 Putting a number back: check or wrap
There are two ways to turn an int into a sized number,
and they must not look alike:
u8(n)isnif it fits, and anOverflowErrorif it does not.u8.wrap(n)keeps the low 8 bits and never fails:u8.wrap(300)is 44, andi8.wrap(200)is − 56.
let a: u8 = 200
let b: u8 = 100
print(u8.wrap(a + b), i8.wrap(200), u16(a + b))44 -56 300
A checksum is meant to lose its top bits, so it wraps:
function checksum(data: list[u8]) -> u8 {
var total = 0
for byte in data {
total += byte
}
return u8.wrap(total)
}
print(checksum([0xFF, 0x02, 0x10]))17
A length that does not fit in its field is a bug, so it is checked:
let length = 300
let field = u8(length)error: uncaught OverflowError: 300 does not fit in a u8 (0 to 255)
--> main.zeno:2:13
|
2 | let field = u8(length)
| ^
In C both are written (uint8_t)x, and the reader has to
guess which was meant. Here the short spelling is the safe one, and
wrapping is a word that a reviewer can search for. (Decision 2.8b.)
count += 1
count += 1 on a sized number means
count = u8(count + 1): the sum is an int, and it is checked
where it is stored. A counter that passes 255 without anybody deciding
it should is a bug:
var count: u8 = 254
count += 1
print(count)
count += 1255
error: uncaught OverflowError: 256 does not fit in a u8 (0 to 255)
--> main.zeno:4:1
|
4 | count += 1
| ^
A counter that is meant to go round says so:
count = u8.wrap(count + 1). (Decision 10.27.)
18.5 What goes where by itself
A sized number goes wherever an
intis wanted, with nothing written: everyu8is anint.An
intdoes not go where au8is wanted, and au8does not go where au16is wanted. Each needsu8(...)oru16(...).
let reading = 5
let level: u8 = readingerror: `level` should be u8, but this is int. Convert it with `u8(...)`, which checks that it fits
--> main.zeno:2:17
|
2 | let level: u8 = reading
| ^
1 error found. Nothing was run.
The first cannot lose anything, so asking for it would be noise. The
second can, so it is written. A list[u8] is not a
list[int], because lists are shared: whoever held it as a
list[int] could append 300. Copy it,
[int(b) for b in frame].
There is no u64. An int is 64 bits with a
sign, so half the values of a u64 would not fit in one, and
"arithmetic gives an int" would stop being true. (Decision
2.8d.)
18.6 A worked example: a frame from a sensor
A sensor sends a frame of four bytes: a start byte 0x02,
a 16-bit reading high byte first, and a checksum of the first three.
This program builds one and reads it back:
frame.zeno
function checksum(data: list[u8]) -> u8 {
var total = 0
for byte in data {
total += byte
}
return u8.wrap(total)
}
function make_frame(reading: u16) -> list[u8] {
let frame: list[u8] = [0x02, u8(reading >> 8), u8(reading & 0xFF)]
frame.append(checksum(frame))
return frame
}
function read_frame(frame: list[u8]) -> u16 raises ValueError {
if frame[0] != 0x02 {
raise ValueError("a frame starts with 0x02")
}
if checksum(frame.slice(0, 3)) != frame[3] {
raise ValueError("the checksum does not match")
}
return u16(frame[1] << 8 | frame[2])
}
let frame = make_frame(931)
print([f"{b:02X}" for b in frame])
print(read_frame(frame))
frame[2] = 0x00
try {
read_frame(frame)
} except ValueError as e {
print("refused:", e.message)
}["02", "03", "A3", "A8"]
931
refused: the checksum does not match
Whole numbers can be written in 0x, 0b and
0o. &, |, ^,
~, << and >> work on
bits, bind tighter than comparisons, and shifts are checked.
u8, u16, u32, i8,
i16 and i32 say how many bits a number fits
in. Arithmetic on them gives an int; u8(n)
puts it back with a check, and u8.wrap(n) by cutting. A
sized number is an int for free; the other way is
written.
Write
function bit_is_set(value: int, bit: int) -> boolandfunction set_bit(value: int, bit: int) -> int.Split a
u32into fouru8s, high byte first, and join them again.Count the set bits of a number with a loop,
&and>>.Change the checksum in the frame example to an exclusive or of the bytes. Does it still need
wrap? Why not?