12. Enums, variants and match
In this chapter you will learn:
- how to use an
enumfor values that can only be one of a fixed set of names, such as a direction or a season; - how to use a
variantwhen each case carries data, such as "a circle has a radius"; - how to handle every case at once with
match; miss one and the compiler stops you; - how the expression form and the statement form of
matchdiffer; - a trap beginners hit:
var v = Shape.Dothas typeShape.Dot, notShape; - recursive variants: a variant whose fields are the variant itself, which is how you build a tree.
12.1 enum: a fixed set of names
A value that can only be one of a few things is everywhere in programs: a direction, a weekday, a state, a kind of command. Strings would allow typos, inconsistent capitalization, and nobody can list the possible values. An enum lists them:
enum Direction:
North
East
South
West
func turn_right(d: Direction) -> Direction:
return match d:
case Direction.North:
Direction.East
case Direction.East:
Direction.South
case Direction.South:
Direction.West
case Direction.West:
Direction.North
print(turn_right(Direction.North))
print(turn_right(Direction.West))East
Northenum Direction:declares an enumeration type; the indented names below it are its members:North,East,South,West. You use them asDirection.North, and you never worry about typos — a misspelled name isSPR-NAME-UNRESOLVED.turn_right(d: Direction)takes a direction and returns the direction after a right turn.return match d:is a match expression:matchsits where a value is needed (afterreturn), eachcaseholds a single expression, and the wholematchevaluates to that branch's value.- The four
case Direction.North:branches cover every possibility. There is noelseand no default branch. - The first line,
East, isDirection.Northafter a right turn. The second,North, isDirection.Westturned right, back to north.
A case can also hold several statements; then the match is a statement, and each branch has to return its own value. The area function in 12.2 is written that way.
12.2 variant: cases that carry data
Sometimes each case also carries data: a shape is either a circle (with a radius), a rectangle (with a width and height), or a dot. A variant's cases can declare fields:
variant Shape:
Circle(radius: Float)
Rect(width: Float, height: Float)
Dot
func area(shape: Shape) -> Float:
match shape:
case Shape.Circle as c:
return 3.14159 * c.radius * c.radius
case Shape.Rect as r:
return r.width * r.height
case Shape.Dot:
return 0.0
let shapes: List[Shape] = [Shape.Circle(radius=1.0), Shape.Rect(width=2.0, height=3.0), Shape.Dot]
for shape in shapes:
print(area(shape))
print(Shape.Rect(width=2.0, height=3.0) == Shape.Rect(width=2.0, height=3.0))3.14159
6.0
0.0
truevariant Shape:declares the typeShapewith three cases:Circle(radius: Float),Rect(width: Float, height: Float)andDot. A case without fields (Dot) is written like an enum member.- Constructing a case with fields writes the field names:
Shape.Circle(radius=1.0), just like creating a class object. case Shape.Circle as c:binds the matchedShapevalue toc, so the branch can usec.radius. When you do not need the fields, leave outas, as incase Shape.Dot:.- The name bound by
asis read-only: writingc = ...inside givesSPR-NAME-LET-ASSIGN, whose message says to declare it withvar(you rarely need to; the binding only names the value). match shape:at the top of a function is the statement form; each branch usesreturn. The three branches compute3.14159,6.0and0.0.- The last line,
true: a variant compares by content.Shape.Rect(width=2.0, height=3.0)equals anotherRectwith the same fields. That is the opposite of the classes in the previous chapter, which compare by identity. - Because all cases share the type
Shape, they fit in oneList[Shape]and can be passed as arguments.
Coming from another language?
enumis like an enum elsewhere;variantis Rust's enum, Swift's enum with associated values, Kotlin's sealed class, or a TypeScript discriminated union.- Construction writes field names, as with classes; Python dataclasses and Java records express part of this, but their type is not "one of a fixed set".
- There is no fall-through as in
switch, and nodefault; the next section shows what happens when a case is missing.
12.3 match must be exhaustive
match has no default, no else and no _ fallback: every case is written out. Miss one and the compiler names it:
variant Shape:
Circle(radius: Float)
Rect(width: Float, height: Float)
Dot
func name(shape: Shape) -> String:
match shape:
case Shape.Circle:
return "circle"
case Shape.Rect:
return "rect"SPR-MATCH-NONEXHAUSTIVE [FLOW] main.spr:7:5: Missing case: Shape.Dot
hint: Add 'case Shape.Dot:' (there is no default case)- the code is
SPR-MATCH-NONEXHAUSTIVE, at the line of thematchstatement; - the message names the missing
Shape.Dot; - the hint is the fix: add
case Shape.Dot:.
The rule pays off as the program grows: imagine adding a Triangle to Shape a month from now. Every match that forgot it is pointed out at compile time, one by one, instead of failing at run time.
For the same reason, match is only for enums and variants — types whose cases you can list. It cannot test whether an object is some class: Sprig has no type tests.
12.4 Deliberate mistake: the singleton case type
An easy trap: the value Shape.Dot has the type Shape.Dot (that one case), not the whole Shape. The compiler infers a narrower type than you expected.
variant Shape:
Circle(radius: Float)
Dot
var v = Shape.Dot
v = Shape.Circle(radius=1.0)
let s = Shape.Circle(radius=1.0)
match s:
case Shape.Circle as c:
print(c.radius)
case Shape.Dot:
print("dot")SPR-TYPE-ASSIGN [TYPE] main.spr:6:5: Type mismatch in assignment (expected Shape.Dot, actual Shape.Circle)
SPR-FLOW-UNREACHABLE [FLOW] main.spr:12:10: Case 'Shape.Dot' is impossible for statically known Shape.CircleRead both errors together:
- Line 6:
var v = Shape.Dotmakesvof typeShape.Dot, so the next line assigningShape.Circle(...)reports a type mismatch:expected Shape.Dot, actual Shape.Circle. - Line 12:
let s = Shape.Circle(radius=1.0)makessof typeShape.Circle. The compiler knowsscan only be a circle, socase Shape.Dot:can never be reached:SPR-FLOW-UNREACHABLE.
The fix is simple: when a variable may later hold another case, write the type as Shape. The annotation tells the compiler "I want the whole variant, not this one case":
variant Shape:
Circle(radius: Float)
Dot
var v: Shape = Shape.Dot
v = Shape.Circle(radius=1.0)
print(v)
let s: Shape = Shape.Circle(radius=2.0)
match s:
case Shape.Circle as c:
print(c.radius)
case Shape.Dot:
print("dot")Circle(radius=1.0)
2.0After var v: Shape = Shape.Dot, v can take Shape.Circle(...) too; after let s: Shape = Shape.Circle(radius=2.0), a match with both cases is fine and nothing is unreachable.
Inference itself is not wrong — when a value really is always that one case, the precise type is better. Just remember: a variable you construct once and later reassign to another case needs : Shape.
12.5 Recursive variants: a variant containing itself
A variant's field can have the variant's own type. That is how you build trees, expressions and nested structures. Here is an expression tree with integers, addition and negation:
variant Expr:
Num(value: Int)
Add(left: Expr, right: Expr)
Neg(value: Expr)
func eval(expr: Expr) -> Int:
match expr:
case Expr.Num as n:
return n.value
case Expr.Add as a:
return eval(a.left) + eval(a.right)
case Expr.Neg as n:
return -eval(n.value)
let tree: Expr = Expr.Add(left=Expr.Num(value=2), right=Expr.Neg(value=Expr.Num(value=3)))
print(eval(tree))
print(eval(Expr.Num(value=7)))-1
7Num(value: Int)is a leaf; the fields ofAdd(left: Expr, right: Expr)andNeg(value: Expr)areExpragain, so the tree can be as deep as you like.eval(expr: Expr) -> Intturns the tree into an integer.case Expr.Add as a: return eval(a.left) + eval(a.right)recurses into both subtrees — the recursion from chapter 7 again.let tree: Expr = ...builds a tree by hand: 2 + (-3).- The first
printis-1; the second is7.
Follow eval(tree) through its two levels of recursion:
| step | evaluation | result |
|---|---|---|
| 1 | eval(Add(Num 2, Neg(Num 3))) | eval(Num 2) + eval(Neg(Num 3)) |
| 2 | eval(Num 2) | 2 |
| 3 | eval(Neg(Num 3)) | -eval(Num 3) = -3 |
| 4 | 2 + (-3) | -1 |
12.6 No fallback, no guards
Two things you may expect but that Sprig deliberately leaves out:
No case _:. A wildcard would make "missed a case" possible again:
enum Direction:
North
South
func name(d: Direction) -> String:
match d:
case _:
return "somewhere"SPR-MATCH-UNKNOWN-CASE [TYPE] main.spr:7:14: Match case must be written as Type.Case
hint: match is for enums and variants; there are no type tests on class or contract values. A closed set of types is a variant (declare one with a case per type and match on it); an open set is a contract (call its methods instead of testing the type).The hint mentions contract classes, which are chapter 16's topic; for now keep the first half: a case must be written Type.Case.
No if guards. Some languages allow case Shape.Circle if c.radius > 1.0:. Sprig does not; the condition is a plain if inside the branch body:
enum Direction:
North
South
func name(d: Direction) -> String:
match d:
case Direction.North if true:
return "north"
case Direction.South:
return "south"SPR-SYNTAX-ERROR [SYNTAX] main.spr:7:30: A match case has no 'if' guard
hint: Match the case, then put 'if condition:' inside the case's body.There is also no multi-case branch: case Shape.Circle, Shape.Dot: is not allowed; each case gets its own line.
Summary
- An
enumlists names; avariantlists cases with fields. Construction writes field names, and theasbinding is read-only. matchhandles every case, must be exhaustive, and has no fallback, no guards and no type tests.- Used where a value is needed,
matchis an expression (one expression per branch); as a statement, branches can hold several lines andreturnthemselves. - Variants compare by content and can be recursive: a field may have the variant's own type.
- The trap: a single case's value has the singleton case type; annotate with
: Shapewhen the variable must hold several cases.
Exercises
Exercise 1 (enum and match expression). Define enum Season: Spring, Summer, Autumn, Winter and write is_warm(s: Season) -> Bool returning true for spring and summer and false for autumn and winter, using a match expression.
Answer
enum Season:
Spring
Summer
Autumn
Winter
func is_warm(s: Season) -> Bool:
return match s:
case Season.Summer:
true
case Season.Spring:
true
case Season.Autumn:
false
case Season.Winter:
false
print(is_warm(Season.Summer))
print(is_warm(Season.Winter))true
falseExercise 2 (a variant with data). Define a Temperature with cases Celsius(degrees: Float) and Fahrenheit(degrees: Float), and write to_celsius to convert both. Check that 20°C stays 20.0 and 212°F becomes 100.0.
Answer
variant Temperature:
Celsius(degrees: Float)
Fahrenheit(degrees: Float)
func to_celsius(t: Temperature) -> Float:
match t:
case Temperature.Celsius as c:
return c.degrees
case Temperature.Fahrenheit as f:
return (f.degrees - 32.0) * 5.0 / 9.0
print(to_celsius(Temperature.Celsius(degrees=20.0)))
print(to_celsius(Temperature.Fahrenheit(degrees=212.0)))20.0
100.0Exercise 3 (complete the match). The describe below misses one case. Run the compiler to see what it says, then add the case so the program prints dot: variant Shape has Circle(radius: Float), Rect(width: Float, height: Float) and Dot, and describe handles only the first two.
Answer
variant Shape:
Circle(radius: Float)
Rect(width: Float, height: Float)
Dot
func describe(shape: Shape) -> String:
match shape:
case Shape.Circle:
return "circle"
case Shape.Rect:
return "rect"
case Shape.Dot:
return "dot"
print(describe(Shape.Dot))dotExercise 4 (recursive variant). Define variant Tree: Leaf(value: Int), Node(left: Tree, right: Tree) and write total(tree: Tree) -> Int summing all leaves. Build a tree with three leaves; the total is 6.
Answer
variant Tree:
Leaf(value: Int)
Node(left: Tree, right: Tree)
func total(tree: Tree) -> Int:
match tree:
case Tree.Leaf as leaf:
return leaf.value
case Tree.Node as node:
return total(node.left) + total(node.right)
let tree: Tree = Tree.Node(left=Tree.Leaf(value=1), right=Tree.Node(left=Tree.Leaf(value=2), right=Tree.Leaf(value=3)))
print(total(tree))6total recurses into both subtrees for a Node and returns value for a Leaf; the three leaves are 1 + 2 + 3.
Next chapter: Values that may be missing.
