Rest Pattern

The rest pattern (..) is a structural matching construct in Rust used to explicitly ignore unmentioned fields or elements within composite data types during pattern matching. It signals to the compiler that the remaining, unspecified parts of a struct, tuple, enum variant, array, or slice are intentionally disregarded, satisfying Rust’s exhaustive matching requirements without requiring explicit bindings for every component.

Syntax and Mechanics

The rest pattern adapts its behavior based on the composite type being destructured:

1. Structs In struct destructuring, .. is placed at the end of the field list to ignore all named fields that have not been explicitly matched.

struct Point3D { x: i32, y: i32, z: i32 }

let point = Point3D { x: 1, y: 2, z: 3 };
let Point3D { x, .. } = point; 

2. Tuples and Tuple Structs In positional types, .. ignores a contiguous sequence of elements. It can be positioned at the beginning, middle, or end of the pattern, dynamically expanding to consume all elements between the explicitly bound variables.

let tuple = (1, 2, 3, 4, 5);

// Ignores elements 2, 3, and 4
let (first, .., last) = tuple; 

struct Color(u8, u8, u8, u8);
let bg = Color(255, 0, 0, 255);

// Ignores the first three elements
let Color(.., alpha) = bg;

3. Slices and Arrays When matching against arrays or slices, .. matches a variable-length sequence of elements. The rest pattern can be bound to a variable using the @ (at) binding operator. The type of the bound variable depends strictly on the type being matched: matching against an array yields a smaller array of the exact remaining size, whereas matching against a slice yields a dynamically sized sub-slice.

Because slices are dynamically sized, matching against them with a specific number of elements is a refutable operation (it can fail if the slice is too short). Therefore, slice destructuring requires constructs that handle refutability, such as if let or match. Furthermore, when matching against a reference to a slice, Rust’s match ergonomics implicitly push the reference down to the individual bindings.

let arr = [10, 20, 30, 40];

// Binds 10 to `head`, ignores 20 and 30, binds 40 to `tail`
let [head, .., tail] = arr;

// Binds [20, 30] to the variable `middle` as an array of type `[i32; 2]`
let [head, middle @ .., tail] = arr;

let slice: &[i32] = &arr[..];

// Uses `if let` because the slice length is dynamic (refutable pattern).
// Match ergonomics implicitly bind `head` and `tail` as references (`&i32`).
// `middle_slice` is bound as a sub-slice (`&[i32]`).
if let [head, middle_slice @ .., tail] = slice {
    // head: &i32
    // middle_slice: &[i32]
    // tail: &i32
}

Compiler Constraints

Single Instance Rule The Rust compiler strictly enforces a limit of one rest pattern per structural level (e.g., per individual tuple, array, or struct). Using multiple .. tokens within the same level results in a parser error, as it creates unresolvable ambiguity regarding how many elements each rest pattern should consume. However, multiple rest patterns are permitted within a single overall pattern definition provided they are located in separate, nested structures.

let tuple = (1, 2, 3, 4, 5, 6);

// PARSER ERROR: `..` can only be used once per tuple pattern
// let (a, .., b, .., c) = tuple; 

// VALID: Multiple `..` are allowed if they are in separate nested levels
let nested = ((1, 2, 3), (4, 5, 6));
let ((a, ..), (b, ..)) = nested;

Arity and Wildcard Distinction The .. token is distinct from the wildcard pattern (_). While _ ignores exactly one element or field, .. ignores zero or more elements. It guarantees that the pattern remains exhaustive regardless of the arity of the underlying composite type, even if the rest pattern ends up consuming zero elements.

let tuple = (1, 2);

// Valid: `..` consumes zero elements here
let (first, second, ..) = tuple; 

Master Rust with Deep Grasping Methodology!

Learn More