src/libcore/iter/traits/exact_size.rs

   1 /// An iterator that knows its exact length.
   2 ///
   3 /// Many [`Iterator`]s don't know how many times they will iterate, but some do.
   4 /// If an iterator knows how many times it can iterate, providing access to
   5 /// that information can be useful. For example, if you want to iterate
   6 /// backwards, a good start is to know where the end is.
   7 ///
   8 /// When implementing an `ExactSizeIterator`, you must also implement
   9 /// [`Iterator`]. When doing so, the implementation of [`size_hint`] *must*
  10 /// return the exact size of the iterator.
  11 ///
  12 /// [`Iterator`]: trait.Iterator.html
  13 /// [`size_hint`]: trait.Iterator.html#method.size_hint
  14 ///
  15 /// The [`len`] method has a default implementation, so you usually shouldn't
  16 /// implement it. However, you may be able to provide a more performant
  17 /// implementation than the default, so overriding it in this case makes sense.
  18 ///
  19 /// [`len`]: #method.len
  20 ///
  21 /// # Examples
  22 ///
  23 /// Basic usage:
  24 ///
  25 /// ```
  26 /// // a finite range knows exactly how many times it will iterate
  27 /// let five = 0..5;
  28 ///
  29 /// assert_eq!(5, five.len());
  30 /// ```
  31 ///
  32 /// In the [module level docs][moddocs], we implemented an [`Iterator`],
  33 /// `Counter`. Let's implement `ExactSizeIterator` for it as well:
  34 ///
  35 /// [moddocs]: index.html
  36 ///
  37 /// ```
  38 /// # struct Counter {
  39 /// #     count: usize,
  40 /// # }
  41 /// # impl Counter {
  42 /// #     fn new() -> Counter {
  43 /// #         Counter { count: 0 }
  44 /// #     }
  45 /// # }
  46 /// # impl Iterator for Counter {
  47 /// #     type Item = usize;
  48 /// #     fn next(&mut self) -> Option<Self::Item> {
  49 /// #         self.count += 1;
  50 /// #         if self.count < 6 {
  51 /// #             Some(self.count)
  52 /// #         } else {
  53 /// #             None
  54 /// #         }
  55 /// #     }
  56 /// # }
  57 /// impl ExactSizeIterator for Counter {
  58 ///     // We can easily calculate the remaining number of iterations.
  59 ///     fn len(&self) -> usize {
  60 ///         5 - self.count
  61 ///     }
  62 /// }
  63 ///
  64 /// // And now we can use it!
  65 ///
  66 /// let counter = Counter::new();
  67 ///
  68 /// assert_eq!(5, counter.len());
  69 /// ```
  70 #[stable(feature = "rust1", since = "1.0.0")]
  71 pub trait ExactSizeIterator: Iterator {
  72     /// Returns the exact length of the iterator, which is the number of times
  73     /// the iterator will return `Some(T)` before returning `None`.
  74     ///
  75     /// This method has a default implementation, so you usually should not
  76     /// implement it directly. However, if you can provide a more efficient
  77     /// implementation, you can do so. See the [trait-level] docs for an
  78     /// example.
  79     ///
  80     /// This function has the same safety guarantees as the [`size_hint`]
  81     /// function.
  82     ///
  83     /// [trait-level]: trait.ExactSizeIterator.html
  84     /// [`size_hint`]: trait.Iterator.html#method.size_hint
  85     ///
  86     /// # Examples
  87     ///
  88     /// Basic usage:
  89     ///
  90     /// ```
  91     /// // a finite range knows exactly how many times it will iterate
  92     /// let five = 0..5;
  93     ///
  94     /// assert_eq!(5, five.len());
  95     /// ```
  96     #[inline]
  97     #[stable(feature = "rust1", since = "1.0.0")]
  98     fn len(&self) -> usize {
  99         let (lower, upper) = self.size_hint();
 100         // Note: This assertion is overly defensive, but it checks the invariant
 101         // guaranteed by the trait. If this trait were rust-internal,
 102         // we could use debug_assert!; assert_eq! will check all Rust user
 103         // implementations too.
 104         assert_eq!(upper, Some(lower));
 105         lower
 106     }
 107
 108     /// Returns `true` if the iterator is empty.
 109     ///
 110     /// This method has a default implementation using `self.len()`, so you
 111     /// don't need to implement it yourself.
 112     ///
 113     /// # Examples
 114     ///
 115     /// Basic usage:
 116     ///
 117     /// ```
 118     /// #![feature(exact_size_is_empty)]
 119     ///
 120     /// let mut one_element = std::iter::once(0);
 121     /// assert!(!one_element.is_empty());
 122     ///
 123     /// assert_eq!(one_element.next(), Some(0));
 124     /// assert!(one_element.is_empty());
 125     ///
 126     /// assert_eq!(one_element.next(), None);
 127     /// ```
 128     #[inline]
 129     #[unstable(feature = "exact_size_is_empty", issue = "35428")]
 130     fn is_empty(&self) -> bool {
 131         self.len() == 0
 132     }
 133 }
 134
 135 #[stable(feature = "rust1", since = "1.0.0")]
 136 impl<I: ExactSizeIterator + ?Sized> ExactSizeIterator for &mut I {
 137     fn len(&self) -> usize {
 138         (**self).len()
 139     }
 140     fn is_empty(&self) -> bool {
 141         (**self).is_empty()
 142     }
 143 }