Enums & Pattern Matching in Machine Code
Rust enums leave their C cousins in the dust. They carry data (tagged unions), and match is exhaustive — miss a variant and the compiler shouts at you. In this lesson we'll dig into how enums are laid out in memory, how match compiles down to jumps, and meet one of Rust's slyest tricks: niche filling.
Basic Enum Layout
enum Direction { North, South, East, West,}
fn describe(d: Direction) -> i32 { match d { Direction::North => 0, Direction::South => 1, Direction::East => 2, Direction::West => 3, }}describe: ; edi = discriminant (0, 1, 2, or 3) mov eax, edi ; Return the discriminant directly! retA data-less enum is just an integer discriminant — same as C. Direction::North is 0, South is 1, and so on. Here the compiler noticed the match returns exactly the discriminant and dissolved the whole thing into a single mov.
For a more complex match:
describe_complex: cmp edi, 1 je .south cmp edi, 2 je .east cmp edi, 3 je .west ; Fall through to North (0) mov eax, 100 ret.south: mov eax, 200 ret.east: mov eax, 300 ret.west: mov eax, 400 retA chain of comparisons. Same shape a C switch would lower to.
Enums with Data (Tagged Unions)
enum Shape { Circle(f64), // radius Rectangle(f64, f64), // width, height Triangle(f64, f64, f64), // three sides}Memory layout:
Every variant takes the same total space — large enough to fit the biggest one, plus the tag. The tag (discriminant) is the cheat sheet: read it to know which variant is live.
fn area(s: &Shape) -> f64 { match s { Shape::Circle(r) => std::f64::consts::PI * r * r, Shape::Rectangle(w, h) => w * h, Shape::Triangle(a, b, c) => { let s = (a + b + c) / 2.0; (s * (s - a) * (s - b) * (s - c)).sqrt() } }}area: ; rdi = pointer to Shape mov rax, QWORD PTR [rdi] ; Load tag cmp rax, 1 je .rectangle cmp rax, 2 je .triangle
; Circle: PI * r * r movsd xmm0, QWORD PTR [rdi+8] ; Load radius mulsd xmm0, xmm0 ; r * r mulsd xmm0, QWORD PTR [rip+.LC_PI] ; * PI ret
.rectangle: movsd xmm0, QWORD PTR [rdi+8] ; Load width mulsd xmm0, QWORD PTR [rdi+16] ; * height ret
.triangle: ; Heron's formula movsd xmm0, QWORD PTR [rdi+8] ; a movsd xmm1, QWORD PTR [rdi+16] ; b movsd xmm2, QWORD PTR [rdi+24] ; c ; ... compute semi-perimeter and area ... retThe tag check is a cmp plus a je, and each branch reads the variant's payload at a fixed offset. The exact recipe a C programmer would reach for: tagged union in a struct, dispatch on the tag, hope nobody touched the wrong field.
Option<T> and Niche Optimisation
Now the cleverness kicks in. Option<T> is just an enum:
enum Option<T> { None, Some(T),}For Option<i32>, the naive layout would be:
And that's exactly what you get. size_of::<Option<i32>>() is 8 bytes.
But for Option<&T> (option of a reference), something remarkable happens:
fn example() { let x: Option<&i32> = None; let y: Option<&i32> = Some(&42); println!("{}", std::mem::size_of::<Option<&i32>>()); // Prints 8, not 16!}Option<&i32> weighs 8 bytes — the same as a raw pointer. The compiler pulls a stunt called niche optimisation: Rust guarantees a reference is never null, so the bit pattern 0 is otherwise illegal. The compiler steals it to mean None. No discriminant byte required.
; Option<&i32>::None xor eax, eax ; rax = 0 (null pointer = None)
; Option<&i32>::Some(&value) lea rax, [rip+value] ; rax = address of value (non-null = Some)
; Pattern matching: test rax, rax ; Is it null? je .none_branch ; If null, it's None ; Otherwise, rax is the &i32 pointer (Some branch) mov eax, DWORD PTR [rax] ; Dereference the referenceFunctionally identical to the NULL-pointer dance C has played for fifty years — except the type checker forces you to handle the null case before you can dereference. Same machine code, free safety.
Niche Optimisation for Other Types
Niche optimisation kicks in for any type that has illegal bit patterns lying around:
// All of these are the same size as their inner type:size_of::<Option<&T>>() == size_of::<&T>() // 8 bytessize_of::<Option<Box<T>>>() == size_of::<Box<T>>() // 8 bytessize_of::<Option<NonZeroU32>>() == size_of::<NonZeroU32>() // 4 bytes
// Nesting runs out of niches:size_of::<Option<Option<&T>>>() // 16 bytesNesting is where the trick runs dry. The only forbidden value rustc borrows from a reference is null, and the inner Option has already spent it on None. The outer Option needs a second spare pattern, finds none, and falls back to a separate tag, so Option<Option<&T>> is 16 bytes. Types with plenty of unused bit patterns go further: a bool only ever holds 0 or 1, so even Option<Option<bool>> fits in one byte.
Time to test your intuition. Write down a size for every line before you run it, then explain each miss. One catch: the runner uses an older compiler (Rust 1.40), and layouts have improved since. Result<i32, String> prints 32 here, where a current rustc gets it down to 24 by hiding the tag in a niche inside the String.
Match Compilation Strategies
When an enum has many variants, the compiler picks its weapon:
Dense variants (0, 1, 2, ...): jump table
enum Color { Red, Orange, Yellow, Green, Blue, Indigo, Violet }
fn to_hex(c: Color) -> u32 { match c { Color::Red => 0xFF0000, Color::Orange => 0xFF8000, // ... etc }}to_hex: ; Use the discriminant as an index into a lookup table lea rax, [rip+.Ltable] mov eax, DWORD PTR [rax+rdi*4] ret
.Ltable: .long 0xFF0000 ; Red .long 0xFF8000 ; Orange .long 0xFFFF00 ; Yellow ; ...Sparse or complex patterns: chained comparisons
cmp edi, 0 je .red cmp edi, 1 je .orange ; ...Boolean-like patterns: conditional moves
fn is_some(opt: Option<i32>) -> bool { opt.is_some()}is_some: ; The discriminant is 0 for None, 1 for Some cmp edi, 1 ; Or the tag might be tested differently sete al ; al = 1 if Some, 0 if None retResult<T, E> Layout
Result<T, E> has the same structure as any data-carrying enum:
enum Result<T, E> { Ok(T), Err(E),}For Result<i32, String>:
That's the classic layout, and the one older compilers produce. Current rustc does better: it stores the tag in a niche inside the String, so size_of::<Result<i32, String>>() reports 24.
The ? operator on a Result compiles to a simple tag check and conditional branch:
fn parse_and_add(a: &str, b: &str) -> Result<i32, ParseIntError> { let x = a.parse::<i32>()?; // Check tag, branch if Err let y = b.parse::<i32>()?; Ok(x + y)}The listing below is schematic. Result<i32, ParseIntError> is only 8 bytes, so real code gets it back in a register rather than reading it from [rsp], but the check-and-branch shape is the same:
; After calling parse: cmp QWORD PTR [rsp], 0 ; Check tag: 0 = Ok, 1 = Err jne .propagate_error ; If Err, jump to error propagation
; Ok path: extract the value and continue mov eax, DWORD PTR [rsp+8] ; Load the parsed i32
; ...
.propagate_error: ; Copy the error value to the return slot and return ; (The ? operator does this automatically)The ? operator is a conditional branch. No exception tables, no stack unwinding, no runtime cost beyond the cmp and jne. That's the gulf between this and C++ exceptions, and it's why Rust error handling stays predictable when you start measuring it.
Key Takeaways
-
Enum discriminants are integers. A bare enum is identical to a C enum once the assembler is done with it.
-
Data-carrying enums are tagged unions. A tag word, then enough payload for the biggest variant. Exactly what you'd build in C with a
unionand atagfield. -
Niche optimisation eliminates the tag. For
Option<&T>,Option<Box<T>>, and friends, the compiler reuses an illegal bit pattern as the tag, so theOptionshrinks to the size of the inner type. -
Match compiles to jumps. Jump tables for dense variants, chained
cmp/jefor sparse ones, conditional moves for boolean-shaped cases. -
The
?operator is a conditional branch. No exceptions, no unwinding — the same handful of instructions you'd write yourself in C.