1 | use crate::fmt; |
2 | use crate::iter::{FusedIterator, TrustedLen}; |
3 | use crate::ops::Try; |
4 | |
5 | /// Creates a new iterator that repeats elements of type `A` endlessly by |
6 | /// applying the provided closure, the repeater, `F: FnMut() -> A`. |
7 | /// |
8 | /// The `repeat_with()` function calls the repeater over and over again. |
9 | /// |
10 | /// Infinite iterators like `repeat_with()` are often used with adapters like |
11 | /// [`Iterator::take()`], in order to make them finite. |
12 | /// |
13 | /// If the element type of the iterator you need implements [`Clone`], and |
14 | /// it is OK to keep the source element in memory, you should instead use |
15 | /// the [`repeat()`] function. |
16 | /// |
17 | /// An iterator produced by `repeat_with()` is not a [`DoubleEndedIterator`]. |
18 | /// If you need `repeat_with()` to return a [`DoubleEndedIterator`], |
19 | /// please open a GitHub issue explaining your use case. |
20 | /// |
21 | /// [`repeat()`]: crate::iter::repeat |
22 | /// |
23 | /// # Examples |
24 | /// |
25 | /// Basic usage: |
26 | /// |
27 | /// ``` |
28 | /// use std::iter; |
29 | /// |
30 | /// // let's assume we have some value of a type that is not `Clone` |
31 | /// // or which we don't want to have in memory just yet because it is expensive: |
32 | /// #[derive(PartialEq, Debug)] |
33 | /// struct Expensive; |
34 | /// |
35 | /// // a particular value forever: |
36 | /// let mut things = iter::repeat_with(|| Expensive); |
37 | /// |
38 | /// assert_eq!(Some(Expensive), things.next()); |
39 | /// assert_eq!(Some(Expensive), things.next()); |
40 | /// assert_eq!(Some(Expensive), things.next()); |
41 | /// assert_eq!(Some(Expensive), things.next()); |
42 | /// assert_eq!(Some(Expensive), things.next()); |
43 | /// ``` |
44 | /// |
45 | /// Using mutation and going finite: |
46 | /// |
47 | /// ```rust |
48 | /// use std::iter; |
49 | /// |
50 | /// // From the zeroth to the third power of two: |
51 | /// let mut curr = 1; |
52 | /// let mut pow2 = iter::repeat_with(|| { let tmp = curr; curr *= 2; tmp }) |
53 | /// .take(4); |
54 | /// |
55 | /// assert_eq!(Some(1), pow2.next()); |
56 | /// assert_eq!(Some(2), pow2.next()); |
57 | /// assert_eq!(Some(4), pow2.next()); |
58 | /// assert_eq!(Some(8), pow2.next()); |
59 | /// |
60 | /// // ... and now we're done |
61 | /// assert_eq!(None, pow2.next()); |
62 | /// ``` |
63 | #[inline ] |
64 | #[stable (feature = "iterator_repeat_with" , since = "1.28.0" )] |
65 | pub fn repeat_with<A, F: FnMut() -> A>(repeater: F) -> RepeatWith<F> { |
66 | RepeatWith { repeater } |
67 | } |
68 | |
69 | /// An iterator that repeats elements of type `A` endlessly by |
70 | /// applying the provided closure `F: FnMut() -> A`. |
71 | /// |
72 | /// This `struct` is created by the [`repeat_with()`] function. |
73 | /// See its documentation for more. |
74 | #[derive (Copy, Clone)] |
75 | #[stable (feature = "iterator_repeat_with" , since = "1.28.0" )] |
76 | pub struct RepeatWith<F> { |
77 | repeater: F, |
78 | } |
79 | |
80 | #[stable (feature = "iterator_repeat_with_debug" , since = "1.68.0" )] |
81 | impl<F> fmt::Debug for RepeatWith<F> { |
82 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
83 | f.debug_struct(name:"RepeatWith" ).finish_non_exhaustive() |
84 | } |
85 | } |
86 | |
87 | #[stable (feature = "iterator_repeat_with" , since = "1.28.0" )] |
88 | impl<A, F: FnMut() -> A> Iterator for RepeatWith<F> { |
89 | type Item = A; |
90 | |
91 | #[inline ] |
92 | fn next(&mut self) -> Option<A> { |
93 | Some((self.repeater)()) |
94 | } |
95 | |
96 | #[inline ] |
97 | fn size_hint(&self) -> (usize, Option<usize>) { |
98 | (usize::MAX, None) |
99 | } |
100 | |
101 | #[inline ] |
102 | fn try_fold<Acc, Fold, R>(&mut self, mut init: Acc, mut fold: Fold) -> R |
103 | where |
104 | Fold: FnMut(Acc, Self::Item) -> R, |
105 | R: Try<Output = Acc>, |
106 | { |
107 | // This override isn't strictly needed, but avoids the need to optimize |
108 | // away the `next`-always-returns-`Some` and emphasizes that the `?` |
109 | // is the only way to exit the loop. |
110 | |
111 | loop { |
112 | let item = (self.repeater)(); |
113 | init = fold(init, item)?; |
114 | } |
115 | } |
116 | } |
117 | |
118 | #[stable (feature = "iterator_repeat_with" , since = "1.28.0" )] |
119 | impl<A, F: FnMut() -> A> FusedIterator for RepeatWith<F> {} |
120 | |
121 | #[unstable (feature = "trusted_len" , issue = "37572" )] |
122 | unsafe impl<A, F: FnMut() -> A> TrustedLen for RepeatWith<F> {} |
123 | |