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 #[cfg_attr(not(test), rustc_diagnostic_item = "iter_repeat")]
  55 pub fn repeat<T: Clone>(elt: T) -> Repeat<T> {
  56     Repeat { element: elt }
  57 }
  58
  59 /// An iterator that repeats an element endlessly.
  60 ///
  61 /// This `struct` is created by the [`repeat()`] function. See its documentation for more.
  62 #[derive(Clone, Debug)]
  63 #[stable(feature = "rust1", since = "1.0.0")]
  64 pub struct Repeat<A> {
  65     element: A,
  66 }
  67
  68 #[stable(feature = "rust1", since = "1.0.0")]
  69 impl<A: Clone> Iterator for Repeat<A> {
  70     type Item = A;
  71
  72     #[inline]
  73     fn next(&mut self) -> Option<A> {
  74         Some(self.element.clone())
  75     }
  76
  77     #[inline]
  78     fn size_hint(&self) -> (usize, Option<usize>) {
  79         (usize::MAX, None)
  80     }
  81
  82     #[inline]
  83     fn advance_by(&mut self, n: usize) -> Result<(), usize> {
  84         // Advancing an infinite iterator of a single element is a no-op.
  85         let _ = n;
  86         Ok(())
  87     }
  88
  89     #[inline]
  90     fn nth(&mut self, n: usize) -> Option<A> {
  91         let _ = n;
  92         Some(self.element.clone())
  93     }
  94
  95     fn last(self) -> Option<A> {
  96         loop {}
  97     }
  98
  99     fn count(self) -> usize {
 100         loop {}
 101     }
 102 }
 103
 104 #[stable(feature = "rust1", since = "1.0.0")]
 105 impl<A: Clone> DoubleEndedIterator for Repeat<A> {
 106     #[inline]
 107     fn next_back(&mut self) -> Option<A> {
 108         Some(self.element.clone())
 109     }
 110
 111     #[inline]
 112     fn advance_back_by(&mut self, n: usize) -> Result<(), usize> {
 113         // Advancing an infinite iterator of a single element is a no-op.
 114         let _ = n;
 115         Ok(())
 116     }
 117
 118     #[inline]
 119     fn nth_back(&mut self, n: usize) -> Option<A> {
 120         let _ = n;
 121         Some(self.element.clone())
 122     }
 123 }
 124
 125 #[stable(feature = "fused", since = "1.26.0")]
 126 impl<A: Clone> FusedIterator for Repeat<A> {}
 127
 128 #[unstable(feature = "trusted_len", issue = "37572")]
 129 unsafe impl<A: Clone> TrustedLen for Repeat<A> {}