Enums and Data-Carrying Variants

18 min read

Rust enums are the tool you reach for when a value is “one of several shapes.” If you have ever written a TypeScript union type or a discriminated union, you already understand the idea — but Rust’s enums are first-class, exhaustively-checked, and can carry data per variant with zero runtime tagging overhead.

Quick Overview

A Rust enum defines a type that can be exactly one of a fixed set of variants, and each variant can carry its own data. This is Rust’s answer to the TypeScript union type A | B | C, and especially to the discriminated union pattern. The big payoff for a TypeScript/JavaScript developer: the compiler forces you to handle every variant (no forgotten case), and there is no separate kind string to keep in sync by hand — the variant is the tag.

Key takeaway: In TypeScript a discriminated union is a convention you assemble out of object types plus a literal kind field. In Rust an enum is a built-in language construct, so the tag and the payload are one inseparable thing.

TypeScript/JavaScript Example

1
// The classic discriminated union: a `kind` field is the discriminant,
2
// and each member carries its own payload.
3
type WebEvent =
4
  | { kind: "pageLoad" }
5
  | { kind: "pageUnload" }
6
  | { kind: "keyPress"; key: string }
7
  | { kind: "paste"; text: string }
8
  | { kind: "click"; x: number; y: number };
9

10
function describe(event: WebEvent): string {
11
  switch (event.kind) {
12
    case "pageLoad":
13
      return "page loaded";
14
    case "pageUnload":
15
      return "page unloaded";
16
    case "keyPress":
17
      return `pressed '${event.key}'`;
18
    case "paste":
19
      return `pasted "${event.text}"`;
20
    case "click":
21
      return `clicked at (${event.x}, ${event.y})`;
22
    // Forget a case and TypeScript only complains if you opted into
23
    // exhaustiveness (e.g. a `never` default). It is not automatic.
24
  }
25
}
26

27
const event: WebEvent = { kind: "click", x: 20, y: 80 };
28
console.log(describe(event)); // clicked at (20, 80)

Key points:

The union is built by hand: object types glued together with |.
The kind string literal is the discriminant — you invent and maintain it.
Narrowing happens via switch (event.kind); inside each case, TypeScript narrows event to the matching member.
Exhaustiveness is opt-in (you add a never trick). Miss a case and, by default, you just get undefined at runtime.

Rust Equivalent

1
// One language construct. Each variant is a shape; some carry data.
2
#[derive(Debug)]
3
enum WebEvent {
4
    PageLoad,                  // unit-like: no data
5
    PageUnload,                // unit-like: no data
6
    KeyPress(char),            // tuple-like: one positional field
7
    Paste(String),             // tuple-like: one positional field
8
    Click { x: i64, y: i64 },  // struct-like: named fields
9
}
10

11
fn describe(event: &WebEvent) -> String {
12
    match event {
13
        WebEvent::PageLoad => "page loaded".to_string(),
14
        WebEvent::PageUnload => "page unloaded".to_string(),
15
        WebEvent::KeyPress(c) => format!("pressed '{c}'"),
16
        WebEvent::Paste(s) => format!("pasted \"{s}\""),
17
        WebEvent::Click { x, y } => format!("clicked at ({x}, {y})"),
18
    }
19
}
20

21
fn main() {
22
    let event = WebEvent::Click { x: 20, y: 80 };
23
    println!("{}", describe(&event)); // clicked at (20, 80)
24
}

Running it prints:

1
clicked at (20, 80)

Key points:

enum WebEvent { ... } declares the whole closed set of shapes in one place.
Variants come in three flavors: unit-like (PageLoad), tuple-like (KeyPress(char)), and struct-like (Click { x, y }).
The variant name is the discriminant — there is no separate kind string to maintain.
match narrows and destructures in one step, and (as we’ll see) the compiler checks exhaustiveness for free.

Detailed Explanation

The three variant shapes, line by line

1
enum WebEvent {
2
    PageLoad,                  // (1) unit-like variant
3
    KeyPress(char),            // (2) tuple-like variant, one field
4
    Paste(String),             // (3) tuple-like variant, owns a String
5
    Click { x: i64, y: i64 },  // (4) struct-like variant, named fields
6
}

Unit-like variants carry no data. They are the closest thing to a plain TypeScript string-literal member like { kind: "pageLoad" } — except there is no object at all, just a tag.
Tuple-like variants hold positional data, like a tuple struct. KeyPress(char) holds exactly one char.
Paste(String) owns its String. This matters: constructing WebEvent::Paste(s) moves s into the enum (see Section 05 — Ownership).
Struct-like variants hold named fields, mirroring a discriminated-union member with several properties ({ kind: "click"; x; y }).

You can mix all three flavors freely in one enum, which has no clean TypeScript equivalent — there, every union member is an object type.

Constructing a value

1
let a = WebEvent::PageLoad;                       // unit-like
2
let b = WebEvent::KeyPress('x');                  // tuple-like
3
let c = WebEvent::Paste(String::from("hello"));   // tuple-like
4
let d = WebEvent::Click { x: 20, y: 80 };         // struct-like

Every value is namespaced under the enum type: WebEvent::Click, not bare Click. Compare this to TypeScript, where you just write an object literal { kind: "click", x: 20, y: 80 } and rely on structural typing. Rust is nominal: the value’s type is WebEvent, full stop.

Reading the data back: `match`

You cannot read a variant’s payload directly (more on that in Common Pitfalls). You destructure it, almost always with match:

1
match event {
2
    WebEvent::KeyPress(c) => format!("pressed '{c}'"),       // bind the char as `c`
3
    WebEvent::Click { x, y } => format!("at ({x}, {y})"),    // bind both fields
4
    // ...
5
}

This is the same instinct as switch (event.kind) followed by event.key, but fused into one operation: matching the variant and pulling out its fields happen together, and the binding (c, x, y) only exists inside that arm where the type is known. Pattern matching gets its own deep dive in pattern-matching.md.

Memory: a tag plus the largest payload

A TypeScript discriminated-union value is a heap-allocated object with a kind property string plus its other fields. A Rust enum value is laid out inline as a small integer discriminant (the tag) followed by enough space for the largest variant’s payload — no heap allocation, no string tag. The whole WebEvent lives on the stack. This is why Rust enums are cheap enough to use everywhere, including in hot loops.

Note: The compiler is clever about layout. For example Option<&T> (an enum!) needs no extra tag byte at all, because a reference can never be null — None reuses the all-zero bit pattern. This “niche optimization” means many Rust enums are as compact as the raw data they wrap.

`Option` and `Result` are just enums

Two of the most important types in Rust are nothing more than enums defined in the standard library:

1
let found: Option<i32> = Some(7);
2
let missing: Option<i32> = None;
3
println!("{found:?} {missing:?}"); // Some(7) None

Option<T> is enum Option<T> { Some(T), None } and Result<T, E> is enum Result<T, E> { Ok(T), Err(E) }. Everything you learn here applies to them. Option<T> is Rust’s replacement for null/undefined and gets its own page: option-enum.md. Result powers error handling in Section 08.

Key Differences

Concept	TypeScript discriminated union	Rust enum
Definition	Hand-assembled: `A \| B \| C` of object types	One `enum` declaration
Discriminant	A literal field you invent (`kind: "click"`)	The variant name, built into the language
Payload	Each member is an object with properties	Per-variant: unit, tuple, or named fields
Runtime representation	Heap object with a string tag + fields	Inline tag (small int) + largest payload, often stack-allocated
Narrowing	`switch`/`if` on the tag, then read fields	`match` / `if let` destructures variant + fields together
Exhaustiveness	Opt-in (`never` trick); otherwise silent	Mandatory — compiler error if a variant is missed
Adding a variant	Misses are silent until runtime	Compiler points at every `match` you must update
Type identity	Structural (shape-compatible counts)	Nominal (the named type is the type)
Generics	Erased at runtime	Monomorphized (real specialized code)

Exhaustiveness is the headline feature

In TypeScript, adding a new union member compiles fine and your existing switch statements silently fall through. In Rust, adding a variant turns every match that doesn’t handle it into a compile error, with the compiler naming the exact uncovered case. This turns “did I update every place?” from a manual audit into something the type checker guarantees.

Enums can have methods

Like structs, enums can have impl blocks. The matches! macro is handy for a quick boolean check:

1
#[derive(Debug, Clone)]
2
enum JobState {
3
    Queued,
4
    Running { progress: u8 },
5
    Succeeded { output: String },
6
    Failed { code: u32, message: String },
7
}
8

9
impl JobState {
10
    fn is_terminal(&self) -> bool {
11
        matches!(self, JobState::Succeeded { .. } | JobState::Failed { .. })
12
    }
13
}

Methods on enums are covered alongside structs in impl-blocks.md; here we just note that data and behavior live together.

C-like enums with explicit discriminants

When variants carry no data, an enum behaves like a classic C enum, and you can pin each tag to an integer and cast to it:

1
#[derive(Debug, Clone, Copy)]
2
enum HttpStatus {
3
    Ok = 200,
4
    NotFound = 404,
5
    ServerError = 500,
6
}
7

8
fn main() {
9
    let all = [HttpStatus::Ok, HttpStatus::NotFound, HttpStatus::ServerError];
10
    for s in all {
11
        println!("{s:?} = {}", s as i32);
12
    }
13
}

This prints:

1
Ok = 200
2
NotFound = 404
3
ServerError = 500

Note: Casting an enum to an integer with as only works for these data-less, “field-less” enums. Once a variant carries a payload, there is no single integer to cast to. (And as only goes one way — there is no built-in 404 as HttpStatus. Reverse conversion needs a match or the num_enum crate.)

Common Pitfalls

Pitfall 1: Forgetting a variant in `match`

A TypeScript switch will happily skip a missing case. Rust refuses to compile:

1
enum Shape {
2
    Circle(f64),
3
    Rectangle(f64, f64),
4
    Triangle(f64, f64),
5
}
6

7
fn area(s: &Shape) -> f64 {
8
    match s { // does not compile (error[E0004]: non-exhaustive patterns)
9
        Shape::Circle(r) => 3.14159 * r * r,
10
        Shape::Rectangle(w, h) => w * h,
11
        // Triangle is missing!
12
    }
13
}

The real compiler error:

1
error[E0004]: non-exhaustive patterns: `&Shape::Triangle(_, _)` not covered
2
 --> src/main.rs:8:11
3
  |
4
8 |     match s {
5
  |           ^ pattern `&Shape::Triangle(_, _)` not covered
6
  |
7
note: `Shape` defined here
8
 --> src/main.rs:1:6
9
  |
10
1 | enum Shape {
11
  |      ^^^^^
12
...
13
4 |     Triangle(f64, f64),
14
  |     -------- not covered
15
  = note: the matched value is of type `&Shape`
16
help: ensure that all possible cases are being handled by adding a match arm with a
17
      wildcard pattern or an explicit pattern as shown

Fix: add the missing arm. Reach for a catch-all _ => ... only when you genuinely want a default; if you use _ everywhere, you lose the very compiler nudge that makes enums safe when you add variants later.

Pitfall 2: Trying to read a payload like a TypeScript property

In TypeScript, after narrowing you read event.key. In Rust there is no field to read until you destructure — an enum is not a struct:

1
enum Msg {
2
    Text(String),
3
    Quit,
4
}
5

6
fn main() {
7
    let m = Msg::Text(String::from("hi"));
8
    println!("{}", m.0); // does not compile (error[E0609]: no field `0` on type `Msg`)
9
}

The real error:

1
error[E0609]: no field `0` on type `Msg`
2
 --> src/main.rs:8:22
3
  |
4
8 |     println!("{}", m.0);
5
  |                      ^ unknown field

Fix: match or use if let to bind the inner value:

1
if let Msg::Text(s) = &m {
2
    println!("{s}");
3
}

Pitfall 3: Comparing enum values with `==` before deriving `PartialEq`

In JavaScript a === b always works. In Rust, == is the PartialEq trait, and an enum doesn’t get it automatically:

1
enum Direction {
2
    North,
3
    South,
4
}
5

6
fn main() {
7
    let d = Direction::North;
8
    if d == Direction::North { // does not compile (error[E0369])
9
        println!("going north");
10
    }
11
}

The real error (note the actionable hint):

1
error[E0369]: binary operation `==` cannot be applied to type `Direction`
2
 --> src/main.rs:8:10
3
  |
4
8 |     if d == Direction::North {
5
  |        - ^^ ---------------- Direction
6
  |        |
7
  |        Direction
8
  |
9
note: an implementation of `PartialEq` might be missing for `Direction`
10
 --> src/main.rs:1:1
11
  |
12
1 | enum Direction {
13
  | ^^^^^^^^^^^^^^ must implement `PartialEq`
14
help: consider annotating `Direction` with `#[derive(PartialEq)]`

Fix: add #[derive(PartialEq)] (and usually Debug) above the enum. Deriving traits is covered for structs in structs.md and in full in Section 09.

Pitfall 4: Expecting structural typing

Two TypeScript unions with the same members are interchangeable. In Rust two enums with identical-looking variants are different, incompatible types — Rust is nominal. If function f wants a WebEvent, no other enum will do, even one defined with the same variants.

Best Practices

Reach for an enum whenever you’d write a TypeScript union of object types. It is the idiomatic, type-safe way to model “one of N shapes.”
Prefer named fields for variants with 2+ pieces of data. Click { x: i64, y: i64 } documents itself; Click(i64, i64) makes the call site guess which number is which.
Let match enforce exhaustiveness — avoid a blanket _ arm unless a default truly is correct. The exhaustiveness error is a feature, not an obstacle.
Derive the traits you need (#[derive(Debug, Clone, PartialEq)] is a common starting set). Add Copy only for small, data-light enums where copying is trivially cheap.
Put behavior on the enum with impl. A JobState::is_terminal() method keeps the logic next to the data, the way a class method would in TypeScript.
Use if let (or matches!) when you care about exactly one variant; use match when you must handle them all.
Model invalid states out of existence. If a “loading” request has no response and a “loaded” one always does, encode that in the variants so an impossible combination simply cannot be constructed — something a TypeScript object with optional fields can’t guarantee.

Real-World Example

A job/task status is a textbook case for a data-carrying enum: each state carries different information, and several states are terminal. In TypeScript you’d model it as a discriminated union; in Rust the enum carries the right payload per state and a method answers questions about it.

1
#[derive(Debug, Clone)]
2
enum JobState {
3
    Queued,
4
    Running { progress: u8 },
5
    Succeeded { output: String },
6
    Failed { code: u32, message: String },
7
}
8

9
impl JobState {
10
    /// A job is "terminal" once it can no longer change.
11
    fn is_terminal(&self) -> bool {
12
        matches!(self, JobState::Succeeded { .. } | JobState::Failed { .. })
13
    }
14

15
    /// A human-readable one-liner for logs or a UI.
16
    fn summary(&self) -> String {
17
        match self {
18
            JobState::Queued => "waiting to start".to_string(),
19
            JobState::Running { progress } => format!("running ({progress}%)"),
20
            JobState::Succeeded { output } => format!("done: {output}"),
21
            JobState::Failed { code, message } => format!("failed [{code}]: {message}"),
22
        }
23
    }
24
}
25

26
fn main() {
27
    let states = [
28
        JobState::Queued,
29
        JobState::Running { progress: 42 },
30
        JobState::Succeeded { output: "report.pdf".to_string() },
31
        JobState::Failed { code: 503, message: "upstream timeout".to_string() },
32
    ];
33

34
    for s in &states {
35
        println!("{:<28} terminal={}", s.summary(), s.is_terminal());
36
    }
37
}

Output:

1
waiting to start             terminal=false
2
running (42%)                terminal=false
3
done: report.pdf             terminal=true
4
failed [503]: upstream timeout terminal=true

Notice what the type system buys you: a Failed value always has a code and a message, and a Queued value cannot carry a progress number. In the TypeScript equivalent you’d typically end up with optional fields (progress?: number) that are technically present in every member, and nothing stops you from constructing a { kind: "queued", progress: 99 }. The Rust enum makes that nonsensical state unrepresentable.

Exercises

Exercise 1: A `Shape` enum with an `area` method

Difficulty: Beginner

Objective: Practice declaring struct-like variants and matching on them inside a method.

Instructions: Define an enum Shape with three variants — Circle { radius: f64 }, Rectangle { width: f64, height: f64 }, and Triangle { base: f64, height: f64 }. Add an impl Shape with a method area(&self) -> f64. In main, put three shapes in an array and print each one’s area.

Solution

1
#[derive(Debug)]
2
enum Shape {
3
    Circle { radius: f64 },
4
    Rectangle { width: f64, height: f64 },
5
    Triangle { base: f64, height: f64 },
6
}
7

8
impl Shape {
9
    fn area(&self) -> f64 {
10
        match self {
11
            Shape::Circle { radius } => std::f64::consts::PI * radius * radius,
12
            Shape::Rectangle { width, height } => width * height,
13
            Shape::Triangle { base, height } => 0.5 * base * height,
14
        }
15
    }
16
}
17

18
fn main() {
19
    let shapes = [
20
        Shape::Circle { radius: 2.0 },
21
        Shape::Rectangle { width: 3.0, height: 4.0 },
22
        Shape::Triangle { base: 6.0, height: 2.0 },
23
    ];
24
    for s in &shapes {
25
        println!("{:?} -> area {:.2}", s, s.area());
26
    }
27
}

Output:

1
Circle { radius: 2.0 } -> area 12.57
2
Rectangle { width: 3.0, height: 4.0 } -> area 12.00
3
Triangle { base: 6.0, height: 2.0 } -> area 6.00

Exercise 2: A recursive `Json` enum

Difficulty: Intermediate

Objective: Model a value that is “one of several shapes,” including ones that contain more of itself — the way a TypeScript JSONValue union does.

Instructions: Define an enum Json with variants Null, Bool(bool), Number(f64), Str(String), Array(Vec<Json>), and Object(HashMap<String, Json>). Add a method type_name(&self) -> &'static str returning "null", "boolean", etc. In main, build a small object and print the type name of the whole document and of one of its fields.

Tip: Variants like Array and Object hold a Vec/HashMap of Json, which is fine because those collections heap-allocate their contents. (A directly self-containing variant like Node(Json) would need a Box; see the hint in the next exercise.)

Solution

1
use std::collections::HashMap;
2

3
#[derive(Debug)]
4
#[allow(dead_code)] // payloads are intentionally only matched with `_` in `type_name`
5
enum Json {
6
    Null,
7
    Bool(bool),
8
    Number(f64),
9
    Str(String),
10
    Array(Vec<Json>),
11
    Object(HashMap<String, Json>),
12
}
13

14
impl Json {
15
    fn type_name(&self) -> &'static str {
16
        match self {
17
            Json::Null => "null",
18
            Json::Bool(_) => "boolean",
19
            Json::Number(_) => "number",
20
            Json::Str(_) => "string",
21
            Json::Array(_) => "array",
22
            Json::Object(_) => "object",
23
        }
24
    }
25
}
26

27
fn main() {
28
    let mut obj = HashMap::new();
29
    obj.insert("name".to_string(), Json::Str("Ada".to_string()));
30
    obj.insert("age".to_string(), Json::Number(36.0));
31
    obj.insert("admin".to_string(), Json::Bool(true));
32
    obj.insert(
33
        "tags".to_string(),
34
        Json::Array(vec![Json::Str("a".into()), Json::Null]),
35
    );
36

37
    let doc = Json::Object(obj);
38
    println!("top-level type: {}", doc.type_name());
39

40
    if let Json::Object(map) = &doc {
41
        if let Some(name) = map.get("name") {
42
            println!("name field is a {}", name.type_name());
43
        }
44
    }
45
}

Output:

1
top-level type: object
2
name field is a string

Note: Because type_name only inspects each variant’s discriminant (matching the payloads with _), the compiler considers the inner data unread and would emit dead_code warnings. The #[allow(dead_code)] above silences them; in a real codebase you’d read those payloads (e.g. to serialize the value) and the warnings would disappear on their own.

Exercise 3: A `Light` state machine

Difficulty: Advanced

Objective: Combine a data-less enum, derived traits, match-based state transitions, and the matches! macro.

Instructions: Define enum Light { Red, Yellow, Green } deriving Debug, Clone, Copy, PartialEq. Add a method next(self) -> Light that advances the cycle Red → Green → Yellow → Red, and a method may_go(self) -> bool that returns true only for Green (use matches!). In main, start at Red and print four steps of the cycle with whether you may go.

Tip: A recursive variant that contains the enum directly — such as a Node(Tree, Tree) — would have infinite size, so it must wrap the inner value in a Box (a heap pointer): Node(Box<Tree>, Box<Tree>). You won’t need that here, but it’s the standard fix and you’ll meet Box in Section 10.

Solution

1
#[derive(Debug, Clone, Copy, PartialEq)]
2
enum Light {
3
    Red,
4
    Yellow,
5
    Green,
6
}
7

8
impl Light {
9
    fn next(self) -> Light {
10
        match self {
11
            Light::Red => Light::Green,
12
            Light::Green => Light::Yellow,
13
            Light::Yellow => Light::Red,
14
        }
15
    }
16

17
    fn may_go(self) -> bool {
18
        matches!(self, Light::Green)
19
    }
20
}
21

22
fn main() {
23
    let mut light = Light::Red;
24
    for _ in 0..4 {
25
        println!("{light:?} (go? {})", light.may_go());
26
        light = light.next();
27
    }
28
}

Output:

1
Red (go? false)
2
Green (go? true)
3
Yellow (go? false)
4
Red (go? false)

Enums and Data-Carrying Variants

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The three variant shapes, line by line

Constructing a value

Reading the data back: match

Memory: a tag plus the largest payload

Option and Result are just enums

Key Differences

Exhaustiveness is the headline feature

Enums can have methods

C-like enums with explicit discriminants

Common Pitfalls

Pitfall 1: Forgetting a variant in match

Pitfall 2: Trying to read a payload like a TypeScript property

Pitfall 3: Comparing enum values with == before deriving PartialEq

Pitfall 4: Expecting structural typing

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: A Shape enum with an area method

Exercise 2: A recursive Json enum

Exercise 3: A Light state machine

Reading the data back: `match`

`Option` and `Result` are just enums

Pitfall 1: Forgetting a variant in `match`

Pitfall 3: Comparing enum values with `==` before deriving `PartialEq`

Exercise 1: A `Shape` enum with an `area` method

Exercise 2: A recursive `Json` enum

Exercise 3: A `Light` state machine