/// 知道其确切长度的迭代器。
///
/// 许多 [`Iterator`] 不知道它们将迭代多少次，但是有些迭代器知道。
/// 如果迭代器知道可以迭代多少次，则提供对该信息的访问将很有用。
/// 例如，如果要向后迭代，一个好的开始就是知道终点在哪里。
///
/// 实现 `ExactSizeIterator` 时，还必须实现 [`Iterator`]。
/// 这样做时，[`Iterator::size_hint`] 的实现 *必须* 返回迭代器的确切大小。
///
/// [`len`] 方法具有默认实现，因此通常不应该实现它。
/// 但是，您可能能够提供比默认设置更有效的实现，因此在这种情况下将其覆盖是有道理的。
///
/// 请注意，此 trait 是安全的 trait，因此 *not* 和 *cannot* 不能保证返回的长度正确。
/// 这意味着 `unsafe` 代码一定不要依赖 [`Iterator::size_hint`] 的正确性。
/// 不稳定且不安全的 [`TrustedLen`](super::marker::TrustedLen) trait 提供了此额外的保证。
///
/// [`len`]: ExactSizeIterator::len
///
/// # 什么时候*不应该*适配器是 `ExactSizeIterator`?
///
/// 如果适配器使迭代器*更长*，那么该适配器实现 `ExactSizeIterator` 通常是不正确的。
/// 内部精确大小的迭代器可能已经是 `usize::MAX`-long，因此更长的适配迭代器的长度将不再能在 `usize` 中精确表示。
///
///
/// 这就是 [`Chain<A, B>`](crate::iter::Chain) 不是 `ExactSizeIterator` 的原因，即使 `A` 和 `B` 都是 `ExactSizeIterator`。
///
/// # Examples
///
/// 基本用法：
///
/// ```
/// // 一个有限的范围确切地知道它将迭代多少次
/// let five = 0..5;
///
/// assert_eq!(5, five.len());
/// ```
///
/// 在 [模块级文档][module-level docs] 中，我们实现了 [`Iterator`]、`Counter`。
/// 让我们也为其实现 `ExactSizeIterator`：
///
/// [module-level docs]: crate::iter
///
/// ```
/// # struct Counter {
/// #     count: usize,
/// # }
/// # impl Counter {
/// #     fn new() -> Counter {
/// #         Counter { count: 0 }
/// #     }
/// # }
/// # impl Iterator for Counter {
/// #     type Item = usize;
/// #     fn next(&mut self) -> Option<Self::Item> {
/// #         self.count += 1;
/// #         if self.count < 6 {
/// #             Some(self.count)
/// #         } else {
/// #             None
/// #         }
/// #     }
/// # }
/// impl ExactSizeIterator for Counter {
///     // 我们可以轻松计算剩余的迭代次数。
///     fn len(&self) -> usize {
///         5 - self.count
///     }
/// }
///
/// // 现在我们可以使用它了！
///
/// let mut counter = Counter::new();
///
/// assert_eq!(5, counter.len());
/// let _ = counter.next();
/// assert_eq!(4, counter.len());
/// ```
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub trait ExactSizeIterator: Iterator {
    /// 返回迭代器的确切剩余长度。
    ///
    /// 该实现可确保迭代器在返回 [`None`] 之前，将返回 [`Some(T)`] 值的次数正好多于 `len()`。
    ///
    /// 此方法具有默认实现，因此通常不应直接实现它。
    /// 但是，如果您可以提供更有效的实现，则可以这样做。
    /// 有关示例，请参见 [trait-level] 文档。
    ///
    /// 该函数与 [`Iterator::size_hint`] 函数具有相同的安全保证。
    ///
    /// [trait-level]: ExactSizeIterator
    /// [`Some(T)`]: Some
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// // 一个有限的范围确切地知道它将迭代多少次
    /// let mut range = 0..5;
    ///
    /// assert_eq!(5, range.len());
    /// let _ = range.next();
    /// assert_eq!(4, range.len());
    /// ```
    ///
    ///
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    fn len(&self) -> usize {
        let (lower, upper) = self.size_hint();
        // Note: 该断言过于防御，但它检查 trait 保证的不变性。
        // 如果此 trait 是内部的 rust，则可以使用 debug_assert! ;。assert_eq！还将检查所有 Rust 用户实现。
        //
        //
        assert_eq!(upper, Some(lower));
        lower
    }

    /// 如果迭代器为空，则返回 `true`。
    ///
    /// 此方法具有使用 [`ExactSizeIterator::len()`] 的默认实现，因此您无需自己实现。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// #![feature(exact_size_is_empty)]
    ///
    /// let mut one_element = std::iter::once(0);
    /// assert!(!one_element.is_empty());
    ///
    /// assert_eq!(one_element.next(), Some(0));
    /// assert!(one_element.is_empty());
    ///
    /// assert_eq!(one_element.next(), None);
    /// ```
    #[inline]
    #[unstable(feature = "exact_size_is_empty", issue = "35428")]
    fn is_empty(&self) -> bool {
        self.len() == 0
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<I: ExactSizeIterator + ?Sized> ExactSizeIterator for &mut I {
    fn len(&self) -> usize {
        (**self).len()
    }
    fn is_empty(&self) -> bool {
        (**self).is_empty()
    }
}