Struct indexing::Range

pub struct Range<'id, Proof = Unknown> { /* fields omitted */ }

A branded range.

Range<'id> only indexes the container instantiated with the exact same particular lifetime for the parameter 'id at its inception from the scope() function.

The Range may carry a proof of nonemptiness (type parameter Proof), which enables further methods.

The range is delimited by a start index and an end index. Some methods will use offsets relative the the start of a range, others will use “absolute indices” which are offsets relative to the base Container itself.

Methods

impl<'id, P> Range<'id, P>

pub fn len(&self) -> usize

Return the length of the range.

pub fn is_empty(&self) -> bool

Return true if the range is empty.

pub fn nonempty(&self) -> Result<Range<'id, NonEmpty>, IndexingError>

Try to create a proof that the Range is nonempty; return a Result where the Ok branch carries a non-empty Range.

pub fn start(&self) -> usize

Return the start index.

pub fn end(&self) -> usize

Return the end index.

pub fn split_in_half(self) -> (Range<'id>, Range<'id, P>)

Split the range in half, with the upper middle index landing in the latter half. Proof of length P transfers to the latter half.

pub fn split_at(&self, index: usize) -> (Range<'id>, Range<'id>, bool)

Split to length index; if past the end, return false and clamp to the end

index is a relative index.

pub fn contains(&self, abs_index: usize) -> Option<Index<'id>>

abs_index is an absolute index

Important traits for Subdivide<'id>

impl<'id> Iterator for Subdivide<'id> type Item = Range<'id, NonEmpty>;

pub fn subdivide(&self, n: usize) -> Subdivide<'id>

Return an iterator that divides the range in n parts, in as even length chunks as possible.

pub fn join<Q>(
    &self,
    other: Range<'id, Q>
) -> Result<Range<'id, <(P, Q) as ProofAdd>::Sum>, IndexingError> where
    (P, Q): ProofAdd, 

Join together two adjacent ranges (they must be exactly touching, and in left to right order).

pub fn join_cover<Q>(&self, other: Range<'id, Q>) -> Range<'id, P> where
    (P, Q): ProofAdd, 

Extend the range to the end of other, including any space in between

The following example exists only to check that it fails to compile:

// Bug from https://github.com/bluss/indexing/issues/12
use indexing::scope;

let array = [0, 1, 2, 3, 4, 5];
scope(&array[..], |arr| {
    let left = arr.vet_range(0..2).unwrap();
    let left = left.nonempty().unwrap();
    let (_, right) = arr.range().frontiers();
    let joined = right.join_cover(left);
    let ix = joined.first();
    arr[ix];  //~ ERROR: Can't index by ix, because it's an edge index
});

pub fn join_cover_both<Q>(
    &self,
    other: Range<'id, Q>
) -> Range<'id, <(P, Q) as ProofAdd>::Sum> where
    (P, Q): ProofAdd, 

Extend the range to start and end of other, including any space in between

pub fn as_range(&self) -> Range<usize>

pub fn frontiers(&self) -> (Range<'id>, Range<'id>)

Return two empty ranges, at the front and the back of the range respectively

pub fn forward_by(&self, index: &mut Index<'id>, offset: usize) -> bool

Increment index, if doing so would still be before the end of the range

Return true if the index was incremented.

pub fn forward_range_by<Q>(&self, r: Range<'id, Q>, offset: usize) -> Range<'id>

Increment r, clamping to the end of self.

pub fn no_proof(&self) -> Range<'id>

impl<'id, P> Range<'id, P>

pub fn first(&self) -> Index<'id, P>

Return the first index in the range (The index is accessible if the range is NonEmpty).

pub fn upper_middle(&self) -> Index<'id, P>

Return the middle index, rounding up.

Produces mid where mid = start + len / 2.

pub fn past_the_end(self) -> Index<'id, Unknown>

Return the index past the end of the range.

impl<'id> Range<'id, NonEmpty>

pub fn lower_middle(&self) -> Index<'id>

Return the middle index, rounding down.

Produces mid where mid = start + (len - 1)/ 2.

pub fn last(&self) -> Index<'id>

pub fn tail(self) -> Range<'id>

pub fn init(&self) -> Range<'id>

pub fn advance_(&self) -> Result<Range<'id, NonEmpty>, IndexingError>

pub fn advance(&mut self) -> bool

Increase the range's start, if the result is still a non-empty range.

Return true if stepped successfully, false if the range would be empty.

pub fn advance_by(&mut self, offset: usize) -> bool

Increase the range's start, if the result is still a non-empty range.

Return true if stepped successfully, false if the range would be empty.

pub fn advance_back(&mut self) -> bool

Decrease the range's end, if the result is still a non-empty range.

Return true if stepped successfully, false if the range would be empty.

Trait Implementations

impl<'id> IntoCheckedRange<'id> for Range<'id>

fn into(self) -> Result<Range<'id, NonEmpty>, IndexingError>

impl<'id> IntoCheckedRange<'id> for Range<'id, NonEmpty>

fn into(self) -> Result<Range<'id, NonEmpty>, IndexingError>

impl<'id, P> Provable for Range<'id, P>

type Proof = P

type WithoutProof = Range<'id, Unknown>

fn no_proof(self) -> Self::WithoutProof

Return a copy of self with the proof parameter set to Unknown.

impl<'id, P> Clone for Range<'id, P>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'id, P, Q> PartialOrd<Range<'id, Q>> for Range<'id, P>

Compare the order of two ranges.

Ranges compare like an ordered pair of indices, and the proof parameter does not matter.

fn partial_cmp(&self, rhs: &Range<'id, Q>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, rhs: &Range<'id, Q>) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

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

impl<'id, P> Copy for Range<'id, P>

impl<'id, P> Eq for Range<'id, P>

impl<'id, P> IntoIterator for Range<'id, P>

type Item = Index<'id>

The type of the elements being iterated over.

type IntoIter = RangeIter<'id>

Which kind of iterator are we turning this into?

Important traits for RangeIter<'id>

impl<'id> Iterator for RangeIter<'id> type Item = Index<'id>;

fn into_iter(self) -> RangeIter<'id>

Creates an iterator from a value.

impl<'id, P> Ord for Range<'id, P>

Compare the order of two ranges.

Ranges compare like an ordered pair of indices, and the proof parameter does not matter.

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<'id, P, Q> PartialEq<Range<'id, Q>> for Range<'id, P>

fn eq(&self, other: &Range<'id, Q>) -> bool

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'id, P> Debug for Range<'id, P>

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

Formats the value using the given formatter.

impl<'id, T, Array, P, M> Index<Range<'id, P>> for Container<'id, Array, M> where
    Array: Contiguous<Item = T>, 

&self[r] where r is a Range<'id>.

type Output = [T]

The returned type after indexing.

fn index(&self, r: Range<'id, P>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<'id, Array, P, M> IndexMut<Range<'id, P>> for Container<'id, Array, M> where
    Array: ContiguousMut, 

&mut self[r] where r is a Range<'id>.

fn index_mut(&mut self, r: Range<'id, P>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<'id, P> Hash for Range<'id, P>

fn hash<H: Hasher>(&self, h: &mut H)

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].