Struct extendr_api::wrapper::matrix::RArray

pub struct RArray<T, D> {
    robj: Robj,
    dim: D,
    _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).

dim: D

Dimensions of the array.

_data: PhantomData<T>

Implementations

impl<T> RArray<T, [usize; 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, [usize; 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<'a, T, D> RArray<T, D>

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

pub fn from_parts(robj: Robj, dim: D) -> Self

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

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

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

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

pub fn dim(&self) -> &D

Get the dimensions for this array.

impl<'a, T: ToVectorValue + 'a> RArray<T, [usize; 1]>

where Robj: 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<'a, T: ToVectorValue + 'a> RArray<T, [usize; 2]>

where Robj: 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<'a, T: ToVectorValue + 'a> RArray<T, [usize; 3]>

where Robj: 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, D: Debug> Debug for RArray<T, D>

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

Formats the value using the given formatter.

impl<T, D> Deref for RArray<T, D>

type Target = Robj

The resulting type after dereferencing.

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

Dereferences the value.

impl<T, D> DerefMut for RArray<T, D>

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

Mutably dereferences the value.

impl<T, D> From<RArray<T, D>> for Robj

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

Convert a column, matrix or matrix3d to an Robj.

impl<'a, T: 'a> FromRobj<'a> for RArray<T, [usize; 2]>

where Robj: AsTypedSlice<'a, T>,

fn from_robj(robj: &'a Robj) -> Result<Self, &'static str>

impl<'a, T> Index<[usize; 2]> for RArray<T, [usize; 2]>

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

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

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.);
}

type Output = T

The returned type after indexing.

impl<'a, T> IndexMut<[usize; 2]> for RArray<T, [usize; 2]>

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

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

Zero-based mutable indexing in row, column order.

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.]);
}

impl<T> Offset<[usize; 1]> for RArray<T, [usize; 1]>

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

Get the offset into the array for a given index.

impl<T> Offset<[usize; 2]> for RArray<T, [usize; 2]>

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

Get the offset into the array for a given index.

impl<T> Offset<[usize; 3]> for RArray<T, [usize; 3]>

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

Get the offset into the array for a given index.

impl<T: PartialEq, D: PartialEq> PartialEq for RArray<T, D>

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<T, D> StructuralPartialEq for RArray<T, D>