core/iter/sources/repeat_with.rs
1use crate::fmt;
2use crate::iter::{FusedIterator, TrustedLen};
3use 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")]
65pub 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")]
76pub struct RepeatWith<F> {
77 repeater: F,
78}
79
80#[stable(feature = "iterator_repeat_with_debug", since = "1.68.0")]
81impl<F> fmt::Debug for RepeatWith<F> {
82 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
83 f.debug_struct("RepeatWith").finish_non_exhaustive()
84 }
85}
86
87#[stable(feature = "iterator_repeat_with", since = "1.28.0")]
88impl<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")]
119impl<A, F: FnMut() -> A> FusedIterator for RepeatWith<F> {}
120
121#[unstable(feature = "trusted_len", issue = "37572")]
122unsafe impl<A, F: FnMut() -> A> TrustedLen for RepeatWith<F> {}