404

[giscus[bot]]

404

https://course.rs/pitfalls/stack-overflow.html

[blkcor]

哈喽有人吗

[litingyes]

不知道

[pussyWang]

咋404了

[belonace]

哦可以

[leozhang007]

为什么 404 了？

[stevenkitter]

rustup doc
后找到The Standard Library就行了

[liwuhou]

这是还没写吧

[YongxinCao12138]

写的非常精彩醍醐灌顶

[YongxinCao12138]

狗头

[iamtaojin]

404

[ZiYouPunk]

路过

[zmgCoder]

依旧是404

[bcdax110]

这里讲的真的精彩 滑稽.png

[Pro741]

看来作者还没写, 贴一个前一阵子看迭代器源码的笔记, 给大家做参考

---

Iterator Tricks

Iterator 是一个特征, 用来实现迭代器. 这些特征很多常用库都会用到, 并且特质基本相同, 因此直接整理该特征是很有必要的.

迭代器定义

关联1个类型: Item, 代指迭代器内元素的类型

pub trait Iterator {
    /// The type of the elements being iterated over.
    type Item;

迭代器方法

注: 方法名带()的表示不需要其他传参, 而方法名不带()表示或多或少需要传参.

&mut 类方法

==可变迭代器==: 这类方法需要迭代器是可变的(mut). 方法调用完毕后, 原变量(迭代器)可用

next()

Advances the iterator and returns the next value. Returns [None] when iteration is finished.

Individual iterator implementations may choose to resume iteration, and so calling next() again may or may not eventually start returning [Some(Item)] again at some point.

迭代器前进, 然后返回该值. 如果迭代器用完则返回None

每个特定迭代器的实现可选则重利用迭代器(循环迭代器), 再次调用next方法可能还会再次返回 [Some(Item)]

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

切片/array等的实现

这些内置类型基本实现了迭代器特征的所有方法, 但查源代码似乎没有看到 impl Iterator for Type的字样, 实际上这些代码是利用 宏命令 (macros) 批处理实现的!
其余的类同

iterator! {struct Iter -> *const T, &'a T, const, {/* no mut */}, as_ref, {
    fn is_sorted_by<F>(self, mut compare: F) -> bool
    where
        Self: Sized,
        F: FnMut(&Self::Item, &Self::Item) -> Option<Ordering>,
    {
        self.as_slice().is_sorted_by(|a, b| compare(&a, &b))
    }
}}

来源: slice下的iter.rs文件

// The shared definition of the `Iter` and `IterMut` iterators
macro_rules! iterator {
    (
        struct $name:ident -> $ptr:ty,
        $elem:ty,
        $raw_mut:tt,
        {$( $mut_:tt )?},
        $into_ref:ident,
        {$($extra:tt)*}
    ) => {
        // Returns the first element and moves the start of the iterator forwards by 1.
        // Greatly improves performance compared to an inlined function. The iterator
        // must not be empty.
        macro_rules! next_unchecked {
            ($self: ident) => { $self.post_inc_start(1).$into_ref() }
        }

        // Returns the last element and moves the end of the iterator backwards by 1.
        // Greatly improves performance compared to an inlined function. The iterator
        // must not be empty.
        macro_rules! next_back_unchecked {
            ($self: ident) => { $self.pre_dec_end(1).$into_ref() }
        }

        impl<'a, T> $name<'a, T> {
            // Helper function for creating a slice from the iterator.
            #[inline(always)]
            fn make_slice(&self) -> &'a [T] {
                // SAFETY: the iterator was created from a slice with pointer
                // `self.ptr` and length `len!(self)`. This guarantees that all
                // the prerequisites for `from_raw_parts` are fulfilled.
                unsafe { from_raw_parts(self.ptr.as_ptr(), len!(self)) }
            }

            // Helper function for moving the start of the iterator forwards by `offset` elements,
            // returning the old start.
            // Unsafe because the offset must not exceed `self.len()`.
            #[inline(always)]
            unsafe fn post_inc_start(&mut self, offset: usize) -> NonNull<T> {
                let old = self.ptr;

                // SAFETY: the caller guarantees that `offset` doesn't exceed `self.len()`,
                // so this new pointer is inside `self` and thus guaranteed to be non-null.
                unsafe {
                    if_zst!(mut self,
                        len => *len = len.unchecked_sub(offset),
                        _end => self.ptr = self.ptr.add(offset),
                    );
                }
                old
            }

            // Helper function for moving the end of the iterator backwards by `offset` elements,
            // returning the new end.
            // Unsafe because the offset must not exceed `self.len()`.
            #[inline(always)]
            unsafe fn pre_dec_end(&mut self, offset: usize) -> NonNull<T> {
                if_zst!(mut self,
                    // SAFETY: By our precondition, `offset` can be at most the
                    // current length, so the subtraction can never overflow.
                    len => unsafe {
                        *len = len.unchecked_sub(offset);
                        self.ptr
                    },
                    // SAFETY: the caller guarantees that `offset` doesn't exceed `self.len()`,
                    // which is guaranteed to not overflow an `isize`. Also, the resulting pointer
                    // is in bounds of `slice`, which fulfills the other requirements for `offset`.
                    end => unsafe {
                        *end = end.sub(offset);
                        *end
                    },
                )
            }
        }

        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T> ExactSizeIterator for $name<'_, T> {
            #[inline(always)]
            fn len(&self) -> usize {
                len!(self)
            }

            #[inline(always)]
            fn is_empty(&self) -> bool {
                is_empty!(self)
            }
        }

        #[stable(feature = "rust1", since = "1.0.0")]
        impl<'a, T> Iterator for $name<'a, T> {
            type Item = $elem;

            #[inline]
            fn next(&mut self) -> Option<$elem> {
                // could be implemented with slices, but this avoids bounds checks

                // SAFETY: The call to `next_unchecked!` is
                // safe since we check if the iterator is empty first.
                unsafe {
                    if is_empty!(self) {
                        None
                    } else {
                        Some(next_unchecked!(self))
                    }
                }
            }

            #[inline]
            fn size_hint(&self) -> (usize, Option<usize>) {
                let exact = len!(self);
                (exact, Some(exact))
            }

            #[inline]
            fn count(self) -> usize {
                len!(self)
            }

            #[inline]
            fn nth(&mut self, n: usize) -> Option<$elem> {
                if n >= len!(self) {
                    // This iterator is now empty.
                    if_zst!(mut self,
                        len => *len = 0,
                        end => self.ptr = *end,
                    );
                    return None;
                }
                // SAFETY: We are in bounds. `post_inc_start` does the right thing even for ZSTs.
                unsafe {
                    self.post_inc_start(n);
                    Some(next_unchecked!(self))
                }
            }

            #[inline]
            fn advance_by(&mut self, n: usize) -> Result<(), NonZeroUsize> {
                let advance = cmp::min(len!(self), n);
                // SAFETY: By construction, `advance` does not exceed `self.len()`.
                unsafe { self.post_inc_start(advance) };
                NonZeroUsize::new(n - advance).map_or(Ok(()), Err)
            }

            #[inline]
            fn last(mut self) -> Option<$elem> {
                self.next_back()
            }

            #[inline]
            fn fold<B, F>(self, init: B, mut f: F) -> B
                where
                    F: FnMut(B, Self::Item) -> B,
            {
                // this implementation consists of the following optimizations compared to the
                // default implementation:
                // - do-while loop, as is llvm's preferred loop shape,
                //   see https://releases.llvm.org/16.0.0/docs/LoopTerminology.html#more-canonical-loops
                // - bumps an index instead of a pointer since the latter case inhibits
                //   some optimizations, see #111603
                // - avoids Option wrapping/matching
                if is_empty!(self) {
                    return init;
                }
                let mut acc = init;
                let mut i = 0;
                let len = len!(self);
                loop {
                    // SAFETY: the loop iterates `i in 0..len`, which always is in bounds of
                    // the slice allocation
                    acc = f(acc, unsafe { & $( $mut_ )? *self.ptr.add(i).as_ptr() });
                    // SAFETY: `i` can't overflow since it'll only reach usize::MAX if the
                    // slice had that length, in which case we'll break out of the loop
                    // after the increment
                    i = unsafe { i.unchecked_add(1) };
                    if i == len {
                        break;
                    }
                }
                acc
            }

            // We override the default implementation, which uses `try_fold`,
            // because this simple implementation generates less LLVM IR and is
            // faster to compile.
            #[inline]
            fn for_each<F>(mut self, mut f: F)
            where
                Self: Sized,
                F: FnMut(Self::Item),
            {
                while let Some(x) = self.next() {
                    f(x);
                }
            }

            // We override the default implementation, which uses `try_fold`,
            // because this simple implementation generates less LLVM IR and is
            // faster to compile.
            #[inline]
            fn all<F>(&mut self, mut f: F) -> bool
            where
                Self: Sized,
                F: FnMut(Self::Item) -> bool,
            {
                while let Some(x) = self.next() {
                    if !f(x) {
                        return false;
                    }
                }
                true
            }

            // We override the default implementation, which uses `try_fold`,
            // because this simple implementation generates less LLVM IR and is
            // faster to compile.
            #[inline]
            fn any<F>(&mut self, mut f: F) -> bool
            where
                Self: Sized,
                F: FnMut(Self::Item) -> bool,
            {
                while let Some(x) = self.next() {
                    if f(x) {
                        return true;
                    }
                }
                false
            }

            // We override the default implementation, which uses `try_fold`,
            // because this simple implementation generates less LLVM IR and is
            // faster to compile.
            #[inline]
            fn find<P>(&mut self, mut predicate: P) -> Option<Self::Item>
            where
                Self: Sized,
                P: FnMut(&Self::Item) -> bool,
            {
                while let Some(x) = self.next() {
                    if predicate(&x) {
                        return Some(x);
                    }
                }
                None
            }

            // We override the default implementation, which uses `try_fold`,
            // because this simple implementation generates less LLVM IR and is
            // faster to compile.
            #[inline]
            fn find_map<B, F>(&mut self, mut f: F) -> Option<B>
            where
                Self: Sized,
                F: FnMut(Self::Item) -> Option<B>,
            {
                while let Some(x) = self.next() {
                    if let Some(y) = f(x) {
                        return Some(y);
                    }
                }
                None
            }

            // We override the default implementation, which uses `try_fold`,
            // because this simple implementation generates less LLVM IR and is
            // faster to compile. Also, the `assume` avoids a bounds check.
            #[inline]
            #[rustc_inherit_overflow_checks]
            fn position<P>(&mut self, mut predicate: P) -> Option<usize> where
                Self: Sized,
                P: FnMut(Self::Item) -> bool,
            {
                let n = len!(self);
                let mut i = 0;
                while let Some(x) = self.next() {
                    if predicate(x) {
                        // SAFETY: we are guaranteed to be in bounds by the loop invariant:
                        // when `i >= n`, `self.next()` returns `None` and the loop breaks.
                        unsafe { assume(i < n) };
                        return Some(i);
                    }
                    i += 1;
                }
                None
            }

            // We override the default implementation, which uses `try_fold`,
            // because this simple implementation generates less LLVM IR and is
            // faster to compile. Also, the `assume` avoids a bounds check.
            #[inline]
            fn rposition<P>(&mut self, mut predicate: P) -> Option<usize> where
                P: FnMut(Self::Item) -> bool,
                Self: Sized + ExactSizeIterator + DoubleEndedIterator
            {
                let n = len!(self);
                let mut i = n;
                while let Some(x) = self.next_back() {
                    i -= 1;
                    if predicate(x) {
                        // SAFETY: `i` must be lower than `n` since it starts at `n`
                        // and is only decreasing.
                        unsafe { assume(i < n) };
                        return Some(i);
                    }
                }
                None
            }

            #[inline]
            unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
                // SAFETY: the caller must guarantee that `i` is in bounds of
                // the underlying slice, so `i` cannot overflow an `isize`, and
                // the returned references is guaranteed to refer to an element
                // of the slice and thus guaranteed to be valid.
                //
                // Also note that the caller also guarantees that we're never
                // called with the same index again, and that no other methods
                // that will access this subslice are called, so it is valid
                // for the returned reference to be mutable in the case of
                // `IterMut`
                unsafe { & $( $mut_ )? * self.ptr.as_ptr().add(idx) }
            }

            $($extra)*
        }

        #[stable(feature = "rust1", since = "1.0.0")]
        impl<'a, T> DoubleEndedIterator for $name<'a, T> {
            #[inline]
            fn next_back(&mut self) -> Option<$elem> {
                // could be implemented with slices, but this avoids bounds checks

                // SAFETY: The call to `next_back_unchecked!`
                // is safe since we check if the iterator is empty first.
                unsafe {
                    if is_empty!(self) {
                        None
                    } else {
                        Some(next_back_unchecked!(self))
                    }
                }
            }

            #[inline]
            fn nth_back(&mut self, n: usize) -> Option<$elem> {
                if n >= len!(self) {
                    // This iterator is now empty.
                    if_zst!(mut self,
                        len => *len = 0,
                        end => *end = self.ptr,
                    );
                    return None;
                }
                // SAFETY: We are in bounds. `pre_dec_end` does the right thing even for ZSTs.
                unsafe {
                    self.pre_dec_end(n);
                    Some(next_back_unchecked!(self))
                }
            }

            #[inline]
            fn advance_back_by(&mut self, n: usize) -> Result<(), NonZeroUsize> {
                let advance = cmp::min(len!(self), n);
                // SAFETY: By construction, `advance` does not exceed `self.len()`.
                unsafe { self.pre_dec_end(advance) };
                NonZeroUsize::new(n - advance).map_or(Ok(()), Err)
            }
        }

        #[stable(feature = "fused", since = "1.26.0")]
        impl<T> FusedIterator for $name<'_, T> {}

        #[unstable(feature = "trusted_len", issue = "37572")]
        unsafe impl<T> TrustedLen for $name<'_, T> {}

        impl<'a, T> UncheckedIterator for $name<'a, T> {
            unsafe fn next_unchecked(&mut self) -> $elem {
                // SAFETY: The caller promised there's at least one more item.
                unsafe {
                    next_unchecked!(self)
                }
            }
        }

        #[stable(feature = "default_iters", since = "1.70.0")]
        impl<T> Default for $name<'_, T> {
            /// Creates an empty slice iterator.
            ///
            /// ```
            #[doc = concat!("# use core::slice::", stringify!($name), ";")]
            #[doc = concat!("let iter: ", stringify!($name<'_, u8>), " = Default::default();")]
            /// assert_eq!(iter.len(), 0);
            /// ```
            fn default() -> Self {
                (& $( $mut_ )? []).into_iter()
            }
        }
    }
}

来源: iter下的macros文件.

nth

Returns the nth element of the iterator.

Like most indexing operations, the count starts from zero, so nth(0) returns the first value, nth(1) the second, and so on.

**Note **that all preceding elements, as well as the returned element, will be consumed from the iterator.

也就是说, nth(0) == next()

源代码:

    fn nth(&mut self, n: usize) -> Option<Self::Item> {
        self.advance_by(n).ok()?;
        self.next()
    }

这里的advance_by()是night版方法, 相当于用这个方法跳过前n个值, 如果出现None了提前返回Err(但返回的这个报错信息没赋值给任何变量, 因此即便报错不会又任何显示).

跳过n个值后, self.next()执行, 将第n+1个值返回

例如:

let a = [1, 2, 3];

let mut iter = a.iter();

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

by_ref()

Borrows an iterator, rather than consuming it.

This is useful to allow applying iterator adapters while still retaining ownership of the original iterator.

借用迭代器, 而不是消耗它

    fn by_ref(&mut self) -> &mut Self
    where
        Self: Sized,
    {
        self
    }

示例:

    let mut words = ["hello", "world", "of", "Rust"].into_iter();

    // Take the first two words.
    let hello_world: Vec<_> = words.by_ref().take(2).collect();
    assert_eq!(hello_world, vec!["hello", "world"]);

    // Collect the rest of the words.
    // We can only do this because we used `by_ref` earlier.
    let of_rust: Vec<_> = words.collect();
    assert_eq!(of_rust, vec!["of", "Rust"]);

by_ref 将输入转换为了原迭代器引用, 即使后续take() 方法转移所有权, 由于输入变成了& mut, 原迭代器依然生效. 未遍历到的部分保留.

try_fold

An iterator method that applies a function as long as it returns successfully, producing a single, final value.

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

Note to Implementors:

Several of the other (forward) methods have default implementations in terms of this one, so try to implement this explicitly if it can do something better than the default for loop implementation.

In particular, try to have this call try_fold() on the internal parts from which this iterator is composed. If multiple calls are needed, the ? operator may be convenient for chaining the accumulator value along, but beware any invariants that need to be upheld before those
early returns. This is a &mut self method, so iteration needs to be resumable after hitting an error here.

只要成功返回，就会调用一个闭包，如此循环整个迭代器, 最终产生一个值. 当你想利用迭代器的值来产生一个单个值时, 折叠函数就很有用.

对特征实现者的注意事项:

迭代器 trait 中的多个前向遍历（forward）方法, 例如 sum, product, any 等等, 默认实现时通过 try_fold() 实现的, 因此, 当你定义一个新的迭代器类型时，如果直接实现 try_fold 方法并提供了更高效的逻辑，那么依赖于此的其他方法也将自动受益于这种优化，而不需要分别去覆盖它们的默认实现。

特别注意: 在实现try_fold()方法时, 要尽量用内部的迭代器本身实现的try_fold()方法, 以获得其原有的优化逻辑. 多个调用时善于利用?的传播特性, 但要注意正确使用, ? 当前函数或闭包的返回类型也应该是一个 Result. 也要当心如果有任何必须在“早期返回”（即遇到错误时的返回）之前维持的不变性条件或清理工作，确保这些条件在错误传播前得到恰当处理。最后, 这是一个 &mut self 方法，因此，如果在 try_fold 过程中遇到错误并返回，迭代器的状态应该是可恢复的，即之后还可以从当前位置继续迭代。

==传入参数== init: 初始值, 任意类型

f: 对初始值的迭代闭包函数. 输入是init类型的初始变量和代表迭代器目前迭代元素item的变量. 最终返回一个Try特征下的一种声明类型: B, 例如 Option 或 Result 类型, 以及Poll类型, 如果类型B没有在Try 下声明, 则报错.

    fn try_fold<B, F, R>(&mut self, init: B, mut f: F) -> R
    where
        Self: Sized,
        F: FnMut(B, Self::Item) -> R,
        R: Try<Output = B>,
    {
        let mut accum = init;
        while let Some(x) = self.next() {
            accum = f(accum, x)?;
        }
        try { accum }
    }

示例:

fn main() {
    let a = [10, 20, 30, 100, 40, 50];
    let mut it = a.iter();

    // This sum overflows when adding the 100 element
    let sum = it.try_fold(0i8, |acc, &x| acc.checked_add(x));
    assert_eq!(sum, None);

    // Because it short-circuited, the remaining elements are still
    // available through the iterator.
    assert_eq!(it.len(), 2);
    assert_eq!(it.next(), Some(&40));
}

try_for_each

An iterator method that applies a fallible function to each item in the iterator, stopping at the first error and returning that error.

一个迭代器方法, 成功则返回成功值(Some(_), Ok(_)等等), 如果失败则立即返回失败信息(None, Err(_)等等)

这是一个&mut方法, 不会消耗原迭代器(原迭代器可用), 如果遇到失败情况, 那么原迭代器可以从失败位置下一个值继续使用.(见上一个try_fold的示例)

==传入参数== f: 闭包, 闭包输出必须是 Option , Result 或Poll 之一, 只有实现Try特征的输出类型才能够作为返回值.

    fn try_for_each<F, R>(&mut self, f: F) -> R
    where
        Self: Sized,
        F: FnMut(Self::Item) -> R,
        R: Try<Output = ()>,
    {
        #[inline]
        fn call<T, R>(mut f: impl FnMut(T) -> R) -> impl FnMut((), T) -> R {
            move |(), x| f(x)
        }

        self.try_fold((), call(f))
    }

fold

Folds every element into an accumulator by applying an operation, returning the final result.

fold() 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, fold() 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: fold(), and similar methods that traverse the entire iterator, might not terminate for infinite iterators, even on traits for which a result is determinable in finite time.

Note: [reduce()] can be used to use the first element as the initial value, if the accumulator type and item type is the same.

Note: fold() combines elements in a left-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 right-associative version of fold(), see [DoubleEndedIterator::rfold()].

折叠函数. 通过应用一种操作(闭包), 折叠每个元素到一个累加器中, 返回最终的累加结果.

==传入参数== init: 一个初始值, 类型为B, 用于闭包f的初始化操作

f: 一个闭包, 有两个传参, 第一个参数类型为B, 是个累加器, 第二个参数是迭代器各个元素(item), 最终返回这个累加器累加后的结果B

这个方法有些语言也叫做 reduce 或 inject

在你有个某个类型元素的集合, 然后想用这个集合的元素产生单个值 (例如, 累加所有元素之和, 统计符合某种特征(谓词判断)元素数量等等), 这时候折叠很好用

注意: fold 和其他遍历整个迭代器的方法, 在应用到无限迭代器上时可能不会终止, 这种情况即使在理论上可以根据迭代器产生的规律在有限时间内确定结果的场合（比如某些周期性规律的无限序列），fold() 函数也无法意识到这一点，它会一直尝试获取下一个元素并进行累积操作，从而导致程序陷入无限循环，无法正常结束。因此对无限迭代器使用fold()要小心

注意2: reduce() 方法是fold的一种特殊情况 ①第一个初始元素是迭代器第一个元素, ②累加类型和迭代器元素类型一致

注意3: fold函数的元素的结合方式是以左结合的流行形式实现的, 对于可结合的操作(例如+法), 元素的结合顺序不重要, 但对于不可结合的操作, 类似于-法, 结合的先后顺序会影响最终结果, 另见rfold它从右面开始累加元素, 便于操作那些右结合的情况

    fn fold<B, F>(mut self, init: B, mut f: F) -> B
    where
        Self: Sized,
        F: FnMut(B, Self::Item) -> B,
    {
        let mut accum = init;
        while let Some(x) = self.next() {
            accum = f(accum, x);
        }
        accum
    }

示例:

下面示例展示了左右结合结果不同的例子:

fn main() {

    let numbers = vec![1, 2, 3, 4];
    let sum_left = numbers.iter().fold(0, |acc, x| acc + x);
    // sum_left 结果为 10，无论左右结合，结果不变
    println!("{}", sum_left);

    let difference_left = numbers.iter().skip(1).fold(numbers[0], |acc, x| acc - *x);
    println!("{:?}", difference_left);
    println!("{}", numbers.iter().skip(1).rfold(numbers[3], |acc, x| acc - *x))
}

reduce

Reduces the elements to a single one, by repeatedly applying a reducing operation.

If the iterator is empty, returns [None]; otherwise, returns the result of the reduction.

The reducing function is a closure with two arguments: an 'accumulator', and an element.
For iterators with at least one element, this is the same as [fold()] with the first element of the iterator as the initial accumulator value, folding every subsequent element into it.

reduce. 通过重复应用减少(的闭包)操作, 将元素减到一个值.

如果迭代器为空, 返回None, 否则为Some(_)

减少reduce方法的闭包f和fold的闭包相同, 但初始值变为了迭代器的第一个元素, 累加器也变为了迭代器元素类型, 返回值也加了一层封装Option

底层使用fold实现的

    fn reduce<F>(mut self, f: F) -> Option<Self::Item>
    where
        Self: Sized,
        F: FnMut(Self::Item, Self::Item) -> Self::Item,
    {
        let first = self.next()?;
        Some(self.fold(first, f))
    }

示例:

let reduced: i32 = (1..10).reduce(|acc, e| acc + e).unwrap();
assert_eq!(reduced, 45);

all

Tests if every element of the iterator matches a predicate.

all() is short-circuiting; in other words, it will stop processing as soon as it finds a false, given that no matter what else happens, the result will also be false.

测试是否迭代器的所有元素都符合谓词. 只有所有元素均符合闭包的谓词判断, 才返回true, 否则返回false

all 是短路的, 也就是说, 一旦查询到一个false, 立刻返回结果(迭代器后面的元素不在访问)

规定空迭代器返回true

==传入参数== f: 谓词闭包. 闭包返回true或false

    fn all<F>(&mut self, f: F) -> bool
    where
        Self: Sized,
        F: FnMut(Self::Item) -> bool,
    {
        #[inline]
        fn check<T>(mut f: impl FnMut(T) -> bool) -> impl FnMut((), T) -> ControlFlow<()> {
            move |(), x| {
                if f(x) { ControlFlow::Continue(()) } else { ControlFlow::Break(()) }
            }
        }
        self.try_fold((), check(f)) == ControlFlow::Continue(())
    }

这个源代码怎么理解呢?

首先, try_fold函数声明为:fn try_fold<B, F, R>(&mut self, init: B, mut f: F) -> R

其中f是一个闭包, F: FnMut(B, Self::Item) -> R,, 返回值是关于B的一个Try 特征封装类型:

R: Try<Output = B>

回过头看all方法: self.try_fold((), check(f)) == ControlFlow::Continue(()), 这里制定了:

• B的类型是(), 也就是单元类型

• check() 是一个辅助函数(不是闭包), 它的作用是, 输入一个闭包, 返回一个新闭包: ControlFlow<()>, 而这个返回的新闭包, 满足try_fold的输入要求: F: FnMut(B, Self::Item) -> R,

  这实际上说明了, ControlFlow<()>就是返回的实现了Try特征的单元(())封装:

  impl<B, C> ops::Try for ControlFlow<B, C> {
      type Output = C;
      type Residual = ControlFlow<B, convert::Infallible>;
  
      #[inline]
      fn from_output(output: Self::Output) -> Self {
          ControlFlow::Continue(output)
      }
  
      #[inline]
      fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
          match self {
              ControlFlow::Continue(c) => ControlFlow::Continue(c),
              ControlFlow::Break(b) => ControlFlow::Break(ControlFlow::Break(b)),
          }
      }
  }

• 因此, 每次迭代, 都会把check()返回的闭包返回, 做try_fold的闭包判断, 也就等价于下面代码:

  self.try_fold((), move |(), x| {
      if f(x) {
          ControlFlow::Continue(())
      } else {
          ControlFlow::Break(())
      }
  })})

any

Tests if any element of the iterator matches a predicate.

测试是否有任何一个元素与谓词匹配. 只要有一个匹配, 则立刻返回true,否则(也就是所有元素都不匹配)返回false

==传入参数== f: 谓词闭包. 闭包返回true或false

都是用try_fold实现的, 因此上面try_fold那说如果想改前向方法, 应该直接改try_fold而不是改这些具体的前向函数

    fn any<F>(&mut self, f: F) -> bool
    where
        Self: Sized,
        F: FnMut(Self::Item) -> bool,
    {
        #[inline]
        fn check<T>(mut f: impl FnMut(T) -> bool) -> impl FnMut((), T) -> ControlFlow<()> {
            move |(), x| {
                if f(x) { ControlFlow::Break(()) } else { ControlFlow::Continue(()) }
            }
        }

        self.try_fold((), check(f)) == ControlFlow::Break(())
    }

find

Searches for an element of an iterator that satisfies a predicate.

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

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

查找迭代器中第一个满足谓词的元素. 只要任何一个元素返回true, 那就返回Some(_), 如果所有元素都不满足谓词, 则返回None

find 也是短路的, 也就是说, 一旦闭包返回true 那就直接返回元素, 不再遍历后续值

==传入参数== f: 谓词闭包. 闭包返回true或false

只要有短路, 那么闭包中必然出现了ControlFlow枚举类型.

另外, find(f) 从结果上看, 等价于 filter(f).next()

    fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
    where
        Self: Sized,
        P: FnMut(&Self::Item) -> bool,
    {
        #[inline]
        fn check<T>(mut predicate: impl FnMut(&T) -> bool) -> impl FnMut((), T) -> ControlFlow<T> {
            move |(), x| {
                if predicate(&x) { ControlFlow::Break(x) } else { ControlFlow::Continue(()) }
            }
        }

        self.try_fold((), check(predicate)).break_value()
    }

find_map

Applies function to the elements of iterator and returns the first non-none result.

iter.find_map(f) is equivalent to iter.filter_map(f).next().

对所有元素执行map映射函数, 返回第一个非None的值.

相当于iter.filter_map(f).next().

    fn find_map<B, F>(&mut self, f: F) -> Option<B>
    where
        Self: Sized,
        F: FnMut(Self::Item) -> Option<B>,
    {
        #[inline]
        fn check<T, B>(mut f: impl FnMut(T) -> Option<B>) -> impl FnMut((), T) -> ControlFlow<B> {
            move |(), x| match f(x) {
                Some(x) => ControlFlow::Break(x),
                None => ControlFlow::Continue(()),
            }
        }

        self.try_fold((), check(f)).break_value()
    }

position

Searches for an element in an iterator, returning its index.

position() is short-circuiting; in other words, it will stop processing as soon as it finds a true.

Panics: Overflow Behavior. if there are more than [usize::MAX] non-matching elements, it either produces the wrong result or panics.

和find类似但不同. position返回的是查询到符合谓词元素的索引(usize)

position也是短路的

==输入参数== predicate: 谓词闭包, 返回true或false

    fn position<P>(&mut self, predicate: P) -> Option<usize>
    where
        Self: Sized,
        P: FnMut(Self::Item) -> bool,
    {
        #[inline]
        fn check<'a, T>(
            mut predicate: impl FnMut(T) -> bool + 'a,
            acc: &'a mut usize,
        ) -> impl FnMut((), T) -> ControlFlow<usize, ()> + 'a {
            #[rustc_inherit_overflow_checks]
            move |_, x| {
                if predicate(x) {
                    ControlFlow::Break(*acc)
                } else {
                    *acc += 1;
                    ControlFlow::Continue(())
                }
            }
        }

        let mut acc = 0;
        self.try_fold((), check(predicate, &mut acc)).break_value()
    }

rposition

Searches for an element in an iterator from the right, returning its index.

和position一样, 但是是从右向左查找.

    fn rposition<P>(&mut self, predicate: P) -> Option<usize>
    where
        P: FnMut(Self::Item) -> bool,
        Self: Sized + ExactSizeIterator + DoubleEndedIterator,
    {
        // No need for an overflow check here, because `ExactSizeIterator`
        // implies that the number of elements fits into a `usize`.
        #[inline]
        fn check<T>(
            mut predicate: impl FnMut(T) -> bool,
        ) -> impl FnMut(usize, T) -> ControlFlow<usize, usize> {
            move |i, x| {
                let i = i - 1;
                if predicate(x) { ControlFlow::Break(i) } else { ControlFlow::Continue(i) }
            }
        }

        let n = self.len();
        self.try_rfold(n, check(predicate)).break_value()
    }

& 类方法

==引用迭代器==: 这里方法适用于任何迭代器, 其作用往往是查询.

size_hint()

Returns the bounds on the remaining length of the iterator.

size_hint是一个有关迭代器大小的提示, 查询目前迭代器大小可能是在(usize, Option)之间.

• usize: 迭代器至少还剩多少个元素, 是一个确定的下界
• Option<usize>: 迭代器最多还剩多少个元素, 这是一个可能的上界.
  • A [None] here means that either there is no known upper bound, or the upper bound is larger than [usize].

NOTE: It is not enforced that an iterator implementation yields the declared number of elements. A buggy iterator may yield less than the lower bound or more than the upper bound of elements.

size_hint() is primarily intended to be used for optimizations such as reserving space for the elements of the iterator, but must not be trusted to e.g., omit bounds checks in unsafe code. An incorrect implementation of size_hint() should not lead to memory safety violations.

size_hint() 的主要目的是提供一种优化手段，而不是严格的长度保证。在设计算法时，应灵活处理这些提示信息。

    fn size_hint(&self) -> (usize, Option<usize>) {
        (0, None)  // 默认实现是对所有迭代器都适用的0到无穷大
    }

例如:

fn main() {
    let mut iter = (0..10).filter(|x| x % 2 == 0).chain(15..20);
    println!("{:?}", iter.size_hint());

    for _ in 0..10 {
        iter.next();
        println!("{:?}", iter.size_hint());
    }
}
/*
结果为: 
(5, Some(15))		(5, Some(14))
(5, Some(12))		(5, Some(10))
(5, Some(8))		(5, Some(6)) 
(4, Some(4))		(3, Some(3))
(2, Some(2))		(1, Some(1))
(0, Some(0))
*/

这里说明一下, Filter结构的迭代器实现的size_hint()默认为(0, Option(len)), 也就是要么一个也不过滤, 迭代器大小为原迭代器长度(len), 要么全过滤了, 迭代器大小为0.

chain()的作用是拼接两个迭代器, 上一个迭代器(这里是Filter)用完, 那么下一个迭代器(这里是15..20)开始迭代.

因此, 最开始, (0..10).filter(|x| x % 2 == 0)这块迭代器长度是(0, 10), 后面又拼接了一个确定长度的迭代器Chain, 是(5, 5). 因此整个迭代器长度给到(5, 15).

经过迭代, 上界一步步变小, 当Filter用尽后, 开始使用Chain的固定迭代器, 上下界同时减少.

self 类方法

==消耗迭代器==: 这类迭代器会消耗掉原本的迭代器, 也就是说, 这些方法的调用会直接转移迭代器的所有权, 方法调用立即使原迭代器失效.

但实际上, 这对迭代器的影像不大. 因为迭代器一般是懒惰的, 虽然迭代器转移了所有权, 但实际上并没有真正遍历整个迭代器的值, 每当next()等& mut self 方法得到调用时, 迭代器才会真正使用, 这时, 这些self类的消耗迭代器才开始进行运算.

count()

Consumes the iterator, counting the number of iterations and returning it.

    fn count(self) -> usize
    where
        Self: Sized,
    {
        self.fold(
            0,
            #[rustc_inherit_overflow_checks]
            |count, _| count + 1,
        )
    }

last()

Consumes the iterator, returning the last element.

    fn last(self) -> Option<Self::Item>
    where
        Self: Sized,
    {
        #[inline]
        fn some<T>(_: Option<T>, x: T) -> Option<T> {
            Some(x)
        }

        self.fold(None, some)
    }

step_by

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

step_by()方法将原迭代器转变为一个StepBy结构的步进迭代器, 步长是 step, step==1时, 相当于没有跳过.

==输入参数== step: usize 步长, 步长不能为0

    fn step_by(self, step: usize) -> StepBy<Self>
    where
        Self: Sized,
    {
        StepBy::new(self, step)
    }

例如

    let a = [0, 1, 2, 3, 4, 5];
    let mut iter = a.iter().step_by(2);

    assert_eq!(iter.next(), Some(&0));
    assert_eq!(iter.next(), Some(&2));
    assert_eq!(iter.next(), Some(&4));
    assert_eq!(iter.next(), None);

也就是说, 步长迭代器的第一个元素总是原迭代器第一个元素, 如果也迭代器有筛选, 可能会更快地消耗迭代器, 这和如何实现这个特征有关

chain

Takes two iterators and creates a new iterator over both in sequence. In other words, it links two iterators together, in a chain. 🔗

链接两个迭代器. 原迭代器消耗, 生成一个新迭代器Chain. 当前一个迭代器消耗完毕, 后一个迭代器other无缝续接.

==传入参数== other: 必须实现IntoIterator特征. 也就是说, 传的参实现了可转换迭代器这个特征即可, 未必是真正的迭代器(如切片 &[T])

    fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter>
    where
        Self: Sized,
        U: IntoIterator<Item = Self::Item>,
    {
        Chain::new(self, other.into_iter())
    }

zip

'Zips up' two iterators into a single iterator of pairs.

zip() returns a new iterator that will iterate over two other iterators, returning a tuple where the first element comes from the first iterator, and the second element comes from the second iterator.

将两个迭代器打包成一个Zip迭代器. 这个Zip迭代器会以(iter1.next(), iter2.next()) 这样的元组形式返回, 当任意一个迭代器消耗殆尽, Zip也将耗尽, 返回None

==传入参数== other: 必须实现IntoIterator特征. 也就是说, 传的参实现了可转换迭代器这个特征即可, 未必是真正的迭代器(如切片 &[T])

    fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter>
    where
        Self: Sized,
        U: IntoIterator,
    {
        Zip::new(self, other.into_iter())
    }

例如

fn main() {
    let enumerate: Vec<_> = "foo".chars().enumerate().collect();

    // 使用zip方法, 实现将无限迭代器转换为有限
    let zipper: Vec<_> = (0..).zip("foo".chars()).collect();

    assert_eq!((0, 'f'), enumerate[0]);
    assert_eq!((0, 'f'), zipper[0]);

    assert_eq!((1, 'o'), enumerate[1]);
    assert_eq!((1, 'o'), zipper[1]);

    assert_eq!((2, 'o'), enumerate[2]);
    assert_eq!((2, 'o'), zipper[2]);
}

与zip()方法类似, 在std::iter::zip下也有zip()函数, 该函数需要传入迭代器, 实现功能与zip()方法相同, 但可读性更高.

fn main() {
    use std::iter::zip;

    let a = [1, 2, 3];
    let b = [2, 3, 4];

    let mut zipped = zip(
        a.into_iter().map(|x| x * 2).skip(1),
        b.into_iter().map(|x| x * 2).skip(1),
    );

    assert_eq!(zipped.next(), Some((4, 6)));
    assert_eq!(zipped.next(), Some((6, 8)));
    assert_eq!(zipped.next(), None);
}

fn main() {
    let a = [1, 2, 3];
    let b = [2, 3, 4];

    let mut zipped = a
        .into_iter()
        .map(|x| x * 2)
        .skip(1)
        .zip(b.into_iter().map(|x| x * 2).skip(1));
    
    assert_eq!(zipped.next(), Some((4, 6)));
    assert_eq!(zipped.next(), Some((6, 8)));
    assert_eq!(zipped.next(), None);
}

map

Takes a closure and creates an iterator which calls that closure on each element.

map() transforms one iterator into another, by means of its argument: something that implements [FnMut]. It produces a new iterator which calls this closure on each element of the original iterator.

传入一个闭包, 通过对原迭代器的各个元素逐一映射(每个元素传入闭包中, 然后再返回一个新元素值), 得到一个新迭代器Map.

==传入参数== f: 一个闭包

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

示例:

fn main() {
    let a = [1, 2, 3];
    let mut iter = a.iter().map(|x| 2 * x);
    assert_eq!(iter.next(), Some(2));
    assert_eq!(iter.next(), Some(4));
    assert_eq!(iter.next(), Some(6));
    assert_eq!(iter.next(), None);
}

for_each

Calls a closure on each element of an iterator.

This is equivalent to using a [for] loop on the iterator, although break and continue are not possible from a closure. It's generally more idiomatic to use a for loop, but for_each may be more legible when processing items at the end of longer iterator chains. In some
cases for_each may also be faster than a loop, because it will use internal iteration on adapters like Chain.

对迭代器的每个元素调用闭包. 等价于for循环. 虽然用for循环更惯用, 但是for_each有些情况下更易读, 也会更快. 因为这会使用一些内部优化器, 例如Chain优化器

==传入参数== f: 闭包

    fn for_each<F>(self, f: F)
    where
        Self: Sized,
        F: FnMut(Self::Item),
    {
        #[inline]
        fn call<T>(mut f: impl FnMut(T)) -> impl FnMut((), T) {
            move |(), item| f(item)  // move 关键字表示转移所有权
           	// 也就说明了, item的所有权使用时会强制转移, 无论是否取引用
        }

        self.fold((), call(f));
    }

例如:

fn main() {
     // 生成100-110, 200-220, ... , 400-440 这么多个数: 10+20+30+40=100
    (0..5).flat_map(|x| x * 100 .. x * 110)
    .enumerate()
    .filter(|&(i, x)| (i + x) % 3 == 0)
    .for_each(|(i, x)| println!("{i}:{x}"));
}

filter

Creates an iterator which uses a closure to determine if an element should be yielded.

过滤一些元素, 返回符合条件的元素组成的迭代器. 条件由传入参数: 谓词闭包来判断

==传入参数== predicate: 谓词闭包, 或者叫做条件闭包. 也就是输出必须是一个判断(true, false): FnMut(&Self::Item) -> bool

该闭包传入参数要求是 迭代器元素(item) 的引用形式(references), 因此, 当 item 是引用时, 需要传入 引用的引用

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

示例:

fn main() {
    let a = [0, 1, 2];

    let mut iter = a.iter().filter(|&&x| x > 1); // need two *s!

    assert_eq!(iter.next(), Some(&2));
    assert_eq!(iter.next(), None);
}

filter_map

Creates an iterator that both filters and maps.

filter_map can be used to make chains of [filter] and [map] more concise. The example below shows how a map().filter().map() can be shortened to a single call to filter_map.

实现即filter又map的迭代器FilterMap. 实现对迭代器的部分映射而不是全映射. 这会使代码更简洁

==传入参数== f: 一个闭包, 该闭包返回一个Option结构, 仅有闭包值为Some(value)时, 才会将value 存入迭代器中.

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

例如:

fn main() {
    let a = ["1", "two", "NaN", "four", "5"];

    let mut iter = a.iter().filter_map(|s| s.parse().ok());

    assert_eq!(iter.next(), Some(1));
    assert_eq!(iter.next(), Some(5));
    assert_eq!(iter.next(), None);
}

迭代器需要两件事: 第一将数字形式的字符串筛选出来, 第二需要将字符串转换为数字, 这如果单独用filter和map会很麻烦:

fn main() {
    let a = ["1", "two", "NaN", "four", "5"];
    let mut iter = a.iter().map(|s| s.parse()).filter(|s| s.is_ok()).map(|s| s.unwrap());
    assert_eq!(iter.next(), Some(1));
    assert_eq!(iter.next(), Some(5));
    assert_eq!(iter.next(), None);
}

enumerate()

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

The iterator returned yields pairs (i, val), where i is the current index of iteration and val is the value returned by the iterator.

消耗原迭代器, 得到一个Enumerate 枚举迭代器, 其值是元组 (i, val) . i 值大于 usize::MAX时panic

    fn enumerate(self) -> Enumerate<Self>
    where
        Self: Sized,
    {
        Enumerate::new(self)
    }

peekable()

Creates an iterator which can use the [peek] and [peek_mut] methods to look at the next element of the iterator without consuming it. See their documentation for more information.

Note that the underlying iterator is still advanced when [peek] or [peek_mut] are called for the first time: In order to retrieve the next element, [next] is called on the underlying iterator, hence any side effects (i.e. anything other than fetching the next value) of the [next] method will occur.

创建一个增强型迭代器. 这个迭代器可以 前瞻 (peek) 迭代器的下一个值, 而不消耗它(next).

创建的Peekable迭代器会得到四个新方法:

• peek() -> Option<&I::Item>: 查看下一个迭代器的值, 以引用的形式返回
• peek_mut() -> Option<&mut I::Item>: 查看下一个迭代器的值, 返回它的可变引用, 或None
• next_if()
• next_if_eq()

但是, 请注意, 首次调用peek()方法时, 底层迭代器会调用一次next()方法, 以此来缓存下一个元素.

原说明文档中给出的是anything other than fetching the next value of the [next] . (意思是, 如果next()方法如果除了捕获下一个值外, 还会做其他操作, 则可能会出现一些副作用. 主要是自己实现这个特征时要注意)

    fn peekable(self) -> Peekable<Self>
    where
        Self: Sized,
    {
        Peekable::new(self)
    }

下面举个side effects的例子:

struct LoggingIterator {
    data: Vec<i32>,
    index: usize,
}

impl LoggingIterator {
    fn new(data: Vec<i32>) -> Self {
        LoggingIterator { data, index: 0 }
    }
}

impl Iterator for LoggingIterator {
    type Item = i32;

    fn next(&mut self) -> Option<Self::Item> {
        if self.index < self.data.len() {
            println!("Fetching number: {}", self.data[self.index]);
            self.index += 1;
            Some(self.data[self.index - 1])
        } else {
            None
        }
    }
}

这个迭代器，它不仅仅是简单地遍历一系列数字，还在每次调用 next() 时打印出一条消息，表示正在获取下一个数字。

fn main() {
    let numbers = vec![1, 2, 3];
    let mut iter = LoggingIterator::new(numbers).peekable();

    // 首次调用 peek()
    println!("Peeking at the next element...");
    iter.peek();
    // 此时，尽管我们只是“窥视”下一个元素，但“Fetching number: 1”已经被打印出来，
    // 这是因为在内部调用了 next() 方法来获取该元素。
    
    // 继续迭代
    while let Some(number) = iter.next() {
        println!("{}", number);
    }
}

除了获取下一个值之外，next() 方法中可能包含的任何其他操作（副作用）也会执行。

skip_while

Creates an iterator that [skip]s elements based on a predicate.

skip_while() takes a closure as an argument. It will call this closure on each element of the iterator, and ignore elements until it returns false.

After false is returned, skip_while()'s job is over, and the rest of the elements are yielded.

消耗原迭代器, 转换为一个 一次条件跳过 迭代器. (谓词跳过迭代器)

也就是说, 先while, 把所有谓词为 true 的全部执行跳过, 然后跳出while, 此后就正常输出迭代器(和往常迭代器一样)

==输入参数== predicate: 条件闭包 / 谓词闭包. 当闭包返回 true 时, 跳过该值, 再次判断下一个值. 直到首次得到 false后, 闭包功能用尽.

该闭包传入参数要求是 迭代器元素(item) 的引用形式(references), 因此, 当 item 是引用时, 需要传入 引用的引用

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

在第一次false产生后, skip_over()的职能用尽, 其余元素(无论是否通过判断), 都将正常产生. 例如

fn main() {
    let a = [-1, 0, 1, -2];
    let mut iter = a.iter().skip_while(|x| **x < 0);
    assert_eq!(iter.next(), Some(&0));
    assert_eq!(iter.next(), Some(&1));

    // 尽管这个判断也是false, 但已经得到过一次false,
    // skip_while() 不会再生效
    assert_eq!(iter.next(), Some(&-2));
    assert_eq!(iter.next(), None);
}

take_while

Creates an iterator that yields elements based on a predicate.

take_while() takes a closure as an argument. It will call this closure on each element of the iterator, and yield elements while it returns true.

After false is returned, take_while()'s job is over, and the rest of the elements are ignored.

和上一个类似, 但是谓词为true则捕获(take), 知道出现false, 迭代器直接用完

==输入参数== predicate, 判断闭包, 这里是是真则输出, 遇到假直接耗尽迭代器, 此后一直输出 None

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

Because take_while() needs to look at the value in order to see if should be included or not, consuming iterators will see that it is removed:

let a = [1, 2, 3, 4];
let mut iter = a.iter();
let result: Vec<i32> = iter.by_ref()
                           .take_while(|n| **n != 3)
                           .cloned()
                           .collect();
assert_eq!(result, &[1, 2]);
let result: Vec<i32> = iter.cloned().collect();
assert_eq!(result, &[4]);

这里 cloned()保证原迭代器所有权保留, take_while()消耗了迭代器中的[1, 2, 3] 3个 item, 但仅捕获了[1, 2]两个元素. 因为 it was consumed in order to see the iteration should stop, but wasn't placed back into the iterator. 最终, 原迭代器还有一个元素[4].

map_while

Creates an iterator that both yields elements based on a predicate and maps.

同理, 消耗迭代器, 只有符合Some(val)的, 执行映射, 得到新的元素val, 输出. 首次出现None后迭代器用尽, 此后返回None

该迭代器是map和take_while的组合, 用来简化代码

==输入参数==: predicate: 谓词闭包. 这次的判断是返回值是否非空. Some(_)和None为两类判断形式.

    fn map_while<B, P>(self, predicate: P) -> MapWhile<Self, P>
    where
        Self: Sized,
        P: FnMut(Self::Item) -> Option<B>,
    {
        MapWhile::new(self, predicate)
    }

skip

Creates an iterator that skips the first n elements.

将原迭代器转换为一个新迭代器, 该迭代器会跳过前n个元素.

迭代器太短会直接为空迭代器. 没必要重写此方法, 不如重写nth()方法.

==传入参数== n: 跳过值的个数. 如果n==0, 则相当于没跳过值.

    fn skip(self, n: usize) -> Skip<Self>
    where
        Self: Sized,
    {
        Skip::new(self, n)
    }

take

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

将原迭代器转换为一个新迭代器, 该迭代器会只迭代前n个元素.

迭代器太短, 则相当于没对迭代器限制, 迭代器正常输出所有值.

==传入参数== n: 捕获的个数. 如果n==0, 则相当于让迭代器直接变空

    fn take(self, n: usize) -> Take<Self>
    where
        Self: Sized,
    {
        Take::new(self, n)
    }

scan

An iterator adapter which, like [fold], holds internal state, but unlike [fold], produces a new iterator.

获取原迭代器的所有权, 产生一个新迭代器Scan. 这个方法类似于fold方法, 但不同, scan不会将initial_state所有权转移, 而是在闭包中生成一个可变引用, 去更改initial_state的值. 其返回值Scan是一个迭代器, 因此我们需要将经过initial_state运算后的新 item 值映射给这个迭代器, 每层迭代得到的是Scan的一个元素.

==传入参数== initial_state: 初始值.任意的

f: 一个闭包, 第一个参是 initial_state的可变引用, 第二个参是迭代器元素item. 返回值也有要求, 每次迭代返回一个 Option<B> , 这里的B就是Scan迭代器的item, 因此我们需要在这些迭代中自己规定Scan的元素, 何时返回Some(B), 何时返回None

    fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F>
    where
        Self: Sized,
        F: FnMut(&mut St, Self::Item) -> Option<B>,
    {
        Scan::new(self, initial_state, f)
    }

示例:

let a = [1, 2, 3, 4];
let mut iter = a.iter().scan(1, |state, &x| {
    // each iteration, we'll multiply the state by the element ...
    *state = *state * x;
    
    // ... and terminate if the state exceeds 6
    if *state > 6 {
        return None;
    }
    // ... else yield the negation of the state
    Some(-*state)
});

assert_eq!(iter.next(), Some(-1));
assert_eq!(iter.next(), Some(-2));
assert_eq!(iter.next(), Some(-6));
assert_eq!(iter.next(), None);

flat_map

Creates an iterator that works like map, but flattens nested structure.

The [map] adapter is very useful, but only when the closure argument produces values. If it produces an iterator instead, there's an extra layer of indirection. flat_map() will remove this extra layer on its own.

You can think of flat_map(f) as the semantic equivalent of [map]ping, and then [flatten]ing as in map(f).flatten().

Another way of thinking about flat_map(): [map]'s closure returns one item for each element, and flat_map()'s closure returns an iterator for each element.

将迭代器转换为 展平映射迭代器. 作用是展平嵌套结构.

flat_map和map很类似, map适配器很有用, 但它仅在闭包返回值是values时更有用. 如果返回值是一个iterator, 那么其输出将会有一个额外的间接层(类似于[1, 2, 3] —map(|x| [x,x,x])—> [[1, 1, 1], [2, 2, 2], [3, 3, 3]], 出现了嵌套结构). 使用flat_map会去除由map产生的这个额外层(上例也就变成了 [1, 1, 1, 2, 2, 2, 3, 3, 3],)

你可以把flap_map(f)看作这样一个语义等价: map(f).flatten(), 他们的最终结果相同, 但是展平时机不同

另一种理解方式: map(f)的闭包f要求返回值是迭代元素经映射后得到的一个值 (item), 而flat_map(f)的闭包f要求返回值是经迭代元素映射后得到的一个迭代器(iterator)

==传入参数== f: 一个闭包, 闭包返回值必须满足 U 特征, 也就是是一个迭代器

    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)
    }

示例:

let words = ["alpha", "beta", "gamma"];
// chars() returns an iterator
let merged: String = words.iter()
                          .flat_map(|s| s.chars())
                          .collect();
assert_eq!(merged, "alphabetagamma");

flatten()

Creates an iterator that flattens nested structure.

展平 一层嵌套, 也就是说, 释放迭代器内元素的一层. 这常用于降维, 如3维变2维, 2维变1维

注意, 调用一次flatten(), 仅会降1维

==使用限制== 迭代器的元素item必须也可转换为迭代器 IntoIterator

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

**Option和Result**两类结构也实现了IntoIterator方法!

let options = vec![Some(123), Some(321), None, Some(231)];
let flattened_options: Vec<_> = options.into_iter().flatten().collect();
assert_eq!(flattened_options, vec![123, 321, 231]);

let results = vec![Ok(123), Ok(321), Err(456), Ok(231)];
let flattened_results: Vec<_> = results.into_iter().flatten().collect();
assert_eq!(flattened_results, vec![123, 321, 231]);

Flattening only removes one level of nesting at a time:

let d3 = [[[1, 2], [3, 4]], [[5, 6], [7, 8]]];

let d2 = d3.iter().flatten().collect::<Vec<_>>();
assert_eq!(d2, [&[1, 2], &[3, 4], &[5, 6], &[7, 8]]);

let d1 = d3.iter().flatten().flatten().collect::<Vec<_>>();
assert_eq!(d1, [&1, &2, &3, &4, &5, &6, &7, &8]);

// 所以如果想要从3维降到1维, 就需要两次fatten(). 把里面的值剥离出来
// 层层扒皮

fuse()

Creates an iterator which ends after the first [None].

After an iterator returns [None], future calls may or may not yield [Some(T)] again. fuse() adapts an iterator, ensuring that after a [None] is given, it will always return [None] forever.

Note that the [Fuse] wrapper is a no-op on iterators that implement the [FusedIterator] trait. fuse() may therefore behave incorrectly if the [FusedIterator] trait is improperly implemented.

转换为 守卫迭代器/保险迭代器.

保证迭代器第一次产生(yield) None 后, 往后的值均为 None

这主要是对FusedIterator特征没正确声明的迭代器设计的.

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

示例:

fn main() {
    // an iterator which alternates between Some and None
    struct Alternate {
        state: i32,
    }

    impl Iterator for Alternate {
        type Item = i32;

        fn next(&mut self) -> Option<i32> {
            let val = self.state;
            self.state = self.state + 1;

            // if it's even, Some(i32), else None
            if val % 2 == 0 {
                Some(val)
            } else {
                None
            }
        }
    }

    let mut iter = Alternate { state: 0 };

    // we can see our iterator going back and forth
    assert_eq!(iter.next(), Some(0));
    assert_eq!(iter.next(), None);
    assert_eq!(iter.next(), Some(2));
    assert_eq!(iter.next(), None);

    // however, once we fuse it...
    let mut iter = iter.fuse();

    assert_eq!(iter.next(), Some(4));
    assert_eq!(iter.next(), None);

    // it will always return `None` after the first time.
    assert_eq!(iter.next(), None);
    assert_eq!(iter.next(), None);
    assert_eq!(iter.next(), None);

}

inspect

Does something with each element of an iterator, passing the value on.

When using iterators, you'll often chain several of them together. While working on such code, you might want to check out what's happening at various parts in the pipeline. To do that, insert a call to inspect().

inspect, 观察, 审阅之意. 构建一个中间过程观察迭代器.

这个方法返回的迭代器Inspect 不会对原迭代器做任何操作, 原样输入, 原样输出.

==传入参数== f: 一个闭包, 闭包传入item的引用, 但是这个闭包没有输出!

这也就提示了, 这个函数往往用于提示作用, 闭包用来打印输出(println!()), 因此, 在debug代码时, 查看迭代器各个环节之间 值 是如何变化的, 很有用

    fn inspect<F>(self, f: F) -> Inspect<Self, F>
    where
        Self: Sized,
        F: FnMut(&Self::Item),
    {
        Inspect::new(self, f)
    }

示例1:

fn main() {

    let a = [1, 4, 2, 3];

    // this iterator sequence is complex.
    let sum = a.iter()
        .cloned()
        .filter(|x| x % 2 == 0)
        .fold(0, |sum, i| sum + i);

    println!("{sum}");

    // let's add some inspect() calls to investigate what's happening
    let sum = a.iter()
        .cloned()
        .inspect(|x| println!("about to filter: {x}"))
        .filter(|x| x % 2 == 0)
        .inspect(|x| println!("made it through filter: {x}"))
        .fold(0, |sum, i| sum + i);

    println!("{sum}");
}

可见, inspect 仅仅观察到了当前值, 并把它打印了出来, 给我们提示. 我们根据 filter 前后inspect值的输出, 就可以判断哪些值被filter过滤掉了, 进而判断filter是否按我们期望的功能运行.

示例2:

除了根据 方法 前后的元素变化判断 方法是否正常运作外, 我们还可以只关注失败的元素, 记录错误:

fn main() {

    let lines = ["1", "2", "a"];

    let sum: i32 = lines
        .iter()
        .map(|line| line.parse::<i32>())
        .inspect(|num| {
            if let Err(ref e) = *num {
                println!("Parsing error: {e}");
            }
        })
        .filter_map(Result::ok)
    	// .filter_map(|x| x.ok())  // 上面那句话就等价于这个, 用方法名/函数名代替闭包, 表示对每个元素执行方法.
    	// 这里用到了自动解引用的机制.
        .sum();

    println!("Sum: {sum}");
}

通过map, 一些成功map, 得到Ok(_), 另一些则未成功匹配(如字符串“a”), 得到Rrr(_), 我们通过inspect判断失败匹配的元素并将失败日志打印输出(当然也可以写道log文档中), 并用filter_map只提取成功匹配的值.

filter_map()要求传入一个返回值为Option的闭包, 这里为什么用的是Result::ok呢? Rust 允许将一些关联函数(静态方法)/实例方法的调用自动转换为闭包形式, 当方法的传入参数和迭代器各元素item匹配时, 用方法名指针可以直接转换为闭包. 例如 Result::ok(self) 方法, 其传入参数只有self, 和迭代器元素匹配, 因此可以摆脱冗余的|x| x.ok(), 直接传入 Result::ok 即可.

collect()

Transforms an iterator into a collection.

将迭代器转换为集合。

collect()可以获取任何可迭代的元素(item)，并将其转换为相关的集合(collections)。这是标准库中功能更强大的方法之一，用于各种上下文。

collect() 应用的最基本的模式是, 将一个集合转换为另一个。你拿一个集合，调用[iter]转换为迭代器， 然后做一堆变换，最后再用collect()收集。

collect()还可以创建非典型类型的集合。例如，一个String可以由[char]s构建, [Result<T, E>]或[Result]等元素(item) 组成的迭代器, 可以收集构建为 Result<Collection<T>, E>.

由于collect()方法太笼统了，可能会导致类型推理问题。因此，collect()是你会看到的为数不多的需要用到 被亲切地叫为“涡轮鱼” (turbofish) 语法的方法：::<>. 这帮助编译器的推理算法具体了解到你正在尝试收集为哪个集合 。

==输入参数== 无

==传出参数== 有要求! 传出参数必须申明了 FromIterator 转换特征, 具体转换为什么类型(这里是泛型B), 需要靠 turbofish ::<> 的提示! 同时 turbofish 提示的转换类型需要在 FromIterator 中有申明.

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

这里要说明一下 FromIterator 特征

pub trait FromIterator<A>: Sized {
    fn from_iter<T: IntoIterator<Item = A>>(iter: T) -> Self;
}

特征仅声明了一个方法: from_iter()方法, 它的作用是, 将一个元素是A类型的迭代器(或可转换为迭代器(IntoIterator)的类型), 转换为声明该特征的类型: Self

例如, Vec实现了FromIterator特征,

impl<T> FromIterator<T> for Vec<T> {
    #[inline]
    fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Vec<T> {
        <Self as SpecFromIter<T, I::IntoIter>>::from_iter(iter.into_iter())
    }
}

那么, 这表明任何类型的迭代器最终都能转化为Vec类型, 此时, 如果用collect()方法收集元素(Item=T), 就需要用turbofish注释Self为Vec: collect::<Vec<_>>()

在标准库中, FromIterator 一共有31处声明, 共能转化为20种类型:

输出类型	From	To
Box	IntoIterator<Item = I>	Box<[I]>
BinaryHeap	IntoIterator<Item = T>	BinaryHeap<T>
BTreeMap	IntoIterator<Item = (K, V)>	BTreeMap<K, V>
BTreeSet	IntoIterator<Item = T>	BTreeSet<T>
LinkedList	IntoIterator<Item = T>	LinkedList<T>
VecDeque	IntoIterator<Item = T>	VecDeque<T>
Rc	IntoIterator<Item = T>	Rc<[T]>
String	IntoIterator<Item = char>	String
	IntoIterator<Item = &'a char>	String
	IntoIterator<Item = &'a str>	String
	IntoIterator<Item = String>	String
	IntoIterator<Item = Box<str>>	String
	IntoIterator<Item = Cow<'a, str>>	String
Cow	IntoIterator<Item = char>	Cow<'a, str>
	IntoIterator<Item = &'b str>	Cow<'a, str>
	IntoIterator<Item = String>	Cow<'a, str>
	IntoIterator<Item = T>	Cow<'a, [T]
Arc	IntoIterator<Item = T>	Arc<[T]>
Vec	IntoIterator<Item = T>	Vec<T>
Option	IntoIterator<Item = Option<A>>	Option<V>
Result	IntoIterator<Item = Result<A, E>>	Result<V, E>
unit	IntoIterator<Item = ()>	()
TokenStream	IntoIterator<Item = TokenTree>	TokenStream
	IntoIterator<Item = TokenStream>	TokenStream
HashMap	IntoIterator<Item = (K, V)>	HashMap<K, V, S>
HashSet	IntoIterator<Item = T>	HashSet<T, S>
OsString	IntoIterator<Item = OsString>	OsString
	IntoIterator<Item = &'a OsStr>	OsString
	IntoIterator<Item = Cow<'a, OsStr>>	OsString
PathBuf	IntoIterator<Item = P>	PathBuf
Wtf8Buf	IntoIterator<Item = CodePoint>	Wtf8Buf

根据上表, 我们可以明确判断, 我们的迭代器到底能收集为哪些类型. 同时也可以发现, 当输入的迭代器为IntoIterator<Item = T> 也就是任意类型的迭代器时, 其输出类型是多样的, 如Vec<T>, HashSet<T, S>, BinaryHeap<T>, VecDeque<T>等等. 因此, 对输出类型进行注释很必要.

示例:

let chars = ['g', 'd', 'k', 'k', 'n'];

let hello: String = chars.iter()
    .map(|&x| x as u8)
    .map(|x| (x + 1) as char)
    .collect();

assert_eq!("hello", hello);

用collect查看是否有Err产生:

fn main() {

    let results = [Ok(1), Err("nope"), Ok(3), Err("bad")];

    let result: Result<Vec<_>, &str> = results.iter().cloned().collect();

    // gives us the first error
    println!("{:?}", result);
    // Err("nope")

    let results = [Ok(1), Ok(3)];

    let result: Result<Vec<_>, &str> = results.iter().cloned().collect();

    // gives us the list of answers
    println!("{:?}", result);
    // Ok([1, 3])
}

为啥有这样的输出呢? 这实际上和 Result的from_iter()方法实现有关:

    fn from_iter<I: IntoIterator<Item = Result<A, E>>>(iter: I) -> Result<V, E> {
        iter::try_process(iter.into_iter(), |i| i.collect())
    }

泛型V是一个可以实现了 FromIterator<A> 的类型, 意思是可以将元素为A的迭代器转换为V这种集合类型, try_process()方法表明了:

Takes each element in the Iterator: if it is an Err, no further elements are taken, and the Err is returned. Should no Err occur, a container with the values of each Result is returned.

因此, 如果没有任何Err产生, 则返回用Ok包裹的集合V (如上例的[1, 3]), 只要出现一个Err立刻结束迭代, 直接返回Err包裹的信息(如上例的“Nope”).

partition

Consumes an iterator, creating two collections from it.

The predicate passed to partition() can return true, or false. partition() returns a pair, all of the elements for which it returned true, and all of the elements for which it returned false.

See also [is_partitioned()] and [partition_in_place()].

拆分迭代器. 将原迭代器消耗, 返回两个新迭代器组成的二元组, 元组左边迭代器为谓词为true的元素, 右边为谓词为false的元素.

==传入参数== f: 一个谓词闭包/条件闭包

O(n)复杂度, 没实现二分

    fn partition<B, F>(self, f: F) -> (B, B)
    where
        Self: Sized,
        B: Default + Extend<Self::Item>,
        F: FnMut(&Self::Item) -> bool,
    {
        #[inline]
        fn extend<'a, T, B: Extend<T>>(
            mut f: impl FnMut(&T) -> bool + 'a,
            left: &'a mut B,
            right: &'a mut B,
        ) -> impl FnMut((), T) + 'a {
            move |(), x| {
                if f(&x) {
                    left.extend_one(x);
                } else {
                    right.extend_one(x);
                }
            }
        }

        let mut left: B = Default::default();
        let mut right: B = Default::default();

        self.fold((), extend(f, &mut left, &mut right));

        (left, right)
    }

max()

Returns the maximum element of an iterator.

If several elements are equally maximum, the last element is returned. If the iterator is empty, [None] is returned.

Note that [f32]/[f64] doesn't implement [Ord] due to NaN being incomparable. You can work around this by using [Iterator::reduce]:

消耗整个迭代器, 返回迭代器中最大元素

如果迭代器所有元素值都相等, 返回最后一个元素, 如果迭代器为空, 返回None

浮点数由于存在Nan这个不可比较的值, 所以不能用max方法. 寻找最大值. 这可以使用reduce方法解决这个问题

    fn max(self) -> Option<Self::Item>
    where
        Self: Sized,
        Self::Item: Ord,
    {
        self.max_by(Ord::cmp)
    }

示例:

下面是用reduce代替max的一个示例

fn main() {
    assert_eq!(
        [2.4, f32::NAN, 1.3]
            .into_iter()
            .reduce(f32::min)
            .unwrap(),
        1.3
    );
}

min()

Returns the minimum element of an iterator.

返回迭代器中元素最小的值, 和max的要求一致

    fn min(self) -> Option<Self::Item>
    where
        Self: Sized,
        Self::Item: Ord,
    {
        self.min_by(Ord::cmp)
    }

max_by_key

Returns the element that gives the maximum value from the specified function.

根据给出的指定函数, 判断迭代器的最值

==传入参数== f: 一个闭包, 该闭包返回一个已经实现Ord排序特征的类型

和 max 直接比较元素大小不同, max_by_key先是将元素利用给的闭包做一次映射map(f), 映射(返回一个二元组, 第一个元素是映射结果, 第二个元素是原值, 做返回值用), 然后再进行max的比较

    fn max_by_key<B: Ord, F>(self, f: F) -> Option<Self::Item>
    where
        Self: Sized,
        F: FnMut(&Self::Item) -> B,
    {
        #[inline]
        fn key<T, B>(mut f: impl FnMut(&T) -> B) -> impl FnMut(T) -> (B, T) {
            move |x| (f(&x), x)
        }

        #[inline]
        fn compare<T, B: Ord>((x_p, _): &(B, T), (y_p, _): &(B, T)) -> Ordering {
            x_p.cmp(y_p)
        }

        let (_, x) = self.map(key(f)).max_by(compare)?;
        Some(x)
    }

max_by

Returns the element that gives the maximum value with respect to the specified comparison function.

用指定地比较函数, 比较迭代器各个元素的值.

这是max和max_by_key的底层方法

==传入参数== compare: 一个闭包, 传入两个变量的引用, 输出这两个变量的比较结果Ordering

当 f 为 |&x, &y| x.cmp(y) (或者直接写成方法名 Ord::cmp) 时, max_by就等于max

当 f 为 |&x, &y| |g(x).cmp(g(y)| (这里g是一个映射函数, 即max_by_key(g) 方法的传参闭包 g)时, max_by就等于max_by_key

max_by 更适合自定义最值, 必如如果我要自定义一个二元组, 这样的值时最大的:

• 第一个元素取最大, 第二个元素取最小

那此时就需要用max_by要更优雅. (max_by_key也可以实现, 但不够优雅)

详细见示例

    fn max_by<F>(self, compare: F) -> Option<Self::Item>
    where
        Self: Sized,
        F: FnMut(&Self::Item, &Self::Item) -> Ordering,
    {
        #[inline]
        fn fold<T>(mut compare: impl FnMut(&T, &T) -> Ordering) -> impl FnMut(T, T) -> T {
            move |x, y| cmp::max_by(x, y, &mut compare)
        }

        self.reduce(fold(compare))
    }

源码解释: 从前两个元素开始,利用compare()的比较结果对元素逐个比较, 返回较大的元素再与下一个元素比较(reduce的作用), 直到所有元素比较完成

示例:

取自定义最值:

• 第一个元素取最大, 第二个元素取最小

fn main() {
    let sort = [(0, 1), (5, 1), (5, 3), (3, 5)];

    // 利用max_by, 实现自定义排序
    let max_val = sort.iter().max_by(|&x, &y| {
        match x.0.cmp(&y.0) {
            std::cmp::Ordering::Equal => y.1.cmp(&x.1),
            other => other
        }
    }).unwrap();

    println!("{:?}", max_val);

    // 有些数据类型, 也可以使用sort_by_key实现相同功能
    // 但和数据类型相关, 比如比较的是usize, 可能代码就又需要改变
    let max_key_val = sort.iter().max_by_key(|&x| (x.0, -x.1)).unwrap();

    assert_eq!(max_val, max_key_val);

}

min_by_key

Returns the element that gives the minimum value from the specified function.

根据给定函数判断最值

    fn min_by_key<B: Ord, F>(self, f: F) -> Option<Self::Item>
    where
        Self: Sized,
        F: FnMut(&Self::Item) -> B,
    {
        #[inline]
        fn key<T, B>(mut f: impl FnMut(&T) -> B) -> impl FnMut(T) -> (B, T) {
            move |x| (f(&x), x)
        }

        #[inline]
        fn compare<T, B: Ord>((x_p, _): &(B, T), (y_p, _): &(B, T)) -> Ordering {
            x_p.cmp(y_p)
        }

        let (_, x) = self.map(key(f)).min_by(compare)?;
        Some(x)
    }

min_by

Returns the element that gives the minimum value with respect to the specified comparison function.

自定义比较函数, 实现最小值比较. 比较函数是一个返回Ordering枚举的函数

详见max_by

    fn min_by<F>(self, compare: F) -> Option<Self::Item>
    where
        Self: Sized,
        F: FnMut(&Self::Item, &Self::Item) -> Ordering,
    {
        #[inline]
        fn fold<T>(mut compare: impl FnMut(&T, &T) -> Ordering) -> impl FnMut(T, T) -> T {
            move |x, y| cmp::min_by(x, y, &mut compare)
        }

        self.reduce(fold(compare))
    }

rev()

Reverses an iterator's direction.

翻转迭代器输出顺序. 必须是双端迭代器DoubleEndedIterator才可应用

所有从左连接的方法均变成了右连接(从右索引)

    fn rev(self) -> Rev<Self>
    where
        Self: Sized + DoubleEndedIterator,
    {
        Rev::new(self)
    }

uzip

Converts an iterator of pairs into a pair of containers.

将一个二元组迭代器转换为两个迭代器

如[(1, 2), (3, 4), (5, 6)] –> [1, 3, 5] 和 [2, 4, 6]

迭代器的元素必须是二元组 (A, B), 可以看出来, rust的 zip 打包解包方法没有python智能, python 的 zip()可以输入很多迭代器, 组合成一个多元组, 同时zip(*)又可以把一个多元组/列表等等解包成原来的很多迭代器

当然了, 为什么rust没实现呢? 因为不同迭代器的类型可能不同, 没有一种迭代器, 可以让两种不同类型的放到一起(如果有, 那可能是box等类型, 但是它就失去了性能), 因此不同类型的迭代器很难实现用同一方法. 但我们可以根据这个方法, 对特定容器自己实现这个功能.

    fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)
    where
        FromA: Default + Extend<A>,
        FromB: Default + Extend<B>,
        Self: Sized + Iterator<Item = (A, B)>,
    {
        let mut unzipped: (FromA, FromB) = Default::default();
        unzipped.extend(self);
        unzipped
    }

copied()

Creates an iterator which copies all of its elements.

This is useful when you have an iterator over &T, but you need an iterator over T.

用于将引用变为值. 元素必须实现了Copy 特征

底层是利用Option的copied()方法: 通过模式匹配, 把Some(&T)变为Some(T)

    fn copied<'a, T: 'a>(self) -> Copied<Self>
    where
        Self: Sized + Iterator<Item = &'a T>,
        T: Copy,
    {
        Copied::new(self)
    }

cloned()

Creates an iterator which [clone]s all of its elements.

This is useful when you have an iterator over &T, but you need an iterator over T.

There is no guarantee whatsoever about the clone method actually being called or optimized away. So code should not depend on either.

消耗迭代器的所有元素, 克隆所有元素创建一个新迭代器

这个方法也可以把&T变为T, 但元素可以没实现Copy特征

无法保证cloned是被调用执行了还是被底层优化掉了(未执行), 所以所编写的代码应该不要依赖它.

    fn cloned<'a, T: 'a>(self) -> Cloned<Self>
    where
        Self: Sized + Iterator<Item = &'a T>,
        T: Clone,
    {
        Cloned::new(self)
    }

示例:

cloned可能在底层被优化掉, 从而实现错误答案, 因此我们应避免cloned()这种写法直接生成迭代器, 可能会出问题.

// 下面这个代码是没有出问题的, 只是不好
fn main() {
    let a = [1, 2, 3];
    let v = a.iter().copied();

    // 不要写这种依赖代码
    let v_dont = v.clone();
    // 最好写这种代码
    let v_use = a.iter();

    for i in v {
        println!("{}", i)
    }
    for i in v_dont {
        println!("{i}")
    }
}

cycle()

Repeats an iterator endlessly.

消耗原迭代器, 转换为周期的无限循环迭代器

原来的None变成原迭代器的第一个item, 周而复始

这里还要说明一下, 这个迭代器的next()也可能返回None, 如果原迭代器是空迭代器时, 就返回None

    fn cycle(self) -> Cycle<Self>
    where
        Self: Sized + Clone,
    {
        Cycle::new(self)
    }

sum()

Sums the elements of an iterator.

An empty iterator returns the zero value of the type.

sum() can be used to sum any type implementing [Sum] [core::iter::Sum], including [Option] and [Result].

消耗迭代器, 对元素所有元素. 元素要实现了Sum特征

    fn sum<S>(self) -> S
    where
        Self: Sized,
        S: Sum<Self::Item>,
    {
        Sum::sum(self)
    }

product()

Iterates over the entire iterator, multiplying all the elements

An empty iterator returns the one value of the type.

叠乘迭代器. 消耗迭代器, 返回所有元素相乘的结果

这个方法和sum方法都可以用flod和reduce实现

    fn product<P>(self) -> P
    where
        Self: Sized,
        P: Product<Self::Item>,
    {
        Product::product(self)
    }

示例

// 计算n的阶乘

fn fa(n: i32) -> i32 {
    (1..n).product()
}

// 也可以用reduce实现
fn fa2(n: i32) -> i32 {
    (1..n).reduce(|a, b| a * b).unwrap_or(1)
}

fn fa2(n: i32) -> i32 {
    (1..n).reduce(std::ops::Mul::mul).unwrap_or(1)
}

cmp

Lexicographically compares the elements of this [Iterator] with those of another.

Lexicographical comparison

Lexicographical comparison is an operation with the following properties:

• Two sequences are compared element by element.
• The first mismatching element defines which sequence is lexicographically less or greater than the other.
• If one sequence is a prefix of another, the shorter sequence is lexicographically less than the other.
• If two sequences have equivalent elements and are of the same length, then the sequences are lexicographically equal.
• An empty sequence is lexicographically less than any non-empty sequence.
• Two empty sequences are lexicographically equal.

按字典序比较两个迭代器大小, 返回比较结果Ordering

Less: 左边小于右边, Equal: 左边等于右边, Greater: 左边大于右边 A.fn(B) A为左边, B为右边

    fn cmp<I>(self, other: I) -> Ordering
    where
        I: IntoIterator<Item = Self::Item>,
        Self::Item: Ord,
        Self: Sized,
    {
        self.cmp_by(other, |x, y| x.cmp(&y))
    }

partial_cmp

Lexicographically compares the [PartialOrd] elements of this [Iterator] with those of another. The comparison works like short-circuit evaluation, returning a result without comparing the remaining elements. As soon as an order can be determined, the evaluation stops and a result is returned.

partial, 部分的. 对部分有序的类型进行比较大小

按字典序比较两个迭代器大小, 返回比较结果Option(Ordering)

产生Option的原因是, 类型Item可能存在不能比较大小的值, 因此当与不能比较大小的值比较是, 返回None

    fn partial_cmp<I>(self, other: I) -> Option<Ordering>
    where
        I: IntoIterator,
        Self::Item: PartialOrd<I::Item>,
        Self: Sized,
    {
        self.partial_cmp_by(other, |x, y| x.partial_cmp(&y))
    }

cmp和partical_cmp的区别!

• cmp 方法实现了 std::cmp::Ord trait，它用于完全有序（total order）的类型。这意味着所有同类的值都可以相互比较，总是能确定一个值是小于、等于或大于另一个值。cmp 方法返回一个 std::cmp::Ordering 枚举值，表示 Less、Equal 或 Greater。

• partial_cmp 方法实现了 std::cmp::PartialOrd trait，这个 trait 用于部分有序（partial order）或者说是可能无法比较的所有类型。部分有序意味着某些值可能无法直接比较（例如，NaN（Not a Number）在浮点数中就不与任何值相等，包括自己，也不比任何值大或小）。partial_cmp 返回一个 Option<Ordering>，当两个值可以比较时，它会返回 Some(Ordering)；如果值不能比较（这种情况在实现了 PartialOrd 但没有实现 Ord 的类型中可能出现），则返回 None。

示例:

use std::cmp::Ordering;
assert_eq!([1.0, f64::NAN].iter().partial_cmp([2.0, f64::NAN].iter()), Some(Ordering::Less
assert_eq!([2.0, f64::NAN].iter().partial_cmp([1.0, f64::NAN].iter()), Some(Ordering::Grea
assert_eq!([f64::NAN, 1.0].iter().partial_cmp([f64::NAN, 2.0].iter()), None);

eq

Determines if the elements of this [Iterator] are equal to those of another.

消耗迭代器, 判断两个迭代器是否相等

    fn eq<I>(self, other: I) -> bool
    where
        I: IntoIterator,
        Self::Item: PartialEq<I::Item>,
        Self: Sized,
    {
        self.eq_by(other, |x, y| x == y)
    }

ne

Determines if the elements of this [Iterator] are not equal to those of another.

判断两个迭代器是否不等

    fn ne<I>(self, other: I) -> bool
    where
        I: IntoIterator,
        Self::Item: PartialEq<I::Item>,
        Self: Sized,
    {
        !self.eq(other)
    }

lt

Determines if the elements of this [Iterator] are lexicographically comp less than those of another.

判断左边迭代器是否字典序小于右边迭代器

    fn lt<I>(self, other: I) -> bool
    where
        I: IntoIterator,
        Self::Item: PartialOrd<I::Item>,
        Self: Sized,
    {
        self.partial_cmp(other) == Some(Ordering::Less)
    }

le

Determines if the elements of this [Iterator] are lexicographically less or equal to those of another.

判断迭代器是是否小于或等于其他迭代器

    fn le<I>(self, other: I) -> bool
    where
        I: IntoIterator,
        Self::Item: PartialOrd<I::Item>,
        Self: Sized,
    {
        matches!(self.partial_cmp(other), Some(Ordering::Less | Ordering::Equal))
    }

gt

Determines if the elements of this [Iterator] are lexicographically greater than those of another.

greater. 左边是否大于右边迭代器

    fn gt<I>(self, other: I) -> bool
    where
        I: IntoIterator,
        Self::Item: PartialOrd<I::Item>,
        Self: Sized,
    {
        self.partial_cmp(other) == Some(Ordering::Greater)
    }

ge

Determines if the elements of this [Iterator] are lexicographically greater than or equal to those of another.

greater or equal. 左边是否大于等于右边

    fn ge<I>(self, other: I) -> bool
    where
        I: IntoIterator,
        Self::Item: PartialOrd<I::Item>,
        Self: Sized,
    {
        matches!(self.partial_cmp(other), Some(Ordering::Greater | Ordering::Equal))
    }

[Pro741]

当时就看说明英文直译的, 应该有需要术语不准确的地方, 还请大家多多批评指正:)

[xbsheng]

404