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`](crate::repeat_call) 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`](crate::unfold) 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()`](crate::iterate) function.
138 /// See its documentation for more.
139 #[derive(Clone)]
140 #[must_use = "iterators are lazy and do nothing unless consumed"]
141 pub struct Iterate<St, F> {
142 state: St,
143 f: F,
144 }
145
146 impl<St, F> fmt::Debug for Iterate<St, F>
147 where St: fmt::Debug,
148 {
149 debug_fmt_fields!(Iterate, state);
150 }
151
152 impl<St, F> Iterator for Iterate<St, F>
153 where F: FnMut(&St) -> St
154 {
155 type Item = St;
156
157 #[inline]
next(&mut self) -> Option<Self::Item>158 fn next(&mut self) -> Option<Self::Item> {
159 let next_state = (self.f)(&self.state);
160 Some(mem::replace(&mut self.state, next_state))
161 }
162
163 #[inline]
size_hint(&self) -> (usize, Option<usize>)164 fn size_hint(&self) -> (usize, Option<usize>) {
165 (usize::max_value(), None)
166 }
167 }
168
169 /// Creates a new iterator that infinitely applies function to value and yields results.
170 ///
171 /// ```
172 /// use itertools::iterate;
173 ///
174 /// itertools::assert_equal(iterate(1, |&i| i * 3).take(5), vec![1, 3, 9, 27, 81]);
175 /// ```
iterate<St, F>(initial_value: St, f: F) -> Iterate<St, F> where F: FnMut(&St) -> St176 pub fn iterate<St, F>(initial_value: St, f: F) -> Iterate<St, F>
177 where F: FnMut(&St) -> St
178 {
179 Iterate {
180 state: initial_value,
181 f,
182 }
183 }
184