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.0")]
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.0")]
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<Self::Item>55 fn next(&mut self) -> Option<Self::Item> {
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 fibonacci = unfold((1u32, 1u32), |(x1, x2)| {
80 /// // Attempt to get the next Fibonacci number
81 /// let next = x1.saturating_add(*x2);
82 ///
83 /// // Shift left: ret <- x1 <- x2 <- next
84 /// let ret = *x1;
85 /// *x1 = *x2;
86 /// *x2 = next;
87 ///
88 /// // If addition has saturated at the maximum, we are finished
89 /// if ret == *x1 && ret > 1 {
90 /// None
91 /// } else {
92 /// Some(ret)
93 /// }
94 /// });
95 ///
96 /// itertools::assert_equal(fibonacci.by_ref().take(8),
97 /// vec![1, 1, 2, 3, 5, 8, 13, 21]);
98 /// assert_eq!(fibonacci.last(), Some(2_971_215_073))
99 /// ```
unfold<A, St, F>(initial_state: St, f: F) -> Unfold<St, F> where F: FnMut(&mut St) -> Option<A>100 pub fn unfold<A, St, F>(initial_state: St, f: F) -> Unfold<St, F>
101 where F: FnMut(&mut St) -> Option<A>
102 {
103 Unfold {
104 f,
105 state: initial_state,
106 }
107 }
108
109 impl<St, F> fmt::Debug for Unfold<St, F>
110 where St: fmt::Debug,
111 {
112 debug_fmt_fields!(Unfold, state);
113 }
114
115 /// See [`unfold`](../fn.unfold.html) for more information.
116 #[derive(Clone)]
117 #[must_use = "iterators are lazy and do nothing unless consumed"]
118 pub struct Unfold<St, F> {
119 f: F,
120 /// Internal state that will be passed to the closure on the next iteration
121 pub state: St,
122 }
123
124 impl<A, St, F> Iterator for Unfold<St, F>
125 where F: FnMut(&mut St) -> Option<A>
126 {
127 type Item = A;
128
129 #[inline]
next(&mut self) -> Option<Self::Item>130 fn next(&mut self) -> Option<Self::Item> {
131 (self.f)(&mut self.state)
132 }
133 }
134
135 /// An iterator that infinitely applies function to value and yields results.
136 ///
137 /// This `struct` is created by the [`iterate()`] function. See its documentation for more.
138 ///
139 /// [`iterate()`]: ../fn.iterate.html
140 #[derive(Clone)]
141 #[must_use = "iterators are lazy and do nothing unless consumed"]
142 pub struct Iterate<St, F> {
143 state: St,
144 f: F,
145 }
146
147 impl<St, F> fmt::Debug for Iterate<St, F>
148 where St: fmt::Debug,
149 {
150 debug_fmt_fields!(Iterate, state);
151 }
152
153 impl<St, F> Iterator for Iterate<St, F>
154 where F: FnMut(&St) -> St
155 {
156 type Item = St;
157
158 #[inline]
next(&mut self) -> Option<Self::Item>159 fn next(&mut self) -> Option<Self::Item> {
160 let next_state = (self.f)(&self.state);
161 Some(mem::replace(&mut self.state, next_state))
162 }
163
164 #[inline]
size_hint(&self) -> (usize, Option<usize>)165 fn size_hint(&self) -> (usize, Option<usize>) {
166 (usize::max_value(), None)
167 }
168 }
169
170 /// Creates a new iterator that infinitely applies function to value and yields results.
171 ///
172 /// ```
173 /// use itertools::iterate;
174 ///
175 /// itertools::assert_equal(iterate(1, |&i| i * 3).take(5), vec![1, 3, 9, 27, 81]);
176 /// ```
iterate<St, F>(initial_value: St, f: F) -> Iterate<St, F> where F: FnMut(&St) -> St177 pub fn iterate<St, F>(initial_value: St, f: F) -> Iterate<St, F>
178 where F: FnMut(&St) -> St
179 {
180 Iterate {
181 state: initial_value,
182 f,
183 }
184 }
185