itertools/
sources.rs

1//! Iterators that are sources (produce elements from parameters,
2//! not from another iterator).
3#![allow(deprecated)]
4
5use std::fmt;
6use std::mem;
7
8/// Creates a new unfold source with the specified closure as the "iterator
9/// function" and an initial state to eventually pass to the closure
10///
11/// `unfold` is a general iterator builder: it has a mutable state value,
12/// and a closure with access to the state that produces the next value.
13///
14/// This more or less equivalent to a regular struct with an [`Iterator`]
15/// implementation, and is useful for one-off iterators.
16///
17/// ```
18/// // an iterator that yields sequential Fibonacci numbers,
19/// // and stops at the maximum representable value.
20///
21/// use itertools::unfold;
22///
23/// let mut fibonacci = unfold((1u32, 1u32), |(x1, x2)| {
24///     // Attempt to get the next Fibonacci number
25///     let next = x1.saturating_add(*x2);
26///
27///     // Shift left: ret <- x1 <- x2 <- next
28///     let ret = *x1;
29///     *x1 = *x2;
30///     *x2 = next;
31///
32///     // If addition has saturated at the maximum, we are finished
33///     if ret == *x1 && ret > 1 {
34///         None
35///     } else {
36///         Some(ret)
37///     }
38/// });
39///
40/// itertools::assert_equal(fibonacci.by_ref().take(8),
41///                         vec![1, 1, 2, 3, 5, 8, 13, 21]);
42/// assert_eq!(fibonacci.last(), Some(2_971_215_073))
43/// ```
44#[deprecated(
45    note = "Use [std::iter::from_fn](https://doc.rust-lang.org/std/iter/fn.from_fn.html) instead",
46    since = "0.13.0"
47)]
48pub fn unfold<A, St, F>(initial_state: St, f: F) -> Unfold<St, F>
49where
50    F: FnMut(&mut St) -> Option<A>,
51{
52    Unfold {
53        f,
54        state: initial_state,
55    }
56}
57
58impl<St, F> fmt::Debug for Unfold<St, F>
59where
60    St: fmt::Debug,
61{
62    debug_fmt_fields!(Unfold, state);
63}
64
65/// See [`unfold`](crate::unfold) for more information.
66#[derive(Clone)]
67#[must_use = "iterators are lazy and do nothing unless consumed"]
68#[deprecated(
69    note = "Use [std::iter::FromFn](https://doc.rust-lang.org/std/iter/struct.FromFn.html) instead",
70    since = "0.13.0"
71)]
72pub struct Unfold<St, F> {
73    f: F,
74    /// Internal state that will be passed to the closure on the next iteration
75    pub state: St,
76}
77
78impl<A, St, F> Iterator for Unfold<St, F>
79where
80    F: FnMut(&mut St) -> Option<A>,
81{
82    type Item = A;
83
84    #[inline]
85    fn next(&mut self) -> Option<Self::Item> {
86        (self.f)(&mut self.state)
87    }
88}
89
90/// An iterator that infinitely applies function to value and yields results.
91///
92/// This `struct` is created by the [`iterate()`](crate::iterate) function.
93/// See its documentation for more.
94#[derive(Clone)]
95#[must_use = "iterators are lazy and do nothing unless consumed"]
96pub struct Iterate<St, F> {
97    state: St,
98    f: F,
99}
100
101impl<St, F> fmt::Debug for Iterate<St, F>
102where
103    St: fmt::Debug,
104{
105    debug_fmt_fields!(Iterate, state);
106}
107
108impl<St, F> Iterator for Iterate<St, F>
109where
110    F: FnMut(&St) -> St,
111{
112    type Item = St;
113
114    #[inline]
115    fn next(&mut self) -> Option<Self::Item> {
116        let next_state = (self.f)(&self.state);
117        Some(mem::replace(&mut self.state, next_state))
118    }
119
120    #[inline]
121    fn size_hint(&self) -> (usize, Option<usize>) {
122        (usize::MAX, None)
123    }
124}
125
126/// Creates a new iterator that infinitely applies function to value and yields results.
127///
128/// ```
129/// use itertools::iterate;
130///
131/// itertools::assert_equal(iterate(1, |i| i % 3 + 1).take(5), vec![1, 2, 3, 1, 2]);
132/// ```
133///
134/// **Panics** if compute the next value does.
135///
136/// ```should_panic
137/// # use itertools::iterate;
138/// let mut it = iterate(25u32, |x| x - 10).take_while(|&x| x > 10);
139/// assert_eq!(it.next(), Some(25)); // `Iterate` holds 15.
140/// assert_eq!(it.next(), Some(15)); // `Iterate` holds 5.
141/// it.next(); // `5 - 10` overflows.
142/// ```
143///
144/// You can alternatively use [`core::iter::successors`] as it better describes a finite iterator.
145pub fn iterate<St, F>(initial_value: St, f: F) -> Iterate<St, F>
146where
147    F: FnMut(&St) -> St,
148{
149    Iterate {
150        state: initial_value,
151        f,
152    }
153}
itertools/sources.rs

itertools/
sources.rs
