Struct range_collections::range_set::RangeSet

pub struct RangeSet<T, A: Array<Item = T> = [T; 2]> { /* fields omitted */ }

A set of non-overlapping ranges

let mut a: RangeSet<i32> = RangeSet::from(10..);
let b: RangeSet<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: Ord. It uses a SmallVec<T> of sorted boundaries internally.

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

It does not put any constraints on the element type for requriring an Ord instance. 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	1
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<T, A>

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

iterate over all ranges in this range set

pub fn boundaries(&self) -> &SmallVec<A>

boundaries in this range set

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

get the boundaries in this range set as a SmallVec

pub fn empty() -> Self

the empty range set

pub fn all() -> Self

a range set containing all values

pub fn constant(value: bool) -> Self

a range set with a constant value everywhere

pub fn is_empty(&self) -> bool

true if the range set is empty

pub fn is_all(&self) -> bool

true if the range set contains all values

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

pub fn is_disjoint(&self, that: &Self) -> bool

true if this range set is disjoint from another range set

pub fn is_superset(&self, that: &Self) -> bool

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_subset(&self, that: &Self) -> bool

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 contains(&self, value: &T) -> bool

true if the value is contained in the range set

Trait Implementations

impl<T: Ord + Clone, A: Array<Item = T>, '_> BitAnd<&'_ RangeSet<T, A>> for &'_ RangeSet<T, 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<T, 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<T, A>> for RangeSet<T, A>

fn bitand_assign(&mut self, that: Self)

Performs the &= operation.

impl<T: Ord + Clone, A: Array<Item = T>, '_> BitOr<&'_ RangeSet<T, A>> for &'_ RangeSet<T, 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<T, 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<T, A>> for RangeSet<T, A>

fn bitor_assign(&mut self, that: Self)

Performs the |= operation.

impl<T: Ord + Clone, A: Array<Item = T>, '_> BitXor<&'_ RangeSet<T, A>> for &'_ RangeSet<T, 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<T, A>

The resulting type after applying the ^ operator.

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

Performs the ^ operation.

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

fn bitxor_assign(&mut self, that: Self)

Performs the ^= operation.

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

fn clone(&self) -> RangeSet<T, A>

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<T, A>

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

Formats the value using the given formatter.

impl<'de, T: Deserialize<'de> + Ord, A: Array<Item = T>> Deserialize<'de> for RangeSet<T, A>

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

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

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

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

Performs the conversion.

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

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

Performs the conversion.

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

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

Performs the conversion.

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

fn from(value: bool) -> Self

Performs the conversion.

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

compute the negation of this range set

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

type Output = RangeSet<T, A>

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

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

compute the negation of this range set

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

type Output = RangeSet<T, A>

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

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

fn eq(&self, other: &RangeSet<T, A>) -> bool

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

fn ne(&self, other: &RangeSet<T, A>) -> bool

This method tests for !=.

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

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

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

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

impl<T: Ord + Clone, A: Array<Item = T>, '_> Sub<&'_ RangeSet<T, A>> for &'_ RangeSet<T, 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<T, 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<T, A>> for RangeSet<T, A>

fn sub_assign(&mut self, that: Self)

Performs the -= operation.