10 Aggregates — struct and enum

10.1 struct — a collection of named fields#

A struct is a collection of named fields, each with its own type. The declaration’s body is do … end, and each field is closed with a full stop.

module points .
rem run: demo_dist 3 4
rem run: demo_move 5

struct point do
  x i64 .
  y i64 .
end

struct segment do
  start point .
  stop point .
end

fn manhattan input s segment . output i64 .
do
  let dx i64 be sub (field s stop x) (field s start x) .
  let dy i64 be sub (field s stop y) (field s start y) .
  return add (abs dx) (abs dy) .
end

fn demo_dist input dx i64 . input dy i64 . output i64 .
do
  let a point be make point do x 1 . y 1 . end .
  let b point be make point do x (add 1 dx) . y (add 1 dy) . end .
  return manhattan (make segment do start a . stop b . end) .
end

fn moved input p point . input k i64 . output point .
do
  return make point do x (add (field p x) k) . y (field p y) . end .
end

fn demo_move input k i64 . output i64 .
do
  let p point be make point do x 10 . y 0 . end .
  let q point be moved p k .
  return field q x .
end

$ lowentc --run demo_dist points.low 3 4
demo_dist(3, 4) = 7
$ lowentc --run demo_move points.low 5
demo_move(5) = 15

• make point do x 1 . y 1 . end makes a value. Every field must be filled when making it. No unfilled field quietly becomes 0.
• field s stop x reads the stop field of s and the x field inside it. With several steps, it goes down one field at a time from the left.
• A field’s type may be another struct. segment holds two points.
• moved builds and returns a new value with one field changed. The original stays as it was.

There is no glued dot like p.x. Dots are already used for module names (allocs.byte_allocator) and variant names (shape.dot). If looking inside a value were written with a dot too, what a.b means would only be settled after looking up whether a is a value or a module. The field form settles it the moment you read it.

field is both a place to read and a place to write. A field of a value received as mut is changed with set (field p x) 3 . — reading and writing use the same spelling. The rules for borrowing a value to change it are in chapter 12.

10.2 enum — one of several#

An enum is one of several variants. A variant can carry values, written as <field name> <type> pairs.

module shapes .
rem run: demo_area 0
rem run: demo_area 1
rem run: demo_area 2

enum shape do
  circle r u32 .
  rect w u32 h u32 .
  dot .
end

fn area input s shape . output u32 .
do
  match s do
    case circle r . do return mul 3 (mul r r) . end
    case rect w h . do return mul w h . end
    case dot . do return 0 . end
  end
end

fn demo_area input k u8 . output u32 .
do
  if eq k 0 . do return area (shape.circle 2) . end
  if eq k 1 . do return area (shape.rect 3 5) . end
  return area shape.dot .
end

$ lowentc --run demo_area shapes.low 0
demo_area(0) = 12
$ lowentc --run demo_area shapes.low 1
demo_area(1) = 15
$ lowentc --run demo_area shapes.low 2
demo_area(2) = 0

• circle r u32 . carries one value named r, and rect w u32 h u32 . carries two. dot . carries nothing.
• A value is made with the variant name, as in shape.circle 2.
• case rect w h . in a match binds the two carried values to w and h when the variant is rect.

However many variants there are, the match must cover them all. Leaving out dot is rejected.

module missing_case .
rem expect: E-MATCH-INEXHAUSTIVE

enum shape do
  circle r u32 .
  rect w u32 h u32 .
  dot .
end

fn corners input s shape . output u32 .
do
  match s do
    case circle r . do return 0 . end
    case rect w h . do return 4 . end
  end
end

$ lowentc --check missing_case.low
missing_case.low:12:0 E-MATCH-INEXHAUSTIVE: this `match` does not handle every variant of the enum — add the missing `case` (that exhaustiveness is what a `match` buys you over an if-chain: add a variant later and the compiler finds every place that must change), or add a `case _ .` wildcard to cover the rest

This check is the greatest value of an enum. When a triangle variant is added later, every match over shape, area and corners included, stops at translation. Nobody has to remember the places to fix.

To ask only which variant without a match, isa n lit gives a bool.

10.3 Variants are closed with full stops#

A newline is not a closer (chapter 3). So writing variants one per line without full stops runs several variants together into one.

module enum_dot .
rem expect: E-ENUM-DOT

enum color do
  red
  green
  blue .
end

$ lowentc --check enum_dot.low
enum_dot.low:6:0 E-ENUM-DOT: this enum variant is not closed with `.`, so the NEXT line was read as part of it — a newline does not close a form (RFC-0103). Close every variant: `red .` · `green .`. Without the dot `red green blue` is ONE variant `red` whose payload field `green` has a type `blue`

red green blue nearly became one variant’s name plus field pairs. The compiler rejects it and tells you to close each variant, as in red ..

10.4 Nothing may contain itself#

A variant that holds its own type by value would have infinite size.

module infinite .
rem expect: E-ENUM-INFINITE

enum expr_tree do
  lit v u32 .
  add l expr_tree r expr_tree .
end

$ lowentc --check infinite.low
6:0 E-ENUM-INFINITE: an enum variant cannot embed its OWN type BY VALUE — the size would be infinite. Recursion must go through indirection: an index into a node arena (e.g. `u32`) or an `owned` box (RFC-0080 §4.2)
6:0 E-ENUM-INFINITE: an enum variant cannot embed its OWN type BY VALUE — the size would be infinite. Recursion must go through indirection: an index into a node arena (e.g. `u32`) or an `owned` box (RFC-0080 §4.2)

The same goes for struct. Holding itself as a field, directly or through other types, is rejected with E-STRUCT-CYCLE. When you need a tree-like structure, link it by number as the diagnostic suggests. Put the nodes in a slice and point at children by their position in that slice.

module tree .

enum node do
  lit v u32 .
  add l u32 r u32 .
  mul l u32 r u32 .
end

fn eval input nodes slice node . input i u32 . output u32 .
do
  let n node be index nodes i .
  match n do
    case lit v . do return v . end
    case add l r . do return add (eval nodes l) (eval nodes r) . end
    case mul l r . do return mul (eval nodes l) (eval nodes r) . end
  end
end

fn is_leaf input n node . output bool .
do
  return isa n lit .
end

$ lowentc --check tree.low
== check: ok ==

The l and r of add l u32 r u32 . are not nodes but positions in nodes. eval finds children by position and recurses. The size is fixed, and the index that follows a position still gets its bounds check. The storage for such node slices — regions — is covered in chapter 18.

10.5 Common mistakes#

module mistake_missfield .
rem expect: E-TYPE-FIELD

struct point do
  x u64 .
  y u64 .
end

fn origin_x output u64 .
do
  rem ✘ `y` is not filled in --- `make` must fill every field
  let p point be make point do x 1 . end .
  return field p x .
end

$ lowentc --check mistake_missfield.low
mistake_missfield.low:12:0 E-TYPE-FIELD: a declared field is missing from this `make` (every field must be given)

module mistake_unitvariant .
rem run: pick_bare
rem run: pick_qualified

enum light do
  red .
  green .
end

fn code input c light . output u64 .
do
  match c do
    case red . return 1 .
    case green . return 2 .
  end
end

fn pick_bare output u64 .
do
  rem a variant that carries no value is written by its bare name
  return code green .
end

fn pick_qualified output u64 .
do
  rem ✘ in this edition, passing `light.green` stops while running
  return code light.green .
end

$ lowentc --run pick_bare mistake_unitvariant.low
pick_bare() = 2
$ lowentc --run pick_qualified mistake_unitvariant.low
pick_qualified() = 2

module mistake_eqstruct .
rem expect: E-TYPE-KIND

struct point do
  x u64 .
  y u64 .
end

fn same output bool .
do
  let p point be make point do x 1 . y 2 . end .
  let q point be make point do x 1 . y 2 . end .
  rem ✘ compares two structs with `eq` --- `eq` compares numbers and booleans
  return eq p q .
end

$ lowentc --check mistake_eqstruct.low
mistake_eqstruct.low:14:0 E-TYPE-KIND: `eq` / `ne` compare numbers and booleans, not STRUCTS. What "equal" means for a struct differs by type — every field, or only the identifying one? — so the language does not guess: write an op that says it (field by field). This used to pass `--check` and stop at run time with `E-VM-TYPE`

module eqstruct_fixed .
rem run: same

struct point do
  x u64 .
  y u64 .
end

rem spell out field by field what "equal" means --- it differs from type to type
fn point_eq input a point . input b point . output bool .
do
  return expr ((field a x) eq (field b x)) and ((field a y) eq (field b y)) .
end

fn same output bool .
do
  let p point be make point do x 1 . y 2 . end .
  let q point be make point do x 1 . y 2 . end .
  return point_eq p q .
end

$ lowentc --run same eqstruct_fixed.low
same() = 1

module mistake_alias .
rem run: copy_then_change

struct point do
  x u64 .
  y u64 .
end

fn copy_then_change output u64 .
do
  let p point be make point do x 1 . y 2 . end .
  rem ✘ meant to make a copy --- in this edition q refers to the same place as p
  var q point be p .
  set (field q x) 99 .
  rem p is a let, and yet this gives 99
  return field p x .
end

$ lowentc --run copy_then_change mistake_alias.low
copy_then_change() = 1

module alias_fixed .
rem run: copy_then_change

struct point do
  x u64 .
  y u64 .
end

fn copy_then_change output u64 .
do
  let p point be make point do x 1 . y 2 . end .
  rem when you need a new value, build it with make --- copy the fields one by one
  var q point be make point do x (field p x) . y (field p y) . end .
  set (field q x) 99 .
  return field p x .
end

$ lowentc --run copy_then_change alias_fixed.low
copy_then_change() = 1

10.6 This chapter’s syntax at a glance#