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 )]
unfold<A, St, F>(initial_state: St, f: F) -> Unfold<St, F> where F: FnMut(&mut St) -> Option<A>,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]
next(&mut self) -> Option<Self::Item>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]
next(&mut self) -> Option<Self::Item>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]
size_hint(&self) -> (usize, Option<usize>)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.
iterate<St, F>(initial_value: St, f: F) -> Iterate<St, F> where F: FnMut(&St) -> St,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 }
154