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