Struct Variant

A struct variant is a specific type of enumeration (enum) variant in Rust that encapsulates data using named fields, mirroring the syntax and memory layout of a standard nominal struct. It allows an enum to carry complex, heterogeneous, and labeled data payloads directly within a specific state.

Declaration Syntax

A struct variant is defined inside an enum block using curly braces {} containing comma-separated field_name: Type pairs.

enum NetworkEvent {
    // Struct variant
    ConnectionClosed { 
        error_code: u32, 
        reason: String, 
        is_recoverable: bool 
    },
    // Unit and Tuple variants for contrast
    Ping,
    DataReceived(Vec<u8>),
}

Instantiation

To instantiate a struct variant, you must use the fully qualified path (or an imported path) to the variant, followed by curly braces initializing every named field.

let event = NetworkEvent::ConnectionClosed {
    error_code: 404,
    reason: String::from("Not Found"),
    is_recoverable: false,
};

Destructuring and Pattern Matching

Because an enum can be any of its variants, Rust does not allow direct field access via dot notation (e.g., event.error_code is a compilation error). Data must be extracted via pattern matching using match, if let, or let else.

match event {
    NetworkEvent::ConnectionClosed { error_code, reason, is_recoverable } => {
        // Fields are now bound to local variables
        println!("Code: {error_code}, Reason: {reason}");
    }
    _ => {}
}

Advanced Destructuring Mechanics:

• Renaming bindings: You can bind a field to a new variable name using field: new_name.
• Ignoring fields: You can ignore specific fields using the .. operator to discard the remainder of the struct variant.

if let NetworkEvent::ConnectionClosed { error_code: code, .. } = event {
    // Only `code` is bound; `reason` and `is_recoverable` are ignored
}

Technical Characteristics

Type System Constraints A struct variant is not an independent type in Rust’s type system. In the example above, NetworkEvent is the type, while NetworkEvent::ConnectionClosed is merely a constructor for that type. You cannot define a function signature that accepts only a ConnectionClosed variant; the function must accept the entire NetworkEvent enum.

Memory Layout Like all Rust enums, an enum containing a struct variant is represented in memory as a tagged union. The total size of the enum is determined by the size of its largest variant, plus the size of the discriminant (the tag used to identify the active variant), plus any necessary alignment padding.

If a struct variant contains many large fields, it will inflate the memory footprint of the entire enum, even when the enum is currently holding a zero-sized unit variant.

enum State {
    Active, // 0 bytes of data
    // This struct variant forces the entire enum to be at least 24 bytes 
    // (assuming 64-bit architecture), plus the discriminant.
    Suspended { 
        duration: u64, 
        context_ptr: usize, 
        flags: u64 
    },
}

To mitigate this memory inflation, large struct variants are often refactored to hold a smart pointer (like Box<T>) to a heap-allocated standard struct.

Master Rust with Deep Grasping Methodology!

Learn More