Struct Ranges

pub struct Ranges<V> { /* private fields */ }

Ranges represents multiple intervals of a continuous range of monotone increasing values.

Internally, Ranges are an ordered list of segments, where segment is a bounds pair.

Invariants:

1. The segments are sorted, from lowest to highest (through Ord).
2. Each segment contains at least one version (start < end).
3. There is at least one version between two segments.

These ensure that equivalent instances have an identical representation, which is important for Eq and Hash. Note that this representation cannot strictly guaranty equality of Ranges with equality of its representation without also knowing the nature of the underlying versions. In particular, if the version space is discrete, different representations, using different types of bounds (exclusive/inclusive) may correspond to the same set of existing versions. It is a tradeoff we acknowledge, but which makes representations of continuous version sets more accessible, to better handle features like pre-releases and other types of version modifiers. For example, [(Included(3u32), Excluded(7u32))] and [(Included(3u32), Included(6u32))] refer to the same version set, since there is no version between 6 and 7, which this crate doesn’t know about.

Implementations

impl<V> Ranges<V>

pub fn empty() -> Self

Empty set of versions.

pub fn full() -> Self

Set of all possible versions

pub fn higher_than(v: impl Into<V>) -> Self

Set of all versions higher or equal to some version

pub fn strictly_higher_than(v: impl Into<V>) -> Self

Set of all versions higher to some version

pub fn strictly_lower_than(v: impl Into<V>) -> Self

Set of all versions lower to some version

pub fn lower_than(v: impl Into<V>) -> Self

Set of all versions lower or equal to some version

pub fn between(v1: impl Into<V>, v2: impl Into<V>) -> Self

Set of versions greater or equal to v1 but less than v2.

pub fn is_empty(&self) -> bool

Whether the set is empty, i.e. it has not ranges

impl<V: Clone> Ranges<V>

pub fn singleton(v: impl Into<V>) -> Self

Set containing exactly one version

pub fn complement(&self) -> Self

Returns the complement, which contains everything not included in self.

impl<V: Ord> Ranges<V>

pub fn as_singleton(&self) -> Option<&V>

If self contains exactly a single version, return it, otherwise, return None.

pub fn bounding_range(&self) -> Option<(Bound<&V>, Bound<&V>)>

Convert to something that can be used with BTreeMap::range. All versions contained in self, will be in the output, but there may be versions in the output that are not contained in self. Returns None if the range is empty.

pub fn contains(&self, version: &V) -> bool

Returns true if self contains the specified value.

pub fn contains_many<'s, I, BV>( &'s self, versions: I, ) -> impl Iterator<Item = bool> + 's

where I: Iterator<Item = BV> + 's, BV: Borrow<V> + 's,

Returns true if self contains the specified values.

The versions iterator must be sorted. Functionally equivalent to versions.map(|v| self.contains(v)). Except it runs in O(size_of_range + len_of_versions) not O(size_of_range * len_of_versions)

pub fn from_range_bounds<R, IV>(bounds: R) -> Self

where R: RangeBounds<IV>, IV: Clone + Into<V>,

Construct a simple range from anything that impls RangeBounds like v1..v2.

impl<V: Ord + Clone> Ranges<V>

pub fn union(&self, other: &Self) -> Self

Computes the union of this Ranges and another.

pub fn intersection(&self, other: &Self) -> Self

Computes the intersection of two sets of versions.

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

Return true if there can be no V so that V is contained in both self and other.

Note that we don’t know that set of all existing Vs here, so we only check if the segments are disjoint, not if no version is contained in both.

pub fn subset_of(&self, other: &Self) -> bool

Return true if any V that is contained in self is also contained in other.

Note that we don’t know that set of all existing Vs here, so we only check if all segments self are contained in a segment of other.

pub fn simplify<'s, I, BV>(&self, versions: I) -> Self

where I: Iterator<Item = BV> + 's, BV: Borrow<V> + 's,

Returns a simpler representation that contains the same versions.

For every one of the Versions provided in versions the existing range and the simplified range will agree on whether it is contained. The simplified version may include or exclude versions that are not in versions as the implementation wishes.

If none of the versions are contained in the original than the range will be returned unmodified. If the range includes a single version, it will be returned unmodified. If all the versions are contained in the original than the range will be simplified to full.

If the given versions are not sorted the correctness of this function is not guaranteed.

pub fn iter(&self) -> impl Iterator<Item = (&Bound<V>, &Bound<V>)>

Iterate over the parts of the range.

Trait Implementations

impl<V: Clone> Clone for Ranges<V>

fn clone(&self) -> Ranges<V>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<V: Debug> Debug for Ranges<V>

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

Formats the value using the given formatter.

impl<V: Display + Eq> Display for Ranges<V>

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

Formats the value using the given formatter.

impl<V: Ord> FromIterator<(Bound<V>, Bound<V>)> for Ranges<V>

fn from_iter<T: IntoIterator<Item = (Bound<V>, Bound<V>)>>(iter: T) -> Self

Constructor from arbitrary, unsorted and potentially overlapping ranges.

This is equivalent, but faster, to computing the Ranges::union of the Ranges::from_range_bounds of each segment.

impl<V: Hash> Hash for Ranges<V>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<V> IntoIterator for Ranges<V>

type Item = (Bound<V>, Bound<V>)

The type of the elements being iterated over.

type IntoIter = RangesIter<V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<V: Ord> Ord for Ranges<V>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<V: PartialEq> PartialEq for Ranges<V>

fn eq(&self, other: &Ranges<V>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<V: PartialOrd> PartialOrd for Ranges<V>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

A simple ordering scheme where we zip the segments and compare all bounds in order. If all bounds are equal, the longer range is considered greater. (And if all zipped bounds are equal and we have the same number of segments, the ranges are equal).

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<V: Eq> Eq for Ranges<V>

impl<V> StructuralPartialEq for Ranges<V>