make CsubsetDT callable from C from in other packages

NEWS.md

@@ -8,6 +8,8 @@
 
 1. `DT[, {...; .(A,B)}]` (i.e. when `.()` is the final item of a multi-statement `{...}`) now auto-names the columns `A` and `B` (just like `DT[, .(A,B)]`) rather than `V1` and `V2`, [#2478](https://github.com/Rdatatable/data.table/issues/2478) [#609](https://github.com/Rdatatable/data.table/issues/609). Similarly, `DT[, if (.N>1) .(B), by=A]` now auto-names the column `B` rather than `V1`. Explicit names are unaffected; e.g. `DT[, {... y= ...; .(A=C+y)}, by=...]` named the column `A` before, and still does. Thanks also to @renkun-ken for his go-first strong testing which caught an issue not caught by the test suite or by revdep testing, related to NULL being the last item, [#4061](https://github.com/Rdatatable/data.table/issues/4061).
 
+2. The C function `CsubsetDT` is exported in order to allow another package to use this fast subsetting of a `data.table` at C level. The exporting uses R's standard `R_RegisterCCallable` mechanism, which means other packages wishing to call this function use `R_GetCCallable` at C level in order to make the call. This mechanism is described in [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html) in _Linking to native routines in other packages_ section. See [`?cdt`](https://rdatatable.gitlab.io/data.table/reference/cdt.html) for details. Thanks to @lsilvest for request and submitting PR [#3751](https://github.com/Rdatatable/data.table/issues/3751).
+
 ## BUG FIXES
 
 ## NOTES

man/cdt.Rd

@@ -0,0 +1,20 @@
+\name{cdt}
+\alias{cdatatable}
+\title{ data.table exported C routines }
+\description{
+  Some of internally used C routines are now exported. This interface should be considered experimental. List of exported C routines and their signatures are provided below in the usage section.
+}
+\usage{
+# SEXP subsetDT(SEXP x, SEXP rows, SEXP cols);
+# p_dtCsubsetDT = R_GetCCallable("data.table", "CsubsetDT");
+}
+\details{
+  For details how to use those see \emph{Writing R Extensions} manual \emph{Linking to native routines in other packages} section.
+}
+\note{
+  Be aware C routines are likely to have less input validation than their corresponding R interface. For example one should not expect \code{DT[-5L]} will be equal to \code{.Call(CsubsetDT, DT, -5L, seq_along(DT))} because translation of \code{i=-5L} to \code{seq_len(nrow(DT))[-5L]} might be happening on R level. Moreover checks that \code{i} argument is in range of \code{1:nrow(DT)}, missingness, etc. might be happening on R level too.
+}
+\references{
+  \url{https://cran.r-project.org/doc/manuals/r-release/R-exts.html}
+}
+\keyword{ data }

src/init.c

@@ -202,6 +202,9 @@ static void setSizes() {
 void attribute_visible R_init_datatable(DllInfo *info)
 // relies on pkg/src/Makevars to mv data.table.so to datatable.so
 {
+  // C exported routines, see ?cdt for details
+  R_RegisterCCallable("data.table", "CsubsetDT", (DL_FUNC) &subsetDT);
+
   R_registerRoutines(info, NULL, callMethods, NULL, externalMethods);
   R_useDynamicSymbols(info, FALSE);
   setSizes();

src/subset.c

@@ -242,7 +242,7 @@ static void checkCol(SEXP col, int colNum, int nrow, SEXP x)
 *   4) Could do it other ways but may as well go to C now as we were going to do that anyway
 */
 
-SEXP subsetDT(SEXP x, SEXP rows, SEXP cols) {
+SEXP subsetDT(SEXP x, SEXP rows, SEXP cols) { // API change needs update NEWS.md and man/cdt.Rd
   int nprotect=0;
   if (!isNewList(x)) error("Internal error. Argument 'x' to CsubsetDT is type '%s' not 'list'", type2char(TYPEOF(rows))); // # nocov
   if (!length(x)) return(x);  // return empty list

vignettes/datatable-importing.Rmd

@@ -189,7 +189,11 @@ If this is anyway your preferred approach to package development, please define
 
 ## Further information on dependencies
 
-For more canonical documentation of defining packages dependency check the official manual: [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html)
+For more canonical documentation of defining packages dependency check the official manual: [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html).
+
+## Importing data.table C routines
+
+Some of internally used C routines are now exported on C level thus can be used in R packages directly from their C code. See [`?cdt`](https://rdatatable.gitlab.io/data.table/reference/cdt.html) for details and [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html) _Linking to native routines in other packages_ section for usage.
 
 ## Importing from non-R Applications {non-r-API}