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/// See [`repeat_call`](crate::repeat_call) for more information.
9#[derive(Clone)]
10#[deprecated(note = "Use std repeat_with() instead", since = "0.8.0")]
11pub struct RepeatCall<F> {
12 f: F,
13}
14
15impl<F> fmt::Debug for RepeatCall<F> {
16 debug_fmt_fields!(RepeatCall,);
17}
18
19/// An iterator source that produces elements indefinitely by calling
20/// a given closure.
21///
22/// Iterator element type is the return type of the closure.
23///
24/// ```
25/// use itertools::repeat_call;
26/// use itertools::Itertools;
27/// use std::collections::BinaryHeap;
28///
29/// let mut heap = BinaryHeap::from(vec![2, 5, 3, 7, 8]);
30///
31/// // extract each element in sorted order
32/// for element in repeat_call(|| heap.pop()).while_some() {
33/// print!("{}", element);
34/// }
35///
36/// itertools::assert_equal(
37/// repeat_call(|| 1).take(5),
38/// vec![1, 1, 1, 1, 1]
39/// );
40/// ```
41#[deprecated(note = "Use std repeat_with() instead", since = "0.8.0")]
42pub fn repeat_call<F, A>(function: F) -> RepeatCall<F>
43where
44 F: FnMut() -> A,
45{
46 RepeatCall { f: function }
47}
48
49impl<A, F> Iterator for RepeatCall<F>
50where
51 F: FnMut() -> A,
52{
53 type Item = A;
54
55 #[inline]
56 fn next(&mut self) -> Option<Self::Item> {
57 Some((self.f)())
58 }
59
60 fn size_hint(&self) -> (usize, Option<usize>) {
61 (usize::max_value(), None)
62 }
63}
64
65/// Creates a new unfold source with the specified closure as the "iterator
66/// function" and an initial state to eventually pass to the closure
67///
68/// `unfold` is a general iterator builder: it has a mutable state value,
69/// and a closure with access to the state that produces the next value.
70///
71/// This more or less equivalent to a regular struct with an [`Iterator`]
72/// implementation, and is useful for one-off iterators.
73///
74/// ```
75/// // an iterator that yields sequential Fibonacci numbers,
76/// // and stops at the maximum representable value.
77///
78/// use itertools::unfold;
79///
80/// let mut fibonacci = unfold((1u32, 1u32), |(x1, x2)| {
81/// // Attempt to get the next Fibonacci number
82/// let next = x1.saturating_add(*x2);
83///
84/// // Shift left: ret <- x1 <- x2 <- next
85/// let ret = *x1;
86/// *x1 = *x2;
87/// *x2 = next;
88///
89/// // If addition has saturated at the maximum, we are finished
90/// if ret == *x1 && ret > 1 {
91/// None
92/// } else {
93/// Some(ret)
94/// }
95/// });
96///
97/// itertools::assert_equal(fibonacci.by_ref().take(8),
98/// vec![1, 1, 2, 3, 5, 8, 13, 21]);
99/// assert_eq!(fibonacci.last(), Some(2_971_215_073))
100/// ```
101pub fn unfold<A, St, F>(initial_state: St, f: F) -> Unfold<St, F>
102where
103 F: FnMut(&mut St) -> Option<A>,
104{
105 Unfold {
106 f,
107 state: initial_state,
108 }
109}
110
111impl<St, F> fmt::Debug for Unfold<St, F>
112where
113 St: fmt::Debug,
114{
115 debug_fmt_fields!(Unfold, state);
116}
117
118/// See [`unfold`](crate::unfold) for more information.
119#[derive(Clone)]
120#[must_use = "iterators are lazy and do nothing unless consumed"]
121pub struct Unfold<St, F> {
122 f: F,
123 /// Internal state that will be passed to the closure on the next iteration
124 pub state: St,
125}
126
127impl<A, St, F> Iterator for Unfold<St, F>
128where
129 F: FnMut(&mut St) -> Option<A>,
130{
131 type Item = A;
132
133 #[inline]
134 fn next(&mut self) -> Option<Self::Item> {
135 (self.f)(&mut self.state)
136 }
137}
138
139/// An iterator that infinitely applies function to value and yields results.
140///
141/// This `struct` is created by the [`iterate()`](crate::iterate) function.
142/// See its documentation for more.
143#[derive(Clone)]
144#[must_use = "iterators are lazy and do nothing unless consumed"]
145pub struct Iterate<St, F> {
146 state: St,
147 f: F,
148}
149
150impl<St, F> fmt::Debug for Iterate<St, F>
151where
152 St: fmt::Debug,
153{
154 debug_fmt_fields!(Iterate, state);
155}
156
157impl<St, F> Iterator for Iterate<St, F>
158where
159 F: FnMut(&St) -> St,
160{
161 type Item = St;
162
163 #[inline]
164 fn next(&mut self) -> Option<Self::Item> {
165 let next_state: St = (self.f)(&self.state);
166 Some(mem::replace(&mut self.state, src:next_state))
167 }
168
169 #[inline]
170 fn size_hint(&self) -> (usize, Option<usize>) {
171 (usize::max_value(), None)
172 }
173}
174
175/// Creates a new iterator that infinitely applies function to value and yields results.
176///
177/// ```
178/// use itertools::iterate;
179///
180/// itertools::assert_equal(iterate(1, |i| i % 3 + 1).take(5), vec![1, 2, 3, 1, 2]);
181/// ```
182///
183/// **Panics** if compute the next value does.
184///
185/// ```should_panic
186/// # use itertools::iterate;
187/// let mut it = iterate(25u32, |x| x - 10).take_while(|&x| x > 10);
188/// assert_eq!(it.next(), Some(25)); // `Iterate` holds 15.
189/// assert_eq!(it.next(), Some(15)); // `Iterate` holds 5.
190/// it.next(); // `5 - 10` overflows.
191/// ```
192///
193/// You can alternatively use [`core::iter::successors`] as it better describes a finite iterator.
194pub fn iterate<St, F>(initial_value: St, f: F) -> Iterate<St, F>
195where
196 F: FnMut(&St) -> St,
197{
198 Iterate {
199 state: initial_value,
200 f,
201 }
202}
203