Multi Ranged

Efficient data structures for representing and manipulating ranges of discrete values. The crate provides three range types with a unified MultiRanged trait: SimpleRange for contiguous ranges similar to Rust's std::ops::Range but with stable semantics, BiRange for ranges split into two parts, and MultiRange for arbitrary collections of disjoint ranges. All types support incremental insertion, merging, and efficient iteration over their elements. The Step trait abstracts over numeric types that can be used as range boundaries, providing operations for stepping forward and backward with saturating arithmetic.

Examples

Simple Range

A contiguous range from start to end. See SimpleRange for more details.

use multi_ranged::{SimpleRange, MultiRanged};

// Create a range [0, 10)
let mut range = SimpleRange::try_from((0, 10))?;
assert_eq!(range.len(), 10);
assert!(range.contains(5));
assert!(!range.contains(15));

// Extend the range to [0, 11)
range.insert(10)?;
assert_eq!(range.len(), 11);
# Ok::<(), multi_ranged::errors::Error<i32>>(())

Bi Range

A range that can be split into at most two non-contiguous parts. See BiRange for more details.

use multi_ranged::{BiRange, MultiRanged};

// Create a BiRange from a slice of integers.
// This creates two disjoint ranges: [1, 3) and [5, 7).
let mut range = BiRange::try_from([1, 2, 5, 6])?;
assert!(!range.is_dense());
assert_eq!(range.len(), 4);

// Insert a value that bridges the gap.
range.insert(3)?; // Now we have [1, 4) and [5, 7)
range.insert(4)?; // Now we have [1, 7)

assert!(range.is_dense());
assert_eq!(range.absolute_start(), Some(1));
assert_eq!(range.absolute_end(), Some(7));
# Ok::<(), multi_ranged::errors::Error<i32>>(())

Multi Range

Multiple disjoint ranges that can be built incrementally. See MultiRange for more details.

use multi_ranged::{MultiRange, MultiRanged};

// Create a MultiRange from a slice of integers.
// This creates two disjoint ranges: [1, 4) and [10, 13).
let mut range = MultiRange::try_from([1, 2, 3, 10, 11, 12])?;
assert!(!range.is_dense());

// Insert values that bridge the gap between [1, 4) and [10, 13).
range.insert(4)?; // Now we have [1, 5) and [10, 13)
range.insert(5)?; // Now we have [1, 6) and [10, 13)
range.insert(6)?; // Now we have [1, 7) and [10, 13)
range.insert(7)?; // Now we have [1, 8) and [10, 13)
range.insert(8)?; // Now we have [1, 9) and [10, 13)
range.insert(9)?; // Now we have [1, 13)

// The ranges have merged into a single contiguous range: [1, 13).
assert!(range.is_dense());
assert_eq!(range.absolute_start(), Some(1));
assert_eq!(range.absolute_end(), Some(13));
# Ok::<(), multi_ranged::errors::Error<i32>>(())

Trait Overview

The MultiRanged trait provides a common interface for all range types with methods for insertion, merging, containment checking, and iteration. The Step trait enables generic range operations over any numeric type supporting saturating arithmetic and ordering.