Skip to main content
Be Bitwise
RustWhat Your Rust Code Actually Does

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

rust
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,
}
}
asm
describe:
; edi = discriminant (0, 1, 2, or 3)
mov eax, edi ; Return the discriminant directly!
ret

A 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:

asm
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
ret

A chain of comparisons. Same shape a C switch would lower to.

Enums with Data (Tagged Unions)

rust
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.

rust
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()
}
}
}
asm
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 ...
ret

The 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:

rust
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:

rust
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.

asm
; 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 reference

Functionally 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:

rust
// All of these are the same size as their inner type:
size_of::<Option<&T>>() == size_of::<&T>() // 8 bytes
size_of::<Option<Box<T>>>() == size_of::<Box<T>>() // 8 bytes
size_of::<Option<NonZeroU32>>() == size_of::<NonZeroU32>() // 4 bytes
// Nesting runs out of niches:
size_of::<Option<Option<&T>>>() // 16 bytes

Nesting 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.

Try itGuess every size first, then run it and account for each one you got wrong.
Rust (1.40.0)

Match Compilation Strategies

When an enum has many variants, the compiler picks its weapon:

Dense variants (0, 1, 2, ...): jump table

rust
enum Color { Red, Orange, Yellow, Green, Blue, Indigo, Violet }
fn to_hex(c: Color) -> u32 {
match c {
Color::Red => 0xFF0000,
Color::Orange => 0xFF8000,
// ... etc
}
}
asm
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

asm
cmp edi, 0
je .red
cmp edi, 1
je .orange
; ...

Boolean-like patterns: conditional moves

rust
fn is_some(opt: Option<i32>) -> bool {
opt.is_some()
}
asm
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
ret

Result<T, E> Layout

Result<T, E> has the same structure as any data-carrying enum:

rust
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:

rust
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:

asm
; 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

  1. Enum discriminants are integers. A bare enum is identical to a C enum once the assembler is done with it.

  2. 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 union and a tag field.

  3. Niche optimisation eliminates the tag. For Option<&T>, Option<Box<T>>, and friends, the compiler reuses an illegal bit pattern as the tag, so the Option shrinks to the size of the inner type.

  4. Match compiles to jumps. Jump tables for dense variants, chained cmp/je for sparse ones, conditional moves for boolean-shaped cases.

  5. The ? operator is a conditional branch. No exceptions, no unwinding — the same handful of instructions you'd write yourself in C.