Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

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"),
}
Master Rust with Deep Grasping Methodology!Learn More