Nullable Optional Arguments in Rcpp functions

Satyaprakash Nayak — written May 18, 2020 — source

Introduction

Often we need to have optional arguments in R of Rcpp functions with default values. Sometimes, the default value for the optional parameters is set to be NULL. Rcpp provides the Nullable <> to set default value as to be R_NilValue (equivalent of NULL in Rcpp). There have been several StackOverflow posts on using the Nullable behavior. As seen from quite a few posts, the key step in using Rcpp::Nullable<> is to cast it to the underlying type first (i.e., instantiation) after checking that the input is not NULL.

Nullability of Vector, Matrix or Logical Vector

// Checking setting Vector, Matrix and LogicalVector to NULL by default and 
// using the input if not set to NULL
#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
void nullable1(Nullable<NumericVector> NV_ = R_NilValue, 
               Nullable<NumericMatrix> NM_ = R_NilValue, 
               Nullable<LogicalVector> LG_ = R_NilValue){
  
    if (NV_.isNotNull()) {
        NumericVector NV(NV_);        // casting to underlying type NumericVector
        Rcout << "Numeric Vector is set to not NULL." << std::endl;
        Rcout << NV << std::endl;
    } else if (NM_.isNotNull()){
        NumericMatrix NM(NM_);       // casting to underlying type NumericMatrix
        Rcout << "Numeric Matrix is set to not NULL." << std::endl;
        Rcout << NM << std::endl;
    } else if (LG_.isNotNull()){
        LogicalVector LG(LG_);       // casting to underlying type Boolean
        Rcout << "Logical Vector is set to not NULL." << std::endl;
        Rcout << LG << std::endl;
    } else {
        warning("All arguments are set to NULL.\n");
    }
}

Running a few examples with setting NULL for a vector, matrix or a boolean value gives us the expected results.

nullable1(c(1,2), NULL, NULL)

Numeric Vector is set to not NULL.
1 2

m <- matrix(-0.5, 3, 3)
nullable1(NULL, m, NULL)

Numeric Matrix is set to not NULL.
-0.500000 -0.500000 -0.500000
-0.500000 -0.500000 -0.500000
-0.500000 -0.500000 -0.500000

nullable1(NULL, NULL, FALSE)

Logical Vector is set to not NULL.
0

nullable1(NULL, NULL, NULL)

Warning in nullable1(NULL, NULL, NULL): All arguments are set to NULL.

nullable1(c(), NULL, NULL)

Warning in nullable1(c(), NULL, NULL): All arguments are set to NULL.

We get the same result when the input to the NumericVector argument is not NULL but an empty vector, i.e., c(), which is also expected since is.null(c()) is TRUE in R.

A stricter test whether the input is usable can be (aptly named) isUsable().

// Testing another check, isUsable for a Nullable Vector
#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
void nullable2(Nullable<NumericVector> NV_ = R_NilValue) {
  
    if (NV_.isUsable()) {
        NumericVector NV(NV_);        // casting to underlying type NumericVector
        Rcout << "Input is usable." << std::endl;
        Rcout << NV << std::endl;
    } else {
        Rcout << "Input is either NULL or not usable." << std::endl;
    }
}

Nullability of DataFrame and List

Rcpp::Nullable<> works for SEXP based Rcpp types, so Rcpp::DataFrame and Rcpp::List can also be set to Nullable and instantiated if not NULL.

// Checking setting List and DataFrame to NULL by default and 
// using the input if not set to NULL
#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
void nullable3(Nullable<List> ls_ = R_NilValue, Nullable<DataFrame> df_ = R_NilValue){

    if (ls_.isNotNull()){
        Rcpp::List ls(ls_);                          // casting to underlying type List
        Rcout << "List is not NULL." << std::endl;
        Rcout << "List length of " << ls.length() << " elements." << std::endl;
    } else if(df_.isNotNull()) {
        Rcpp::DataFrame df(df_);                    // casting to underlying type DataFrame
        Rcout << "DataFrame is not NULL." << std::endl;
        Rcout << "DataFrame of " << df.nrows() << " rows and " << df.length() << " columns." << std::endl;
    } else {
        warning("Both inputs are NULL.\n");
    }
}

Testing with Rcpp::List and Rcpp::DataFrame gives expected results, i.e.,

mylist <- list(A = 1:10, B = letters[1:10])
nullable3(mylist, NULL)

List is not NULL.
List length of 2 elements.

df  <- data.frame(A = 1:20, B = letters[1:20])
nullable3(NULL, df)

DataFrame is not NULL.
DataFrame of 20 rows and 2 columns.

Nullability of `RcppGSL::Matrix`

In addition to Rcpp types, RcppGSL::Matrix can also be set with Nullable type (e.g, in the mvlabund package): e.g.,

// Checking setting RcppGSL Matrix to NULL by default and 
// using the input if not set to NULL
// [[Rcpp::depends(RcppGSL)]]
#include <RcppGSL.h>

using namespace Rcpp;

// [[Rcpp::export]]
void nullable4(Rcpp::Nullable<RcppGSL::Matrix> M_ = R_NilValue) {
  
    if (M_.isNotNull()){
        RcppGSL::Matrix M(M_);      // casting to underlying type RcppGSL::Matrix
        Rcout << "Input is not NULL." << std::endl;
        Rcout << "Input GSL matrix has " << M.nrow() << " and " << M.ncol() << " columns.\n";
    } else {
        warning("Input GSL Matrix is NULL.\n");
    }
}

Finally, testing with RcppGSL::Matrix which can also be set to Nullable<>, i.e.,

nullable4(NULL)  # testing with NULL

Warning in nullable4(NULL): Input GSL Matrix is NULL.

m <- matrix(-0.5, 3, 3) # testing with a non-NULL matrix
nullable4(m)

Input is not NULL.
Input GSL matrix has 3 and 3 columns.

Summary

Rcpp provides a convenient construct to set datatypes to NULL using R_NilValue and application of the datatype if not set to NULL using the .isNotNull() check. This construct to applied to set datatypes to NULL as default values and possible simple simplification.

tags: nullable

Extending R with C++ and Fortran — Dirk Eddelbuettel and JBrandon Duck-Mayr
Benchmarking Rcpp code with RcppClock — Zach DeBruine
Simulation Smoother using RcppArmadillo — Tomasz Woźniak