Recommended approach for extracting Nullable values

[m-muecke]

I found the gallery post on working with Nullable, but couldn't find guidance specific to scalar types (integers and doubles) or Armadillo matrices. I wanted to check if the pattern below is a recommended approach.

void fn(Nullable<NumericMatrix>& x, Nullable<int>& c, Nullable<arma::mat>& mat) {
  // 1. using as<>
  if (x.isNotNull()) {
    NumericMatrix x_ = as<NumericMatrix>(x);
  }
  // 2. using constructor
  if (x.isNotNull()) {
    NumericMatrix x_(x);
  }
  // nullable for scalar
  if (c.isNotNull()) {
    int c_ = as<int>(c);
  }
  // with arma::mat works but creates a copy
  if (mat.isNotNull()) {
    arma::mat mat_ = as<arma::mat>(mat);
  }
}

[eddelbuettel]

It may help to step back. Nullable is for optional elements in a function signature for which we let Rcpp build an interface. This is constrained (by R itself) to work via .Call() where each element has to be a SEXP. So Nullable<> wraps around SEXP types. That is why the Gallery article mentions NumericMatrix, List, DataFrame (also a List, really).

'Plain old scalar' types like double are not a SEXP and cannot be overloaded that way. I might use the R ability to set them to NA to flag 'not here'. As for Armadillo's arma::mat and alike: similar. I would probably have to bite the bullet and a use NumericMatrix and then cast it if not null.

Otherwise what you do in your post seems roughly correct. The Nullable<> approach in Rcpp is a relatively simple trick, and in the 'object present' case you always have to cast so the ctor approach seems as valid as the as<> approach. As for Armadillo requiring a passage via NumericMatrix: that's just how the templating code is set up now. One could possibly add a bit more here but so far nobody has volunteered to do so, and what we have works well enough.

[m-muecke]

Much appreciated. Then I assume the above just worked "by accident" and isn't intended behaviour.
One more question: is there a preference between the as<> approach vs the constructor approach for extracting from Nullable, or is it purely stylistic?

[eddelbuettel]

Yep I would agree 😆 I think it is purely stylistic, and the end of the day we have to give the compiler something it can work with. I just played a little with this via Rcpp::cppFunction() and these all build (all of course skip the test for NonNull so it is really just a 'does it compile?' test and not meant to be used as is):

> cppFunction("arma::mat foo(Nullable<NumericMatrix> m) { NumericMatrix nm{m}; arma::mat am{Rcpp::as<arma::mat>(nm)}; return am; }", depends="RcppArmadillo")
> cppFunction("arma::mat foo(Nullable<NumericMatrix> m) { NumericMatrix nm{m}; arma::mat am{Rcpp::as<arma::mat>(m)}; return am; }", depends="RcppArmadillo")
> cppFunction("arma::mat foo(Nullable<NumericMatrix> m) { arma::mat am{Rcpp::as<arma::mat>(m)}; return am; }", depends="RcppArmadillo")

[eddelbuettel]

Actually, come to think about it, "by accident" is not right. These will likely invoke the same templating via as<>() that allow us to use double etc in a signature. So what you have works as intended. We just never (?) really documented it, but you unearthed it correctly.

> cppFunction("void foo(Nullable<double> s) { if (s.isNotNull()) { double d = as<double>(s); } }")
> 

In case like this is can be illuminating to look at either one of the unit tests (not much here) or within CRAN if the search is good and we see that Nullable<double> is indeed used that way in a few packages.

PS And even more for Nullable<int>

[eddelbuettel]

So a fuller answer may be: supports all types for we have SEXP converters -- including those for which you wrote your own (another Gallery etc topic).

[cgiachalis]

For Armadillo matrices, you can use a small lambda expression, initialise with arma advanced ctor, and invoke it immediately:

cppFunction("

arma::mat foo(Nullable<NumericMatrix> m = R_NilValue) {

 const arma::mat& x = [&m] {

    if (m.isNotNull()) {

      NumericMatrix M(m);
      arma::mat x(M.begin(), M.nrow(), M.ncol(), false, true); //  copy_aux_mem is set to false, no copying

      return x;

    } else {

      arma::mat x(0, 0, arma::fill::none);

      return x;
    }

  }();  // invoke!

  return x;

}

/*** R
foo(m = NULL)

foo(m = matrix(1:4, ncol = 2))

*/

", depends="RcppArmadillo")

From R console:

foo()
<0 x 0 matrix>

foo(matrix(1:4, ncol = 2))

     [,1] [,2]
[1,]    1    3
[2,]    2    4

[eddelbuettel]

And it does. So nice. We don't even need the lambda anymore.

Code

#include <RcppArmadillo/Lightest>
// [[Rcpp::depends(RcppArmadillo)]]

// [[Rcpp::export]]
arma::mat foo(Rcpp::Nullable<Rcpp::NumericMatrix> m = R_NilValue) {
    const arma::mat& x = [&m] {
        if (m.isNotNull()) {
            Rcpp::NumericMatrix M(m);
            arma::mat x(M.begin(), M.nrow(), M.ncol(), false, true); //  adv ctor, no copying
            return x;
        } else {
            arma::mat x(0, 0, arma::fill::none);
            return x;
        }
    }();  // invoke!
    return x;
}

// [[Rcpp::export]]
arma::mat bar(Rcpp::Nullable<arma::mat> m = R_NilValue) {
    const arma::mat& x = [&m] {
        if (m.isNotNull()) {
            return m.as();
        } else {
            return arma::mat{0, 0, arma::fill::none};
        }
    }();  // invoke!
    return x;
}

// [[Rcpp::export]]
arma::mat bis(Rcpp::Nullable<arma::mat> m = R_NilValue) {
    return (m.isNotNull() ? m.as() : arma::mat{0, 0, arma::fill::none});
}

/*** R
foo(NULL)
foo(matrix(1:4, ncol = 2))
bar()
bar(matrix(1:4, ncol = 2))
bis()
bis(matrix(1:4, ncol = 2))
*/

Demo

> Rcpp::sourceCpp("arma_nullable_example.cpp")

> foo(NULL)
<0 x 0 matrix>

> foo(matrix(1:4, ncol = 2))
     [,1] [,2]
[1,]    1    3
[2,]    2    4

> bar()
<0 x 0 matrix>

> bar(matrix(1:4, ncol = 2))
     [,1] [,2]
[1,]    1    3
[2,]    2    4

> bis()
<0 x 0 matrix>

> bis(matrix(1:4, ncol = 2))
     [,1] [,2]
[1,]    1    3
[2,]    2    4
> 

[eddelbuettel]

Now PR #1471 addressing issue #1470.

[cgiachalis]

And it does. So nice. We don't even need the lambda anymore.

Just a note, m.as() creates copy but with lambda variant we can pass by reference using armadillio's advanced ctor.

#include <RcppArmadillo/Lightest>
// [[Rcpp::depends(RcppArmadillo)]]

// [[Rcpp::export]]
arma::mat foo(Rcpp::Nullable<Rcpp::NumericMatrix> m = R_NilValue) {
  const arma::mat& x = [&m] {
    if (m.isNotNull()) {
      Rcpp::NumericMatrix M(m);
      arma::mat x(M.begin(), M.nrow(), M.ncol(), false, true); //  adv ctor, no copying
      return x += 1;
    } else {
      arma::mat x(0, 0, arma::fill::none);
      return x;
    }
  }();  // invoke!
  return x;
}

// [[Rcpp::export]]
arma::mat bis(Rcpp::Nullable<arma::mat> m = R_NilValue) {
  return (m.isNotNull() ? m.as() += 1: arma::mat{0, 0, arma::fill::none});
}


/*** R
# Pass by reference
x1 <- matrix(rep(1, 4), ncol = 2)
foo(x1)
cat("x1 after: ")
x1
# Pass by value
x2 <- matrix(rep(1, 4), ncol = 2)
bis(x2)
cat("x2 after: ")
x2
*/

> # Pass by reference
> x1 <- matrix(rep(1, 4), ncol = 2)

> foo(x1)
     [,1] [,2]
[1,]    2    2
[2,]    2    2

# x1 after: 
> x1
     [,1] [,2]
[1,]    2    2
[2,]    2    2

> # Pass by value
> x2 <- matrix(rep(1, 4), ncol = 2)

> bis(x2)
     [,1] [,2]
[1,]    2    2
[2,]    2    2

# x2 after: 
> x2
     [,1] [,2]
[1,]    1    1
[2,]    1    1

[eddelbuettel]

Quite possibly, and that may well be true in many, many other use cases of the Rcpp::as<arma::mat>() converter which tries to rely on the advanctor too (see inst/include/RcppArmadillo/interface/RcppArmadilloAs.h).

[eddelbuettel]

And it doesn't for me, oddly. What happens when you run this? My mistake. I created an integer matrix. Always a copy to Numeric.

#include <RcppArmadillo/Lightest>
// [[Rcpp::depends(RcppArmadillo)]]

// [[Rcpp::export]]
arma::mat foo(Rcpp::Nullable<Rcpp::NumericMatrix> m = R_NilValue) {
    const arma::mat& x = [&m] {
        if (m.isNotNull()) {
            Rcpp::NumericMatrix M(m);
            arma::mat x(M.begin(), M.nrow(), M.ncol(), false, true); //  adv ctor, no copying
            x += 1;
            return x;
        } else {
            arma::mat x(0, 0, arma::fill::none);
            return x;
        }
    }();  // invoke!
    return x;
}

// [[Rcpp::export]]
arma::mat bar(Rcpp::Nullable<arma::mat> m = R_NilValue) {
    const arma::mat& x = [&m] {
        if (m.isNotNull()) {
            return m.as();
        } else {
            return arma::mat{0, 0, arma::fill::none};
        }
    }();  // invoke!
    return x;
}

// [[Rcpp::export]]
arma::mat bis(Rcpp::Nullable<arma::mat> m = R_NilValue) {
    return (m.isNotNull() ? m.as() : arma::mat{0,0, arma::fill::none});
}


/*** R
m <- matrix(1:4, ncol = 2)
foo(NULL)
foo(m)
m
bar()
bar(m)
m
bis()
bis(m)
m
*/

I still have 1:4 at the end.

> Rcpp::sourceCpp("arma_nullable_example.cpp")

> m <- matrix(1:4, ncol = 2)

> foo(NULL)
<0 x 0 matrix>

> foo(m)
     [,1] [,2]
[1,]    2    4
[2,]    3    5

> m
     [,1] [,2]
[1,]    1    3
[2,]    2    4

> bar()
<0 x 0 matrix>

> bar(m)
     [,1] [,2]
[1,]    1    3
[2,]    2    4

> m
     [,1] [,2]
[1,]    1    3
[2,]    2    4

> bis()
<0 x 0 matrix>

> bis(m)
     [,1] [,2]
[1,]    1    3
[2,]    2    4

> m
     [,1] [,2]
[1,]    1    3
[2,]    2    4
> 

It works with m <- matrix(1.0*(1:4), ncol = 2)

[eddelbuettel]

To sum up, and circle back to the original point by @m-muecke : Going via SEXP to Rcpp::NumericMatrix to (advanced) ctor for arma::mat with re-use --- which used to be the default for the Armadillo package until an interface rewrite / enhancement in the early 2010s -- seems to be the only 'non-copy way'. We can transfer arma::mat object that way (including via the const & approach) but not once Nullable is involved.

I don't think that is a big deal as Nullable is chiefly a helper for function signature objects which tend to be small (and often scalar). And when one needs to transfer a yuge matrix and is afraid of copies, the moer verbose alternate exists.