Rust Tuple Struct Pattern

A tuple struct pattern is a destructuring mechanism in Rust used to bind variables to the unnamed fields of a tuple struct. It mirrors the syntax used to construct the tuple struct, allowing developers to extract inner values by their positional index during pattern matching operations. Because tuple structs lack named fields, the pattern relies strictly on the arity and order of the fields defined in the struct signature.

Basic Destructuring

To destructure a tuple struct, the pattern must match the struct’s identifier followed by a set of parentheses containing sub-patterns for each field.

struct Color(u8, u8, u8);

let background = Color(25, 50, 75);

// Destructuring via the tuple struct pattern in a `let` binding
let Color(r, g, b) = background;

Usage in Match Expressions

Tuple struct patterns are heavily utilized within match arms to evaluate specific positional values or bind them to local variables.

struct Status(u32, String);

let current_status = Status(404, String::from("Not Found"));

match current_status {
    // Matching a literal value in the first position, binding the second
    Status(200, msg) => println!("Success: {}", msg),
    Status(404, msg) => println!("Error: {}", msg),
    // Binding all positions
    Status(code, msg) => println!("Code {}: {}", code, msg),
}

Ignoring Fields

When destructuring, you can selectively ignore fields using the wildcard pattern (_) for individual positions, or the rest pattern (..) to ignore multiple remaining fields.

struct Point3D(f64, f64, f64);

let point = Point3D(1.5, 2.0, 3.5);

// Ignoring a single field at a specific index
let Point3D(x, _, z) = point;

// Ignoring all fields after the first matched field
let Point3D(x, ..) = point;

// Ignoring all fields before the last matched field
let Point3D(.., z) = point;

Nested Patterns

Tuple struct patterns can recursively contain other patterns, allowing for deep destructuring of complex types in a single expression.

struct Wrapper(Option<i32>, Result<bool, String>);

let data = Wrapper(Some(42), Ok(true));

match data {
    // Deeply destructuring the inner Option and Result enums
    Wrapper(Some(val), Ok(flag)) => {
        // `val` is bound to 42, `flag` is bound to true
    },
    Wrapper(None, Err(e)) => {
        // Handles the case where the first field is None and the second is an Error
    },
    Wrapper(..) => {
        // Catch-all for any other combination
    }
}

Function Parameters

The tuple struct pattern can be applied directly within function signatures to destructure arguments at the point of invocation.

struct Velocity(f64, f64);

// The pattern `Velocity(vx, vy)` destructures the argument immediately
fn calculate_speed(Velocity(vx, vy): Velocity) -> f64 {
    (vx.powi(2) + vy.powi(2)).sqrt()
}