RUST: enum

Think of an enum as defining a set of named constants that represent all the possible values a type can have. However, Rust enums go beyond simple named constants found in many other languages by allowing variants to hold associated data.

Core Concepts:

1. Defining Variants: An enum lists out all possible “kinds” or “states” that a value of this type can be.
2. One Variant at a Time: An instance of an enum can only be one of its defined variants at any given moment.
3. Associated Data: Variants can optionally store data related to that specific variant. This data can have different types for different variants within the same enum.
4. Type Safety: Enums, combined with Rust’s match expression, provide strong compile-time guarantees that you’ve handled all possible variants.

Basic Syntax:

// Define an enum named 'Direction'
enum Direction {
    North, // A simple variant with no associated data
    South,
    East,
    West,
}

// Define an enum for a simple state machine
enum Status {
    Pending,
    Processing,
    Completed,
    Failed,
}

fn main() {
    // Create instances of the enum variants
    let go_direction: Direction = Direction::North;
    let current_status: Status = Status::Processing;

    // A variable of type 'Direction' can hold any of the four variants
    let another_direction = Direction::West;
}

Enums with Associated Data:

This is where Rust enums really shine. Each variant can be defined to hold specific data types.

// An enum representing different kinds of messages
enum Message {
    Quit, // No data associated
    Move { x: i32, y: i32 }, // Named fields like a struct (anonymous struct)
    Write(String), // Holds a single String value (like a tuple struct)
    ChangeColor(i32, i32, i32), // Holds three i32 values (like a tuple)
}

fn main() {
    // Create instances with associated data
    let msg1 = Message::Quit;
    let msg2 = Message::Move { x: 10, y: -5 };
    let msg3 = Message::Write(String::from("Hello, Rust!"));
    let msg4 = Message::ChangeColor(255, 0, 128);
}

Canonical Examples: Option and Result

Two extremely common enums are built into the Rust standard library:

1. Option<T>: Represents a value that might be present or absent. Used to handle nullability safely.

enum Option<T> {
    Some(T), // Variant holding a value of type T
    None,    // Variant representing the absence of a value
}

let some_number: Option<i32> = Some(5);
let absent_number: Option<i32> = None;

2. Result<T, E>: Represents the result of an operation that could succeed (with a value of type T) or fail (with an error of type E). Used extensively for error handling.

enum Result<T, E> {
    Ok(T),  // Variant holding the success value of type T
    Err(E), // Variant holding the error value of type E
}

// Example: Parsing a string to a number
let parse_result: Result<i32, std::num::ParseIntError> = "123".parse(); // This returns Ok(123)
let failed_parse: Result<i32, std::num::ParseIntError> = "abc".parse(); // This returns Err(...)

Working with Enums: match

The primary way to work with enums is the match expression. match allows you to compare a value against a series of patterns (one for each variant) and execute code based on which pattern matches. Rust’s compiler ensures that your match is exhaustive, meaning you must handle every possible variant.

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn process_message(msg: Message) {
    match msg {
        Message::Quit => {
            println!("Quit message received.");
        }
        Message::Move { x, y } => { // Destructure the fields
            println!("Move message received: move to ({}, {})", x, y);
        }
        Message::Write(text) => { // Bind the associated data to 'text'
            println!("Write message received: '{}'", text);
        }
        Message::ChangeColor(r, g, b) => { // Bind associated data
            println!("ChangeColor message received: R={}, G={}, B={}", r, g, b);
        }
        // No 'default' or '_' needed here because we handled all variants.
        // If we missed one, the compiler would give an error.
    }
}

fn main() {
    process_message(Message::Move { x: 5, y: 10 });
    process_message(Message::Write(String::from("Match is powerful!")));
}

if let:

For cases where you only care about one specific variant and want to ignore the others, if let provides a more concise alternative to match.

fn main() {
    let maybe_message = Some(Message::Quit);
    // let maybe_message: Option<Message> = None; // Try this too

    // If maybe_message is Some(Message::Quit), execute the block
    if let Some(Message::Quit) = maybe_message {
        println!("It was the Quit message!");
    } else {
        println!("It was some other message or None.");
    }

    let msg = Message::Move{ x: 1, y: 2};
    // If msg is the Move variant, extract x and y
    if let Message::Move{ x, y } = msg {
       println!("Destructured via if let: x={}, y={}", x, y);
    }
}

In Summary:

• Enums define a type with a fixed set of possible named variants.
• Variants can optionally hold associated data of different types.
• The Option and Result enums are crucial for handling absence and errors safely.
• match is the primary tool for working with enums, ensuring all possibilities are handled.
• if let is a convenient shorthand for handling a single variant.

Enums are a cornerstone of Rust’s expressiveness and safety, allowing you to model complex states and data variations in a clear and robust way.