Adapted from the official Armadillo documentation.

armadillo4r provides a set of conversion functions, declared across armadillo4r/wrappers/matrices.hpp, armadillo4r/wrappers/vectors.hpp, armadillo4r/wrappers/cubes.hpp, and armadillo4r/wrappers/fields.hpp, and all automatically available after including <armadillo4r.hpp>. This vignette documents every function and shows a minimal C++ example for each group.

1 R to Armadillo

1.1 Matrices

R matrices are represented in cpp4r as doubles_matrix<> (numeric) or integers_matrix<> (integer). The following functions convert them to Armadillo dense matrices:

cpp4r input	Function	Armadillo output	Notes
doubles_matrix<>	as_Mat(x) / as_mat(x)	Mat<double>	as_mat() is a lowercase alias
integers_matrix<>	as_Mat(x) / as_mat(x)	Mat<int>	same alias applies
integers_matrix<>	as_imat(x)	imat (Mat<sword>)	signed integer matrix
integers_matrix<>	as_umat(x)	umat (Mat<uword>)	unsigned integer matrix; copies element-by-element
doubles_matrix<>	as_fmat(x)	fmat (Mat<float>)	narrows double to float

#include <cpp4r.hpp>
#include <armadillo4r.hpp>

using namespace arma;
using namespace cpp4r;

[[cpp4r::register]]
doubles_matrix<> mat_demo_(const doubles_matrix<>& x,
                           const integers_matrix<>& xi) {
  mat    A  = as_Mat(x);    // double matrix
  imat   Ai = as_imat(xi);  // signed int matrix
  umat   Au = as_umat(xi);  // unsigned int matrix
  fmat   Af = as_fmat(x);   // float matrix

  // use A, Ai, Au, Af ...
  return as_doubles_matrix(A * A.t());
}

x <- matrix(c(1.5, 2.5, 3.5, 4.5), nrow = 2)
xi <- matrix(1:4, nrow = 2)
mat_demo_(x, xi)

1.2 Vectors

R vectors (doubles / integers) map to Armadillo column vectors:

cpp4r input	Function	Armadillo output	Notes
doubles	as_Col(x) / as_col(x)	Col<double> (vec)	as_col() is a lowercase alias
integers	as_Col(x) / as_col(x)	Col<int>	same alias applies
integers	as_uvec(x)	uvec (Col<uword>)	copies element-by-element (no reinterpret)

[[cpp4r::register]]
doubles vec_demo_(const doubles& y, const integers& yi) {
  vec  v  = as_Col(y);    // double column vector
  uvec vu = as_uvec(yi);  // unsigned int column vector

  // use v, vu ...
  return as_doubles(v % v);   // element-wise square
}

vec_demo_(c(1.0, 2.0, 3.0), 1:3)

1.3 Cubes

R has no native quasi third-order tensors (“3D matrices”) that maps directly onto Armadillo’s memory layout. armadillo4r therefore represents a cube on the R side as a list of matrices, where every element is a matrix of the same dimensions. Slice s of the Armadillo cube corresponds to element s + 1 of the R list (R is 1-indexed).

The most commonly used cube typedefs are:

Typedef	Equivalent	Element type
cube / dcube	Cube<double>	double
fcube	Cube<float>	float
icube	Cube<sword>	long long (signed, platform-dependent)
ucube	Cube<uword>	unsigned int
cx_cube / cx_dcube	Cube<cx_double>	std::complex<double>

cpp4r input	Function	Armadillo output	Notes
list of doubles_matrix<>	as_Cube(x) / as_cube(x)	Cube<double> (cube)	as_cube() is a lowercase alias
list of integers_matrix<>	as_icube(x)	Cube<int>	note: assigns to Cube<int>, not icube (Cube<sword>)

Both functions throw std::runtime_error if the list is empty or any matrix has dimensions different from the first.

[[cpp4r::register]]
doubles_matrix<> cube_col_means_(const list& slices) {
  cube C = as_Cube(slices);   // list of doubles_matrix<> -> cube

  mat result(C.n_slices, C.n_cols);
  for (uword s = 0; s < C.n_slices; ++s) {
    result.row(s) = mean(C.slice(s), 0);  // column means of each slice
  }

  return as_doubles_matrix(result);
}

slices <- list(
  matrix(1:6, nrow = 2), # slice 1
  matrix(7:12, nrow = 2), # slice 2
  matrix(13:18, nrow = 2) # slice 3
)
cube_col_means_(slices)

1.4 Fields

An Armadillo field<object_type> stores arbitrary objects (matrices, vectors, strings, …) in a matrix-like or cube-like layout. Unlike Cube, the elements of a field do not need to have the same size — each element is an independent object.

Tip: when all matrices share the same dimensions, prefer Cube over field<mat> because Cube is more memory-efficient and faster.

On the R side a field is always represented as a plain list (or strings for field<std::string>). Element i of the Armadillo field (0-indexed) corresponds to element i + 1 of the R list (1-indexed).

cpp4r input	Function	Armadillo output	Notes
list of doubles_matrix<>	as_field_mat(x)	field<mat>	matrices may differ in size
list of integers_matrix<>	as_field_imat(x)	field<imat>	matrices may differ in size
list of doubles	as_field_vec(x)	field<vec>	vectors may differ in length
strings	as_field_str(x)	field<std::string>

All four functions throw std::runtime_error if the input list is empty.

[[cpp4r::register]]
list field_mat_demo_(const list& mats) {
  // Ragged list of matrices -> field<mat>
  field<mat> F = as_field_mat(mats);

  // Normalise each matrix independently
  for (uword i = 0; i < F.n_elem; ++i) {
    F(i) = normalise(F(i));  // L2-normalise columns
  }

  // field<mat> -> list of doubles_matrix<>
  return as_doubles_matrix_field(F);
}

mats <- list(
  matrix(1:6, nrow = 2), # 2x3 matrix
  matrix(1:12, nrow = 4) # 4x3 matrix  (different nrow!)
)
field_mat_demo_(mats)

2 Armadillo to R

2.1 Matrices

Armadillo input	Function	cpp4r output
Mat<double> / mat / fmat	as_doubles_matrix(A)	doubles_matrix<>
Mat<int> / imat / umat	as_integers_matrix(A)	integers_matrix<>
Mat<cx_double> / cx_mat	as_complexes_matrix(A)	complexes_matrix<>

[[cpp4r::register]]
doubles_matrix<> mat_out_demo_(const doubles_matrix<>& x) {
  mat A = as_Mat(x);
  return as_doubles_matrix(A.t() * A);  // mat -> doubles_matrix<>
}

x <- matrix(1:9, nrow = 3) * 1.0
mat_out_demo_(x)

2.2 Vectors

Armadillo input	Function	cpp4r output
Col<double> / vec	as_doubles(v)	doubles
Col<int> / ivec	as_integers(v)	integers
uvec	as_integers(v)	integers

[[cpp4r::register]]
doubles vec_out_demo_(const doubles& y) {
  return as_doubles(normalise(as_Col(y)));  // vec -> doubles
}

vec_out_demo_(c(3.0, 4.0)) # should give c(0.6, 0.8)

2.3 Cubes

Armadillo input	Function	cpp4r output
Cube<double> / cube	as_doubles_matrix_list(C)	list of doubles_matrix<>
Cube<int> / icube	as_integers_matrix_list(C)	list of integers_matrix<>
ucube	as_integers_matrix_list(C)	list of integers_matrix<>

Slice s of the cube becomes element s + 1 of the returned R list.

[[cpp4r::register]]
list random_cube_(const int n_rows, const int n_cols, const int n_slices) {
  cube C(n_rows, n_cols, n_slices, fill::randn);
  return as_doubles_matrix_list(C);  // cube -> list of doubles_matrix<>
}

set.seed(42)
result <- random_cube_(3L, 4L, 2L)

length(result) # 2  (one element per slice)
dim(result[[1]]) # 3 4

2.4 Fields

Armadillo input	Function	cpp4r output
field<mat>	as_doubles_matrix_field(F)	list of doubles_matrix<>
field<imat>	as_integers_matrix_field(F)	list of integers_matrix<>
field<vec>	as_doubles_field(F)	list of doubles
field<std::string>	as_strings_field(F)	strings

Element i of the field (0-indexed) becomes element i + 1 of the returned R list (1-indexed). Because field elements may differ in size, the returned list is potentially ragged.

[[cpp4r::register]]
list build_field_(const integers& sizes) {
  // Build a field<vec> where each vector has a different length
  field<vec> F(sizes.size());

  for (uword i = 0; i < F.n_elem; ++i) {
    F(i) = randn<vec>(sizes[static_cast<int>(i)]);  // random vector of length sizes[i]
  }

  return as_doubles_field(F);  // field<vec> -> list of doubles
}

build_field_(c(3L, 5L, 2L)) # list of three vectors of lengths 3, 5, 2

2.5 Generic conversion with cpp4r::as_sexp()

For cases where the return type is determined at compile time, cpp4r::as_sexp() provides a single generic entry point that dispatches to the appropriate conversion based on the Armadillo type:

Armadillo input	as_sexp() output
vec / fvec	doubles
ivec / uvec	integers
mat / fmat	doubles_matrix<>
imat / umat	integers_matrix<>
rowvec / frowvec	doubles_matrix<> (1-row matrix)
irowvec / urowvec	integers_matrix<> (1-row matrix)

[[cpp4r::register]]
SEXP as_sexp_demo_(const doubles& y) {
  return cpp4r::as_sexp(arma::sort(as_Col(y)));  // vec -> doubles (dispatched automatically)
}

as_sexp_demo_(c(3.0, 1.0, 2.0)) # returns c(1, 2, 3)

3 References

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.