Struct RArray 

#[repr(transparent)]
pub struct RArray<T, const NDIM: usize> {
    sexp: SEXP,
    _marker: PhantomData<*const T>,
}

An N-dimensional R array.

This type wraps an R array SEXP. The dimension count NDIM is tracked at compile time, but dimension sizes are read from the R object.

Type Parameters

• T: The element type, must implement RNativeType
• NDIM: The number of dimensions (compile-time constant)

Thread Safety

This type is !Send and !Sync because its methods require access to R APIs that must run on the R main thread.

Fields

sexp: SEXP

_marker: PhantomData<*const T>

Implementations

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

pub const unsafe fn from_sexp_unchecked(sexp: SEXP) -> Self

Create an RArray from a SEXP without validation.

Safety

• The SEXP must be protected from GC
• The SEXP must have the correct type for T
• The SEXP must have exactly NDIM dimensions

pub const fn as_sexp(&self) -> SEXP

Get the underlying SEXP.

pub fn into_inner(self) -> SEXP

Consume and return the underlying SEXP.

pub unsafe fn dims(&self) -> [usize; NDIM]

Get the dimensions as an array.

Safety

The SEXP must be valid.

pub unsafe fn dim(&self, dim: usize) -> usize

Get a specific dimension size.

Safety

The SEXP must be valid.

Panics

Panics if dim >= NDIM.

pub fn len(&self) -> usize

Get the total number of elements.

pub fn is_empty(&self) -> bool

Check if the array is empty.

pub unsafe fn linear_index(&self, indices: [usize; NDIM]) -> usize

Convert N-dimensional indices to linear index (column-major).

Safety

The SEXP must be valid (needed to read dims).

Panics

Panics if any index is out of bounds.

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

pub unsafe fn from_sexp(sexp: SEXP) -> Result<Self, SexpError>

Create an RArray from a SEXP, validating type and dimensions.

Safety

The SEXP must be protected from GC for the lifetime of the returned RArray.

Errors

Returns an error if:

• The SEXP type doesn’t match T::SEXP_TYPE
• The dim attribute has wrong number of dimensions

pub unsafe fn as_slice(&self) -> &[T]

Get the data as a slice (column-major order).

Safety

The SEXP must be protected and valid.

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

Get the data as a mutable slice (column-major order).

Safety

• The SEXP must be protected and valid
• No other references to the data may exist

pub unsafe fn to_vec(&self) -> Vec<T>

where T: Copy,

Copy array data to an owned Vec<T>.

This method copies the data, making it safe to use in worker threads or pass to parallel computation. The copy is performed on the current thread (which must be the R main thread).

Safety

The SEXP must be protected and valid.

Example

use miniextendr_api::rarray::RMatrix;

#[miniextendr(unsafe(main_thread))]
fn process_matrix(m: RMatrix<f64>) -> f64 {
    // Copy data - Vec<f64> is Send and can be used in worker threads
    let data: Vec<f64> = unsafe { m.to_vec() };
    // Now data can be passed to parallel computation
    data.iter().sum()
}

pub unsafe fn get(&self, indices: [usize; NDIM]) -> T

where T: Copy,

Get an element by N-dimensional indices.

Safety

The SEXP must be protected and valid.

Panics

Panics if any index is out of bounds.

pub unsafe fn set(&mut self, indices: [usize; NDIM], value: T)

where T: Copy,

Set an element by N-dimensional indices.

Safety

• The SEXP must be protected and valid
• No other references to the data may exist

Panics

Panics if any index is out of bounds.

impl<T: RNativeType> RArray<T, 2>

pub unsafe fn nrow(&self) -> usize

Get the number of rows.

Safety

The SEXP must be valid.

pub unsafe fn ncol(&self) -> usize

Get the number of columns.

Safety

The SEXP must be valid.

pub unsafe fn get_rc(&self, row: usize, col: usize) -> T

where T: Copy,

Get an element by row and column.

Safety

The SEXP must be protected and valid.

pub unsafe fn set_rc(&mut self, row: usize, col: usize, value: T)

where T: Copy,

Set an element by row and column.

Safety

• The SEXP must be protected and valid
• No other references to the data may exist

pub unsafe fn column(&self, col: usize) -> &[T]

Get a column as a slice.

Safety

The SEXP must be protected and valid.

pub unsafe fn column_mut(&mut self, col: usize) -> &mut [T]

Get a mutable column as a slice.

Columns are contiguous in R’s column-major layout, so this returns a proper &mut [T] without any striding.

Safety

The SEXP must be protected and valid.

Panics

Panics if col >= ncol.

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

fn get_attr_opt(&self, name: SEXP) -> Option<SEXP>

Get an arbitrary attribute by symbol (unchecked internal helper).

Safety

• The SEXP must be valid.
• what must be a valid symbol SEXP.

pub unsafe fn get_names(&self) -> Option<SEXP>

Get the names attribute if present.

Equivalent to R’s GET_NAMES(x).

Safety

The SEXP must be valid.

pub unsafe fn get_class(&self) -> Option<SEXP>

Get the class attribute if present.

Equivalent to R’s GET_CLASS(x).

Safety

The SEXP must be valid.

pub unsafe fn get_dimnames(&self) -> Option<SEXP>

Get the dimnames attribute if present.

Equivalent to R’s GET_DIMNAMES(x).

Safety

The SEXP must be valid.

pub unsafe fn get_rownames(&self) -> Option<SEXP>

Get row names from the dimnames attribute.

Equivalent to R’s GET_ROWNAMES(x) / Rf_GetRowNames(x).

Safety

The SEXP must be valid.

pub unsafe fn get_colnames(&self) -> Option<SEXP>

Get column names from the dimnames attribute.

Equivalent to R’s GET_COLNAMES(x) / Rf_GetColNames(x).

Safety

The SEXP must be valid.

pub unsafe fn set_names(&mut self, names: SEXP)

Set an arbitrary attribute by symbol (unchecked internal helper).

Safety

Set the names attribute.

Equivalent to R’s SET_NAMES(x, n).

Safety

The SEXP must be valid and not shared.

pub unsafe fn set_class(&mut self, class: SEXP)

Set the class attribute.

Equivalent to R’s SET_CLASS(x, n).

Safety

The SEXP must be valid and not shared.

pub unsafe fn set_dimnames(&mut self, dimnames: SEXP)

Set the dimnames attribute.

Equivalent to R’s SET_DIMNAMES(x, n).

Safety

The SEXP must be valid and not shared.

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

pub unsafe fn new<F>(dims: [usize; NDIM], init: F) -> Self

where F: FnOnce(&mut [T]),

Allocate a new R array with the given dimensions.

The array is allocated. The closure receives a mutable slice to initialize the data.

Safety

Must be called from the R main thread (or via routed FFI). The returned RArray holds an unprotected SEXP - caller must protect.

Example

let matrix = unsafe {
    RMatrix::<f64>::new([3, 4], |slice| {
        for (i, v) in slice.iter_mut().enumerate() {
            *v = i as f64;
        }
    })
};

pub unsafe fn zeros(dims: [usize; NDIM]) -> Self

where T: Default + Copy,

Allocate a new R array filled with zeros.

Safety

Must be called from the R main thread (or via routed FFI). The returned RArray holds an unprotected SEXP - caller must protect.

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

pub unsafe fn to_vec_coerced(&self) -> Vec<i8>

Copy array data to an owned Vec, coercing from the R native type.

Safety

The SEXP must be protected and valid.

Panics

Panics if any element fails to coerce (shouldn’t happen if constructed via TryFromSexp).

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

pub unsafe fn to_vec_coerced(&self) -> Vec<i16>

Copy array data to an owned Vec, coercing from the R native type.

Safety

The SEXP must be protected and valid.

Panics

Panics if any element fails to coerce (shouldn’t happen if constructed via TryFromSexp).

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

pub unsafe fn to_vec_coerced(&self) -> Vec<i64>

Copy array data to an owned Vec, coercing from the R native type.

Safety

The SEXP must be protected and valid.

Panics

Panics if any element fails to coerce (shouldn’t happen if constructed via TryFromSexp).

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

pub unsafe fn to_vec_coerced(&self) -> Vec<isize>

Copy array data to an owned Vec, coercing from the R native type.

Safety

The SEXP must be protected and valid.

Panics

Panics if any element fails to coerce (shouldn’t happen if constructed via TryFromSexp).

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

pub unsafe fn to_vec_coerced(&self) -> Vec<u16>

Copy array data to an owned Vec, coercing from the R native type.

Safety

The SEXP must be protected and valid.

Panics

Panics if any element fails to coerce (shouldn’t happen if constructed via TryFromSexp).

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

pub unsafe fn to_vec_coerced(&self) -> Vec<u32>

Copy array data to an owned Vec, coercing from the R native type.

Safety

The SEXP must be protected and valid.

Panics

Panics if any element fails to coerce (shouldn’t happen if constructed via TryFromSexp).

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

pub unsafe fn to_vec_coerced(&self) -> Vec<u64>

Copy array data to an owned Vec, coercing from the R native type.

Safety

The SEXP must be protected and valid.

Panics

Panics if any element fails to coerce (shouldn’t happen if constructed via TryFromSexp).

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

pub unsafe fn to_vec_coerced(&self) -> Vec<usize>

Copy array data to an owned Vec, coercing from the R native type.

Safety

The SEXP must be protected and valid.

Panics

Panics if any element fails to coerce (shouldn’t happen if constructed via TryFromSexp).

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

pub unsafe fn to_vec_coerced(&self) -> Vec<f32>

Copy array data to an owned Vec, coercing from the R native type.

Safety

The SEXP must be protected and valid.

Panics

Panics if any element fails to coerce (shouldn’t happen if constructed via TryFromSexp).

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

pub unsafe fn to_vec_coerced(&self) -> Vec<bool>

Copy array data to an owned Vec, coercing from the R native type.

Safety

The SEXP must be protected and valid.

Panics

Panics if any element fails to coerce (shouldn’t happen if constructed via TryFromSexp).

Trait Implementations

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

fn clone(&self) -> RArray<T, NDIM>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<T: RNativeType, const NDIM: usize> IntoR for RArray<T, NDIM>

type Error = Infallible

The error type for fallible conversions.

fn try_into_sexp(self) -> Result<SEXP, Self::Error>

Try to convert this value to an R SEXP.

unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error>

Try to convert to SEXP without thread safety checks.

fn into_sexp(self) -> SEXP

Convert this value to an R SEXP, panicking on error.

unsafe fn into_sexp_unchecked(self) -> SEXP

Convert to SEXP without thread safety checks, panicking on error.

impl<T: RNativeType, const NDIM: usize> TryFromSexp for RArray<T, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

impl<const NDIM: usize> TryFromSexp for RArray<bool, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

impl<const NDIM: usize> TryFromSexp for RArray<f32, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

impl<const NDIM: usize> TryFromSexp for RArray<i16, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

impl<const NDIM: usize> TryFromSexp for RArray<i64, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

impl<const NDIM: usize> TryFromSexp for RArray<i8, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

impl<const NDIM: usize> TryFromSexp for RArray<isize, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

impl<const NDIM: usize> TryFromSexp for RArray<u16, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

impl<const NDIM: usize> TryFromSexp for RArray<u32, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

impl<const NDIM: usize> TryFromSexp for RArray<u64, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

impl<const NDIM: usize> TryFromSexp for RArray<usize, NDIM>

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

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

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 8 bytes