Module std::iter

Iteration: the Iterator pull trait, its adaptors and consumers, and integer ranges.

Items are copied values, never borrows of the collection. A collection's iterator holds a loan of it while the iterator lives. All arithmetic here wraps, so iteration needs no capability.

Source: std/iter.weir; committed interface: std/iter.iface. Index

trait Iterator

pub trait Iterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
    fn map<B, F: Fn(Self::Item) -> B>(self, f: F) -> Map<Self, F> {
        Map { inner: self, f }
    }
    fn filter<P: Fn(&Self::Item) -> Bool>(self, p: P) -> Filter<Self, P> {
        Filter { inner: self, p }
    }
    fn enumerate(self) -> Enumerate<Self> {
        Enumerate { inner: self, i: 0usize }
    }
    fn zip<J: Iterator>(self, other: J) -> Zip<Self, J> {
        Zip { a: self, b: other }
    }
    fn take(self, n: usize) -> Take<Self> {
        Take { inner: self, left: n }
    }
    fn skip(self, n: usize) -> Skip<Self> {
        Skip { inner: self, n }
    }
    fn chain<J: Iterator<Item = Self::Item>>(self, other: J) -> Chain<Self, J> {
        Chain { a: self, b: other, first: true }
    }
    fn take_while<P: Fn(&Self::Item) -> Bool>(self, p: P) -> TakeWhile<Self, P> {
        TakeWhile { inner: self, p, done: false }
    }
    fn skip_while<P: Fn(&Self::Item) -> Bool>(self, p: P) -> SkipWhile<Self, P> {
        SkipWhile { inner: self, p, skipping: true }
    }
    fn step_by(self, n: usize) -> StepBy<Self> requires 0usize < n {
        StepBy { inner: self, gap: n -% 1usize, first: true }
    }
    fn fold<B, F: Fn(&mut B, Self::Item)>(self, init: B, f: F) -> B {
        let acc = init;
        loop {
            match self.next() {
                Some(x) => f.call(&mut acc, x),
                None => { return acc },
            }
        }
    }
    fn count(self) -> usize where Self::Item: forget {
        let n = 0usize;
        loop {
            match self.next() {
                Some(x) => { n = n +% 1usize },
                None => { return n },
            }
        }
    }
    fn any<P: Fn(Self::Item) -> Bool>(self, p: P) -> Bool {
        loop {
            match self.next() {
                Some(x) => { if p.call(x) { return true } },
                None => { return false },
            }
        }
    }
    fn all<P: Fn(Self::Item) -> Bool>(self, p: P) -> Bool {
        loop {
            match self.next() {
                Some(x) => { if !p.call(x) { return false } },
                None => { return true },
            }
        }
    }
    fn min(self) -> Option<Self::Item> where Self::Item: Ord + forget {
        let best = match self.next() {
            Some(x) => x,
            None => { return None },
        };
        loop {
            match self.next() {
                Some(x) => match x.cmp(&best) {
                    Less => { best = x },
                    Equal | Greater => {},
                },
                None => { return Some(best) },
            }
        }
    }
    fn max(self) -> Option<Self::Item> where Self::Item: Ord + forget {
        let best = match self.next() {
            Some(x) => x,
            None => { return None },
        };
        loop {
            match self.next() {
                Some(x) => match x.cmp(&best) {
                    Less => {},
                    Equal | Greater => { best = x },
                },
                None => { return Some(best) },
            }
        }
    }
    fn find<P: Fn(&Self::Item) -> Bool>(self, p: P) -> Option<Self::Item> where Self::Item: forget {
        loop {
            match self.next() {
                Some(x) => { if p.call(&x) { return Some(x) } },
                None => { return None },
            }
        }
    }
    fn position<P: Fn(Self::Item) -> Bool>(self, p: P) -> Option<usize> {
        let i = 0usize;
        loop {
            match self.next() {
                Some(x) => { if p.call(x) { return Some(i) } },
                None => { return None },
            };
            i = i +% 1usize
        }
    }
    fn last(self) -> Option<Self::Item> where Self::Item: forget {
        let last = None;
        loop {
            match self.next() {
                Some(x) => { last = Some(x) },
                None => { return last },
            }
        }
    }
    fn nth(self, n: usize) -> Option<Self::Item> where Self::Item: forget {
        let left = n;
        loop {
            match self.next() {
                Some(x) => { if left == 0usize { return Some(x) } },
                None => { return None },
            };
            left = left -% 1usize
        }
    }
    fn for_each<F: Fn(Self::Item)>(self, f: F) {
        loop {
            match self.next() {
                Some(x) => f.call(x),
                None => { return },
            }
        }
    }
    fn sum(self) -> Self::Item where Self::Item: Sum + copy {
        let s = Self::Item::zero();
        loop {
            match self.next() {
                Some(x) => { s = s.plus(x) },
                None => { return s },
            }
        }
    }
    fn collect(self) -> Buf<Self::Item> with Alloc {alloc: tail} where Self::Item: copy {
        let b: Buf<Self::Item> = Buf::new();
        loop {
            match self.next() {
                Some(x) => b.push(x),
                None => { return b },
            }
        }
    }
}

A source of items pulled one at a time; for x in it loops until next returns None. Adaptors and consumers take the iterator by value.

Implementations:

method next

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

Pulls the next item, or None once the iterator is exhausted.

struct Map

pub struct Map<I, F> {
    /* private fields */
}

The iterator map returns: each item passed through the closure.

struct Filter

pub struct Filter<I, P> {
    /* private fields */
}

The iterator filter returns: the items the predicate accepts, others dropped.

struct Enumerate

pub struct Enumerate<I> {
    /* private fields */
}

The iterator enumerate returns: each item paired with its index from 0, as (index, item).

struct Zip

pub struct Zip<A, B> {
    /* private fields */
}

The iterator zip returns: items of both sources pulled in step, ending with the shorter.

struct Take

pub struct Take<I> {
    /* private fields */
}

The iterator take returns: at most the first n items.

struct Skip

pub struct Skip<I> {
    /* private fields */
}

The iterator skip returns: all items after the first n, which it drops at the first pull.

struct Chain

pub struct Chain<A, B> {
    /* private fields */
}

The iterator chain returns: the first source's items, then the second's.

struct TakeWhile

pub struct TakeWhile<I, P> {
    /* private fields */
}

The iterator take_while returns: the items before the first the predicate rejects.

struct SkipWhile

pub struct SkipWhile<I, P> {
    /* private fields */
}

The iterator skip_while returns: the items from the first the predicate rejects on.

struct StepBy

pub struct StepBy<I> {
    /* private fields */
}

The iterator step_by returns: the first item, then every nth after it.

trait Sum

pub trait Sum {
    fn zero() -> Self;
    fn plus(self, o: Self) -> Self;
}

Integer types sum can add; addition wraps.

Implementations:

method zero

fn zero() -> Self;

The sum of no items.

method plus

fn plus(self, o: Self) -> Self;

self + o, wrapping on overflow.

trait Step

pub trait Step {
    fn before(&self, o: &Self) -> Bool;
    fn succ(self) -> Self;
}

Integer types a range steps over.

Implementations:

method before

fn before(&self, o: &Self) -> Bool;

Whether self is less than o.

method succ

fn succ(self) -> Self;

The next value, self + 1; ranges call it only below their end, so it never wraps.

struct Range

pub struct Range<T: copy>: copy {
    pub start: T,
    pub end: T,
}

The half-open range start..end: a copy value, not an iterator; iter makes one, any number of times.

Fields:

impl<T: Step + copy> Range<T>

method iter

pub fn iter(self) -> RangeIter<T>

An iterator from start up to, not including, end.

Committed interface (std/iter.iface):

bound Step: std::iter::Step<T> any row {Diverge}

struct RangeInclusive

pub struct RangeInclusive<T: copy>: copy {
    pub start: T,
    pub end: T,
}

The closed range start..=end: a copy value; iter makes an iterator.

Fields:

impl<T: Step + copy> RangeInclusive<T>

method iter

pub fn iter(self) -> RangeInclusiveIter<T>

An iterator from start through end.

Committed interface (std/iter.iface):

bound Step: std::iter::Step<T> any row {Diverge}

fn range

pub fn range<T: copy>(start: T, end: T) -> Range<T>

The range start..end, as written a..b.

Committed interface (std/iter.iface): the signature alone.

fn range_inclusive

pub fn range_inclusive<T: copy>(start: T, end: T) -> RangeInclusive<T>

The range start..=end, as written a..=b.

Committed interface (std/iter.iface): the signature alone.

struct RangeIter

pub struct RangeIter<T: copy> {
    /* private fields */
}

The iterator over a Range: start up to, not including, end; empty if end is not above start.

struct RangeInclusiveIter

pub struct RangeInclusiveIter<T: copy> {
    /* private fields */
}

The iterator over a RangeInclusive: start through end, which may be the type's maximum.