Struct range_collections::range_set::RangeSet

pub struct RangeSet<A: Array>(_);

A set of non-overlapping ranges

let mut a: RangeSet2<i32> = RangeSet::from(10..);
let b: RangeSet2<i32> = RangeSet::from(1..5);

a |= b;
let r = !a;

A data structure to represent a set of non-overlapping ranges of element type T: RangeSetEntry. It uses a SmallVec<T> of sorted boundaries internally.

It can represent not just finite ranges but also ranges with unbounded end. Because it can represent infinite ranges, it can also represent the set of all elements, and therefore all boolean operations including negation.

Adjacent ranges will be merged.

It provides very fast operations for set operations (&, |, ^) as well as for intersection tests (is_disjoint, is_subset).

In addition to the fast set operations that produce a new range set, it also supports the equivalent in-place operations.

Complexity

Complexity is given separately for the number of comparisons and the number of copies, since sometimes you have a comparison operation that is basically free (any of the primitive types), whereas sometimes you have a comparison operation that is many orders of magnitude more expensive than a copy (long strings, arbitrary precision integers, …)

Number of comparisons

operation	best	worst	remark
negation	1	O(N)
union	O(log(N))	O(N)	binary merge
intersection	O(log(N))	O(N)	binary merge
difference	O(log(N))	O(N)	binary merge
xor	O(log(N))	O(N)	binary merge
membership	O(log(N))	O(log(N))	binary search
is_disjoint	O(log(N))	O(N)	binary merge with cutoff
is_subset	O(log(N))	O(N)	binary merge with cutoff

Number of copies

For creating new sets, obviously there needs to be at least one copy for each element of the result set, so the complexity is always O(N). For in-place operations it gets more interesting. In case the number of elements of the result being identical to the number of existing elements, there will be no copies and no allocations.

E.g. if the result just has some of the ranges of the left hand side extended or truncated, but the same number of boundaries, there will be no allocations and no copies except for the changed boundaries themselves.

If the result has fewer boundaries than then lhs, there will be some copying but no allocations. Only if the result is larger than the capacity of the underlying vector of the lhs will there be allocations.

operation	best	worst
negation	1	1
union	1	O(N)
intersection	1	O(N)
difference	1	O(N)
xor	1	O(N)

Testing

Testing is done by some simple smoke tests as well as quickcheck tests of the algebraic properties of the boolean operations.

Implementations

impl<T, A: Array<Item = T>> RangeSet<A>

pub fn new(boundaries: SmallVec<A>) -> Option<Self>where A::Item: Ord,

create a new range set from the given boundaries

This performs a check that the boundaries are strictly sorted. If you want to avoid this check, use new_unchecked (behind a feature flag because it is unsafe)

pub fn iter(&self) -> Iter<'_, T>

iterate over all ranges in this range set

pub fn into_inner(self) -> SmallVec<A>

get the boundaries in this range set as a SmallVec

impl<T: RangeSetEntry, A: Array<Item = T>> RangeSet<A>

pub fn empty() -> Self

the empty range set

pub fn all() -> Self

a range set containing all values

impl<T: RangeSetEntry + Clone, A: Array<Item = T>> RangeSet<A>

pub fn intersection_with(&mut self, that: &RangeSetRef<T>)

intersection in place

pub fn union_with(&mut self, that: &RangeSetRef<T>)

union in place

pub fn difference_with(&mut self, that: &RangeSetRef<T>)

difference in place

pub fn symmetric_difference_with(&mut self, that: &RangeSetRef<T>)

symmetric difference in place (xor)

Methods from Deref<Target = RangeSetRef<T>>

pub fn split(&self, at: T) -> (&Self, &Self)where T: Ord,

Split this range set into two parts left, right at position at, so that left is identical to self for all x < at and right is identical to self for all x >= at.

More precisely: contains(left, x) == contains(ranges, x) for x < at contains(right, x) == contains(ranges, x) for x >= at

This is not the same as limiting the ranges to the left or right of at, but it is much faster. It requires just a binary search and no allocations.

pub fn boundaries(&self) -> &[T]

The boundaries of the range set, guaranteed to be strictly sorted

pub fn contains(&self, value: &T) -> boolwhere T: Ord,

true if the value is contained in the range set

pub fn is_empty(&self) -> bool

true if the range set is empty

pub fn is_all(&self) -> boolwhere T: RangeSetEntry,

true if the range set contains all values

pub fn intersects(&self, that: &RangeSetRef<T>) -> boolwhere T: Ord,

true if this range set intersects from another range set

This is just the opposite of is_disjoint, but is provided for better discoverability.

pub fn is_disjoint(&self, that: &RangeSetRef<T>) -> boolwhere T: Ord,

true if this range set is disjoint from another range set

pub fn is_subset(&self, that: &RangeSetRef<T>) -> boolwhere T: Ord,

true if this range set is a superset of another range set

A range set is considered to be a superset of itself

pub fn is_superset(&self, that: &RangeSetRef<T>) -> boolwhere T: Ord,

true if this range set is a subset of another range set

A range set is considered to be a subset of itself

pub fn iter(&self) -> Iter<'_, T>

iterate over all ranges in this range set

pub fn intersection<A>(&self, that: &RangeSetRef<T>) -> RangeSet<A>where A: Array<Item = T>, T: Ord + Clone,

intersection

pub fn union<A>(&self, that: &RangeSetRef<T>) -> RangeSet<A>where A: Array<Item = T>, T: Ord + Clone,

union

pub fn difference<A>(&self, that: &RangeSetRef<T>) -> RangeSet<A>where A: Array<Item = T>, T: Ord + Clone,

difference

pub fn symmetric_difference<A>(&self, that: &RangeSetRef<T>) -> RangeSet<A>where A: Array<Item = T>, T: Ord + Clone,

symmetric difference (xor)

Trait Implementations

impl<T, A: Array<Item = T>> AsRef<RangeSetRef<T>> for RangeSet<A>

fn as_ref(&self) -> &RangeSetRef<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: RangeSetEntry + Clone, A: Array<Item = T>> BitAnd<&RangeSet<A>> for &RangeSet<A>

compute the intersection of this range set with another, producing a new range set

∀ t ∈ T, r(t) = a(t) & b(t)

type Output = RangeSet<A>

The resulting type after applying the & operator.

fn bitand(self, that: Self) -> Self::Output

Performs the & operation.

impl<T: Ord, A: Array<Item = T>> BitAndAssign<RangeSet<A>> for RangeSet<A>

fn bitand_assign(&mut self, that: Self)

Performs the &= operation.

impl<T: RangeSetEntry + Clone, A: Array<Item = T>> BitOr<&RangeSet<A>> for &RangeSet<A>

compute the union of this range set with another, producing a new range set

∀ t ∈ T, r(t) = a(t) | b(t)

type Output = RangeSet<A>

The resulting type after applying the | operator.

fn bitor(self, that: Self) -> Self::Output

Performs the | operation.

impl<T: Ord, A: Array<Item = T>> BitOrAssign<RangeSet<A>> for RangeSet<A>

fn bitor_assign(&mut self, that: Self)

Performs the |= operation.

impl<T: RangeSetEntry + Clone, A: Array<Item = T>> BitXor<&RangeSet<A>> for &RangeSet<A>

compute the exclusive or of this range set with another, producing a new range set

∀ t ∈ T, r(t) = a(t) ^ b(t)

type Output = RangeSet<A>

The resulting type after applying the ^ operator.

fn bitxor(self, that: Self) -> Self::Output

Performs the ^ operation.

impl<T: RangeSetEntry, A: Array<Item = T>> BitXorAssign<RangeSet<A>> for RangeSet<A>

fn bitxor_assign(&mut self, that: Self)

Performs the ^= operation.

impl<T, A: Array<Item = T>> Borrow<RangeSetRef<T>> for RangeSet<A>

fn borrow(&self) -> &RangeSetRef<T>

Immutably borrows from an owned value.

impl<A: Array> Clone for RangeSet<A>where A::Item: Clone,

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug, A: Array<Item = T>> Debug for RangeSet<A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, A: Array<Item = T>> Deref for RangeSet<A>

type Target = RangeSetRef<T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: RangeSetEntry, A: Array<Item = T>> From<Range<T>> for RangeSet<A>

fn from(value: Range<T>) -> Self

Converts to this type from the input type.

impl<T: RangeSetEntry, A: Array<Item = T>> From<RangeFrom<T>> for RangeSet<A>

fn from(value: RangeFrom<T>) -> Self

Converts to this type from the input type.

impl<T: RangeSetEntry, A: Array<Item = T>> From<RangeSetRange<T>> for RangeSet<A>

fn from(value: RangeSetRange<T>) -> Self

Converts to this type from the input type.

impl<T: RangeSetEntry, A: Array<Item = T>> From<RangeTo<T>> for RangeSet<A>

fn from(value: RangeTo<T>) -> Self

Converts to this type from the input type.

impl<T: RangeSetEntry, A: Array<Item = T>> From<bool> for RangeSet<A>

fn from(value: bool) -> Self

Converts to this type from the input type.

impl<T: RangeSetEntry + Clone, A: Array<Item = T>> Not for &RangeSet<A>

compute the negation of this range set

∀ t ∈ T, r(t) = !a(t)

type Output = RangeSet<A>

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

impl<T: RangeSetEntry + Clone, A: Array<Item = T>> Not for RangeSet<A>

compute the negation of this range set

∀ t ∈ T, r(t) = !a(t)

type Output = RangeSet<A>

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

impl<A: Array, R: AsRef<RangeSetRef<A::Item>>> PartialEq<R> for RangeSet<A>where A::Item: RangeSetEntry,

fn eq(&self, that: &R) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: RangeSetEntry + Clone, A: Array<Item = T>> Sub<&RangeSet<A>> for &RangeSet<A>

compute the difference of this range set with another, producing a new range set

∀ t ∈ T, r(t) = a(t) & !b(t)

type Output = RangeSet<A>

The resulting type after applying the - operator.

fn sub(self, that: Self) -> Self::Output

Performs the - operation.

impl<T: Ord, A: Array<Item = T>> SubAssign<RangeSet<A>> for RangeSet<A>

fn sub_assign(&mut self, that: Self)

Performs the -= operation.

impl<A: Array> Eq for RangeSet<A>where A::Item: Eq + RangeSetEntry,