core/iter/sources/
repeat_with.rs

Help
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> {}
core/iter/sources/repeat_with.rs

core/iter/sources/
repeat_with.rs
