Struct RawRef 

pub struct RawRef<A, D>(/* private fields */);

A reference to an n-dimensional array whose data is not safe to read or write.

This type is similar to ArrayRef but does not guarantee that its data is safe to read or write; i.e., the underlying data may come from a shared array or be otherwise unsafe to dereference. This type should be used sparingly and with extreme caution; most of its methods either provide pointers or return RawArrayView, both of which tend to be full of unsafety.

For the few times when this type is appropriate, it has the same AsRef semantics as LayoutRef; see its documentation on writing functions for information on how to properly handle functionality on this type.

Implementations

impl<A, D: Dimension> RawRef<A, D>

pub fn get_ptr<I>(&self, index: I) -> Option<*const A>

where I: NdIndex<D>,

Return a raw pointer to the element at index, or return None if the index is out of bounds.

use ndarray::arr2;

let a = arr2(&[[1., 2.], [3., 4.]]);

let v = a.raw_view();
let p = a.get_ptr((0, 1)).unwrap();

assert_eq!(unsafe { *p }, 2.);

impl<A, D: Dimension> RawRef<A, D>

pub fn get_mut_ptr<I>(&mut self, index: I) -> Option<*mut A>

where I: NdIndex<D>,

Return a raw pointer to the element at index, or return None if the index is out of bounds.

use ndarray::arr2;

let mut a = arr2(&[[1., 2.], [3., 4.]]);

let v = a.raw_view_mut();
let p = a.get_mut_ptr((0, 1)).unwrap();

unsafe {
    *p = 5.;
}

assert_eq!(a.get((0, 1)), Some(&5.));

impl<A, D: Dimension> RawRef<A, D>

pub fn as_ptr(&self) -> *const A

Return a pointer to the first element in the array.

Raw access to array elements needs to follow the strided indexing scheme: an element at multi-index I in an array with strides S is located at offset

Σ_{0 ≤ k < d} I_k × S_k

where d is self.ndim().

pub fn as_mut_ptr(&mut self) -> *mut A

Return a mutable pointer to the first element in the array reference.

impl<A, D: Dimension> RawRef<A, D>

pub fn raw_view(&self) -> RawArrayView<A, D>

Return a raw view of the array.

pub fn raw_view_mut(&mut self) -> RawArrayViewMut<A, D>

Return a raw mutable view of the array.

Methods from Deref<Target = LayoutRef<A, D>>

pub fn len(&self) -> usize

Return the total number of elements in the array.

pub fn len_of(&self, axis: Axis) -> usize

Return the length of axis.

The axis should be in the range Axis( 0 .. n ) where n is the number of dimensions (axes) of the array.

Panics if the axis is out of bounds.

pub fn is_empty(&self) -> bool

Return whether the array has any elements

pub fn ndim(&self) -> usize

Return the number of dimensions (axes) in the array

pub fn dim(&self) -> D::Pattern

Return the shape of the array in its “pattern” form, an integer in the one-dimensional case, tuple in the n-dimensional cases and so on.

pub fn raw_dim(&self) -> D

Return the shape of the array as it’s stored in the array.

This is primarily useful for passing to other ArrayBase functions, such as when creating another array of the same shape and dimensionality.

use ndarray::Array;

let a = Array::from_elem((2, 3), 5.);

// Create an array of zeros that's the same shape and dimensionality as `a`.
let b = Array::<f64, _>::zeros(a.raw_dim());

pub fn shape(&self) -> &[usize]

Return the shape of the array as a slice.

Note that you probably don’t want to use this to create an array of the same shape as another array because creating an array with e.g. Array::zeros() using a shape of type &[usize] results in a dynamic-dimensional array. If you want to create an array that has the same shape and dimensionality as another array, use .raw_dim() instead:

use ndarray::{Array, Array2};

let a = Array2::<i32>::zeros((3, 4));
let shape = a.shape();
assert_eq!(shape, &[3, 4]);

// Since `a.shape()` returned `&[usize]`, we get an `ArrayD` instance:
let b = Array::zeros(shape);
assert_eq!(a.clone().into_dyn(), b);

// To get the same dimension type, use `.raw_dim()` instead:
let c = Array::zeros(a.raw_dim());
assert_eq!(a, c);

pub fn strides(&self) -> &[isize]

Return the strides of the array as a slice.

pub fn stride_of(&self, axis: Axis) -> isize

Return the stride of axis.

The axis should be in the range Axis( 0 .. n ) where n is the number of dimensions (axes) of the array.

Panics if the axis is out of bounds.

pub fn slice_collapse<I>(&mut self, info: I)

where I: SliceArg<D>,

Slice the array in place without changing the number of dimensions.

In particular, if an axis is sliced with an index, the axis is collapsed, as in .collapse_axis(), rather than removed, as in .slice_move() or .index_axis_move().

See Slicing for full documentation. See also s!, SliceArg, and SliceInfo.

Panics in the following cases:

• if an index is out of bounds
• if a step size is zero
• if SliceInfoElem::NewAxis is in info, e.g. if NewAxis was used in the s! macro
• if D is IxDyn and info does not match the number of array axes

pub fn slice_axis_inplace(&mut self, axis: Axis, indices: Slice)

Slice the array in place along the specified axis.

Panics if an index is out of bounds or step size is zero.
Panics if axis is out of bounds.

pub fn slice_each_axis_inplace<F>(&mut self, f: F)

where F: FnMut(AxisDescription) -> Slice,

Slice the array in place, with a closure specifying the slice for each axis.

This is especially useful for code which is generic over the dimensionality of the array.

Panics if an index is out of bounds or step size is zero.

pub fn collapse_axis(&mut self, axis: Axis, index: usize)

Selects index along the axis, collapsing the axis into length one.

Panics if axis or index is out of bounds.

pub fn is_standard_layout(&self) -> bool

Return true if the array data is laid out in contiguous “C order” in memory (where the last index is the most rapidly varying).

Return false otherwise, i.e. the array is possibly not contiguous in memory, it has custom strides, etc.

pub fn swap_axes(&mut self, ax: usize, bx: usize)

Swap axes ax and bx.

This does not move any data, it just adjusts the array’s dimensions and strides.

Panics if the axes are out of bounds.

use ndarray::arr2;

let mut a = arr2(&[[1., 2., 3.]]);
a.swap_axes(0, 1);
assert!(
    a == arr2(&[[1.], [2.], [3.]])
);

pub fn axes(&self) -> Axes<'_, D>

Return an iterator over the length and stride of each axis.

pub fn max_stride_axis(&self) -> Axis

Return the axis with the greatest stride (by absolute value), preferring axes with len > 1.

pub fn invert_axis(&mut self, axis: Axis)

Reverse the stride of axis.

Panics if the axis is out of bounds.

pub fn merge_axes(&mut self, take: Axis, into: Axis) -> bool

If possible, merge in the axis take to into.

Returns true iff the axes are now merged.

This method merges the axes if movement along the two original axes (moving fastest along the into axis) can be equivalently represented as movement along one (merged) axis. Merging the axes preserves this order in the merged axis. If take and into are the same axis, then the axis is “merged” if its length is ≤ 1.

If the return value is true, then the following hold:

• The new length of the into axis is the product of the original lengths of the two axes.

• The new length of the take axis is 0 if the product of the original lengths of the two axes is 0, and 1 otherwise.

If the return value is false, then merging is not possible, and the original shape and strides have been preserved.

Note that the ordering constraint means that if it’s possible to merge take into into, it’s usually not possible to merge into into take, and vice versa.

use ndarray::Array3;
use ndarray::Axis;

let mut a = Array3::<f64>::zeros((2, 3, 4));
assert!(a.merge_axes(Axis(1), Axis(2)));
assert_eq!(a.shape(), &[2, 1, 12]);

Panics if an axis is out of bounds.

pub fn nrows(&self) -> usize

Return the number of rows (length of Axis(0)) in the two-dimensional array.

use ndarray::{array, Axis};

let array = array![[1., 2.],
                   [3., 4.],
                   [5., 6.]];
assert_eq!(array.nrows(), 3);

// equivalent ways of getting the dimensions
// get nrows, ncols by using dim:
let (m, n) = array.dim();
assert_eq!(m, array.nrows());
// get length of any particular axis with .len_of()
assert_eq!(m, array.len_of(Axis(0)));

pub fn ncols(&self) -> usize

Return the number of columns (length of Axis(1)) in the two-dimensional array.

use ndarray::{array, Axis};

let array = array![[1., 2.],
                   [3., 4.],
                   [5., 6.]];
assert_eq!(array.ncols(), 2);

// equivalent ways of getting the dimensions
// get nrows, ncols by using dim:
let (m, n) = array.dim();
assert_eq!(n, array.ncols());
// get length of any particular axis with .len_of()
assert_eq!(n, array.len_of(Axis(1)));

pub fn is_square(&self) -> bool

Return true if the array is square, false otherwise.

Examples

Square:

use ndarray::array;
let array = array![[1., 2.], [3., 4.]];
assert!(array.is_square());

Not square:

use ndarray::array;
let array = array![[1., 2., 5.], [3., 4., 6.]];
assert!(!array.is_square());

pub fn insert_axis_inplace(&mut self, axis: Axis)

Insert new array axis of length 1 at axis, modifying the shape and strides in-place.

Panics if the axis is out of bounds.

use ndarray::{Axis, arr2, arr3};

let mut a = arr2(&[[1, 2, 3], [4, 5, 6]]).into_dyn();
assert_eq!(a.shape(), &[2, 3]);

a.insert_axis_inplace(Axis(1));
assert_eq!(a, arr3(&[[[1, 2, 3]], [[4, 5, 6]]]).into_dyn());
assert_eq!(a.shape(), &[2, 1, 3]);

pub fn index_axis_inplace(&mut self, axis: Axis, index: usize)

Collapses the array to index along the axis and removes the axis, modifying the shape and strides in-place.

Panics if axis or index is out of bounds.

use ndarray::{Axis, arr1, arr2};

let mut a = arr2(&[[1, 2, 3], [4, 5, 6]]).into_dyn();
assert_eq!(a.shape(), &[2, 3]);

a.index_axis_inplace(Axis(1), 1);
assert_eq!(a, arr1(&[2, 5]).into_dyn());
assert_eq!(a.shape(), &[2]);

Trait Implementations

impl<A, D> AsMut<LayoutRef<A, D>> for RawRef<A, D>

fn as_mut(&mut self) -> &mut LayoutRef<A, D>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<A, S, D> AsMut<RawRef<A, D>> for ArrayBase<S, D>

where S: RawDataMut<Elem = A>,

fn as_mut(&mut self) -> &mut RawRef<A, D>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<A, D> AsMut<RawRef<A, D>> for ArrayRef<A, D>

fn as_mut(&mut self) -> &mut RawRef<A, D>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<A, D> AsMut<RawRef<A, D>> for RawRef<A, D>

fn as_mut(&mut self) -> &mut RawRef<A, D>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<A, D> AsRef<LayoutRef<A, D>> for RawRef<A, D>

fn as_ref(&self) -> &LayoutRef<A, D>

Converts this type into a shared reference of the (usually inferred) input type.

impl<A, S, D> AsRef<RawRef<A, D>> for ArrayBase<S, D>

where S: RawData<Elem = A>,

fn as_ref(&self) -> &RawRef<A, D>

Converts this type into a shared reference of the (usually inferred) input type.

impl<A, D> AsRef<RawRef<A, D>> for ArrayRef<A, D>

fn as_ref(&self) -> &RawRef<A, D>

Converts this type into a shared reference of the (usually inferred) input type.

impl<A, D> AsRef<RawRef<A, D>> for RawRef<A, D>

fn as_ref(&self) -> &RawRef<A, D>

Converts this type into a shared reference of the (usually inferred) input type.

impl<S, D> Borrow<RawRef<<S as RawData>::Elem, D>> for ArrayBase<S, D>

where S: RawData,

fn borrow(&self) -> &RawRef<S::Elem, D>

Immutably borrows from an owned value.

impl<S, D> BorrowMut<RawRef<<S as RawData>::Elem, D>> for ArrayBase<S, D>

where S: RawDataMut,

fn borrow_mut(&mut self) -> &mut RawRef<S::Elem, D>

Mutably borrows from an owned value.

impl<A, D> Deref for RawRef<A, D>

type Target = LayoutRef<A, D>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<A, D> DerefMut for RawRef<A, D>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.