A list of a fixed length
A buffer in firmware nearly always has a size that is known when the
program is written: a frame of 8 bytes, a block of 512, a ring of 64.
list[u8, 64] is a list that always has 64 items.
var buffer: list[u8, 64] = [0] * 64
buffer[0] = 0x7E
buffer[63] = 0x7F
print(len(buffer)) # 64
print(buffer[0]) # 126
The reasons for each choice are in chapters 36.3 and 36.4 of
decisions.md.
Filling a list: [0] * 64
* with a list and a number makes a new list with the items so many
times over. It works for every list, not only one of a fixed length:
print([0] * 4) # [0, 0, 0, 0]
print([0x7E, 0] * 2) # [126, 0, 126, 0]
let n = 3
print(["-"] * n) # ["-", "-", "-"]
The list comes first: 3 * [0] is refused, with a message that shows
[0] * 3. A count below zero is a ValueError. A list of lists, dicts
or objects cannot be repeated, because every row would be the same row:
error: `*` would put the same list[int] in the list again and again, and a change to one would be a change to all. Make each one: `[[0] * 4 for i in range(3)]`
Giving one a value
A list of a fixed length gets a list whose length is known before the
program runs: one written out with that many items, [0] * 64, or
another list of the same type and length.
let header: list[u8, 4] = [0x7E, command, 0, 0x7F]
let zeros: list[u8, 512] = [0] * 512
let copy: list[u8, 4] = header
The count is checked then:
error: this list has 2 items, and a list[u8, 8] always has 8
A list whose length is only known when the program runs cannot be one:
error: `frame` should be list[u8, 8], but this is list[u8]. A list[u8, 8] always has 8 items, and how many this one has is only known when the program runs. Write the 8 items, or `[0] * 8`
What it does
Everything a list does that leaves its length as it is: an index,
buffer[i] = v, len, for, in, ==, find, sort, reverse,
slice, map, filter, sum, min, max, printing. + makes a new,
ordinary list.
append, pop, insert and clear would change the length, and are
refused:
error: `append` would change how many items this list has, and a list of a fixed length always has 64. Give an item a new value instead, as in `list[0] = 7`
A position written as a number is checked before the program runs:
error: 64 is outside a list of 64 items, whose positions are 0 to 63
Passing one to a function
A parameter, a field and what a function gives back can each be a list of a fixed length:
class Packet {
kind: u8
data: list[u8, 4]
}
function frame_of(command: u8) -> list[u8, 4] {
return [0x7E, command, 0, 0x7F]
}
let packet = Packet(1, frame_of(9))
And a function that takes an ordinary list[u8] can be given one, as
long as it never changes how many items the list has:
function checksum(data: list[u8]) -> u8 {
var total = 0
for b in data {
total = (total + b) % 256
}
return u8(total)
}
function fill(data: list[u8], value: u8) {
for i in range(len(data)) {
data[i] = value
}
}
fill(buffer, 0xFF)
print(checksum(buffer))
The checker reads the function to know. If something in it could change the length, the message names the line:
error: this list always has 64 items, and `pad` may change how many its `data` has: it calls `data.append` (line 11). A function that only reads a list, or gives its items new values, can be given one of a fixed length
What counts as a change: append, pop, insert and clear, and
anything that keeps the list where it could be changed later: a
variable, another list, a dict, a field, a return, or a function the
checker cannot read, such as one held in a variable. Handing the list
on to another function of the program is fine when that function keeps
the length too.
A list of a fixed length is not kept where an ordinary list is, such as
a let that says list[u8]: whatever held it there could append to
it. Copy the items if a list that can grow is wanted:
let longer: list[u8] = buffer.slice(0)
longer.append(1)
In every build
A list of a fixed length is a list in every engine, every build and all
fifteen target languages. The length is made sure of before the program
runs, so nothing is left to check while it runs. A list[u8, 64] takes
64 bytes in a compiled program, as any list[u8] does (36.2).
In a build with no collector it is a block from the pool, as any list
is, and its type is written owned list[u8, 64] where a list needs an
owner. Keeping its items inside the object or on the stack, with no
block at all, is the next step (36.5).
How it is built
- The parser (
parser.rs) reads a number among the types in[ ]as a length:ast::Type::Length. - The checker (
checker.rs) has the typeTy::Fixed(item, length). Whatever only looks at a value sees it as a list, solen, an index, a loop and the methods that read work as they did. The places that keep a value see the length.src/lengths.rsreads a function's body to say whether it changes the length of a parameter. [0] * 64isops.rsforzeno runand the VM,zeno_list_repeatandzeno_bytes_repeatinruntime.cfor C and LLVM, and themulof each target language's runtime.
How it is tested
cargo test:a_list_is_repeated_with_a_star,a_list_of_a_fixed_length_keeps_its_length(every message) anda_list_of_a_fixed_length_is_the_same_in_every_build.tools/targets.py:tools/targets/edge-repeat.zenoandtools/targets/edge-fixed.zenoin all fifteen languages.
Things to try
- Make a
list[u8, 8]and printlenof it. Try toappendto it, and read the message. - Write
function sum8(data: list[u8]) -> intthat adds the bytes. Give it alist[u8, 8]. Then adddata.append(0)at the end of the function, and read what the checker says now. - Write a ring buffer: a
list[u8, 16], avar head = 0, and a functionput(byte: u8)that writes atheadand moves it on with% 16. Why does a ring buffer never needappend? - Try
let grid = [[0] * 3] * 3. Then write it the way the message says, setgrid[0][0] = 1, and printgrid. - Write a class
Framewith a fielddata: list[u8, 6], and a function that gives back a frame with the CRC-16 of its first four bytes in the last two.
This page is docs/fixed-lists.md in the language repository.