//! 可组合的外部迭代。
//!
//! 如果您发现自己具有某种类型的集合，并且需要对所述集合的元素执行操作，那么您会很快遇到 'iterators'。
//! 迭代器在惯用的 Rust 代码中大量使用，所以值得熟悉它们。
//!
//! 在解释更多内容之前，让我们讨论一下该模块的结构：
//!
//! # Organization
//!
//! 该模块主要是按类型来组织的：
//!
//! * [Traits] 是核心部分：这些 traits 定义了存在什么样的迭代器，以及您可以用它们做什么。这些 traits 的方法值得投入一些额外的学习时间。
//! * [Functions] 提供了一些有用的方法来创建一些基本的迭代器。
//! * [Structs] 通常是该模块的 traits 上各种方法的返回类型。通常，您将需要查看创建 `struct` 的方法，而不是 `struct` 本身。
//! 有关原因的更多详细信息，请参见 [实现迭代器](#implementing-iterator)。
//!
//! [Traits]: #traits
//! [Functions]: #functions
//! [Structs]: #structs
//!
//! 就是这样！ 让我们深入研究迭代器。
//!
//! # Iterator
//!
//! 该模块的核心是 [`Iterator`] trait。[`Iterator`] 的核心是这样的：
//!
//! ```
//! trait Iterator {
//!     type Item;
//!     fn next(&mut self) -> Option<Self::Item>;
//! }
//! ```
//!
//! 迭代器有一个方法 [`next`]，当调用它时，返回一个 <code>[Option]\<Item></code>.
//! 只要有元素，调用 [`next`] 就会返回 [`Some(Item)`]，一旦它们全部消费完，将返回 `None` 表示迭代完成。
//! 各个迭代器可能选择恢复迭代，因此再次调用 [`next`] 可能会或可能不会最终在某个时候再次开始返回 [`Some(Item)`] (例如，请参见 [`TryIter`])。
//!
//!
//! [`Iterator`] 的完整定义还包括许多其他方法，但是它们是默认方法，基于 [`next`] 构建，因此您可以免费获得它们。
//!
//! 迭代器也是可组合的，通常将它们链接在一起以进行更复杂的处理形式。有关更多详细信息，请参见下面的 [适配器](#adapters) 部分。
//!
//! [`Some(Item)`]: Some
//! [`next`]: Iterator::next
//! [`TryIter`]: ../../std/sync/mpsc/struct.TryIter.html
//!
//! # 三种迭代形式
//!
//! 有三种常见的方法可以从集合中创建迭代器：
//!
//! * `iter()`，它在 `&T` 上迭代。
//! * `iter_mut()`，它在 `&mut T` 上迭代。
//! * `into_iter()`，它在 `T` 上迭代。
//!
//! 在适当的情况下，标准库中的各种内容都可以实现这三个中的一个或多个。
//!
//! # 实现迭代器
//!
//! 创建自己的迭代器涉及两个步骤：创建一个 `struct` 来保存迭代器的状态，然后为该 `struct` 实现 [`Iterator`]。
//! 这就是为什么此模块中有这么多 `struct` 的原因：每个迭代器和迭代器适配器都有一个。
//!
//! 让我们创建一个名为 `Counter` 的迭代器，该迭代器的范围从 `1` 到 `5`：
//!
//! ```
//! // 首先，结构体：
//!
//! /// 从 1 到 5 计数的迭代器
//! struct Counter {
//!     count: usize,
//! }
//!
//! // 我们希望计数从一开始，所以让我们添加一个 new() 方法来提供帮助。
//! // 这不是严格必要的，但很方便。
//! // 请注意，我们将 `count` 从零开始，我们将在下面的 `next () ` 实现中看到其原因。
//! impl Counter {
//!     fn new() -> Counter {
//!         Counter { count: 0 }
//!     }
//! }
//!
//! // 然后，我们为 `Counter` 实现 `Iterator`：
//!
//! impl Iterator for Counter {
//!     // 我们将使用 usize 进行计数
//!     type Item = usize;
//!
//!     // next() 是唯一必需的方法
//!     fn next(&mut self) -> Option<Self::Item> {
//!         // 增加我们的数量。这就是为什么我们从零开始。
//!         self.count += 1;
//!
//!         // 检查我们是否已经完成计数。
//!         if self.count < 6 {
//!             Some(self.count)
//!         } else {
//!             None
//!         }
//!     }
//! }
//!
//! // 现在我们可以使用它了！
//!
//! let mut counter = Counter::new();
//!
//! assert_eq!(counter.next(), Some(1));
//! assert_eq!(counter.next(), Some(2));
//! assert_eq!(counter.next(), Some(3));
//! assert_eq!(counter.next(), Some(4));
//! assert_eq!(counter.next(), Some(5));
//! assert_eq!(counter.next(), None);
//! ```
//!
//! 以这种方式调用 [`next`] 将重复进行。Rust 有一个构造，可以在迭代器上调用 [`next`]，直到它到达 `None`。让我们接下来讨论。
//!
//! 还要注意，`Iterator` 提供了内部调用 `next` 的方法的默认实现，例如 `nth` 和 `fold`。
//! 但是，如果迭代器可以在不调用 `next` 的情况下更有效地计算它们，则还可以编写方法的自定义实现，例如 `nth` 和 `fold`。
//!
//! # `for` 循环和 `IntoIterator`
//!
//! Rust 的 `for` 循环语法实际上是迭代器的语法糖。这是 `for` 的一个基本示例：
//!
//! ```
//! let values = vec![1, 2, 3, 4, 5];
//!
//! for x in values {
//!     println!("{x}");
//! }
//! ```
//!
//! 这将打印数字 1 到 5，每个数字都在各自的行上。但是您会在这里注意到：我们从未在 vector 上调用任何东西来产生迭代器。是什么给的？
//!
//! 标准库中有一个 trait 用于将某些内容转换为迭代器: [`IntoIterator`]。
//! 这个 trait 具有一个 [`into_iter`] 方法，该方法可以将实现 [`IntoIterator`] 的类型转换为迭代器。
//! 让我们再次看一下 `for` 循环，以及编译器将其转换为什么：
//!
//! [`into_iter`]: IntoIterator::into_iter
//!
//! ```
//! let values = vec![1, 2, 3, 4, 5];
//!
//! for x in values {
//!     println!("{x}");
//! }
//! ```
//!
//! Rust 将其反糖化为：
//!
//! ```
//! let values = vec![1, 2, 3, 4, 5];
//! {
//!     let result = match IntoIterator::into_iter(values) {
//!         mut iter => loop {
//!             let next;
//!             match iter.next() {
//!                 Some(val) => next = val,
//!                 None => break,
//!             };
//!             let x = next;
//!             let () = { println!("{x}"); };
//!         },
//!     };
//!     result
//! }
//! ```
//!
//! 首先，我们在值上调用 `into_iter()`。然后，我们在返回的迭代器上进行匹配，一遍又一遍地调用 [`next`]，直到我们看到一个 `None`。
//! 到那时，我们 `break` 退出了循环，我们已经完成了迭代。
//!
//! 这里还有一点微妙之处：标准库包含一个有趣的 [`IntoIterator`] 实现：
//!
//! ```ignore (only-for-syntax-highlight)
//! impl<I: Iterator> IntoIterator for I
//! ```
//!
//! 换句话说，所有 [`Iterator`] 都通过返回自身来实现 [`IntoIterator`]。这意味着两件事：
//!
//! 1. 如果要编写 [`Iterator`]，则可以将其与 `for` 循环一起使用。
//! 2. 如果要创建集合，则为其实现 [`IntoIterator`] 将使您的集合可以与 `for` 循环一起使用。
//!
//! # 通过引用进行迭代
//!
//! 由于 [`into_iter()`] 将 `self` 作为值，因此使用 `for` 循环遍历一个集合将消耗该集合。通常，您可能需要迭代一个集合而不使用它。
//! 许多集合提供了在引用上提供迭代器的方法，通常分别称为 `iter()` 和 `iter_mut()`：
//!
//! ```
//! let mut values = vec![41];
//! for x in values.iter_mut() {
//!     *x += 1;
//! }
//! for x in values.iter() {
//!     assert_eq!(*x, 42);
//! }
//! assert_eq!(values.len(), 1); // `values` 仍然属于此函数。
//! ```
//!
//! 如果集合类型 `C` 提供 `iter()`，则它通常还为 `&C` 实现 `IntoIterator`，而该实现只是调用 `iter()`。
//! 同样，提供 `iter_mut()` 的集合 `C` 通常通过委派给 `iter_mut()` 来为 `&mut C` 实现 `IntoIterator`。这样可以方便快捷地实现以下目的：
//!
//! ```
//! let mut values = vec![41];
//! for x in &mut values { // 与 `values.iter_mut()` 相同
//!     *x += 1;
//! }
//! for x in &values { // 与 `values.iter()` 相同
//!     assert_eq!(*x, 42);
//! }
//! assert_eq!(values.len(), 1);
//! ```
//!
//! 尽管许多集合都提供 `iter()`，但并非所有人都提供 `iter_mut()`。
//! 例如，如果 key 的哈希发生变化，更改 [`HashSet<T>`] 的键可能会使集合处于不一致的状态，因此这个集合仅提供 `iter()`。
//!
//! [`into_iter()`]: IntoIterator::into_iter
//! [`HashSet<T>`]: ../../std/collections/struct.HashSet.html
//!
//! # Adapters
//!
//! 接受一个 [`Iterator`] 并返回另一个 [`Iterator`] 的函数通常被称为迭代器适配器，因为它们是适配器模式的一种形式。
//!
//! 常见的迭代器适配器包括 [`map`]，[`take`] 和 [`filter`]。
//! 有关更多信息，请参见它们的文档。
//!
//! 如果迭代器适配器为 panics，则迭代器将处于未指定 (但内存安全) 状态。
//! 也不能保证此状态在 Rust 的各个版本中都保持不变，因此您应避免依赖 panicked 的迭代器返回的确切值。
//!
//! [`map`]: Iterator::map
//! [`take`]: Iterator::take
//! [`filter`]: Iterator::filter
//!
//! # Laziness
//!
//! 迭代器 (和迭代器 [适配器](#adapters)) 是懒惰的)。这意味着仅仅创建一个迭代器并不会做很多事情。除非您调用 [`next`]，否则什么都不会发生。
//! 当创建仅出于其副作用的迭代器时，这有时会引起混乱。
//! 例如，[`map`] 方法在其迭代的每个元素上调用一个闭包：
//!
//! ```
//! # #![allow(unused_must_use)]
//! # #![allow(map_unit_fn)]
//! let v = vec![1, 2, 3, 4, 5];
//! v.iter().map(|x| println!("{x}"));
//! ```
//!
//! 这将不会打印任何值，因为我们只是创建了一个迭代器，而不是使用它。编译器将警告我们这种行为：
//!
//! ```text
//! warning: unused result that must be used: iterators are lazy and
//! do nothing unless consumed
//! ```
//!
//! 编写 [`map`] 的副作用的惯用方式是使用 `for` 循环或调用 [`for_each`] 方法：
//!
//! ```
//! let v = vec![1, 2, 3, 4, 5];
//!
//! v.iter().for_each(|x| println!("{x}"));
//! // or
//! for x in &v {
//!     println!("{x}");
//! }
//! ```
//!
//! [`map`]: Iterator::map
//! [`for_each`]: Iterator::for_each
//!
//! 评估迭代器的另一种常见方法是使用 [`collect`] 方法来生成新的集合。
//!
//! [`collect`]: Iterator::collect
//!
//! # Infinity
//!
//! 迭代器不必一定是有限的。例如，开放式范围是一个无限迭代器：
//!
//! ```
//! let numbers = 0..;
//! ```
//!
//! 通常使用 [`take`] 迭代器适配器将无限迭代器转换为有限迭代器：
//!
//! ```
//! let numbers = 0..;
//! let five_numbers = numbers.take(5);
//!
//! for number in five_numbers {
//!     println!("{number}");
//! }
//! ```
//!
//! 这将在各自的行上打印数字 `0` 至 `4`。
//!
//! 请记住，无限迭代器上的方法，即使是可以在有限时间内通过数学方法确定结果的方法，也可能不会终止。
//! 具体来说，通常需要遍历迭代器中每个元素的方法 (如 [`min`]) 对于任何无限迭代器都可能不会成功返回。
//!
//! ```no_run
//! let ones = std::iter::repeat(1);
//! let least = ones.min().unwrap(); // 不好了！ 无限循环！
//! // `ones.min()` 会导致无限循环，所以我们不会达到这一点！
//! println!("The smallest number one is {least}.");
//! ```
//!
//! [`take`]: Iterator::take
//! [`min`]: Iterator::min
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

#![stable(feature = "rust1", since = "1.0.0")]

// 这需要在这里才能在子模块中使用
macro_rules! impl_fold_via_try_fold {
    (fold -> try_fold) => {
        impl_fold_via_try_fold! { @internal fold -> try_fold }
    };
    (rfold -> try_rfold) => {
        impl_fold_via_try_fold! { @internal rfold -> try_rfold }
    };
    (@internal $fold:ident -> $try_fold:ident) => {
        #[inline]
        fn $fold<AAA, FFF>(mut self, init: AAA, fold: FFF) -> AAA
        where
            FFF: FnMut(AAA, Self::Item) -> AAA,
        {
            use crate::ops::NeverShortCircuit;

            self.$try_fold(init, NeverShortCircuit::wrap_mut_2(fold)).0
        }
    };
}

#[stable(feature = "rust1", since = "1.0.0")]
pub use self::traits::Iterator;

#[unstable(
    feature = "step_trait",
    reason = "likely to be replaced by finer-grained traits",
    issue = "42168"
)]
pub use self::range::Step;

#[unstable(
    feature = "iter_from_generator",
    issue = "43122",
    reason = "generators are unstable"
)]
pub use self::sources::from_generator;
#[stable(feature = "iter_empty", since = "1.2.0")]
pub use self::sources::{empty, Empty};
#[stable(feature = "iter_from_fn", since = "1.34.0")]
pub use self::sources::{from_fn, FromFn};
#[stable(feature = "iter_once", since = "1.2.0")]
pub use self::sources::{once, Once};
#[stable(feature = "iter_once_with", since = "1.43.0")]
pub use self::sources::{once_with, OnceWith};
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::sources::{repeat, Repeat};
#[unstable(feature = "iter_repeat_n", issue = "104434")]
pub use self::sources::{repeat_n, RepeatN};
#[stable(feature = "iterator_repeat_with", since = "1.28.0")]
pub use self::sources::{repeat_with, RepeatWith};
#[stable(feature = "iter_successors", since = "1.34.0")]
pub use self::sources::{successors, Successors};

#[stable(feature = "fused", since = "1.26.0")]
pub use self::traits::FusedIterator;
#[unstable(issue = "none", feature = "inplace_iteration")]
pub use self::traits::InPlaceIterable;
#[unstable(feature = "trusted_len", issue = "37572")]
pub use self::traits::TrustedLen;
#[unstable(feature = "trusted_step", issue = "85731")]
pub use self::traits::TrustedStep;
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::traits::{
    DoubleEndedIterator, ExactSizeIterator, Extend, FromIterator, IntoIterator, Product, Sum,
};

#[stable(feature = "iter_zip", since = "1.59.0")]
pub use self::adapters::zip;
#[unstable(feature = "iter_array_chunks", reason = "recently added", issue = "100450")]
pub use self::adapters::ArrayChunks;
#[unstable(feature = "std_internals", issue = "none")]
pub use self::adapters::ByRefSized;
#[stable(feature = "iter_cloned", since = "1.1.0")]
pub use self::adapters::Cloned;
#[stable(feature = "iter_copied", since = "1.36.0")]
pub use self::adapters::Copied;
#[stable(feature = "iterator_flatten", since = "1.29.0")]
pub use self::adapters::Flatten;
#[stable(feature = "iter_map_while", since = "1.57.0")]
pub use self::adapters::MapWhile;
#[unstable(feature = "inplace_iteration", issue = "none")]
pub use self::adapters::SourceIter;
#[stable(feature = "iterator_step_by", since = "1.28.0")]
pub use self::adapters::StepBy;
#[unstable(feature = "trusted_random_access", issue = "none")]
pub use self::adapters::TrustedRandomAccess;
#[unstable(feature = "trusted_random_access", issue = "none")]
pub use self::adapters::TrustedRandomAccessNoCoerce;
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::adapters::{
    Chain, Cycle, Enumerate, Filter, FilterMap, FlatMap, Fuse, Inspect, Map, Peekable, Rev, Scan,
    Skip, SkipWhile, Take, TakeWhile, Zip,
};
#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")]
pub use self::adapters::{Intersperse, IntersperseWith};

pub(crate) use self::adapters::try_process;
pub(crate) use self::traits::UncheckedIterator;

mod adapters;
mod range;
mod sources;
mod traits;