Struct ndarray::Zip

pub struct Zip<Parts, D> { /* private fields */ }

Lock step function application across several arrays or other producers.

Zip allows matching several producers to each other elementwise and applying a function over all tuples of elements (one item from each input at a time).

In general, the zip uses a tuple of producers (NdProducer trait) that all have to be of the same shape. The NdProducer implementation defines what its item type is (for example if it’s a shared reference, mutable reference or an array view etc).

If all the input arrays are of the same memory layout the zip performs much better and the compiler can usually vectorize the loop (if applicable).

The order elements are visited is not specified. The producers don’t have to have the same item type.

The Zip has two methods for function application: apply and fold_while. The zip object can be split, which allows parallelization. A read-only zip object (no mutable producers) can be cloned.

See also the azip!() macro which offers a convenient shorthand to common ways to use Zip.

use ndarray::Zip;
use ndarray::Array2;

type M = Array2<f64>;

// Create four 2d arrays of the same size
let mut a = M::zeros((64, 32));
let b = M::from_elem(a.dim(), 1.);
let c = M::from_elem(a.dim(), 2.);
let d = M::from_elem(a.dim(), 3.);

// Example 1: Perform an elementwise arithmetic operation across
// the four arrays a, b, c, d.

Zip::from(&mut a)
    .and(&b)
    .and(&c)
    .and(&d)
    .apply(|w, &x, &y, &z| {
        *w += x + y * z;
    });

// Example 2: Create a new array `totals` with one entry per row of `a`.
//  Use Zip to traverse the rows of `a` and assign to the corresponding
//  entry in `totals` with the sum across each row.
//  This is possible because the producer for `totals` and the row producer
//  for `a` have the same shape and dimensionality.
//  The rows producer yields one array view (`row`) per iteration.

use ndarray::{Array1, Axis};

let mut totals = Array1::zeros(a.rows());

Zip::from(&mut totals)
    .and(a.genrows())
    .apply(|totals, row| *totals = row.sum());

// Check the result against the built in `.sum_axis()` along axis 1.
assert_eq!(totals, a.sum_axis(Axis(1)));

Implementations

impl<P, D> Zip<(P,), D>where
    D: Dimension,
    P: NdProducer<Dim = D>,

pub fn from<IP>(p: IP) -> Selfwhere
    IP: IntoNdProducer<Dim = D, Output = P, Item = P::Item>,

Create a new Zip from the input array or other producer p.

The Zip will take the exact dimension of p and all inputs must have the same dimensions (or be broadcast to them).

impl<P, D> Zip<(Indices<D>, P), D>where
    D: Dimension + Copy,
    P: NdProducer<Dim = D>,

pub fn indexed<IP>(p: IP) -> Selfwhere
    IP: IntoNdProducer<Dim = D, Output = P, Item = P::Item>,

Create a new Zip with an index producer and the producer p.

The Zip will take the exact dimension of p and all inputs must have the same dimensions (or be broadcast to them).

Note: Indexed zip has overhead.

impl<Parts, D> Zip<Parts, D>where
    D: Dimension,

pub fn size(&self) -> usize

Return a the number of element tuples in the Zip

impl<D: Dimension, P1: NdProducer<Dim = D>> Zip<(P1,), D>

pub fn apply<F>(self, function: F)where
    F: FnMut(P1::Item),

Apply a function to all elements of the input arrays, visiting elements in lock step.

pub fn fold_while<F, Acc>(self, acc: Acc, function: F) -> FoldWhile<Acc>where
    F: FnMut(Acc, P1::Item) -> FoldWhile<Acc>,

Apply a fold function to all elements of the input arrays, visiting elements in lock step.

The fold continues while the return value is a FoldWhile::Continue.

pub fn and<P>(self, p: P) -> Zip<(P1, P::Output), D>where
    P: IntoNdProducer<Dim = D>,

Include the producer p in the Zip.

Panics if p’s shape doesn’t match the Zip’s exactly.

pub fn and_broadcast<'a, P, D2, Elem>(
    self,
    p: P
) -> Zip<(P1, ArrayView<'a, Elem, D>), D>where
    P: IntoNdProducer<Dim = D2, Output = ArrayView<'a, Elem, D2>, Item = &'a Elem>,
    D2: Dimension,

Include the producer p in the Zip, broadcasting if needed.

If their shapes disagree, rhs is broadcast to the shape of self.

Panics if broadcasting isn’t possible.

pub fn split(self) -> (Self, Self)

Split the Zip evenly in two.

It will be split in the way that best preserves element locality.

impl<D: Dimension, P1: NdProducer<Dim = D>, P2: NdProducer<Dim = D>> Zip<(P1, P2), D>

pub fn apply<F>(self, function: F)where
    F: FnMut(P1::Item, P2::Item),

Apply a function to all elements of the input arrays, visiting elements in lock step.

pub fn fold_while<F, Acc>(self, acc: Acc, function: F) -> FoldWhile<Acc>where
    F: FnMut(Acc, P1::Item, P2::Item) -> FoldWhile<Acc>,

Apply a fold function to all elements of the input arrays, visiting elements in lock step.

The fold continues while the return value is a FoldWhile::Continue.

pub fn and<P>(self, p: P) -> Zip<(P1, P2, P::Output), D>where
    P: IntoNdProducer<Dim = D>,

Include the producer p in the Zip.

Panics if p’s shape doesn’t match the Zip’s exactly.

pub fn and_broadcast<'a, P, D2, Elem>(
    self,
    p: P
) -> Zip<(P1, P2, ArrayView<'a, Elem, D>), D>where
    P: IntoNdProducer<Dim = D2, Output = ArrayView<'a, Elem, D2>, Item = &'a Elem>,
    D2: Dimension,

Include the producer p in the Zip, broadcasting if needed.

If their shapes disagree, rhs is broadcast to the shape of self.

Panics if broadcasting isn’t possible.

pub fn split(self) -> (Self, Self)

Split the Zip evenly in two.

It will be split in the way that best preserves element locality.

impl<D: Dimension, P1: NdProducer<Dim = D>, P2: NdProducer<Dim = D>, P3: NdProducer<Dim = D>> Zip<(P1, P2, P3), D>

pub fn apply<F>(self, function: F)where
    F: FnMut(P1::Item, P2::Item, P3::Item),

Apply a function to all elements of the input arrays, visiting elements in lock step.

pub fn fold_while<F, Acc>(self, acc: Acc, function: F) -> FoldWhile<Acc>where
    F: FnMut(Acc, P1::Item, P2::Item, P3::Item) -> FoldWhile<Acc>,

Apply a fold function to all elements of the input arrays, visiting elements in lock step.

The fold continues while the return value is a FoldWhile::Continue.

pub fn and<P>(self, p: P) -> Zip<(P1, P2, P3, P::Output), D>where
    P: IntoNdProducer<Dim = D>,

Include the producer p in the Zip.

Panics if p’s shape doesn’t match the Zip’s exactly.

pub fn and_broadcast<'a, P, D2, Elem>(
    self,
    p: P
) -> Zip<(P1, P2, P3, ArrayView<'a, Elem, D>), D>where
    P: IntoNdProducer<Dim = D2, Output = ArrayView<'a, Elem, D2>, Item = &'a Elem>,
    D2: Dimension,

Include the producer p in the Zip, broadcasting if needed.

If their shapes disagree, rhs is broadcast to the shape of self.

Panics if broadcasting isn’t possible.

pub fn split(self) -> (Self, Self)

Split the Zip evenly in two.

It will be split in the way that best preserves element locality.

impl<D: Dimension, P1: NdProducer<Dim = D>, P2: NdProducer<Dim = D>, P3: NdProducer<Dim = D>, P4: NdProducer<Dim = D>> Zip<(P1, P2, P3, P4), D>

pub fn apply<F>(self, function: F)where
    F: FnMut(P1::Item, P2::Item, P3::Item, P4::Item),

Apply a function to all elements of the input arrays, visiting elements in lock step.

pub fn fold_while<F, Acc>(self, acc: Acc, function: F) -> FoldWhile<Acc>where
    F: FnMut(Acc, P1::Item, P2::Item, P3::Item, P4::Item) -> FoldWhile<Acc>,

Apply a fold function to all elements of the input arrays, visiting elements in lock step.

The fold continues while the return value is a FoldWhile::Continue.

pub fn and<P>(self, p: P) -> Zip<(P1, P2, P3, P4, P::Output), D>where
    P: IntoNdProducer<Dim = D>,

Include the producer p in the Zip.

Panics if p’s shape doesn’t match the Zip’s exactly.

pub fn and_broadcast<'a, P, D2, Elem>(
    self,
    p: P
) -> Zip<(P1, P2, P3, P4, ArrayView<'a, Elem, D>), D>where
    P: IntoNdProducer<Dim = D2, Output = ArrayView<'a, Elem, D2>, Item = &'a Elem>,
    D2: Dimension,

Include the producer p in the Zip, broadcasting if needed.

If their shapes disagree, rhs is broadcast to the shape of self.

Panics if broadcasting isn’t possible.

pub fn split(self) -> (Self, Self)

Split the Zip evenly in two.

It will be split in the way that best preserves element locality.

impl<D: Dimension, P1: NdProducer<Dim = D>, P2: NdProducer<Dim = D>, P3: NdProducer<Dim = D>, P4: NdProducer<Dim = D>, P5: NdProducer<Dim = D>> Zip<(P1, P2, P3, P4, P5), D>

pub fn apply<F>(self, function: F)where
    F: FnMut(P1::Item, P2::Item, P3::Item, P4::Item, P5::Item),

Apply a function to all elements of the input arrays, visiting elements in lock step.

pub fn fold_while<F, Acc>(self, acc: Acc, function: F) -> FoldWhile<Acc>where
    F: FnMut(Acc, P1::Item, P2::Item, P3::Item, P4::Item, P5::Item) -> FoldWhile<Acc>,

Apply a fold function to all elements of the input arrays, visiting elements in lock step.

The fold continues while the return value is a FoldWhile::Continue.

pub fn and<P>(self, p: P) -> Zip<(P1, P2, P3, P4, P5, P::Output), D>where
    P: IntoNdProducer<Dim = D>,

Include the producer p in the Zip.

Panics if p’s shape doesn’t match the Zip’s exactly.

pub fn and_broadcast<'a, P, D2, Elem>(
    self,
    p: P
) -> Zip<(P1, P2, P3, P4, P5, ArrayView<'a, Elem, D>), D>where
    P: IntoNdProducer<Dim = D2, Output = ArrayView<'a, Elem, D2>, Item = &'a Elem>,
    D2: Dimension,

Include the producer p in the Zip, broadcasting if needed.

If their shapes disagree, rhs is broadcast to the shape of self.

Panics if broadcasting isn’t possible.

pub fn split(self) -> (Self, Self)

Split the Zip evenly in two.

It will be split in the way that best preserves element locality.

impl<D: Dimension, P1: NdProducer<Dim = D>, P2: NdProducer<Dim = D>, P3: NdProducer<Dim = D>, P4: NdProducer<Dim = D>, P5: NdProducer<Dim = D>, P6: NdProducer<Dim = D>> Zip<(P1, P2, P3, P4, P5, P6), D>

pub fn apply<F>(self, function: F)where
    F: FnMut(P1::Item, P2::Item, P3::Item, P4::Item, P5::Item, P6::Item),

Apply a function to all elements of the input arrays, visiting elements in lock step.

pub fn fold_while<F, Acc>(self, acc: Acc, function: F) -> FoldWhile<Acc>where
    F: FnMut(Acc, P1::Item, P2::Item, P3::Item, P4::Item, P5::Item, P6::Item) -> FoldWhile<Acc>,

Apply a fold function to all elements of the input arrays, visiting elements in lock step.

The fold continues while the return value is a FoldWhile::Continue.

pub fn split(self) -> (Self, Self)

Split the Zip evenly in two.

It will be split in the way that best preserves element locality.

Trait Implementations

impl<Parts: Clone, D: Clone> Clone for Zip<Parts, D>

fn clone(&self) -> Zip<Parts, D>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Parts: Debug, D: Debug> Debug for Zip<Parts, D>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.