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