Trait Iterator

pub trait Iterator {
    type Item<'a>
       where Self: 'a;

    // Required method
    fn next(&mut self) -> Option<Self::Item<'_>>;

    // Provided methods
    fn size_hint(&self) -> (usize, Option<usize>) { ... }
    fn advance_by(&mut self, n: usize) -> Result<(), usize> { ... }
    fn nth(&mut self, n: usize) -> Option<Self::Item<'_>> { ... }
    fn map<O, F>(self, f: F) -> Map<Self, F> 
       where Self: Sized,
             F: FnMut(Self::Item<'_>) -> O { ... }
    fn touch<F>(self, f: F) -> Touch<Self, F>
       where Self: Sized,
             F: FnMut(&mut Self::Item<'_>) { ... }
    fn filter<F>(self, f: F) -> Filter<Self, F>
       where Self: Sized,
             F: FnMut(&Self::Item<'_>) -> bool { ... }
    fn step_by(self, step: usize) -> StepBy<Self>
       where Self: Sized { ... }
    fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter>
       where Self: Sized,
             U: IntoIterator,
             U::IntoIter: for<'a> Iterator<Item<'a> = Self::Item<'a>> { ... }
    fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter>
       where Self: Sized,
             U: IntoIterator { ... }
    fn enumerate(self) -> Enumerate<Self>
       where Self: Sized { ... }
    fn skip_while<F>(self, f: F) -> SkipWhile<Self, F>
       where Self: Sized,
             F: FnMut(&Self::Item<'_>) -> bool { ... }
    fn take_while<F>(self, f: F) -> TakeWhile<Self, F>
       where Self: Sized,
             F: FnMut(&Self::Item<'_>) -> bool { ... }
    fn skip(self, n: usize) -> Skip<Self>
       where Self: Sized { ... }
    fn take(self, n: usize) -> Take<Self>
       where Self: Sized { ... }
    fn all<F>(&mut self, f: F) -> bool
       where F: FnMut(Self::Item<'_>) -> bool { ... }
    fn any<F>(&mut self, f: F) -> bool
       where F: FnMut(Self::Item<'_>) -> bool { ... }
    fn find<F>(&mut self, f: F) -> Option<Self::Item<'_>>
       where F: FnMut(&Self::Item<'_>) -> bool { ... }
    fn count(self) -> usize
       where Self: Sized { ... }
    fn for_each<F>(self, f: F)
       where Self: Sized,
             F: FnMut(Self::Item<'_>) { ... }
    fn fold<T, F>(self, acc: T, f: F) -> T
       where Self: Sized,
             F: FnMut(T, Self::Item<'_>) -> T { ... }
    fn scan<T, B, F>(self, acc: T, f: F) -> Scan<Self, T, F> 
       where Self: Sized,
             F: FnMut(&mut T, Self::Item<'_>) -> Option<B> { ... }
}

A lending iterator, whose items may have their lifetimes tied to the individual borrow of the iterator. This allows for things like yielding mutable references that overlap, with the trade-off that there’s no generic collect interface - the items of this iterator cannot co-exist.

Required Associated Types

type Item<'a> where Self: 'a

The value yielded by each call to next on this iterator

Required Methods

fn next(&mut self) -> Option<Self::Item<'_>>

Get the next value of this iterator, or return None

Provided Methods

fn size_hint(&self) -> (usize, Option<usize>)

Get a hint as to the size of this iterator - the first value is a lower bound, second is an optional upper bound.

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

Advance the iterator by n elements

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

Return the nth element of the iterator

This does not rewind the iterator after completion, so repeatedly calling nth(0) is equivalent to calling next

fn map<O, F>(self, f: F) -> Map<Self, F>

where Self: Sized, F: FnMut(Self::Item<'_>) -> O,

Take a closure which will take each value from the iterator, and yield a new value computed from it.

The result cannot reference the provided data, as such, this returns an iterator which also implements the non-lending core iterator

fn touch<F>(self, f: F) -> Touch<Self, F>

where Self: Sized, F: FnMut(&mut Self::Item<'_>),

Gain mutable access to each value in this iterator, then yield it to the next step. This allows altering each item without consuming it, preserving the lending nature or the iterator

Examples found in repository

examples/iter.rs (lines 30-32)

fn main() {
    let iter: Custom = Custom::new();

    iter.touch(|val| {
        **val += 1;
    })
    .for_each(|val| println!("{}", *val));
}

fn filter<F>(self, f: F) -> Filter<Self, F>

where Self: Sized, F: FnMut(&Self::Item<'_>) -> bool,

Execute a closure on each item in the iterator, returning true if it should be included, or false to skip it

fn step_by(self, step: usize) -> StepBy<Self>

where Self: Sized,

Creates an iterator starting at the same point, but stepping by the given amount at each iteration

fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter>

where Self: Sized, U: IntoIterator, U::IntoIter: for<'a> Iterator<Item<'a> = Self::Item<'a>>,

Takes two iterators and creates a new iterator over both in sequence

fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter>

where Self: Sized, U: IntoIterator,

‘Zips up’ two iterators into a single iterator of pairs

fn enumerate(self) -> Enumerate<Self>

where Self: Sized,

Creates an iterator which gives the current iteration count as well as the next value

fn skip_while<F>(self, f: F) -> SkipWhile<Self, F>

where Self: Sized, F: FnMut(&Self::Item<'_>) -> bool,

Creates an iterator that skips elements based on a predicate

fn take_while<F>(self, f: F) -> TakeWhile<Self, F>

where Self: Sized, F: FnMut(&Self::Item<'_>) -> bool,

Creates an iterator that yields elements based on a predicate

fn skip(self, n: usize) -> Skip<Self>

where Self: Sized,

Creates an iterator that skips the first n elements

fn take(self, n: usize) -> Take<Self>

where Self: Sized,

Creates an iterator that yields the first n elements, or fewer if the underlying iterator ends sooner

fn all<F>(&mut self, f: F) -> bool

where F: FnMut(Self::Item<'_>) -> bool,

Tests if every element of the iterator matches a predicate

fn any<F>(&mut self, f: F) -> bool

where F: FnMut(Self::Item<'_>) -> bool,

Tests if any element of the iterator matches a predicate

fn find<F>(&mut self, f: F) -> Option<Self::Item<'_>>

where F: FnMut(&Self::Item<'_>) -> bool,

Searches for an element of an iterator that satisfies a predicate

fn count(self) -> usize

where Self: Sized,

Consume the iterator, counting the number of items and returning it

fn for_each<F>(self, f: F)

where Self: Sized, F: FnMut(Self::Item<'_>),

Execute a closure on each value of this iterator

Examples found in repository

examples/iter.rs (line 33)

fn main() {
    let iter: Custom = Custom::new();

    iter.touch(|val| {
        **val += 1;
    })
    .for_each(|val| println!("{}", *val));
}

fn fold<T, F>(self, acc: T, f: F) -> T

where Self: Sized, F: FnMut(T, Self::Item<'_>) -> T,

Execute a closure on each value of this iterator, with an additional ‘accumulator’ value passed to each call. The closure is expected to return the new value of the accumulator.

fn scan<T, B, F>(self, acc: T, f: F) -> Scan<Self, T, F>

where Self: Sized, F: FnMut(&mut T, Self::Item<'_>) -> Option<B>,

Execute a closure on each value of this iterator, with an additional state value passed via mutable reference to each call. The closure is expected to return the new value for each step of the iterator, if the returned value is None the iterator stops early.

The result cannot reference the provided data, as such, this returns an iterator which also implements the non-lending core iterator

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'b, I1, I2> Iterator for Chain<I1, I2>

where I1: Iterator + 'b, I2: Iterator<Item<'b> = I1::Item<'b>> + 'b,

type Item<'a> = <I1 as Iterator>::Item<'a> where Self: 'a

impl<I1, I2> Iterator for Zip<I1, I2>

where I1: Iterator, I2: Iterator,

type Item<'a> = (<I1 as Iterator>::Item<'a>, <I2 as Iterator>::Item<'a>) where Self: 'a

impl<I> Iterator for Enumerate<I>

where I: Iterator,

type Item<'a> = (usize, <I as Iterator>::Item<'a>) where Self: 'a

impl<I> Iterator for FromCore<I>

where I: Iterator,

type Item<'a> = <I as Iterator>::Item where Self: 'a

impl<I> Iterator for Skip<I>

where I: Iterator,

type Item<'a> = <I as Iterator>::Item<'a> where Self: 'a

impl<I> Iterator for StepBy<I>

where I: Iterator,

type Item<'a> = <I as Iterator>::Item<'a> where Self: 'a

impl<I> Iterator for Take<I>

where I: Iterator,

type Item<'a> = <I as Iterator>::Item<'a> where Self: 'a

impl<I, F> Iterator for Filter<I, F>

where I: Iterator, F: FnMut(&I::Item<'_>) -> bool,

type Item<'a> = <I as Iterator>::Item<'a> where Self: 'a

impl<I, F> Iterator for SkipWhile<I, F>

where I: Iterator, F: FnMut(&I::Item<'_>) -> bool,

type Item<'a> = <I as Iterator>::Item<'a> where Self: 'a

impl<I, F> Iterator for TakeWhile<I, F>

where I: Iterator, F: FnMut(&I::Item<'_>) -> bool,

type Item<'a> = <I as Iterator>::Item<'a> where Self: 'a

impl<I, F> Iterator for Touch<I, F>

where I: Iterator, F: FnMut(&mut I::Item<'_>),

type Item<'a> = <I as Iterator>::Item<'a> where Self: 'a