library/core/src/iter/sources/repeat.rs

   1 use crate::iter::{FusedIterator, TrustedLen};
   2
   3 /// Creates a new iterator that endlessly repeats a single element.
   4 ///
   5 /// The `repeat()` function repeats a single value over and over again.
   6 ///
   7 /// Infinite iterators like `repeat()` are often used with adapters like
   8 /// [`Iterator::take()`], in order to make them finite.
   9 ///
  10 /// If the element type of the iterator you need does not implement `Clone`,
  11 /// or if you do not want to keep the repeated element in memory, you can
  12 /// instead use the [`repeat_with()`] function.
  13 ///
  14 /// [`repeat_with()`]: crate::iter::repeat_with
  15 ///
  16 /// # Examples
  17 ///
  18 /// Basic usage:
  19 ///
  20 /// ```
  21 /// use std::iter;
  22 ///
  23 /// // the number four 4ever:
  24 /// let mut fours = iter::repeat(4);
  25 ///
  26 /// assert_eq!(Some(4), fours.next());
  27 /// assert_eq!(Some(4), fours.next());
  28 /// assert_eq!(Some(4), fours.next());
  29 /// assert_eq!(Some(4), fours.next());
  30 /// assert_eq!(Some(4), fours.next());
  31 ///
  32 /// // yup, still four
  33 /// assert_eq!(Some(4), fours.next());
  34 /// ```
  35 ///
  36 /// Going finite with [`Iterator::take()`]:
  37 ///
  38 /// ```
  39 /// use std::iter;
  40 ///
  41 /// // that last example was too many fours. Let's only have four fours.
  42 /// let mut four_fours = iter::repeat(4).take(4);
  43 ///
  44 /// assert_eq!(Some(4), four_fours.next());
  45 /// assert_eq!(Some(4), four_fours.next());
  46 /// assert_eq!(Some(4), four_fours.next());
  47 /// assert_eq!(Some(4), four_fours.next());
  48 ///
  49 /// // ... and now we're done
  50 /// assert_eq!(None, four_fours.next());
  51 /// ```
  52 #[inline]
  53 #[stable(feature = "rust1", since = "1.0.0")]
  54 pub fn repeat<T: Clone>(elt: T) -> Repeat<T> {
  55     Repeat { element: elt }
  56 }
  57
  58 /// An iterator that repeats an element endlessly.
  59 ///
  60 /// This `struct` is created by the [`repeat()`] function. See its documentation for more.
  61 #[derive(Clone, Debug)]
  62 #[stable(feature = "rust1", since = "1.0.0")]
  63 pub struct Repeat<A> {
  64     element: A,
  65 }
  66
  67 #[stable(feature = "rust1", since = "1.0.0")]
  68 impl<A: Clone> Iterator for Repeat<A> {
  69     type Item = A;
  70
  71     #[inline]
  72     fn next(&mut self) -> Option<A> {
  73         Some(self.element.clone())
  74     }
  75
  76     #[inline]
  77     fn size_hint(&self) -> (usize, Option<usize>) {
  78         (usize::MAX, None)
  79     }
  80
  81     #[inline]
  82     fn advance_by(&mut self, n: usize) -> Result<(), usize> {
  83         // Advancing an infinite iterator of a single element is a no-op.
  84         let _ = n;
  85         Ok(())
  86     }
  87
  88     #[inline]
  89     fn nth(&mut self, n: usize) -> Option<A> {
  90         let _ = n;
  91         Some(self.element.clone())
  92     }
  93
  94     fn last(self) -> Option<A> {
  95         loop {}
  96     }
  97
  98     fn count(self) -> usize {
  99         loop {}
 100     }
 101 }
 102
 103 #[stable(feature = "rust1", since = "1.0.0")]
 104 impl<A: Clone> DoubleEndedIterator for Repeat<A> {
 105     #[inline]
 106     fn next_back(&mut self) -> Option<A> {
 107         Some(self.element.clone())
 108     }
 109
 110     #[inline]
 111     fn advance_back_by(&mut self, n: usize) -> Result<(), usize> {
 112         // Advancing an infinite iterator of a single element is a no-op.
 113         let _ = n;
 114         Ok(())
 115     }
 116
 117     #[inline]
 118     fn nth_back(&mut self, n: usize) -> Option<A> {
 119         let _ = n;
 120         Some(self.element.clone())
 121     }
 122 }
 123
 124 #[stable(feature = "fused", since = "1.26.0")]
 125 impl<A: Clone> FusedIterator for Repeat<A> {}
 126
 127 #[unstable(feature = "trusted_len", issue = "37572")]
 128 unsafe impl<A: Clone> TrustedLen for Repeat<A> {}