| 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 |
/// Creates a new unfold source with the specified closure as the "iterator |
| 9 |
/// function" and an initial state to eventually pass to the closure |
| 10 |
/// |
| 11 |
/// `unfold` is a general iterator builder: it has a mutable state value, |
| 12 |
/// and a closure with access to the state that produces the next value. |
| 13 |
/// |
| 14 |
/// This more or less equivalent to a regular struct with an [`Iterator`] |
| 15 |
/// implementation, and is useful for one-off iterators. |
| 16 |
/// |
| 17 |
/// ``` |
| 18 |
/// // an iterator that yields sequential Fibonacci numbers, |
| 19 |
/// // and stops at the maximum representable value. |
| 20 |
/// |
| 21 |
/// use itertools::unfold; |
| 22 |
/// |
| 23 |
/// let mut fibonacci = unfold((1u32, 1u32), |(x1, x2)| { |
| 24 |
/// // Attempt to get the next Fibonacci number |
| 25 |
/// let next = x1.saturating_add(*x2); |
| 26 |
/// |
| 27 |
/// // Shift left: ret <- x1 <- x2 <- next |
| 28 |
/// let ret = *x1; |
| 29 |
/// *x1 = *x2; |
| 30 |
/// *x2 = next; |
| 31 |
/// |
| 32 |
/// // If addition has saturated at the maximum, we are finished |
| 33 |
/// if ret == *x1 && ret > 1 { |
| 34 |
/// None |
| 35 |
/// } else { |
| 36 |
/// Some(ret) |
| 37 |
/// } |
| 38 |
/// }); |
| 39 |
/// |
| 40 |
/// itertools::assert_equal(fibonacci.by_ref().take(8), |
| 41 |
/// vec![1, 1, 2, 3, 5, 8, 13, 21]); |
| 42 |
/// assert_eq!(fibonacci.last(), Some(2_971_215_073)) |
| 43 |
/// ``` |
| 44 |
#[deprecated( |
| 45 |
note = "Use [std::iter::from_fn](https://doc.rust-lang.org/std/iter/fn.from_fn.html) instead", |
| 46 |
since = "0.13.0" |
| 47 |
)] |
| 48 |
pub fn unfold<A, St, F>(initial_state: St, f: F) -> Unfold<St, F> |
| 49 |
where |
| 50 |
F: FnMut(&mut St) -> Option<A>, |
| 51 |
{ |
| 52 |
Unfold { |
| 53 |
f, |
| 54 |
state: initial_state, |
| 55 |
} |
| 56 |
} |
| 57 |
|
| 58 |
impl<St, F> fmt::Debug for Unfold<St, F> |
| 59 |
where |
| 60 |
St: fmt::Debug, |
| 61 |
{ |
| 62 |
debug_fmt_fields!(Unfold, state); |
| 63 |
} |
| 64 |
|
| 65 |
/// See [`unfold`](crate::unfold) for more information. |
| 66 |
#[derive(Clone)] |
| 67 |
#[must_use = "iterators are lazy and do nothing unless consumed"] |
| 68 |
#[deprecated( |
| 69 |
note = "Use [std::iter::FromFn](https://doc.rust-lang.org/std/iter/struct.FromFn.html) instead", |
| 70 |
since = "0.13.0" |
| 71 |
)] |
| 72 |
pub struct Unfold<St, F> { |
| 73 |
f: F, |
| 74 |
/// Internal state that will be passed to the closure on the next iteration |
| 75 |
pub state: St, |
| 76 |
} |
| 77 |
|
| 78 |
impl<A, St, F> Iterator for Unfold<St, F> |
| 79 |
where |
| 80 |
F: FnMut(&mut St) -> Option<A>, |
| 81 |
{ |
| 82 |
type Item = A; |
| 83 |
|
| 84 |
#[inline] |
| 85 |
fn next(&mut self) -> Option<Self::Item> { |
| 86 |
(self.f)(&mut self.state) |
| 87 |
} |
| 88 |
} |
| 89 |
|
| 90 |
/// An iterator that infinitely applies function to value and yields results. |
| 91 |
/// |
| 92 |
/// This `struct` is created by the [`iterate()`](crate::iterate) function. |
| 93 |
/// See its documentation for more. |
| 94 |
#[derive(Clone)] |
| 95 |
#[must_use = "iterators are lazy and do nothing unless consumed"] |
| 96 |
pub struct Iterate<St, F> { |
| 97 |
state: St, |
| 98 |
f: F, |
| 99 |
} |
| 100 |
|
| 101 |
impl<St, F> fmt::Debug for Iterate<St, F> |
| 102 |
where |
| 103 |
St: fmt::Debug, |
| 104 |
{ |
| 105 |
debug_fmt_fields!(Iterate, state); |
| 106 |
} |
| 107 |
|
| 108 |
impl<St, F> Iterator for Iterate<St, F> |
| 109 |
where |
| 110 |
F: FnMut(&St) -> St, |
| 111 |
{ |
| 112 |
type Item = St; |
| 113 |
|
| 114 |
#[inline] |
| 115 |
fn next(&mut self) -> Option<Self::Item> { |
| 116 |
let next_state = (self.f)(&self.state); |
| 117 |
Some(mem::replace(&mut self.state, next_state)) |
| 118 |
} |
| 119 |
|
| 120 |
#[inline] |
| 121 |
fn size_hint(&self) -> (usize, Option<usize>) { |
| 122 |
(usize::MAX, None) |
| 123 |
} |
| 124 |
} |
| 125 |
|
| 126 |
/// Creates a new iterator that infinitely applies function to value and yields results. |
| 127 |
/// |
| 128 |
/// ``` |
| 129 |
/// use itertools::iterate; |
| 130 |
/// |
| 131 |
/// itertools::assert_equal(iterate(1, |i| i % 3 + 1).take(5), vec![1, 2, 3, 1, 2]); |
| 132 |
/// ``` |
| 133 |
/// |
| 134 |
/// **Panics** if compute the next value does. |
| 135 |
/// |
| 136 |
/// ```should_panic |
| 137 |
/// # use itertools::iterate; |
| 138 |
/// let mut it = iterate(25u32, |x| x - 10).take_while(|&x| x > 10); |
| 139 |
/// assert_eq!(it.next(), Some(25)); // `Iterate` holds 15. |
| 140 |
/// assert_eq!(it.next(), Some(15)); // `Iterate` holds 5. |
| 141 |
/// it.next(); // `5 - 10` overflows. |
| 142 |
/// ``` |
| 143 |
/// |
| 144 |
/// You can alternatively use [`core::iter::successors`] as it better describes a finite iterator. |
| 145 |
pub fn iterate<St, F>(initial_value: St, f: F) -> Iterate<St, F> |
| 146 |
where |
| 147 |
F: FnMut(&St) -> St, |
| 148 |
{ |
| 149 |
Iterate { |
| 150 |
state: initial_value, |
| 151 |
f, |
| 152 |
} |
| 153 |
} |