]>
Commit | Line | Data |
---|---|---|
1 | //! Free functions that create iterator adaptors or call iterator methods. | |
2 | //! | |
3 | //! The benefit of free functions is that they accept any `IntoIterator` as | |
4 | //! argument, so the resulting code may be easier to read. | |
5 | ||
6 | use std::fmt::Display; | |
7 | use std::iter::{self, Zip}; | |
8 | use Itertools; | |
9 | ||
10 | pub use adaptors::{ | |
11 | interleave, | |
12 | merge, | |
13 | put_back, | |
14 | put_back_n, | |
15 | }; | |
16 | pub use adaptors::multipeek::multipeek; | |
17 | pub use kmerge_impl::kmerge; | |
18 | pub use zip_eq_impl::zip_eq; | |
19 | pub use rciter_impl::rciter; | |
20 | ||
21 | /// Iterate `iterable` with a running index. | |
22 | /// | |
23 | /// `IntoIterator` enabled version of `.enumerate()`. | |
24 | /// | |
25 | /// ``` | |
26 | /// use itertools::enumerate; | |
27 | /// | |
28 | /// for (i, elt) in enumerate(&[1, 2, 3]) { | |
29 | /// /* loop body */ | |
30 | /// } | |
31 | /// ``` | |
32 | pub fn enumerate<I>(iterable: I) -> iter::Enumerate<I::IntoIter> | |
33 | where I: IntoIterator | |
34 | { | |
35 | iterable.into_iter().enumerate() | |
36 | } | |
37 | ||
38 | /// Iterate `iterable` in reverse. | |
39 | /// | |
40 | /// `IntoIterator` enabled version of `.rev()`. | |
41 | /// | |
42 | /// ``` | |
43 | /// use itertools::rev; | |
44 | /// | |
45 | /// for elt in rev(&[1, 2, 3]) { | |
46 | /// /* loop body */ | |
47 | /// } | |
48 | /// ``` | |
49 | pub fn rev<I>(iterable: I) -> iter::Rev<I::IntoIter> | |
50 | where I: IntoIterator, | |
51 | I::IntoIter: DoubleEndedIterator | |
52 | { | |
53 | iterable.into_iter().rev() | |
54 | } | |
55 | ||
56 | /// Iterate `i` and `j` in lock step. | |
57 | /// | |
58 | /// `IntoIterator` enabled version of `i.zip(j)`. | |
59 | /// | |
60 | /// ``` | |
61 | /// use itertools::zip; | |
62 | /// | |
63 | /// let data = [1, 2, 3, 4, 5]; | |
64 | /// for (a, b) in zip(&data, &data[1..]) { | |
65 | /// /* loop body */ | |
66 | /// } | |
67 | /// ``` | |
68 | pub fn zip<I, J>(i: I, j: J) -> Zip<I::IntoIter, J::IntoIter> | |
69 | where I: IntoIterator, | |
70 | J: IntoIterator | |
71 | { | |
72 | i.into_iter().zip(j) | |
73 | } | |
74 | ||
75 | /// Create an iterator that first iterates `i` and then `j`. | |
76 | /// | |
77 | /// `IntoIterator` enabled version of `i.chain(j)`. | |
78 | /// | |
79 | /// ``` | |
80 | /// use itertools::chain; | |
81 | /// | |
82 | /// for elt in chain(&[1, 2, 3], &[4]) { | |
83 | /// /* loop body */ | |
84 | /// } | |
85 | /// ``` | |
86 | pub fn chain<I, J>(i: I, j: J) -> iter::Chain<<I as IntoIterator>::IntoIter, <J as IntoIterator>::IntoIter> | |
87 | where I: IntoIterator, | |
88 | J: IntoIterator<Item = I::Item> | |
89 | { | |
90 | i.into_iter().chain(j) | |
91 | } | |
92 | ||
93 | /// Create an iterator that clones each element from &T to T | |
94 | /// | |
95 | /// `IntoIterator` enabled version of `i.cloned()`. | |
96 | /// | |
97 | /// ``` | |
98 | /// use itertools::cloned; | |
99 | /// | |
100 | /// assert_eq!(cloned(b"abc").next(), Some(b'a')); | |
101 | /// ``` | |
102 | pub fn cloned<'a, I, T: 'a>(iterable: I) -> iter::Cloned<I::IntoIter> | |
103 | where I: IntoIterator<Item=&'a T>, | |
104 | T: Clone, | |
105 | { | |
106 | iterable.into_iter().cloned() | |
107 | } | |
108 | ||
109 | /// Perform a fold operation over the iterable. | |
110 | /// | |
111 | /// `IntoIterator` enabled version of `i.fold(init, f)` | |
112 | /// | |
113 | /// ``` | |
114 | /// use itertools::fold; | |
115 | /// | |
116 | /// assert_eq!(fold(&[1., 2., 3.], 0., |a, &b| f32::max(a, b)), 3.); | |
117 | /// ``` | |
118 | pub fn fold<I, B, F>(iterable: I, init: B, f: F) -> B | |
119 | where I: IntoIterator, | |
120 | F: FnMut(B, I::Item) -> B | |
121 | { | |
122 | iterable.into_iter().fold(init, f) | |
123 | } | |
124 | ||
125 | /// Test whether the predicate holds for all elements in the iterable. | |
126 | /// | |
127 | /// `IntoIterator` enabled version of `i.all(f)` | |
128 | /// | |
129 | /// ``` | |
130 | /// use itertools::all; | |
131 | /// | |
132 | /// assert!(all(&[1, 2, 3], |elt| *elt > 0)); | |
133 | /// ``` | |
134 | pub fn all<I, F>(iterable: I, f: F) -> bool | |
135 | where I: IntoIterator, | |
136 | F: FnMut(I::Item) -> bool | |
137 | { | |
138 | iterable.into_iter().all(f) | |
139 | } | |
140 | ||
141 | /// Test whether the predicate holds for any elements in the iterable. | |
142 | /// | |
143 | /// `IntoIterator` enabled version of `i.any(f)` | |
144 | /// | |
145 | /// ``` | |
146 | /// use itertools::any; | |
147 | /// | |
148 | /// assert!(any(&[0, -1, 2], |elt| *elt > 0)); | |
149 | /// ``` | |
150 | pub fn any<I, F>(iterable: I, f: F) -> bool | |
151 | where I: IntoIterator, | |
152 | F: FnMut(I::Item) -> bool | |
153 | { | |
154 | iterable.into_iter().any(f) | |
155 | } | |
156 | ||
157 | /// Return the maximum value of the iterable. | |
158 | /// | |
159 | /// `IntoIterator` enabled version of `i.max()`. | |
160 | /// | |
161 | /// ``` | |
162 | /// use itertools::max; | |
163 | /// | |
164 | /// assert_eq!(max(0..10), Some(9)); | |
165 | /// ``` | |
166 | pub fn max<I>(iterable: I) -> Option<I::Item> | |
167 | where I: IntoIterator, | |
168 | I::Item: Ord | |
169 | { | |
170 | iterable.into_iter().max() | |
171 | } | |
172 | ||
173 | /// Return the minimum value of the iterable. | |
174 | /// | |
175 | /// `IntoIterator` enabled version of `i.min()`. | |
176 | /// | |
177 | /// ``` | |
178 | /// use itertools::min; | |
179 | /// | |
180 | /// assert_eq!(min(0..10), Some(0)); | |
181 | /// ``` | |
182 | pub fn min<I>(iterable: I) -> Option<I::Item> | |
183 | where I: IntoIterator, | |
184 | I::Item: Ord | |
185 | { | |
186 | iterable.into_iter().min() | |
187 | } | |
188 | ||
189 | ||
190 | /// Combine all iterator elements into one String, seperated by `sep`. | |
191 | /// | |
192 | /// `IntoIterator` enabled version of `iterable.join(sep)`. | |
193 | /// | |
194 | /// ``` | |
195 | /// use itertools::join; | |
196 | /// | |
197 | /// assert_eq!(join(&[1, 2, 3], ", "), "1, 2, 3"); | |
198 | /// ``` | |
199 | pub fn join<I>(iterable: I, sep: &str) -> String | |
200 | where I: IntoIterator, | |
201 | I::Item: Display | |
202 | { | |
203 | iterable.into_iter().join(sep) | |
204 | } | |
205 | ||
206 | /// Collect all the iterable's elements into a sorted vector in ascending order. | |
207 | /// | |
208 | /// `IntoIterator` enabled version of `iterable.sorted()`. | |
209 | /// | |
210 | /// ``` | |
211 | /// use itertools::sorted; | |
212 | /// use itertools::assert_equal; | |
213 | /// | |
214 | /// assert_equal(sorted("rust".chars()), "rstu".chars()); | |
215 | /// ``` | |
216 | pub fn sorted<I>(iterable: I) -> Vec<I::Item> | |
217 | where I: IntoIterator, | |
218 | I::Item: Ord | |
219 | { | |
220 | iterable.into_iter().sorted() | |
221 | } | |
222 |