> ## 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.
# Rust 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.
```rust theme={"dark"}
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.
```rust theme={"dark"}
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.
```rust theme={"dark"}
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.
```rust theme={"dark"}
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.
```rust theme={"dark"}
let tuple = (1, 2);
// Valid: `..` consumes zero elements here
let (first, second, ..) = tuple;
```
Tired of Poor Rust Skills? Fix That With Deep Grasping!
Learn More
