Skip to main content

Module rarray

Module rarray 

Source
Expand description

N-dimensional R arrays with const generic dimension count. N-dimensional R arrays with const generic dimension count.

This module provides RArray<T, NDIM>, a wrapper around R arrays that tracks the number of dimensions at compile time.

§Type Aliases

AliasTypeR Equivalent
RVector<T>RArray<T, 1>vector (with dim)
RMatrix<T>RArray<T, 2>matrix
RArray3D<T>RArray<T, 3>array(..., dim=c(a,b,c))

§Memory Layout

R arrays are stored in column-major (Fortran) order. For a 2×3 matrix:

Logical layout:     Memory layout:
[0,0] [0,1] [0,2]   [0,0] [1,0] [0,1] [1,1] [0,2] [1,2]
[1,0] [1,1] [1,2]

The get method handles index translation automatically.

§Thread Safety

RArray is !Send and !Sync - it cannot be transferred to or accessed from other threads. This is because the underlying R APIs (DATAPTR_RO, etc.) must be called on the R main thread.

Every #[miniextendr] function runs on R’s main thread, so RArray / RMatrix parameters are read there. No attribute is required.

To use the data on other threads (Rayon, std::thread::spawn), copy it with to_vec() on the main thread and pass the owned Vec on.

§Performance

For best performance, prefer slice-based and column-based access over per-element indexing:

MethodSpeedUse Case
as_slice()FastestFull-buffer iteration, SIMD
column()FastPer-column operations (matrices)
column_mut()FastPer-column mutation
get() / get_rc()SlowerSingle-element access

Why? Per-element methods like get() perform index translation and bounds checks on every call. For tight loops, this overhead dominates.

ⓘ
// Slow: per-element access
for row in 0..nrow {
    for col in 0..ncol {
        let val = unsafe { matrix.get_rc(row, col) };
    }
}

// Fast: slice-based iteration
for val in unsafe { matrix.as_slice() } {
    // ...
}

// Fast: column-wise iteration (columns are contiguous in R)
for col in 0..ncol {
    for val in unsafe { matrix.column(col) } {
        // ...
    }
}

§Example

ⓘ
use miniextendr_api::rarray::{RMatrix, RArray};

// Runs on the main thread due to the RMatrix parameter (RArray is !Send)
#[miniextendr]
fn matrix_sum(m: RMatrix<f64>) -> f64 {
    unsafe { m.as_slice().iter().sum() }
}

Re-exports§

use crate::from_r::SexpError; 🔒
use crate::from_r::SexpLengthError; 🔒
use crate::from_r::SexpTypeError; 🔒
use crate::from_r::TryFromSexp; 🔒
use crate::into_r::IntoR; 🔒
use crate::R_xlen_t; 🔒
use crate::RNativeType; 🔒
use crate::RNativeType; 🔒
use crate::SEXP; 🔒
use crate::SEXPTYPE; 🔒
use crate::SexpExt; 🔒
use core::marker::PhantomData; 🔒
use crate::RLogical; 🔒
use crate::coerce::TryCoerce; 🔒
use crate::sys; 🔒

Macros§

impl_rarray_try_from_sexp_coerce 🔒
Implement TryFromSexp for RArray<$target, NDIM> by reading R’s native $source type.

Structs§

RArray
An N-dimensional R array.

Functions§

get_dims 🔒 ⚠
Get dimensions from SEXP as array.
get_ndim 🔒
Get number of dimensions from SEXP.
set_dims 🔒 ⚠
Set dimensions on a SEXP.
validate_coercion 🔒
Helper to validate all elements can be coerced.

Type Aliases§

RArray3D
A 3-dimensional R array.
RMatrix
A 2-dimensional R matrix.
RVector
A 1-dimensional R vector with explicit dim attribute.