1 //! Iterators that are sources (produce elements from parameters,
2 //! not from another iterator).
3 #![allow(deprecated)]
4
5 use std::fmt;
6 use std::mem;
7
8 /// See [`repeat_call`](../fn.repeat_call.html) for more information.
9 #[derive(Clone)]
10 #[deprecated(note="Use std repeat_with() instead", since="0.8")]
11 pub struct RepeatCall<F> {
12 f: F,
13 }
14
15 impl<F> fmt::Debug for RepeatCall<F>
16 {
17 debug_fmt_fields!(RepeatCall, );
18 }
19
20 /// An iterator source that produces elements indefinitely by calling
21 /// a given closure.
22 ///
23 /// Iterator element type is the return type of the closure.
24 ///
25 /// ```
26 /// use itertools::repeat_call;
27 /// use itertools::Itertools;
28 /// use std::collections::BinaryHeap;
29 ///
30 /// let mut heap = BinaryHeap::from(vec![2, 5, 3, 7, 8]);
31 ///
32 /// // extract each element in sorted order
33 /// for element in repeat_call(|| heap.pop()).while_some() {
34 /// print!("{}", element);
35 /// }
36 ///
37 /// itertools::assert_equal(
38 /// repeat_call(|| 1).take(5),
39 /// vec![1, 1, 1, 1, 1]
40 /// );
41 /// ```
42 #[deprecated(note="Use std repeat_with() instead", since="0.8")]
repeat_call<F, A>(function: F) -> RepeatCall<F> where F: FnMut() -> A43 pub fn repeat_call<F, A>(function: F) -> RepeatCall<F>
44 where F: FnMut() -> A
45 {
46 RepeatCall { f: function }
47 }
48
49 impl<A, F> Iterator for RepeatCall<F>
50 where F: FnMut() -> A
51 {
52 type Item = A;
53
54 #[inline]
next(&mut self) -> Option<A>55 fn next(&mut self) -> Option<A> {
56 Some((self.f)())
57 }
58
size_hint(&self) -> (usize, Option<usize>)59 fn size_hint(&self) -> (usize, Option<usize>) {
60 (usize::max_value(), None)
61 }
62 }
63
64 /// Creates a new unfold source with the specified closure as the "iterator
65 /// function" and an initial state to eventually pass to the closure
66 ///
67 /// `unfold` is a general iterator builder: it has a mutable state value,
68 /// and a closure with access to the state that produces the next value.
69 ///
70 /// This more or less equivalent to a regular struct with an `Iterator`
71 /// implementation, and is useful for one-off iterators.
72 ///
73 /// ```
74 /// // an iterator that yields sequential Fibonacci numbers,
75 /// // and stops at the maximum representable value.
76 ///
77 /// use itertools::unfold;
78 ///
79 /// let (mut x1, mut x2) = (1u32, 1u32);
80 /// let mut fibonacci = unfold((), move |_| {
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 /// return None;
92 /// }
93 ///
94 /// Some(ret)
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 /// ```
unfold<A, St, F>(initial_state: St, f: F) -> Unfold<St, F> where F: FnMut(&mut St) -> Option<A>101 pub fn unfold<A, St, F>(initial_state: St, f: F) -> Unfold<St, F>
102 where F: FnMut(&mut St) -> Option<A>
103 {
104 Unfold {
105 f,
106 state: initial_state,
107 }
108 }
109
110 impl<St, F> fmt::Debug for Unfold<St, F>
111 where St: fmt::Debug,
112 {
113 debug_fmt_fields!(Unfold, state);
114 }
115
116 /// See [`unfold`](../fn.unfold.html) for more information.
117 #[derive(Clone)]
118 #[must_use = "iterators are lazy and do nothing unless consumed"]
119 pub struct Unfold<St, F> {
120 f: F,
121 /// Internal state that will be passed to the closure on the next iteration
122 pub state: St,
123 }
124
125 impl<A, St, F> Iterator for Unfold<St, F>
126 where F: FnMut(&mut St) -> Option<A>
127 {
128 type Item = A;
129
130 #[inline]
next(&mut self) -> Option<A>131 fn next(&mut self) -> Option<A> {
132 (self.f)(&mut self.state)
133 }
134
135 #[inline]
size_hint(&self) -> (usize, Option<usize>)136 fn size_hint(&self) -> (usize, Option<usize>) {
137 // no possible known bounds at this point
138 (0, None)
139 }
140 }
141
142 /// An iterator that infinitely applies function to value and yields results.
143 ///
144 /// This `struct` is created by the [`iterate()`] function. See its documentation for more.
145 ///
146 /// [`iterate()`]: ../fn.iterate.html
147 #[derive(Clone)]
148 #[must_use = "iterators are lazy and do nothing unless consumed"]
149 pub struct Iterate<St, F> {
150 state: St,
151 f: F,
152 }
153
154 impl<St, F> fmt::Debug for Iterate<St, F>
155 where St: fmt::Debug,
156 {
157 debug_fmt_fields!(Iterate, state);
158 }
159
160 impl<St, F> Iterator for Iterate<St, F>
161 where F: FnMut(&St) -> St
162 {
163 type Item = St;
164
165 #[inline]
next(&mut self) -> Option<Self::Item>166 fn next(&mut self) -> Option<Self::Item> {
167 let next_state = (self.f)(&self.state);
168 Some(mem::replace(&mut self.state, next_state))
169 }
170
171 #[inline]
size_hint(&self) -> (usize, Option<usize>)172 fn size_hint(&self) -> (usize, Option<usize>) {
173 (usize::max_value(), None)
174 }
175 }
176
177 /// Creates a new iterator that infinitely applies function to value and yields results.
178 ///
179 /// ```
180 /// use itertools::iterate;
181 ///
182 /// itertools::assert_equal(iterate(1, |&i| i * 3).take(5), vec![1, 3, 9, 27, 81]);
183 /// ```
iterate<St, F>(initial_value: St, f: F) -> Iterate<St, F> where F: FnMut(&St) -> St184 pub fn iterate<St, F>(initial_value: St, f: F) -> Iterate<St, F>
185 where F: FnMut(&St) -> St
186 {
187 Iterate {
188 state: initial_value,
189 f,
190 }
191 }
192