vendor/itertools-0.9.0/src/sources.rs

   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 }