rust Iterator combinator

Iterator中文翻译是迭代器，顾名思义，迭代器肯定记录了当前的迭代位置。
Iterator是我最喜欢的rust结构之一，因为它实现了很多方法，这些方法是可以相互组合的，大大减轻了开发者的工作量。

trait

Iterator

pub trait Iterator {
	/// The type of the elements being iterated over.
	type Item;
	
	/// Advances the iterator and returns the next value.
	fn next(&mut self) -> Option<Self::Item>;
}

FromIterator

FromIterator的作用是将iterator转换为具体类型，标准库中许多类型都实现了，FromIterator，常用的有String，Vec和HashMap

pub trait FromIterator<A>: Sized {
	/// Creates a value from an iterator.
	fn from_iter<T: IntoIterator<Item = A>>(iter: T) -> Self;
}

IntoIterator

有from就有to，IntoIterator的作用是将具体类型转化为Iterator，标准库中同样也有许多类型实现了IntoIterator。

pub trait IntoIterator {
    /// The type of the elements being iterated over.
    #[stable(feature = "rust1", since = "1.0.0")]
    type Item;

    /// Which kind of iterator are we turning this into?
    #[stable(feature = "rust1", since = "1.0.0")]
    type IntoIter: Iterator<Item = Self::Item>;

	/// Creates an iterator from a value.
	fn into_iter(self) -> Self::IntoIter;
}

所有的实现了Iterator的类型自动实现了IntoIterator。

impl<I: Iterator> IntoIterator for I {
    type Item = I::Item;
    type IntoIter = I;

    fn into_iter(self) -> I {
        self
    }
}

方法

map

map方法的作用是将每个Item传入到闭包执行。需要注意的是，map方法仅仅创建了Map，是惰性(lazy)的，需要调用next方法或者collect方法才能执行。

由于Map也实现了Iterator，所以可以继续调用Iterator的方法，将其组合起来。

fn map<B, F>(self, f: F) -> Map<Self, F>
where
    Self: Sized,
    F: FnMut(Self::Item) -> B,
{
    Map::new(self, f)
}

pub struct Map<I, F> {
    iter: I,
    f: F,
}

impl<B, I: Iterator, F> Iterator for Map<I, F>
where
    F: FnMut(I::Item) -> B
{
    type Item = B;

    #[inline]
    fn next(&mut self) -> Option<B> {
        self.iter.next().map(&mut self.f)
    }
}

flatten

flatten的作用是将1个Item是Iterator<Item = B> 的 Iterator展开，变成1个大号的Iterator<Item = B>。

fn flatten(self) -> Flatten<Self>
where
    Self: Sized,
    Self::Item: IntoIterator,
{
    Flatten::new(self)
}

flat_map

flat_map就是map和flatten的合体。

fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F>
where
    Self: Sized,
    U: IntoIterator,
    F: FnMut(Self::Item) -> U,
{
    FlatMap::new(self, f)
}

filter

同理，filter方法创建了Filter，filter_map方法创建了FilterMap，Filter和FilterMap都实现了Iterator，调用next方法，就会迭代到下一个符合过滤条件的位置。
区别是filter的过滤条件闭包的返回值是bool，filter_map是Option。

fn filter<P>(self, predicate: P) -> Filter<Self, P>
where
    Self: Sized,
    P: FnMut(&Self::Item) -> bool,
{
    Filter::new(self, predicate)
}

fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F>
where
    Self: Sized,
    F: FnMut(Self::Item) -> Option<B>,
{
    FilterMap::new(self, f)
}

fuse

fuse方法的作用是，确保Iterator.next()方法一旦返回None，后续调用都是返回None。

fn fuse(self) -> Fuse<Self>
where
    Self: Sized,
{
    Fuse::new(self)
}

tips：
这在异步编程中尤为常见，futures库中select! 要求执行的future必须是FusedFuture，Fuse包裹的Future实现了FusedFuture。

impl<Fut: Future> FusedFuture for Fuse<Fut> {
    fn is_terminated(&self) -> bool {
        self.inner.is_none()
    }
}

collect

collect方法的作用是将Iterator转化为具体类型，该类型必须实现FromIterator。

fn collect<B: FromIterator<Self::Item>>(self) -> B
where
    Self: Sized,
{
    FromIterator::from_iter(self)
}