1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
/// 知道其确切长度的迭代器。
///
/// 许多 [`Iterator`] 不知道它们将迭代多少次,但是有些迭代器知道。
/// 如果迭代器知道可以迭代多少次,则提供对该信息的访问将很有用。
/// 例如,如果要向后迭代,一个好的开始就是知道终点在哪里。
///
/// 实现 `ExactSizeIterator` 时,还必须实现 [`Iterator`]。
/// 这样做时,[`Iterator::size_hint`] 的实现 *必须* 返回迭代器的确切大小。
///
/// [`len`] 方法具有默认实现,因此通常不应该实现它。
/// 但是,您可能能够提供比默认设置更有效的实现,因此在这种情况下将其覆盖是有道理的。
///
///
/// 请注意,此 trait 是安全的 trait,因此 *not* 和 *cannot* 不能保证返回的长度正确。
/// 这意味着 `unsafe` 代码 ** 一定不要依赖 [`Iterator::size_hint`] 的正确性。
/// 不稳定且不安全的 [`TrustedLen`](super::marker::TrustedLen) trait 提供了此额外的保证。
///
/// [`len`]: ExactSizeIterator::len
///
/// # 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 counter = Counter::new();
///
/// assert_eq!(5, 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 five = 0..5;
    ///
    /// assert_eq!(5, five.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()
    }
}