Struct RArray

pub struct RArray<T, const NDIM: usize> {
    robj: Robj,
    _data: PhantomData<T>,
}

Wrapper for creating and using matrices and arrays.

use extendr_api::prelude::*;
test! {
    let matrix = RMatrix::new_matrix(3, 2, |r, c| [
        [1., 2., 3.],
         [4., 5., 6.]][c][r]);
    let robj = r!(matrix);
    assert_eq!(robj.is_matrix(), true);
    assert_eq!(robj.nrows(), 3);
    assert_eq!(robj.ncols(), 2);

    let matrix2 : RMatrix<f64> = robj.as_matrix().ok_or("error")?;
    assert_eq!(matrix2.data().len(), 6);
    assert_eq!(matrix2.nrows(), 3);
    assert_eq!(matrix2.ncols(), 2);
}

Fields

robj: Robj

Owning Robj (probably should be a Pin).

_data: PhantomData<T>

Data type of the n-array

Implementations

impl<T, const NDIM: usize> RArray<T, NDIM>

pub fn get_dimnames(&self) -> List

pub fn get_dim(&self) -> Vec<usize>

Get the dimension vector of the array.

Equivalent to dim() in R

pub fn set_names(&mut self, names: Strings)

Set the names of the elements of an array.

Equivalent to names<- in R

pub fn set_dimnames(&mut self, dimnames: List)

Set the dimension names of an array.

For RMatrix a list of length 2 is required, as that would entail column-names and row-names. If you only wish to set one, but not the other, then the unset element must be R NULL

Equivalent to dimnames<- in R

pub fn set_dim(&mut self, dim: Robj)

Set the dimensions of an array.

Equivalent to dim<-

impl<T, const NDIM: usize> RArray<T, NDIM>

where T: ToVectorValue, Robj: for<'a> AsTypedSlice<'a, T>,

pub fn new_array(dim: [usize; NDIM]) -> Self

impl<T> RArray<T, 2>

where T: ToVectorValue, Robj: for<'a> AsTypedSlice<'a, T>,

pub fn new(nrow: usize, ncol: usize) -> Self

Returns an RMatrix with dimensions according to nrow and ncol, with arbitrary entries. To initialize a matrix containing only NA values, use RMatrix::new_with_na.

impl<T> RArray<T, 2>

where T: ToVectorValue + CanBeNA, Robj: for<'a> AsTypedSlice<'a, T>,

pub fn new_with_na(nrow: usize, ncol: usize) -> Self

Returns an RMatrix with dimensions according to nrow and ncol, with all entries set to NA.

Note that since Raw does not have an NA representation in R, this method is not implemented for [Rbyte].

impl<T> RArray<T, 2>

pub fn get_colnames(&self) -> Option<Strings>

pub fn get_rownames(&self) -> Option<Strings>

impl<T, const NDIM: usize> RArray<T, NDIM>

where Robj: for<'a> AsTypedSlice<'a, T>,

pub fn from_parts(robj: Robj) -> Self

pub fn data(&self) -> &[T]

Returns a flat representation of the array in col-major.

pub fn data_mut(&mut self) -> &mut [T]

Returns a flat, mutable representation of the array in col-major.

pub fn ndim(&self) -> usize

Returns the number of dimensions.

pub fn dim(&self) -> Vec<usize>

Returns the dimensions of the array.

impl<T> RArray<T, 1>

where T: ToVectorValue, Robj: for<'a> AsTypedSlice<'a, T>,

pub fn new_column<F: FnMut(usize) -> T>(nrows: usize, f: F) -> Self

Make a new column type.

pub fn nrows(&self) -> usize

Get the number of rows.

impl<T> RArray<T, 2>

where T: ToVectorValue, Robj: for<'a> AsTypedSlice<'a, T>,

pub fn new_matrix<F: Clone + FnMut(usize, usize) -> T>( nrows: usize, ncols: usize, f: F, ) -> Self

Create a new matrix wrapper.

Arguments

• nrows - the number of rows the returned matrix will have
• ncols - the number of columns the returned matrix will have
• f - a function that will be called for each entry of the matrix in order to populate it with values. It must return a scalar value that can be converted to an R scalar, such as i32, u32, or f64, i.e. see ToVectorValue. It accepts two arguments:
  • r - the current row of the entry we are creating
  • c - the current column of the entry we are creating

pub fn nrows(&self) -> usize

Get the number of rows.

pub fn ncols(&self) -> usize

Get the number of columns.

impl<T> RArray<T, 3>

where T: ToVectorValue, Robj: for<'a> AsTypedSlice<'a, T>,

pub fn new_matrix3d<F: Clone + FnMut(usize, usize, usize) -> T>( nrows: usize, ncols: usize, nmatrix: usize, f: F, ) -> Self

pub fn nrows(&self) -> usize

Get the number of rows.

pub fn ncols(&self) -> usize

Get the number of columns.

pub fn nsub(&self) -> usize

Get the number of submatrices.

Methods from Deref<Target = Robj>

pub fn is_na(&self) -> bool

Is this object is an NA scalar? Works for character, integer and numeric types.

use extendr_api::prelude::*;
test! {

assert_eq!(r!(NA_INTEGER).is_na(), true);
assert_eq!(r!(NA_REAL).is_na(), true);
assert_eq!(r!(NA_STRING).is_na(), true);
}

pub fn as_integer_slice<'a>(&self) -> Option<&'a [i32]>

Get a read-only reference to the content of an integer vector.

use extendr_api::prelude::*;
test! {

let robj = r!([1, 2, 3]);
assert_eq!(robj.as_integer_slice().unwrap(), [1, 2, 3]);
}

pub fn as_integers(&self) -> Option<Integers>

Convert an Robj into Integers.

pub fn as_integer_vector(&self) -> Option<Vec<i32>>

Get a Vec<i32> copied from the object.

use extendr_api::prelude::*;
test! {

let robj = r!([1, 2, 3]);
assert_eq!(robj.as_integer_slice().unwrap(), vec![1, 2, 3]);
}

pub fn as_logical_slice(&self) -> Option<&[Rbool]>

Get a read-only reference to the content of a logical vector using the tri-state Rbool. Returns None if not a logical vector.

use extendr_api::prelude::*;
test! {
    let robj = r!([TRUE, FALSE]);
    assert_eq!(robj.as_logical_slice().unwrap(), [TRUE, FALSE]);
}

pub fn as_logical_vector(&self) -> Option<Vec<Rbool>>

Get a Vec<Rbool> copied from the object using the tri-state Rbool. Returns None if not a logical vector.

use extendr_api::prelude::*;
test! {
    let robj = r!([TRUE, FALSE]);
    assert_eq!(robj.as_logical_vector().unwrap(), vec![TRUE, FALSE]);
}

pub fn as_logical_iter(&self) -> Option<impl Iterator<Item = &Rbool>>

Get an iterator over logical elements of this slice.

use extendr_api::prelude::*;
test! {
    let robj = r!([TRUE, FALSE, NA_LOGICAL]);
    let mut num_na = 0;
    for val in robj.as_logical_iter().unwrap() {
      if val.is_na() {
          num_na += 1;
      }
    }
    assert_eq!(num_na, 1);
}

pub fn as_real_slice(&self) -> Option<&[f64]>

Get a read-only reference to the content of a double vector. Note: the slice may contain NaN or NA values. We may introduce a “Real” type to handle this like the Rbool type.

use extendr_api::prelude::*;
test! {
    let robj = r!([Some(1.), None, Some(3.)]);
    let mut tot = 0.;
    for val in robj.as_real_slice().unwrap() {
      if !val.is_na() {
        tot += val;
      }
    }
    assert_eq!(tot, 4.);
}

pub fn as_real_iter(&self) -> Option<impl Iterator<Item = &f64>>

Get an iterator over real elements of this slice.

use extendr_api::prelude::*;
test! {
    let robj = r!([1., 2., 3.]);
    let mut tot = 0.;
    for val in robj.as_real_iter().unwrap() {
      if !val.is_na() {
        tot += val;
      }
    }
    assert_eq!(tot, 6.);
}

pub fn as_real_vector(&self) -> Option<Vec<f64>>

Get a Vec<f64> copied from the object.

use extendr_api::prelude::*;
test! {
    let robj = r!([1., 2., 3.]);
    assert_eq!(robj.as_real_vector().unwrap(), vec![1., 2., 3.]);
}

pub fn as_raw_slice(&self) -> Option<&[u8]>

Get a read-only reference to the content of an integer or logical vector.

use extendr_api::prelude::*;
test! {
    let robj = r!(Raw::from_bytes(&[1, 2, 3]));
    assert_eq!(robj.as_raw_slice().unwrap(), &[1, 2, 3]);
}

pub fn as_integer_slice_mut(&mut self) -> Option<&mut [i32]>

Get a read-write reference to the content of an integer or logical vector. Note that rust slices are 0-based so slice[1] is the middle value.

use extendr_api::prelude::*;
test! {
    let mut robj = r!([1, 2, 3]);
    let slice : & mut [i32] = robj.as_integer_slice_mut().unwrap();
    slice[1] = 100;
    assert_eq!(robj, r!([1, 100, 3]));
}

pub fn as_real_slice_mut(&mut self) -> Option<&mut [f64]>

Get a read-write reference to the content of a double vector. Note that rust slices are 0-based so slice[1] is the middle value.

use extendr_api::prelude::*;
test! {
    let mut robj = r!([1.0, 2.0, 3.0]);
    let slice = robj.as_real_slice_mut().unwrap();
    slice[1] = 100.0;
    assert_eq!(robj, r!([1.0, 100.0, 3.0]));
}

pub fn as_raw_slice_mut(&mut self) -> Option<&mut [u8]>

Get a read-write reference to the content of a raw vector.

use extendr_api::prelude::*;
test! {
    let mut robj = r!(Raw::from_bytes(&[1, 2, 3]));
    let slice = robj.as_raw_slice_mut().unwrap();
    slice[1] = 100;
    assert_eq!(robj, r!(Raw::from_bytes(&[1, 100, 3])));
}

pub fn as_string_vector(&self) -> Option<Vec<String>>

Get a vector of owned strings. Owned strings have long lifetimes, but are much slower than references.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from("xyz");
   assert_eq!(robj1.as_string_vector(), Some(vec!["xyz".to_string()]));
   let robj2 = Robj::from(1);
   assert_eq!(robj2.as_string_vector(), None);
}

pub fn as_str_vector(&self) -> Option<Vec<&str>>

Get a vector of string references. String references (&str) are faster, but have short lifetimes.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from("xyz");
   assert_eq!(robj1.as_str_vector(), Some(vec!["xyz"]));
   let robj2 = Robj::from(1);
   assert_eq!(robj2.as_str_vector(), None);
}

pub fn as_str<'a>(&self) -> Option<&'a str>

Get a read-only reference to a scalar string type.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from("xyz");
   let robj2 = Robj::from(1);
   assert_eq!(robj1.as_str(), Some("xyz"));
   assert_eq!(robj2.as_str(), None);
}

pub fn as_integer(&self) -> Option<i32>

Get a scalar integer.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from("xyz");
   let robj2 = Robj::from(1);
   let robj3 = Robj::from(NA_INTEGER);
   assert_eq!(robj1.as_integer(), None);
   assert_eq!(robj2.as_integer(), Some(1));
   assert_eq!(robj3.as_integer(), None);
}

pub fn as_real(&self) -> Option<f64>

Get a scalar real.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from(1);
   let robj2 = Robj::from(1.);
   let robj3 = Robj::from(NA_REAL);
   assert_eq!(robj1.as_real(), None);
   assert_eq!(robj2.as_real(), Some(1.));
   assert_eq!(robj3.as_real(), None);
}

pub fn as_bool(&self) -> Option<bool>

Get a scalar rust boolean.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from(TRUE);
   let robj2 = Robj::from(1.);
   let robj3 = Robj::from(NA_LOGICAL);
   assert_eq!(robj1.as_bool(), Some(true));
   assert_eq!(robj2.as_bool(), None);
   assert_eq!(robj3.as_bool(), None);
}

pub fn as_logical(&self) -> Option<Rbool>

Get a scalar boolean as a tri-boolean Rbool value.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from(TRUE);
   let robj2 = Robj::from([TRUE, FALSE]);
   let robj3 = Robj::from(NA_LOGICAL);
   assert_eq!(robj1.as_logical(), Some(TRUE));
   assert_eq!(robj2.as_logical(), None);
   assert_eq!(robj3.as_logical().unwrap().is_na(), true);
}

Trait Implementations

impl<T: Debug, const NDIM: usize> Debug for RArray<T, NDIM>

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

Formats the value using the given formatter.

impl<T, const NDIM: usize> Deref for RArray<T, NDIM>

type Target = Robj

The resulting type after dereferencing.

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

Dereferences the value.

impl<T, const NDIM: usize> DerefMut for RArray<T, NDIM>

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

Mutably dereferences the value.

impl From<&RArray<f64, 2>> for MatRef<'_, f64>

fn from(value: &RMatrix<f64>) -> Self

Converts to this type from the input type.

impl<T, const DIM: usize> From<RArray<T, DIM>> for Robj

fn from(array: RArray<T, DIM>) -> Self

Convert a column, matrix or matrix3d to an Robj.

impl From<RArray<f64, 2>> for Mat<f64>

fn from(value: RMatrix<f64>) -> Self

Converts to this type from the input type.

impl From<RArray<i32, 2>> for Mat<f64>

fn from(value: RMatrix<i32>) -> Self

Converts to this type from the input type.

impl<T, const NDIM: usize> Index<[usize; NDIM]> for RArray<T, NDIM>

where Robj: for<'a> AsTypedSlice<'a, T>,

fn index(&self, index: [usize; NDIM]) -> &Self::Output

Zero-based indexing for DIM-dimensional arrays.

Panics if out of bounds. Zero-based indexing in row, column order.

Panics if out of bounds.

use extendr_api::prelude::*;
test! {
    let matrix = RArray::new_matrix(3, 2, |r, c| [
        [1., 2., 3.],
        [4., 5., 6.]][c][r]);
    assert_eq!(matrix[[0, 0]], 1.);
    assert_eq!(matrix[[1, 0]], 2.);
    assert_eq!(matrix[[2, 1]], 6.);

    let matrix = RArray::new_matrix3d(3, 2, 2, |r, c, d| (r + c + d) as f64);
    assert_eq!(matrix[[0, 0, 0]], 0.);
    assert_eq!(matrix[[1, 0, 1]], 2.);
    assert_eq!(matrix[[2, 1, 1]], 4.);
}

type Output = T

The returned type after indexing.

impl<T, const NDIM: usize> IndexMut<[usize; NDIM]> for RArray<T, NDIM>

where Robj: for<'a> AsTypedSlice<'a, T>,

fn index_mut(&mut self, index: [usize; NDIM]) -> &mut Self::Output

Zero-based mutable indexing for DIM-dimensional arrays.

Panics if out of bounds.

use extendr_api::prelude::*;
test! {
    let mut matrix = RMatrix::new_matrix(3, 2, |_, _| 0.);
    matrix[[0, 0]] = 1.;
    matrix[[1, 0]] = 2.;
    matrix[[2, 0]] = 3.;
    matrix[[0, 1]] = 4.;
    assert_eq!(matrix.as_real_slice().unwrap(), &[1., 2., 3., 4., 0., 0.]);

   let mut matrix = RMatrix3D::new_matrix3d(3, 2, 2, |_, _, _| 0.);
   matrix[[0, 0, 0]] = 1.;
   matrix[[1, 0, 0]] = 2.;
   matrix[[2, 0, 0]] = 3.;
   matrix[[0, 1, 0]] = 4.;
   assert_eq!(matrix.as_real_slice().unwrap(),
       &[1., 2., 3., 4., 0., 0., 0., 0., 0., 0., 0., 0.]);
}

impl<T, const NDIM: usize> Offset<[usize; NDIM]> for RArray<T, NDIM>

fn offset(&self, index: [usize; NDIM]) -> usize

Get the offset into the array for a given index.

impl<T: PartialEq, const NDIM: usize> PartialEq for RArray<T, NDIM>

fn eq(&self, other: &RArray<T, NDIM>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, const NDIM: usize> StructuralPartialEq for RArray<T, NDIM>