|
| 1 | +// Copyright 2014-2019 bluss and ndarray developers |
| 2 | +// and Michał Krasnoborski (krdln) |
| 3 | +// |
| 4 | +// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or |
| 5 | +// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license |
| 6 | +// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your |
| 7 | +// option. This file may not be copied, modified, or distributed |
| 8 | +// except according to those terms. |
| 9 | + |
| 10 | +//! A few iterator-related utilities and tools |
| 11 | +
|
| 12 | +use std::iter; |
| 13 | + |
| 14 | +/// Iterate `iterable` with a running index. |
| 15 | +/// |
| 16 | +/// `IntoIterator` enabled version of `.enumerate()`. |
| 17 | +/// |
| 18 | +/// ``` |
| 19 | +/// use itertools::enumerate; |
| 20 | +/// |
| 21 | +/// for (i, elt) in enumerate(&[1, 2, 3]) { |
| 22 | +/// /* loop body */ |
| 23 | +/// } |
| 24 | +/// ``` |
| 25 | +pub(crate) fn enumerate<I>(iterable: I) -> iter::Enumerate<I::IntoIter> |
| 26 | +where |
| 27 | + I: IntoIterator, |
| 28 | +{ |
| 29 | + iterable.into_iter().enumerate() |
| 30 | +} |
| 31 | + |
| 32 | +/// Iterate `i` and `j` in lock step. |
| 33 | +/// |
| 34 | +/// `IntoIterator` enabled version of `i.zip(j)`. |
| 35 | +/// |
| 36 | +/// ``` |
| 37 | +/// use itertools::zip; |
| 38 | +/// |
| 39 | +/// let data = [1, 2, 3, 4, 5]; |
| 40 | +/// for (a, b) in zip(&data, &data[1..]) { |
| 41 | +/// /* loop body */ |
| 42 | +/// } |
| 43 | +/// ``` |
| 44 | +pub(crate) fn zip<I, J>(i: I, j: J) -> iter::Zip<I::IntoIter, J::IntoIter> |
| 45 | +where |
| 46 | + I: IntoIterator, |
| 47 | + J: IntoIterator, |
| 48 | +{ |
| 49 | + i.into_iter().zip(j) |
| 50 | +} |
| 51 | + |
| 52 | +/// Create an iterator running multiple iterators in lockstep. |
| 53 | +/// |
| 54 | +/// The `izip!` iterator yields elements until any subiterator |
| 55 | +/// returns `None`. |
| 56 | +/// |
| 57 | +/// This is a version of the standard ``.zip()`` that's supporting more than |
| 58 | +/// two iterators. The iterator element type is a tuple with one element |
| 59 | +/// from each of the input iterators. Just like ``.zip()``, the iteration stops |
| 60 | +/// when the shortest of the inputs reaches its end. |
| 61 | +/// |
| 62 | +/// **Note:** The result of this macro is in the general case an iterator |
| 63 | +/// composed of repeated `.zip()` and a `.map()`; it has an anonymous type. |
| 64 | +/// The special cases of one and two arguments produce the equivalent of |
| 65 | +/// `$a.into_iter()` and `$a.into_iter().zip($b)` respectively. |
| 66 | +/// |
| 67 | +/// Prefer this macro `izip!()` over [`multizip`] for the performance benefits |
| 68 | +/// of using the standard library `.zip()`. |
| 69 | +/// |
| 70 | +/// [`multizip`]: fn.multizip.html |
| 71 | +/// |
| 72 | +/// ``` |
| 73 | +/// #[macro_use] extern crate itertools; |
| 74 | +/// # fn main() { |
| 75 | +/// |
| 76 | +/// // iterate over three sequences side-by-side |
| 77 | +/// let mut results = [0, 0, 0, 0]; |
| 78 | +/// let inputs = [3, 7, 9, 6]; |
| 79 | +/// |
| 80 | +/// for (r, index, input) in izip!(&mut results, 0..10, &inputs) { |
| 81 | +/// *r = index * 10 + input; |
| 82 | +/// } |
| 83 | +/// |
| 84 | +/// assert_eq!(results, [0 + 3, 10 + 7, 29, 36]); |
| 85 | +/// # } |
| 86 | +/// ``` |
| 87 | +/// |
| 88 | +/// **Note:** To enable the macros in this crate, use the `#[macro_use]` |
| 89 | +/// attribute when importing the crate: |
| 90 | +/// |
| 91 | +/// ``` |
| 92 | +/// #[macro_use] extern crate itertools; |
| 93 | +/// # fn main() { } |
| 94 | +/// ``` |
| 95 | +macro_rules! izip { |
| 96 | + // @closure creates a tuple-flattening closure for .map() call. usage: |
| 97 | + // @closure partial_pattern => partial_tuple , rest , of , iterators |
| 98 | + // eg. izip!( @closure ((a, b), c) => (a, b, c) , dd , ee ) |
| 99 | + ( @closure $p:pat => $tup:expr ) => { |
| 100 | + |$p| $tup |
| 101 | + }; |
| 102 | + |
| 103 | + // The "b" identifier is a different identifier on each recursion level thanks to hygiene. |
| 104 | + ( @closure $p:pat => ( $($tup:tt)* ) , $_iter:expr $( , $tail:expr )* ) => { |
| 105 | + izip!(@closure ($p, b) => ( $($tup)*, b ) $( , $tail )*) |
| 106 | + }; |
| 107 | + |
| 108 | + // unary |
| 109 | + ($first:expr $(,)*) => { |
| 110 | + IntoIterator::into_iter($first) |
| 111 | + }; |
| 112 | + |
| 113 | + // binary |
| 114 | + ($first:expr, $second:expr $(,)*) => { |
| 115 | + izip!($first) |
| 116 | + .zip($second) |
| 117 | + }; |
| 118 | + |
| 119 | + // n-ary where n > 2 |
| 120 | + ( $first:expr $( , $rest:expr )* $(,)* ) => { |
| 121 | + izip!($first) |
| 122 | + $( |
| 123 | + .zip($rest) |
| 124 | + )* |
| 125 | + .map( |
| 126 | + izip!(@closure a => (a) $( , $rest )*) |
| 127 | + ) |
| 128 | + }; |
| 129 | +} |
0 commit comments