repeat_with.rs - source
Description: Source of the Rust file `library/core/src/iter/sources/repeat_with.rs`.

#
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> {}