rustmax::std::iter

Trait DoubleEndedIterator

pub trait DoubleEndedIterator: Iterator {
    // Required method
    fn next_back(&mut self) -> Option<Self::Item>;

    // Provided methods
    fn next_chunk_back<const N: usize>(
        &mut self,
    ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>
       where Self: Sized { ... }
    fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero<usize>> { ... }
    fn nth_back(&mut self, n: usize) -> Option<Self::Item> { ... }
    fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R
       where Self: Sized,
             F: FnMut(B, Self::Item) -> R,
             R: Try<Output = B> { ... }
    fn rfold<B, F>(self, init: B, f: F) -> B
       where Self: Sized,
             F: FnMut(B, Self::Item) -> B { ... }
    fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>
       where Self: Sized,
             P: FnMut(&Self::Item) -> bool { ... }
}

Expand description

An iterator able to yield elements from both ends.

Something that implements DoubleEndedIterator has one extra capability over something that implements Iterator: the ability to also take Items from the back, as well as the front.

It is important to note that both back and forth work on the same range, and do not cross: iteration is over when they meet in the middle.

In a similar fashion to the Iterator protocol, once a DoubleEndedIterator returns None from a next_back(), calling it again may or may not ever return Some again. next() and next_back() are interchangeable for this purpose.

§Examples

Basic usage:

let numbers = vec![1, 2, 3, 4, 5, 6];

let mut iter = numbers.iter();

assert_eq!(Some(&1), iter.next());
assert_eq!(Some(&6), iter.next_back());
assert_eq!(Some(&5), iter.next_back());
assert_eq!(Some(&2), iter.next());
assert_eq!(Some(&3), iter.next());
assert_eq!(Some(&4), iter.next());
assert_eq!(None, iter.next());
assert_eq!(None, iter.next_back());

Required Methods§

1.0.0 (const: unstable) · Source

fn next_back(&mut self) -> Option<Self::Item>

Removes and returns an element from the end of the iterator.

Returns None when there are no more elements.

The trait-level docs contain more details.

§Examples

Basic usage:

let numbers = vec![1, 2, 3, 4, 5, 6];

let mut iter = numbers.iter();

assert_eq!(Some(&1), iter.next());
assert_eq!(Some(&6), iter.next_back());
assert_eq!(Some(&5), iter.next_back());
assert_eq!(Some(&2), iter.next());
assert_eq!(Some(&3), iter.next());
assert_eq!(Some(&4), iter.next());
assert_eq!(None, iter.next());
assert_eq!(None, iter.next_back());

§Remarks

The elements yielded by DoubleEndedIterator’s methods may differ from the ones yielded by Iterator’s methods:

let vec = vec![(1, 'a'), (1, 'b'), (1, 'c'), (2, 'a'), (2, 'b')];
let uniq_by_fst_comp = || {
    let mut seen = std::collections::HashSet::new();
    vec.iter().copied().filter(move |x| seen.insert(x.0))
};

assert_eq!(uniq_by_fst_comp().last(), Some((2, 'a')));
assert_eq!(uniq_by_fst_comp().next_back(), Some((2, 'b')));

assert_eq!(
    uniq_by_fst_comp().fold(vec![], |mut v, x| {v.push(x); v}),
    vec![(1, 'a'), (2, 'a')]
);
assert_eq!(
    uniq_by_fst_comp().rfold(vec![], |mut v, x| {v.push(x); v}),
    vec![(2, 'b'), (1, 'c')]
);

Provided Methods§

Source

fn next_chunk_back<const N: usize>( &mut self, ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>
where Self: Sized,

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

Advances from the back of the iterator and returns an array containing the next N values in sequence.

If there are not enough elements to fill the array then Err is returned containing an iterator over the remaining elements.

Note: This is not equivalent to doing iter.rev().next_chunk() as this method takes elements from the back of the iterator and preserves the order that the elements were seen in the original iterator.

§Examples

Basic usage:

#![feature(iter_next_chunk)]

let mut iter = "lorem".chars();

assert_eq!(iter.next_chunk_back().unwrap(), ['e', 'm']);              // N is inferred as 2
assert_eq!(iter.next_chunk_back().unwrap(), ['l', 'o', 'r']);         // N is inferred as 3
assert_eq!(iter.next_chunk_back::<4>().unwrap_err().as_slice(), &[]); // N is explicitly 4

Split a string and get the last three items in sequence.

#![feature(iter_next_chunk)]

let quote = "not all those who wander are lost";
let [first, second, third] = quote.split_whitespace().next_chunk_back().unwrap();
assert_eq!(first, "wander");
assert_eq!(second, "are");
assert_eq!(third, "lost");

Source

fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero<usize>>

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

Advances the iterator from the back by n elements.

advance_back_by is the reverse version of advance_by. This method will eagerly skip n elements starting from the back by calling next_back up to n times until None is encountered.

advance_back_by(n) will return Ok(()) if the iterator successfully advances by n elements, or a Err(NonZero<usize>) with value k if None is encountered, where k is remaining number of steps that could not be advanced because the iterator ran out. If self is empty and n is non-zero, then this returns Err(n). Otherwise, k is always less than n.

Calling advance_back_by(0) can do meaningful work, for example Flatten can advance its outer iterator until it finds an inner iterator that is not empty, which then often allows it to return a more accurate size_hint() than in its initial state.

§Examples

Basic usage:

#![feature(iter_advance_by)]

use std::num::NonZero;

let a = [3, 4, 5, 6];
let mut iter = a.iter();

assert_eq!(iter.advance_back_by(2), Ok(()));
assert_eq!(iter.next_back(), Some(&4));
assert_eq!(iter.advance_back_by(0), Ok(()));
assert_eq!(iter.advance_back_by(100), Err(NonZero::new(99).unwrap())); // only `&3` was skipped

1.37.0 (const: unstable) · Source

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

Returns the nth element from the end of the iterator.

This is essentially the reversed version of Iterator::nth(). Although like most indexing operations, the count starts from zero, so nth_back(0) returns the first value from the end, nth_back(1) the second, and so on.

Note that all elements between the end and the returned element will be consumed, including the returned element. This also means that calling nth_back(0) multiple times on the same iterator will return different elements.

nth_back() will return None if n is greater than or equal to the length of the iterator.

§Examples

Basic usage:

let a = [1, 2, 3];
assert_eq!(a.iter().nth_back(2), Some(&1));

Calling nth_back() multiple times doesn’t rewind the iterator:

let a = [1, 2, 3];

let mut iter = a.iter();

assert_eq!(iter.nth_back(1), Some(&2));
assert_eq!(iter.nth_back(1), None);

Returning None if there are less than n + 1 elements:

let a = [1, 2, 3];
assert_eq!(a.iter().nth_back(10), None);

1.27.0 (const: unstable) · Source

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R
where Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try<Output = B>,

This is the reverse version of Iterator::try_fold(): it takes elements starting from the back of the iterator.

§Examples

Basic usage:

let a = ["1", "2", "3"];
let sum = a.iter()
    .map(|&s| s.parse::<i32>())
    .try_rfold(0, |acc, x| x.and_then(|y| Ok(acc + y)));
assert_eq!(sum, Ok(6));

Short-circuiting:

let a = ["1", "rust", "3"];
let mut it = a.iter();
let sum = it
    .by_ref()
    .map(|&s| s.parse::<i32>())
    .try_rfold(0, |acc, x| x.and_then(|y| Ok(acc + y)));
assert!(sum.is_err());

// Because it short-circuited, the remaining elements are still
// available through the iterator.
assert_eq!(it.next_back(), Some(&"1"));

1.27.0 (const: unstable) · Source

fn rfold<B, F>(self, init: B, f: F) -> B
where Self: Sized, F: FnMut(B, Self::Item) -> B,

An iterator method that reduces the iterator’s elements to a single, final value, starting from the back.

This is the reverse version of Iterator::fold(): it takes elements starting from the back of the iterator.

rfold() takes two arguments: an initial value, and a closure with two arguments: an ‘accumulator’, and an element. The closure returns the value that the accumulator should have for the next iteration.

The initial value is the value the accumulator will have on the first call.

After applying this closure to every element of the iterator, rfold() returns the accumulator.

This operation is sometimes called ‘reduce’ or ‘inject’.

Folding is useful whenever you have a collection of something, and want to produce a single value from it.

Note: rfold() combines elements in a right-associative fashion. For associative operators like +, the order the elements are combined in is not important, but for non-associative operators like - the order will affect the final result. For a left-associative version of rfold(), see Iterator::fold().

§Examples

Basic usage:

let a = [1, 2, 3];

// the sum of all of the elements of a
let sum = a.iter()
           .rfold(0, |acc, &x| acc + x);

assert_eq!(sum, 6);

This example demonstrates the right-associative nature of rfold(): it builds a string, starting with an initial value and continuing with each element from the back until the front:

let numbers = [1, 2, 3, 4, 5];

let zero = "0".to_string();

let result = numbers.iter().rfold(zero, |acc, &x| {
    format!("({x} + {acc})")
});

assert_eq!(result, "(1 + (2 + (3 + (4 + (5 + 0)))))");

1.27.0 (const: unstable) · Source

fn rfind(&mut self, predicate: P) -> Option<Self::Item>
where Self: Sized, P: FnMut(&Self::Item) -> bool,

Searches for an element of an iterator from the back that satisfies a predicate.

rfind() takes a closure that returns true or false. It applies this closure to each element of the iterator, starting at the end, and if any of them return true, then rfind() returns Some(element). If they all return false, it returns None.

rfind() is short-circuiting; in other words, it will stop processing as soon as the closure returns true.

Because rfind() takes a reference, and many iterators iterate over references, this leads to a possibly confusing situation where the argument is a double reference. You can see this effect in the examples below, with &&x.

§Examples

Basic usage:

let a = [1, 2, 3];

assert_eq!(a.into_iter().rfind(|&x| x == 2), Some(2));
assert_eq!(a.into_iter().rfind(|&x| x == 5), None);

Iterating over references:

let a = [1, 2, 3];

// `iter()` yields references i.e. `&i32` and `rfind()` takes a
// reference to each element.
assert_eq!(a.iter().rfind(|&&x| x == 2), Some(&2));
assert_eq!(a.iter().rfind(|&&x| x == 5), None);

Stopping at the first true:

let a = [1, 2, 3];

let mut iter = a.iter();

assert_eq!(iter.rfind(|&&x| x == 2), Some(&2));

// we can still use `iter`, as there are more elements.
assert_eq!(iter.next_back(), Some(&1));

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§

1.12.0 · Source§

impl DoubleEndedIterator for Args

1.12.0 · Source§

impl DoubleEndedIterator for ArgsOs

1.0.0 · Source§

DoubleEndedIterator

Trait DoubleEndedIterator Copy item path

§Examples

Required Methods§

fn next_back(&mut self) -> Option<Self::Item>

§Examples

§Remarks

Provided Methods§

fn next_chunk_back<const N: usize>( &mut self, ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>where Self: Sized,

§Examples

fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero<usize>>

§Examples

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

§Examples

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> Rwhere Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try<Output = B>,

§Examples

fn rfold<B, F>(self, init: B, f: F) -> Bwhere Self: Sized, F: FnMut(B, Self::Item) -> B,

§Examples

fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>where Self: Sized, P: FnMut(&Self::Item) -> bool,

§Examples

Dyn Compatibility§

Implementors§

impl DoubleEndedIterator for Args

impl DoubleEndedIterator for ArgsOs

impl DoubleEndedIterator for rustmax::core::str::Bytes<'_>

impl DoubleEndedIterator for rustmax::anyhow::Chain<'_>

impl DoubleEndedIterator for DateIter

impl DoubleEndedIterator for rustmax::alloc::string::Drain<'_>

impl DoubleEndedIterator for EscapeDefault

impl DoubleEndedIterator for Indices<'_>

impl DoubleEndedIterator for IntermediateIterator<'_>

impl DoubleEndedIterator for IntoChars

impl DoubleEndedIterator for rustmax::serde_json::map::IntoIter

impl DoubleEndedIterator for rustmax::serde_json::map::IntoValues

impl DoubleEndedIterator for IpAddrRange

impl DoubleEndedIterator for Ipv4AddrRange

impl DoubleEndedIterator for Ipv6AddrRange

impl DoubleEndedIterator for NaiveDateDaysIterator

impl DoubleEndedIterator for NaiveDateWeeksIterator

impl DoubleEndedIterator for rustmax::regex::bytes::SetMatchesIntoIter

impl DoubleEndedIterator for rustmax::regex::SetMatchesIntoIter

impl DoubleEndedIterator for ToCasefold

impl DoubleEndedIterator for ToLowercase

impl DoubleEndedIterator for ToTitlecase

impl DoubleEndedIterator for ToUppercase

impl DoubleEndedIterator for TypedComponents<'_>

impl DoubleEndedIterator for TypedIter<'_>

impl DoubleEndedIterator for num_bigint::biguint::iter::U32Digits<'_>

impl DoubleEndedIterator for rustmax::num_bigint::U32Digits<'_>

impl DoubleEndedIterator for num_bigint::biguint::iter::U64Digits<'_>

impl DoubleEndedIterator for rustmax::num_bigint::U64Digits<'_>

impl DoubleEndedIterator for UnixComponents<'_>

impl DoubleEndedIterator for Utf8TypedComponents<'_>

impl DoubleEndedIterator for Utf8TypedIter<'_>

impl DoubleEndedIterator for Utf8UnixComponents<'_>

impl DoubleEndedIterator for Utf8WindowsComponents<'_>

impl DoubleEndedIterator for WindowsComponents<'_>

impl<'a, 'h> DoubleEndedIterator for rustmax::memchr::arch::all::memchr::OneIter<'a, 'h>

impl<'a, 'h> DoubleEndedIterator for rustmax::memchr::arch::x86_64::avx2::memchr::OneIter<'a, 'h>

impl<'a, 'h> DoubleEndedIterator for rustmax::memchr::arch::x86_64::sse2::memchr::OneIter<'a, 'h>

impl<'a, 'h> DoubleEndedIterator for rustmax::memchr::arch::all::memchr::ThreeIter<'a, 'h>

impl<'a, 'h> DoubleEndedIterator for rustmax::memchr::arch::x86_64::avx2::memchr::ThreeIter<'a, 'h>

impl<'a, 'h> DoubleEndedIterator for rustmax::memchr::arch::x86_64::sse2::memchr::ThreeIter<'a, 'h>

impl<'a, 'h> DoubleEndedIterator for rustmax::memchr::arch::all::memchr::TwoIter<'a, 'h>

impl<'a, 'h> DoubleEndedIterator for rustmax::memchr::arch::x86_64::avx2::memchr::TwoIter<'a, 'h>

impl<'a, 'h> DoubleEndedIterator for rustmax::memchr::arch::x86_64::sse2::memchr::TwoIter<'a, 'h>

impl<'a, A> DoubleEndedIterator for rustmax::core::option::Iter<'a, A>

impl<'a, A> DoubleEndedIterator for rustmax::core::option::IterMut<'a, A>

impl<'a, B> DoubleEndedIterator for Blocks<'a, B>where B: BitBlock,

impl<'a, B> DoubleEndedIterator for bit_vec::Iter<'a, B>where B: BitBlock,

impl<'a, B> DoubleEndedIterator for bit_vec::IterMut<'a, B>where B: BitBlock,

impl<'a, I, T, E> DoubleEndedIterator for itertools::process_results_impl::ProcessResults<'a, I, E>where I: Iterator<Item = Result<T, E>> + DoubleEndedIterator,

impl<'a, I, T> DoubleEndedIterator for Cloned<I>where T: 'a + Clone, I: DoubleEndedIterator<Item = &'a T>,

impl<'a, I, T> DoubleEndedIterator for Copied<I>where T: 'a + Copy, I: DoubleEndedIterator<Item = &'a T>,

impl<'a, I> DoubleEndedIterator for &'a mut Iwhere I: DoubleEndedIterator + ?Sized,

impl<'a, K, V> DoubleEndedIterator for phf::map::Entries<'a, K, V>

impl<'a, K, V> DoubleEndedIterator for phf::ordered_map::Entries<'a, K, V>

impl<'a, K, V> DoubleEndedIterator for rustmax::toml::map::Iter<'a, K, V>

impl<'a, K, V> DoubleEndedIterator for rustmax::alloc::collections::btree_map::Iter<'a, K, V>where K: 'a, V: 'a,

impl<'a, K, V> DoubleEndedIterator for rustmax::alloc::collections::btree_map::IterMut<'a, K, V>

Trait DoubleEndedIterator

fn next_chunk_back<const N: usize>( &mut self, ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>
where Self: Sized,

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R
where Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try<Output = B>,

fn rfold<B, F>(self, init: B, f: F) -> B
where Self: Sized, F: FnMut(B, Self::Item) -> B,

fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>
where Self: Sized, P: FnMut(&Self::Item) -> bool,

impl<'a, B> DoubleEndedIterator for Blocks<'a, B>
where B: BitBlock,

impl<'a, B> DoubleEndedIterator for bit_vec::Iter<'a, B>
where B: BitBlock,

impl<'a, B> DoubleEndedIterator for bit_vec::IterMut<'a, B>
where B: BitBlock,

impl<'a, I, T, E> DoubleEndedIterator for itertools::process_results_impl::ProcessResults<'a, I, E>
where I: Iterator<Item = Result<T, E>> + DoubleEndedIterator,

impl<'a, I, T> DoubleEndedIterator for Cloned<I>
where T: 'a + Clone, I: DoubleEndedIterator<Item = &'a T>,

impl<'a, I, T> DoubleEndedIterator for Copied<I>
where T: 'a + Copy, I: DoubleEndedIterator<Item = &'a T>,

impl<'a, I> DoubleEndedIterator for &'a mut I
where I: DoubleEndedIterator + ?Sized,

impl<'a, K, V> DoubleEndedIterator for rustmax::alloc::collections::btree_map::Iter<'a, K, V>
where K: 'a, V: 'a,

impl<'a, P> DoubleEndedIterator for MatchIndices<'a, P>
where P: Pattern, <P as Pattern>::Searcher<'a>: DoubleEndedSearcher<'a>,

impl<'a, P> DoubleEndedIterator for Matches<'a, P>
where P: Pattern, <P as Pattern>::Searcher<'a>: DoubleEndedSearcher<'a>,

impl<'a, P> DoubleEndedIterator for Pixels<'a, P>
where P: Pixel + 'a, <P as Pixel>::Subpixel: 'a,

impl<'a, P> DoubleEndedIterator for PixelsMut<'a, P>
where P: Pixel + 'a, <P as Pixel>::Subpixel: 'a,

impl<'a, P> DoubleEndedIterator for RMatchIndices<'a, P>
where P: Pattern, <P as Pattern>::Searcher<'a>: DoubleEndedSearcher<'a>,

impl<'a, P> DoubleEndedIterator for RMatches<'a, P>
where P: Pattern, <P as Pattern>::Searcher<'a>: DoubleEndedSearcher<'a>,

impl<'a, P> DoubleEndedIterator for rustmax::core::str::RSplit<'a, P>
where P: Pattern, <P as Pattern>::Searcher<'a>: DoubleEndedSearcher<'a>,

impl<'a, P> DoubleEndedIterator for RSplitTerminator<'a, P>
where P: Pattern, <P as Pattern>::Searcher<'a>: DoubleEndedSearcher<'a>,

impl<'a, P> DoubleEndedIterator for Rows<'a, P>
where P: Pixel + 'a, <P as Pixel>::Subpixel: 'a,

impl<'a, P> DoubleEndedIterator for RowsMut<'a, P>
where P: Pixel + 'a, <P as Pixel>::Subpixel: 'a,

impl<'a, P> DoubleEndedIterator for rustmax::core::str::Split<'a, P>
where P: Pattern, <P as Pattern>::Searcher<'a>: DoubleEndedSearcher<'a>,

impl<'a, P> DoubleEndedIterator for rustmax::core::str::SplitInclusive<'a, P>
where P: Pattern, <P as Pattern>::Searcher<'a>: DoubleEndedSearcher<'a>,

impl<'a, P> DoubleEndedIterator for SplitTerminator<'a, P>
where P: Pattern, <P as Pattern>::Searcher<'a>: DoubleEndedSearcher<'a>,

impl<'a, T, P> DoubleEndedIterator for ChunkBy<'a, T, P>
where T: 'a, P: FnMut(&T, &T) -> bool,

impl<'a, T, P> DoubleEndedIterator for ChunkByMut<'a, T, P>
where T: 'a, P: FnMut(&T, &T) -> bool,

impl<'a, T, P> DoubleEndedIterator for rustmax::core::slice::RSplit<'a, T, P>
where P: FnMut(&T) -> bool,

impl<'a, T, P> DoubleEndedIterator for RSplitMut<'a, T, P>
where P: FnMut(&T) -> bool,

impl<'a, T, P> DoubleEndedIterator for rustmax::core::slice::Split<'a, T, P>
where P: FnMut(&T) -> bool,

impl<'a, T, P> DoubleEndedIterator for rustmax::core::slice::SplitInclusive<'a, T, P>
where P: FnMut(&T) -> bool,

impl<'a, T, P> DoubleEndedIterator for SplitInclusiveMut<'a, T, P>
where P: FnMut(&T) -> bool,

impl<'a, T, P> DoubleEndedIterator for SplitMut<'a, T, P>
where P: FnMut(&T) -> bool,

impl<'a, T, const CAP: usize> DoubleEndedIterator for arrayvec::arrayvec::Drain<'a, T, CAP>
where T: 'a,

impl<'a, T> DoubleEndedIterator for ArrayVecDrain<'a, T>
where T: 'a + Default,

impl<'a, T> DoubleEndedIterator for smallvec::Drain<'a, T>
where T: 'a + Array,

impl<'a, T> DoubleEndedIterator for typed_path::common::non_utf8::iter::Iter<'a, T>
where T: for<'enc> Encoding + 'a,