logo

Type Definition ndarray::Array

source · []
pub type Array<A, D> = ArrayBase<OwnedRepr<A>, D>;
Expand description

An array that owns its data uniquely.

Array is the main n-dimensional array type, and it owns all its array elements.

The Array<A, D> is parameterized by A for the element type and D for the dimensionality.

ArrayBase is used to implement both the owned arrays and the views; see its docs for an overview of all array features.

See also:

Implementations

Methods specific to Array0.

See also all methods for ArrayBase

Returns the single element in the array without cloning it.

use ndarray::{arr0, Array0};

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

let array: Array0<Foo> = arr0(Foo);
let scalar: Foo = array.into_scalar();
assert_eq!(scalar, Foo);

Methods specific to Array.

See also all methods for ArrayBase

Return a vector of the elements in the array, in the way they are stored internally.

If the array is in standard memory layout, the logical element order of the array (.iter() order) and of the returned vector will be the same.

Methods specific to Array2.

See also all methods for ArrayBase

Append a row to an array

The elements from row are cloned and added as a new row in the array.

Errors with a shape error if the length of the row does not match the length of the rows in the array.

The memory layout of the self array matters for ensuring that the append is efficient. Appending automatically changes memory layout of the array so that it is appended to along the “growing axis”. However, if the memory layout needs adjusting, the array must reallocate and move memory.

The operation leaves the existing data in place and is most efficent if one of these is true:

  • The axis being appended to is the longest stride axis, i.e the array is in row major (“C”) layout.
  • The array has 0 or 1 rows (It is converted to row major)

Ensure appending is efficient by, for example, appending to an empty array and then always pushing/appending along the same axis. For pushing rows, ndarray’s default layout (C order) is efficient.

When repeatedly appending to a single axis, the amortized average complexity of each append is O(m), where m is the length of the row.

use ndarray::{Array, ArrayView, array};

// create an empty array and append
let mut a = Array::zeros((0, 4));
a.push_row(ArrayView::from(&[ 1.,  2.,  3.,  4.])).unwrap();
a.push_row(ArrayView::from(&[-1., -2., -3., -4.])).unwrap();

assert_eq!(
    a,
    array![[ 1.,  2.,  3.,  4.],
           [-1., -2., -3., -4.]]);

Append a column to an array

The elements from column are cloned and added as a new column in the array.

Errors with a shape error if the length of the column does not match the length of the columns in the array.

The memory layout of the self array matters for ensuring that the append is efficient. Appending automatically changes memory layout of the array so that it is appended to along the “growing axis”. However, if the memory layout needs adjusting, the array must reallocate and move memory.

The operation leaves the existing data in place and is most efficent if one of these is true:

  • The axis being appended to is the longest stride axis, i.e the array is in column major (“F”) layout.
  • The array has 0 or 1 columns (It is converted to column major)

Ensure appending is efficient by, for example, appending to an empty array and then always pushing/appending along the same axis. For pushing columns, column major layout (F order) is efficient.

When repeatedly appending to a single axis, the amortized average complexity of each append is O(m), where m is the length of the column.

use ndarray::{Array, ArrayView, array};

// create an empty array and append
let mut a = Array::zeros((2, 0));
a.push_column(ArrayView::from(&[1., 2.])).unwrap();
a.push_column(ArrayView::from(&[-1., -2.])).unwrap();

assert_eq!(
    a,
    array![[1., -1.],
           [2., -2.]]);

Move all elements from self into new_array, which must be of the same shape but can have a different memory layout. The destination is overwritten completely.

The destination should be a mut reference to an array or an ArrayViewMut with A elements.

Panics if the shapes don’t agree.

Example
use ndarray::Array;

// Usage example of move_into in safe code
let mut a = Array::default((10, 10));
let b = Array::from_shape_fn((10, 10), |(i, j)| (i + j).to_string());
b.move_into(&mut a);

Move all elements from self into new_array, which must be of the same shape but can have a different memory layout. The destination is overwritten completely.

The destination should be a mut reference to an array or an ArrayViewMut with MaybeUninit<A> elements (which are overwritten without dropping any existing value).

Minor implementation note: Owned arrays like self may be sliced in place and own elements that are not part of their active view; these are dropped at the end of this function, after all elements in the “active view” are moved into new_array. If there is a panic in drop of any such element, other elements may be leaked.

Panics if the shapes don’t agree.

Example
use ndarray::Array;

let a = Array::from_iter(0..100).into_shape((10, 10)).unwrap();
let mut b = Array::uninit((10, 10));
a.move_into_uninit(&mut b);
unsafe {
    // we can now promise we have fully initialized `b`.
    let b = b.assume_init();
}

Append an array to the array along an axis.

The elements of array are cloned and extend the axis axis in the present array; self will grow in size by 1 along axis.

Append to the array, where the array being pushed to the array has one dimension less than the self array. This method is equivalent to append in this way: self.append(axis, array.insert_axis(axis)).

Errors with a shape error if the shape of self does not match the array-to-append; all axes except the axis along which it being appended matter for this check: the shape of self with axis removed must be the same as the shape of array.

The memory layout of the self array matters for ensuring that the append is efficient. Appending automatically changes memory layout of the array so that it is appended to along the “growing axis”. However, if the memory layout needs adjusting, the array must reallocate and move memory.

The operation leaves the existing data in place and is most efficent if axis is a “growing axis” for the array, i.e. one of these is true:

  • The axis is the longest stride axis, for example the 0th axis in a C-layout or the n-1th axis in an F-layout array.
  • The axis has length 0 or 1 (It is converted to the new growing axis)

Ensure appending is efficient by for example starting from an empty array and/or always appending to an array along the same axis.

The amortized average complexity of the append, when appending along its growing axis, is O(m) where m is the number of individual elements to append.

The memory layout of the argument array does not matter to the same extent.

use ndarray::{Array, ArrayView, array, Axis};

// create an empty array and push rows to it
let mut a = Array::zeros((0, 4));
let ones  = ArrayView::from(&[1.; 4]);
let zeros = ArrayView::from(&[0.; 4]);
a.push(Axis(0), ones).unwrap();
a.push(Axis(0), zeros).unwrap();
a.push(Axis(0), ones).unwrap();

assert_eq!(
    a,
    array![[1., 1., 1., 1.],
           [0., 0., 0., 0.],
           [1., 1., 1., 1.]]);

Append an array to the array along an axis.

The elements of array are cloned and extend the axis axis in the present array; self will grow in size by array.len_of(axis) along axis.

Errors with a shape error if the shape of self does not match the array-to-append; all axes except the axis along which it being appended matter for this check: the shape of self with axis removed must be the same as the shape of array with axis removed.

The memory layout of the self array matters for ensuring that the append is efficient. Appending automatically changes memory layout of the array so that it is appended to along the “growing axis”. However, if the memory layout needs adjusting, the array must reallocate and move memory.

The operation leaves the existing data in place and is most efficent if axis is a “growing axis” for the array, i.e. one of these is true:

  • The axis is the longest stride axis, for example the 0th axis in a C-layout or the n-1th axis in an F-layout array.
  • The axis has length 0 or 1 (It is converted to the new growing axis)

Ensure appending is efficient by for example starting from an empty array and/or always appending to an array along the same axis.

The amortized average complexity of the append, when appending along its growing axis, is O(m) where m is the number of individual elements to append.

The memory layout of the argument array does not matter to the same extent.

use ndarray::{Array, ArrayView, array, Axis};

// create an empty array and append two rows at a time
let mut a = Array::zeros((0, 4));
let ones  = ArrayView::from(&[1.; 8]).into_shape((2, 4)).unwrap();
let zeros = ArrayView::from(&[0.; 8]).into_shape((2, 4)).unwrap();
a.append(Axis(0), ones).unwrap();
a.append(Axis(0), zeros).unwrap();
a.append(Axis(0), ones).unwrap();

assert_eq!(
    a,
    array![[1., 1., 1., 1.],
           [1., 1., 1., 1.],
           [0., 0., 0., 0.],
           [0., 0., 0., 0.],
           [1., 1., 1., 1.],
           [1., 1., 1., 1.]]);

Trait Implementations

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

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