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#[cfg(feature = "use_alloc")]
7use std::fmt::Display;
8use std::iter::{self, Zip};
9#[cfg(feature = "use_alloc")]
10type VecIntoIter<T> = alloc::vec::IntoIter<T>;
11
12#[cfg(feature = "use_alloc")]
13use alloc::string::String;
14
15use crate::intersperse::{Intersperse, IntersperseWith};
16use crate::Itertools;
17
18pub use crate::adaptors::{interleave, put_back};
19#[cfg(feature = "use_alloc")]
20pub use crate::kmerge_impl::kmerge;
21pub use crate::merge_join::{merge, merge_join_by};
22#[cfg(feature = "use_alloc")]
23pub use crate::multipeek_impl::multipeek;
24#[cfg(feature = "use_alloc")]
25pub use crate::peek_nth::peek_nth;
26#[cfg(feature = "use_alloc")]
27pub use crate::put_back_n_impl::put_back_n;
28#[cfg(feature = "use_alloc")]
29pub use crate::rciter_impl::rciter;
30pub use crate::zip_eq_impl::zip_eq;
31
32/// Iterate `iterable` with a particular value inserted between each element.
33///
34/// [`IntoIterator`] enabled version of [`Iterator::intersperse`].
35///
36/// ```
37/// use itertools::intersperse;
38///
39/// itertools::assert_equal(intersperse(0..3, 8), vec![0, 8, 1, 8, 2]);
40/// ```
41pub fn intersperse<I>(iterable: I, element: I::Item) -> Intersperse<I::IntoIter>
42where
43 I: IntoIterator,
44 <I as IntoIterator>::Item: Clone,
45{
46 Itertools::intersperse(self:iterable.into_iter(), element)
47}
48
49/// Iterate `iterable` with a particular value created by a function inserted
50/// between each element.
51///
52/// [`IntoIterator`] enabled version of [`Iterator::intersperse_with`].
53///
54/// ```
55/// use itertools::intersperse_with;
56///
57/// let mut i = 10;
58/// itertools::assert_equal(intersperse_with(0..3, || { i -= 1; i }), vec![0, 9, 1, 8, 2]);
59/// assert_eq!(i, 8);
60/// ```
61pub fn intersperse_with<I, F>(iterable: I, element: F) -> IntersperseWith<I::IntoIter, F>
62where
63 I: IntoIterator,
64 F: FnMut() -> I::Item,
65{
66 Itertools::intersperse_with(self:iterable.into_iter(), element)
67}
68
69/// Iterate `iterable` with a running index.
70///
71/// [`IntoIterator`] enabled version of [`Iterator::enumerate`].
72///
73/// ```
74/// use itertools::enumerate;
75///
76/// for (i, elt) in enumerate(&[1, 2, 3]) {
77/// /* loop body */
78/// # let _ = (i, elt);
79/// }
80/// ```
81pub fn enumerate<I>(iterable: I) -> iter::Enumerate<I::IntoIter>
82where
83 I: IntoIterator,
84{
85 iterable.into_iter().enumerate()
86}
87
88/// Iterate `iterable` in reverse.
89///
90/// [`IntoIterator`] enabled version of [`Iterator::rev`].
91///
92/// ```
93/// use itertools::rev;
94///
95/// for elt in rev(&[1, 2, 3]) {
96/// /* loop body */
97/// # let _ = elt;
98/// }
99/// ```
100pub fn rev<I>(iterable: I) -> iter::Rev<I::IntoIter>
101where
102 I: IntoIterator,
103 I::IntoIter: DoubleEndedIterator,
104{
105 iterable.into_iter().rev()
106}
107
108/// Converts the arguments to iterators and zips them.
109///
110/// [`IntoIterator`] enabled version of [`Iterator::zip`].
111///
112/// ## Example
113///
114/// ```
115/// use itertools::zip;
116///
117/// let mut result: Vec<(i32, char)> = Vec::new();
118///
119/// for (a, b) in zip(&[1, 2, 3, 4, 5], &['a', 'b', 'c']) {
120/// result.push((*a, *b));
121/// }
122/// assert_eq!(result, vec![(1, 'a'),(2, 'b'),(3, 'c')]);
123/// ```
124#[deprecated(
125 note = "Use [std::iter::zip](https://doc.rust-lang.org/std/iter/fn.zip.html) instead",
126 since = "0.10.4"
127)]
128pub fn zip<I, J>(i: I, j: J) -> Zip<I::IntoIter, J::IntoIter>
129where
130 I: IntoIterator,
131 J: IntoIterator,
132{
133 i.into_iter().zip(j)
134}
135
136/// Takes two iterables and creates a new iterator over both in sequence.
137///
138/// [`IntoIterator`] enabled version of [`Iterator::chain`].
139///
140/// ## Example
141/// ```
142/// use itertools::chain;
143///
144/// let mut result:Vec<i32> = Vec::new();
145///
146/// for element in chain(&[1, 2, 3], &[4]) {
147/// result.push(*element);
148/// }
149/// assert_eq!(result, vec![1, 2, 3, 4]);
150/// ```
151pub fn chain<I, J>(
152 i: I,
153 j: J,
154) -> iter::Chain<<I as IntoIterator>::IntoIter, <J as IntoIterator>::IntoIter>
155where
156 I: IntoIterator,
157 J: IntoIterator<Item = I::Item>,
158{
159 i.into_iter().chain(j)
160}
161
162/// Create an iterator that clones each element from `&T` to `T`.
163///
164/// [`IntoIterator`] enabled version of [`Iterator::cloned`].
165///
166/// ```
167/// use itertools::cloned;
168///
169/// assert_eq!(cloned(b"abc").next(), Some(b'a'));
170/// ```
171pub fn cloned<'a, I, T>(iterable: I) -> iter::Cloned<I::IntoIter>
172where
173 I: IntoIterator<Item = &'a T>,
174 T: Clone + 'a,
175{
176 iterable.into_iter().cloned()
177}
178
179/// Perform a fold operation over the iterable.
180///
181/// [`IntoIterator`] enabled version of [`Iterator::fold`].
182///
183/// ```
184/// use itertools::fold;
185///
186/// assert_eq!(fold(&[1., 2., 3.], 0., |a, &b| f32::max(a, b)), 3.);
187/// ```
188pub fn fold<I, B, F>(iterable: I, init: B, f: F) -> B
189where
190 I: IntoIterator,
191 F: FnMut(B, I::Item) -> B,
192{
193 iterable.into_iter().fold(init, f)
194}
195
196/// Test whether the predicate holds for all elements in the iterable.
197///
198/// [`IntoIterator`] enabled version of [`Iterator::all`].
199///
200/// ```
201/// use itertools::all;
202///
203/// assert!(all(&[1, 2, 3], |elt| *elt > 0));
204/// ```
205pub fn all<I, F>(iterable: I, f: F) -> bool
206where
207 I: IntoIterator,
208 F: FnMut(I::Item) -> bool,
209{
210 iterable.into_iter().all(f)
211}
212
213/// Test whether the predicate holds for any elements in the iterable.
214///
215/// [`IntoIterator`] enabled version of [`Iterator::any`].
216///
217/// ```
218/// use itertools::any;
219///
220/// assert!(any(&[0, -1, 2], |elt| *elt > 0));
221/// ```
222pub fn any<I, F>(iterable: I, f: F) -> bool
223where
224 I: IntoIterator,
225 F: FnMut(I::Item) -> bool,
226{
227 iterable.into_iter().any(f)
228}
229
230/// Return the maximum value of the iterable.
231///
232/// [`IntoIterator`] enabled version of [`Iterator::max`].
233///
234/// ```
235/// use itertools::max;
236///
237/// assert_eq!(max(0..10), Some(9));
238/// ```
239pub fn max<I>(iterable: I) -> Option<I::Item>
240where
241 I: IntoIterator,
242 I::Item: Ord,
243{
244 iterable.into_iter().max()
245}
246
247/// Return the minimum value of the iterable.
248///
249/// [`IntoIterator`] enabled version of [`Iterator::min`].
250///
251/// ```
252/// use itertools::min;
253///
254/// assert_eq!(min(0..10), Some(0));
255/// ```
256pub fn min<I>(iterable: I) -> Option<I::Item>
257where
258 I: IntoIterator,
259 I::Item: Ord,
260{
261 iterable.into_iter().min()
262}
263
264/// Combine all iterator elements into one `String`, separated by `sep`.
265///
266/// [`IntoIterator`] enabled version of [`Itertools::join`].
267///
268/// ```
269/// use itertools::join;
270///
271/// assert_eq!(join(&[1, 2, 3], ", "), "1, 2, 3");
272/// ```
273#[cfg(feature = "use_alloc")]
274pub fn join<I>(iterable: I, sep: &str) -> String
275where
276 I: IntoIterator,
277 I::Item: Display,
278{
279 iterable.into_iter().join(sep)
280}
281
282/// Sort all iterator elements into a new iterator in ascending order.
283///
284/// [`IntoIterator`] enabled version of [`Itertools::sorted`].
285///
286/// ```
287/// use itertools::sorted;
288/// use itertools::assert_equal;
289///
290/// assert_equal(sorted("rust".chars()), "rstu".chars());
291/// ```
292#[cfg(feature = "use_alloc")]
293pub fn sorted<I>(iterable: I) -> VecIntoIter<I::Item>
294where
295 I: IntoIterator,
296 I::Item: Ord,
297{
298 iterable.into_iter().sorted()
299}
300
301/// Sort all iterator elements into a new iterator in ascending order.
302/// This sort is unstable (i.e., may reorder equal elements).
303///
304/// [`IntoIterator`] enabled version of [`Itertools::sorted_unstable`].
305///
306/// ```
307/// use itertools::sorted_unstable;
308/// use itertools::assert_equal;
309///
310/// assert_equal(sorted_unstable("rust".chars()), "rstu".chars());
311/// ```
312#[cfg(feature = "use_alloc")]
313pub fn sorted_unstable<I>(iterable: I) -> VecIntoIter<I::Item>
314where
315 I: IntoIterator,
316 I::Item: Ord,
317{
318 iterable.into_iter().sorted_unstable()
319}
320