ndarray/zip/
zipmacro.rs

1/// Array zip macro: lock step function application across several arrays and
2/// producers.
3///
4/// This is a shorthand for [`Zip`](crate::Zip).
5///
6/// This example:
7///
8/// ```rust,ignore
9/// azip!((a in &mut a, &b in &b, &c in &c) *a = b + c);
10/// ```
11///
12/// Is equivalent to:
13///
14/// ```rust,ignore
15/// Zip::from(&mut a).and(&b).and(&c).for_each(|a, &b, &c| {
16///     *a = b + c
17/// });
18/// ```
19///
20/// The syntax is either
21///
22/// `azip!((` *pat* `in` *expr* `,` *[* *pat* `in` *expr* `,` ... *]* `)` *body_expr* `)`
23///
24/// or, to use `Zip::indexed` instead of `Zip::from`,
25///
26/// `azip!((index` *pat* `,` *pat* `in` *expr* `,` *[* *pat* `in` *expr* `,` ... *]* `)` *body_expr* `)`
27///
28/// The *expr* are expressions whose types must implement `IntoNdProducer`, the
29/// *pat* are the patterns of the parameters to the closure called by
30/// `Zip::for_each`, and *body_expr* is the body of the closure called by
31/// `Zip::for_each`. You can think of each *pat* `in` *expr* as being analogous to
32/// the `pat in expr` of a normal loop `for pat in expr { statements }`: a
33/// pattern, followed by `in`, followed by an expression that implements
34/// `IntoNdProducer` (analogous to `IntoIterator` for a `for` loop).
35///
36/// **Panics** if any of the arrays are not of the same shape.
37///
38/// ## Examples
39///
40/// ```rust
41/// use ndarray::{azip, Array1, Array2, Axis};
42///
43/// type M = Array2<f32>;
44///
45/// // Setup example arrays
46/// let mut a = M::zeros((16, 16));
47/// let mut b = M::zeros(a.dim());
48/// let mut c = M::zeros(a.dim());
49///
50/// // assign values
51/// b.fill(1.);
52/// for ((i, j), elt) in c.indexed_iter_mut() {
53///     *elt = (i + 10 * j) as f32;
54/// }
55///
56/// // Example 1: Compute a simple ternary operation:
57/// // elementwise addition of b and c, stored in a
58/// azip!((a in &mut a, &b in &b, &c in &c) *a = b + c);
59///
60/// assert_eq!(a, &b + &c);
61///
62/// // Example 2: azip!() with index
63/// azip!((index (i, j), &b in &b, &c in &c) {
64///     a[[i, j]] = b - c;
65/// });
66///
67/// assert_eq!(a, &b - &c);
68///
69///
70/// // Example 3: azip!() on references
71/// // See the definition of the function below
72/// borrow_multiply(&mut a, &b, &c);
73///
74/// assert_eq!(a, &b * &c);
75///
76///
77/// // Since this function borrows its inputs, the `IntoNdProducer`
78/// // expressions don't need to explicitly include `&mut` or `&`.
79/// fn borrow_multiply(a: &mut M, b: &M, c: &M) {
80///     azip!((a in a, &b in b, &c in c) *a = b * c);
81/// }
82///
83///
84/// // Example 4: using azip!() without dereference in pattern.
85/// //
86/// // Create a new array `totals` with one entry per row of `a`.
87/// // Use azip to traverse the rows of `a` and assign to the corresponding
88/// // entry in `totals` with the sum across each row.
89/// //
90/// // The row is an array view; it doesn't need to be dereferenced.
91/// let mut totals = Array1::zeros(a.nrows());
92/// azip!((totals in &mut totals, row in a.rows()) *totals = row.sum());
93///
94/// // Check the result against the built in `.sum_axis()` along axis 1.
95/// assert_eq!(totals, a.sum_axis(Axis(1)));
96/// ```
97#[macro_export]
98macro_rules! azip {
99    // Indexed with a single producer
100    // we allow an optional trailing comma after the producers in each rule.
101    (@build $apply:ident (index $index:pat, $first_pat:pat in $first_prod:expr $(,)?) $body:expr) => {
102        $crate::Zip::indexed($first_prod).$apply(|$index, $first_pat| $body)
103    };
104    // Indexed with more than one producer
105    (@build $apply:ident (index $index:pat, $first_pat:pat in $first_prod:expr, $($pat:pat in $prod:expr),* $(,)?) $body:expr) => {
106        $crate::Zip::indexed($first_prod)
107            $(.and($prod))*
108            .$apply(|$index, $first_pat, $($pat),*| $body)
109    };
110    // Unindexed with a single producer
111    (@build $apply:ident ($first_pat:pat in $first_prod:expr $(,)?) $body:expr) => {
112        $crate::Zip::from($first_prod).$apply(|$first_pat| $body)
113    };
114    // Unindexed with more than one producer
115    (@build $apply:ident ($first_pat:pat in $first_prod:expr, $($pat:pat in $prod:expr),* $(,)?) $body:expr) => {
116        $crate::Zip::from($first_prod)
117            $(.and($prod))*
118            .$apply(|$first_pat, $($pat),*| $body)
119    };
120
121    // Unindexed with one or more producer, no loop body
122    (@build $apply:ident $first_prod:expr $(, $prod:expr)* $(,)?) => {
123        $crate::Zip::from($first_prod)
124            $(.and($prod))*
125    };
126    // catch-all rule
127    (@build $($t:tt)*) => { compile_error!("Invalid syntax in azip!()") };
128    ($($t:tt)*) => {
129        $crate::azip!(@build for_each $($t)*)
130    };
131}
ndarray/zip/zipmacro.rs

ndarray/zip/
zipmacro.rs
