Jakub Kotur | a425e55 | 2020-12-21 17:28:15 +0100 | [diff] [blame] | 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")] |
| 43 | 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] |
| 55 | fn next(&mut self) -> Option<A> { |
| 56 | Some((self.f)()) |
| 57 | } |
| 58 | |
| 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 | /// ``` |
| 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] |
| 131 | fn next(&mut self) -> Option<A> { |
| 132 | (self.f)(&mut self.state) |
| 133 | } |
| 134 | |
| 135 | #[inline] |
| 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] |
| 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] |
| 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 | /// ``` |
| 184 | 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 | } |