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