# Records, enums and match

> C-layout records, copying and modes, enums stored as u32, unchecked conversion, and match with exhaustiveness.

## Records

`rec Name { type field; ... }` declares a type. The layout is the C layout: fields in declaration order, each at the next multiple of its own alignment, the size of the record rounded up to the largest alignment of any field. Sizes and alignments are 1 for `bool` and the 8-bit types, 2 for the 16-bit types, 4 for the 32-bit types and enums, 8 for the 64-bit types, `isz`, `usz`, pointers and slices (a slice is 16 bytes: pointer, then length). An array has the alignment of its element. A record has at least one field and at most 1 GiB. Padding bytes are zero in a variable that was declared without a value.

`size_of(T)` and `align_of(T)` give the layout as untyped constants. For `rec A { u8 a; u32 b; u8 c; }` the size is 12 and the alignment is 4:

```lane
hex(size_of(A));
hex(align_of(A));
```

Verified: part of a program that builds and runs. For the whole program, exit code 0. Stdout: Lines 1 to 2 of 8.

```text
000000000000000c
0000000000000004
```

`r.f` is the field `f` of the record `r`. It is a place: it can be read, assigned, assigned with an operator, and have its address taken. Fields chain with elements (`xs[i].f`, `r.arr[i]`). On a pointer to a record `p.f` reads the pointer once and takes the field of what it points at.

```lane
rec Instr { Op op; i32 arg; }
rec Vm { [STACK]i32 stack; [MEM]i32 mem; usz sp; usz pc; u64 steps; }
```

```lane
[16]Instr code;
code[0].op = .push; code[0].arg = 100;
```

Rules to know:

- A record variable without an initial value is zero. `a = b;`, `Rec a = b;` and `a := b;` copy all the bytes of `b`, arrays inside it included. Records are not compared: compare their fields.
- A record contains itself only through a pointer or a slice.
- A record is passed by its address in every mode and is read-only without a mode: no field or element reached through it can be assigned or have its address taken (this does not extend through a pointer field).
- A function cannot return a record yet; use an `out` parameter. A record cannot cross the C ABI; pass a pointer. There is no record literal.

```lane
rec A { A a; } 
nul main() { }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:11: error: record `A` contains itself; a field of its own type must be a pointer or a slice
```

```lane
rec A { u8 a; } 
rec B { u8 a; } 
nul g(A a, wr u8 v) { } 
nul main() { A r; g(r, wr r.a); }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:4:28: error: `r` is named by two arguments of one call, and one of them is passed as `wr`
```

```lane
rec A { u32 x; [2]u32 arr; } 
nul f(A r) { r.x = 1; } 
nul main() { }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:2:15: error: parameter `r` is read-only; its fields cannot be assigned
```

```lane
rec A { u32 x; } 
pub A f() { } 
nul main() { }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:2:5: error: not supported by the stage-0 backend yet: returning a record; use an `out` parameter instead
```

```lane
nul main() { u32 a = 1; u32 b = a.x; }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:34: error: `u32` has no field `x`
```

`union Name { type field; ... }` declares a type whose fields share one address.

## Enums

`enum Name { a, b, c }` declares a type whose values are 0, 1, 2 and so on, in the order written. An enum is stored as a `u32`. The zero value, which a variable without an initial value has, is the first variant. `Name.a` is a value wherever a value is expected, and `.a` wherever the context gives the enum: a declared type, an assignment, an argument, a `ret`, the other side of `==` or `!=`, a pattern.

`==` and `!=` compare two values of the same enum. Nothing else is defined on enums: not `<`, not `+`. `u32(e)` gives the number of the variant. `Name(n)` makes an enum from an integer, and it is unchecked: a value that names no variant is possible, and this is the only way to get one.

```lane
        enum Dir { north, east, south, west }
        rec Ship { u8 tag; Dir facing; }
        Dir next(Dir d) { if d == .west { ret .north; } ret Dir(u32(d) + 1); }
        nul set(out Dir d, u32 n) { d = Dir(n); }
        nul main() {
            Dir d;
            hex(u64(u32(d)));
            d = .south;
            hex(u64(u32(d)));
            hex(u64(u32(Dir.west)));
            hex(u64(u32(Dir.north)));
```

Verified: part of a program that builds and runs. For the whole program, exit code 0. Stdout: Lines 1 to 4 of 29.

```text
0000000000000000
0000000000000002
0000000000000003
0000000000000000
```

The four lines of output are the four `hex` calls: the zero value (0), `.south` (2), `Dir.west` (3), `Dir.north` (0).

```lane
enum E { a } 
nul main() { E e = .b; }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:2:20: error: `E` has no variant `b`
```

```lane
enum E { a } 
nul main() { u32 x = .a; }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:2:22: error: expected `u32`, found an enum value
```

## match

`match subject { pattern, pattern { ... } ... else { ... } }` takes an integer or an enum. The subject is computed once. The arms are tested in the order written and the first that matches runs; there is no fall-through, and each arm is its own scope. A pattern is a constant expression of the subject's type. For an integer subject a pattern may also be a range, `a..b` (up to but not including `b`) or `a..=b`. For an enum the patterns are variants.

```lane
        enum Class { digit, lower, upper, space, punct, other }
        Class classify(u8 b) {
            match b {
                '0'..='9' { ret .digit; }
                'a'..='z' { ret .lower; }
                'A'..='Z' { ret .upper; }
                ' ', '\t', '\n', '\r' { ret .space; }
                '!'..='/', ':'..='@', '['..='`', '{'..='~' { ret .punct; }
                else { ret .other; }
            }
        }
        nul main() {
            [6]u32 counts;
            u64 h = 0;
            for b in u32(0)..256 {
                Class c = classify(u8(b));
                counts[usz(u32(c))] += 1;
                h = h * 7 + u64(u32(c)) + 1;
            }
            for i in usz(0)..6 { hex(u64(counts[i])); }
            hex(h);
            hex(u64(u32(classify('a')))); hex(u64(u32(classify('`')))); hex(u64(u32(classify(127))));
        }
```

Verified: part of a program that builds and runs. For the whole program, exit code 0. Stdout:

```text
000000000000000a
000000000000001a
000000000000001a
0000000000000004
0000000000000020
000000000000009e
9509af2cfa3c7520
0000000000000001
0000000000000004
0000000000000005
```

Exhaustiveness: an integer `match` needs an `else`; an enum `match` without `else` must name every variant, and the error lists the ones that are missing.

```lane
enum C { red, green, blue } 
nul main() { C c; match c { .red { } } }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:2:19: error: this `match` does not cover the variants `green`, `blue` of `C`; name them or add an `else` arm
```

```lane
nul main() { u8 x = 1; match x { } }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:24: error: a `match` on an integer needs an `else` arm
```

A value matched by two patterns, or by a range and another pattern, is an error, reported at the later pattern:

```lane
nul main() { u8 x = 1; match x { 5 { } 1..10 { } else { } } }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:40: error: the range 1..10 overlaps an earlier pattern at 5
```

An enum `match` without `else` that is reached by a value naming no variant (made with `Name(n)`) stops the program with an illegal-instruction fault. A `match` takes part in the analyses of returns and `out` parameters as if it were an `if` and `elif` chain: a function whose every path ends in an arm that returns needs no `ret` after it.

A `match` is a chain of comparisons, where a range is one subtraction and one unsigned comparison; jump tables are a later optimization.
