Inclusive Range

The ..= operator in Rust is the inclusive range operator. It constructs a range that spans from a starting bound up to, and strictly including, an ending bound.

Depending on the presence of the starting bound, the operator evaluates to one of two distinct struct types within the std::ops module:

1. start..=end: Evaluates to std::ops::RangeInclusive<Idx>.
2. ..=end: Evaluates to std::ops::RangeToInclusive<Idx>.

// Instantiates std::ops::RangeInclusive<i32>
let bounded_inclusive = 1..=5; 

// Instantiates std::ops::RangeToInclusive<i32>
let half_open_inclusive = ..=5; 

Type Requirements and Trait Implementations

• Iterator: RangeInclusive<Idx> implements the Iterator trait if the underlying type Idx implements the std::iter::Step trait (which is implemented for primitive integers and char). RangeToInclusive<Idx> does not implement Iterator because it lacks a defined starting point.
• SliceIndex: Both RangeInclusive and RangeToInclusive implement the std::slice::SliceIndex trait, allowing them to be passed directly to indexing operations to yield sub-slices.
• Contains: Both types implement the RangeBounds<Idx> trait, providing the contains method to check if a specific value falls within the inclusive bounds.

Internal Mechanics and Overflow Safety

Unlike the exclusive range operator (..), RangeInclusive must safely handle iteration up to the absolute maximum value of a given type (e.g., 255 for u8).

If an exclusive range iterates to u8::MAX, the loop terminates before yielding it. An inclusive range must yield u8::MAX and then terminate. To prevent integer overflow (which would panic in debug mode or wrap in release mode) when attempting to increment past the maximum value, RangeInclusive maintains an internal boolean flag to track iterator exhaustion. Consequently, the memory footprint of RangeInclusive is slightly larger than that of std::ops::Range.

Pattern Matching Syntax

Beyond expression evaluation, the compiler parses ..= as a distinct token for pattern matching. When used in a match arm, it does not instantiate a RangeInclusive struct at runtime; instead, it generates a direct comparison branch at the compiler level.

match target_value {
    // Parsed as a pattern, not a RangeInclusive struct
    0..=100 => { /* ... */ },
    _ => { /* ... */ }
}

Master Rust with Deep Grasping Methodology!

Learn More