Rust Struct Pattern

A struct pattern is a destructuring mechanism in Rust used to unpack and bind the internal fields of a struct to local variables during pattern matching. It allows for precise extraction of data and structural validation within constructs such as match, let, if let, and function signatures.

Basic Destructuring and Binding

To destructure a struct, the pattern must match the exact name of the struct. You map the struct’s fields to new local variables using the field_name: variable_name syntax.

struct Point {
    x: i32,
    y: i32,
}

let p = Point { x: 10, y: 20 };

// Destructuring `p` into new variables `a` and `b`
let Point { x: a, y: b } = p; 

Field Shorthand

If the local variable you are binding to has the exact same name as the struct field, Rust permits a shorthand syntax where you omit the : variable_name declaration.

# struct Point { x: i32, y: i32 }

# let p = Point { x: 10, y: 20 };
// Binds to local variables `x` and `y`
let Point { x, y } = p; 

Binding Modes

Struct patterns support binding modes to modify how fields are extracted. By default, fields are moved or copied (depending on Copy semantics). You can use mut, ref, and ref mut to alter this behavior per field.

# struct Point { x: i32, y: i32 }

# let p = Point { x: 10, y: 20 };
// Binds `x` as a mutable value and `y` as an immutable reference
let Point { mut x, ref y } = p;
x += 5; 


# let mut p2 = Point { x: 10, y: 20 };
// Binds `x` as a mutable reference, allowing modification of the original struct
let Point { ref mut x, y: _ } = p2;
*x += 10;

Function Signatures

Struct patterns can be applied directly within function parameter lists. This allows a function to accept a struct and immediately destructure its fields into local variables for the function body.

# struct Point { x: i32, y: i32 }
// Destructures the struct directly in the parameter list
fn process_point(Point { x, y }: Point) {
    println!("Processing coordinates: {}, {}", x, y);
}


# let p = Point { x: 10, y: 20 };

# process_point(p);

Ignoring Fields with the Rest Pattern

When a struct contains multiple fields but only a subset is required for the binding, the rest pattern (..) is used to explicitly ignore all unlisted fields. This prevents compiler errors regarding exhaustive matching.

struct User {
    id: u32,
    username: String,
    is_active: bool,
}

let user = User { id: 1, username: String::from("admin"), is_active: true };

// Extracts `id` and ignores `username` and `is_active`
let User { id, .. } = user;

Literal and Wildcard Matching

Struct patterns can evaluate the inner values of the fields directly. You can match against specific literals or use the wildcard (_) to ignore a specific field without using the rest pattern.

# struct Point { x: i32, y: i32 }

# let p = Point { x: 0, y: 20 };
match p {
    // Matches only if `x` is exactly 0; binds `y`
    Point { x: 0, y } => println!("On the Y axis at {}", y),
    
    // Matches only if `y` is exactly 0; binds `x`
    Point { x, y: 0 } => println!("On the X axis at {}", x),
    
    // Binds `x`, ignores `y` explicitly
    Point { x, y: _ } => println!("Somewhere else, x is {}", x),
}

Nested Struct Patterns

Struct patterns can be nested to destructure complex, hierarchical data types in a single statement. The syntax cascades inward, matching the outer struct and then immediately destructuring the inner struct.

# struct Point { x: i32, y: i32 }
struct Wrapper {
    id: u32,
    location: Point,
}

let w = Wrapper { id: 100, location: Point { x: 5, y: 15 } };

// Destructures `Wrapper` and its inner `Point` simultaneously
let Wrapper { id, location: Point { x, y } } = w;

Destructuring Enums with Struct Variants

Struct patterns are also applied when matching against enum variants that are defined as struct-like variants. The syntax behaves identically to standard struct destructuring.

enum Message {
    Move { x: i32, y: i32 },
    Quit,
}

let msg = Message::Move { x: 50, y: 100 };

match msg {
    // Struct pattern applied to an enum variant
    Message::Move { x, y } => println!("Moving to {}, {}", x, y),
    Message::Quit => println!("Quitting"),
}

Tired of Poor Rust Skills? Fix That With Deep Grasping!Learn More

Functions

Traits

Closures

Generics

Enums

Pattern Matching

Structs

Macros

Lifetimes

Error Handling

Variables

Control Flow

Loops

Modules

Compound Types

Collection Types

Numeric Types

Text & Boolean Types

Attributes

Comments

Assignment Operators

Arithmetic Operators

Comparison Operators

Logical Operators

Unary Operators

Reference Operators

Access & Path Operators

Range Operators

Bitwise Operators

Type Cast Operators

Rust Struct Pattern

Basic Destructuring and Binding

Field Shorthand

Binding Modes

Function Signatures

Ignoring Fields with the Rest Pattern

Literal and Wildcard Matching

Nested Struct Patterns

Destructuring Enums with Struct Variants

​Basic Destructuring and Binding

​Field Shorthand

​Binding Modes

​Function Signatures

​Ignoring Fields with the Rest Pattern

​Literal and Wildcard Matching

​Nested Struct Patterns

​Destructuring Enums with Struct Variants

Basic Destructuring and Binding

Field Shorthand

Binding Modes

Function Signatures

Ignoring Fields with the Rest Pattern

Literal and Wildcard Matching

Nested Struct Patterns

Destructuring Enums with Struct Variants