logo

Type Definition ndarray::ArrayView

source · [−]
pub type ArrayView<'a, A, D> = ArrayBase<ViewRepr<&'a A>, D>;
Expand description

A read-only array view.

An array view represents an array or a part of it, created from an iterator, subview or slice of an array.

The ArrayView<'a, A, D> is parameterized by 'a for the scope of the borrow, A for the element type and D for the dimensionality.

Array views have all the methods of an array (see ArrayBase).

See also ArrayViewMut.

Implementations

Methods for read-only array views.

Create a read-only array view borrowing its data from a slice.

Checks whether shape are compatible with the slice’s length, returning an Err if not compatible.

use ndarray::ArrayView;
use ndarray::arr3;
use ndarray::ShapeBuilder;

// advanced example where we are even specifying exact strides to use (which is optional).
let s = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
let a = ArrayView::from_shape((2, 3, 2).strides((1, 4, 2)),
                              &s).unwrap();

assert!(
    a == arr3(&[[[0, 2],
                 [4, 6],
                 [8, 10]],
                [[1, 3],
                 [5, 7],
                 [9, 11]]])
);
assert!(a.strides() == &[1, 4, 2]);

Create an ArrayView<A, D> from shape information and a raw pointer to the elements.

Safety

The caller is responsible for ensuring all of the following:

  • The elements seen by moving ptr according to the shape and strides must live at least as long as 'a and must not be not mutably aliased for the duration of 'a.

  • ptr must be non-null and aligned, and it must be safe to .offset() ptr by zero.

  • It must be safe to .offset() the pointer repeatedly along all axes and calculate the counts for the .offset() calls without overflow, even if the array is empty or the elements are zero-sized.

    In other words,

    • All possible pointers generated by moving along all axes must be in bounds or one byte past the end of a single allocation with element type A. The only exceptions are if the array is empty or the element type is zero-sized. In these cases, ptr may be dangling, but it must still be safe to .offset() the pointer along the axes.

    • The offset in units of bytes between the least address and greatest address by moving along all axes must not exceed isize::MAX. This constraint prevents the computed offset, in bytes, from overflowing isize regardless of the starting point due to past offsets.

    • The offset in units of A between the least address and greatest address by moving along all axes must not exceed isize::MAX. This constraint prevents overflow when calculating the count parameter to .offset() regardless of the starting point due to past offsets.

  • The product of non-zero axis lengths must not exceed isize::MAX.

  • Strides must be non-negative.

This function can use debug assertions to check some of these requirements, but it’s not a complete check.

This impl block contains no items.

Private array view methods

Methods for read-only array views.

Convert the view into an ArrayView<'b, A, D> where 'b is a lifetime outlived by 'a'.

Return the array’s data as a slice, if it is contiguous and in standard order. Return None otherwise.

Note that while the method is similar to ArrayBase::as_slice(), this method transfers the view’s lifetime to the slice, so it is a bit more powerful.

Return the array’s data as a slice, if it is contiguous. Return None otherwise.

Note that while the method is similar to ArrayBase::as_slice_memory_order(), this method transfers the view’s lifetime to the slice, so it is a bit more powerful.

Methods specific to ArrayView0.

See also all methods for ArrayView and ArrayBase

Consume the view and return a reference to the single element in the array.

The lifetime of the returned reference matches the lifetime of the data the array view was pointing to.

use ndarray::{arr0, Array0};

// `Foo` doesn't implement `Clone`.
#[derive(Debug, Eq, PartialEq)]
struct Foo;

let array: Array0<Foo> = arr0(Foo);
let view = array.view();
let scalar: &Foo = view.into_scalar();
assert_eq!(scalar, &Foo);
This impl block contains no items.

Private array view methods

Methods for read-only array views.

Split the array view along axis and return one view strictly before the split and one view after the split.

Panics if axis or index is out of bounds.

Examples:

let a = aview2(&[[0, 1, 2, 3],
                 [4, 5, 6, 7],
                 [8, 9, 0, 1]]);

The array view a has two axes and shape 3 × 4:

         ──▶ Axis(1)
        ┌─────┬─────┬─────┬─────┐ 0
      │ │ a₀₀ │ a₀₁ │ a₀₂ │ a₀₃ │
      ▼ ├─────┼─────┼─────┼─────┤ 1
 Axis(0)│ a₁₀ │ a₁₁ │ a₁₂ │ a₁₃ │
        ├─────┼─────┼─────┼─────┤ 2
        │ a₂₀ │ a₂₁ │ a₂₂ │ a₂₃ │
        └─────┴─────┴─────┴─────┘ 3 ↑
        0     1     2     3     4 ← possible split_at indices.

Row indices increase along Axis(0), and column indices increase along Axis(1). Note that we split “before” an element index, and that both 0 and the endpoint are valid split indices.

Example 1: Split a along the first axis, in this case the rows, at index 2.
This produces views v1 and v2 of shapes 2 × 4 and 1 × 4:

let (v1, v2) = a.split_at(Axis(0), 2);
        ┌─────┬─────┬─────┬─────┐       0  ↓ indices
        │ a₀₀ │ a₀₁ │ a₀₂ │ a₀₃ │            along Axis(0)
        ├─────┼─────┼─────┼─────┤ v1    1
        │ a₁₀ │ a₁₁ │ a₁₂ │ a₁₃ │
        └─────┴─────┴─────┴─────┘
        ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄       2
        ┌─────┬─────┬─────┬─────┐
        │ a₂₀ │ a₂₁ │ a₂₂ │ a₂₃ │ v2
        └─────┴─────┴─────┴─────┘       3

Example 2: Split a along the second axis, in this case the columns, at index 2.
This produces views u1 and u2 of shapes 3 × 2 and 3 × 2:

let (u1, u2) = a.split_at(Axis(1), 2);

             u1             u2
        ┌─────┬─────┐┊┌─────┬─────┐
        │ a₀₀ │ a₀₁ │┊│ a₀₂ │ a₀₃ │
        ├─────┼─────┤┊├─────┼─────┤
        │ a₁₀ │ a₁₁ │┊│ a₁₂ │ a₁₃ │
        ├─────┼─────┤┊├─────┼─────┤
        │ a₂₀ │ a₂₁ │┊│ a₂₂ │ a₂₃ │
        └─────┴─────┘┊└─────┴─────┘
        0     1      2      3     4  indices →
                                     along Axis(1)

Splits the view into views of the real and imaginary components of the elements.

use ndarray::prelude::*;
use num_complex::{Complex, Complex64};

let arr = array![
    [Complex64::new(1., 2.), Complex64::new(3., 4.)],
    [Complex64::new(5., 6.), Complex64::new(7., 8.)],
    [Complex64::new(9., 10.), Complex64::new(11., 12.)],
];
let Complex { re, im } = arr.view().split_complex();
assert_eq!(re, array![[1., 3.], [5., 7.], [9., 11.]]);
assert_eq!(im, array![[2., 4.], [6., 8.], [10., 12.]]);

Trait Implementations

Implementation of ArrayView::from(&A) where A is an array.

Create a read-only array view of the array.

Implementation of ArrayView::from(&S) where S is a slice or sliceable.

Create a one-dimensional read-only array view of the data in slice.

Panics if the slice length is greater than isize::MAX.

Get a reference of a element through the view.

This method is like Index::index but with a longer lifetime (matching the array view); which we can only do for the array view and not in the Index trait.

See also the get method which works for all arrays and array views.

Panics if index is out of bounds.

Get a reference of a element through the view without boundary check

This method is like elem with a longer lifetime (matching the array view); which we can’t do for general arrays.

See also the uget method which works for all arrays and array views.

Note: only unchecked for non-debug builds of ndarray.

The type of the reference to the element that is produced, including its lifetime. Read more

Get a reference of a element through the view. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

Requires crate feature rayon.

The type of item that the parallel iterator will produce.

The parallel iterator type that will be created.

Converts self into a parallel iterator. Read more

The element produced per iteration.

Dimension type

Return the shape of the producer.