Exposing RcppTskit_treeseq_xptr in a header for #40 plus polish

Author: gregorgorjanc

RcppTskit/DESCRIPTION

@@ -30,16 +30,16 @@ Depends:
 Imports:
     methods,
     R6,
-    Rcpp (>= 1.1.0),
-    reticulate
+    Rcpp (>= 0.12.10),
+    reticulate (>= 1.41.0)
 Suggests:
     covr,
     knitr,
     quarto,
     spelling,
     testthat (>= 3.0.0)
 LinkingTo:
-    Rcpp (>= 1.1.0)
+    Rcpp (>= 0.12.10)
 VignetteBuilder:
     quarto
 Config/testthat/edition: 3

RcppTskit/R/RcppTskit.R

@@ -17,9 +17,9 @@
 #'   to avoid importing the module repeatedly, if it has been imported already
 #'   in which case we use that imported module. Since this process can be
 #'   finicky (it depends on the availability of reticulate Python, module already
-#'   instaled, internet access, etc.)
+#'   installed, internet access, etc.)
 #' @return \code{get_tskit_py} returns \code{tskit} a reticulate Python module
-#'   if succesful or otherwise throws an error (when \code{object_name} exists
+#'   if successful or otherwise throws an error (when \code{object_name} exists
 #'   but is not a reticulate Python module) or returns \code{simpleError}
 #'   (when installation or import failed). \code{check_tskit_py} returns
 #'   \code{TRUE} if \code{object} is a reticulate Python module or \code{FALSE}
@@ -52,7 +52,7 @@ get_tskit_py <- function(object_name = "tskit", force = FALSE) {
     }
   }
 
-  msgSuccess <- paste0('reticulate::py_require("', object_name, '") succeded!')
+  msgSuccess <- paste0('reticulate::py_require("', object_name, '") succeeded!')
   msgFail <- paste0('reticulate::py_require("', object_name, '") failed!')
   e <- simpleError(msgFail)
   if (!reticulate::py_module_available(object_name)) {

RcppTskit/inst/include/RcppTskit.hpp

@@ -0,0 +1,21 @@
+#ifndef RCPPTSKIT_H
+#define RCPPTSKIT_H
+
+#include <Rcpp.h>
+#include <tskit.h>
+
+// Finaliser to free tsk_treeseq_t when it is garbage collected
+// See \url{https://tskit.dev/tskit/docs/stable/c-api.html#c.tsk_treeseq_free}
+// for more details.
+static void RcppTskit_treeseq_xptr_delete(tsk_treeseq_t *ptr) {
+  if (ptr != NULL) {
+    tsk_treeseq_free(ptr);
+    delete ptr;
+  }
+}
+
+// Define the external pointer type for tsk_treeseq_t with the finaliser
+using RcppTskit_treeseq_xptr = Rcpp::XPtr<tsk_treeseq_t, Rcpp::PreserveStorage,
+                                          RcppTskit_treeseq_xptr_delete, true>;
+
+#endif

RcppTskit/man/get_tskit_py.Rd

@@ -1,21 +1,4 @@
-#include <Rcpp.h>
-#include <tskit.h>
-
-// using namespace Rcpp; // to omit Rcpp:: prefix for whole Rcpp API
-// using Rcpp::IntegerVector; // to omit Rcpp:: prefix for IntegerVector
-
-// Finaliser to free tsk_treeseq_t when it is garbage collected
-// See \url{https://tskit.dev/tskit/docs/stable/c-api.html#c.tsk_treeseq_free}
-// for more details.
-static void RcppTskit_treeseq_xptr_delete(tsk_treeseq_t *ptr) {
-  if (ptr != NULL) {
-    tsk_treeseq_free(ptr);
-    delete ptr;
-  }
-}
-// Define the external pointer type for tsk_treeseq_t with the finaliser
-using RcppTskit_treeseq_xptr = Rcpp::XPtr<tsk_treeseq_t, Rcpp::PreserveStorage,
-                                          RcppTskit_treeseq_xptr_delete, true>;
+#include <RcppTskit.hpp>
 
 //' @title Report the version of installed kastore C API
 //' @details The version is stored in the installed header \code{kastore.h}.

RcppTskit/src/RcppTskit.cpp

@@ -157,16 +157,20 @@ after we describe the implemented data and class model.
 
 ## Data and class model
 
-`RcppTskit` represents a tree sequence as a lightweight R object of R6 class `TreeSequence`.
-R6 class was partially chosen so the R code calls resemble Python code.
-`TreeSequence` wraps an external pointer (`externalptr`) to the `tskit`
-C data structure (`tsk_treeseq_t`).
-Most methods (for example, `ts$num_individuals()`, `ts$dump()`, etc.)
+`RcppTskit` represents a tree sequence as a lightweight R6 object of class `TreeSequence`.
+The R6 class was chosen in part so that `TreeSequence` method calls in R
+resemble the tskit Python API.
+`TreeSequence` wraps an external pointer (`externalptr`) to
+the `tskit` C object structure `tsk_treeseq_t`.
+Most methods (for example, `ts$num_individuals()` and `ts$dump()`)
 call the `tskit` C API via `Rcpp`,
-so the calls are fast and the object is not copied
-unless you explicitly write/read or change it.
+so calls are fast and the object is not copied
+unless you explicitly modify it.
 The underlying pointer is exposed as `TreeSequence$pointer`
-for developers and advanced users that can write C++ code.
+for developers and advanced users who work with C++.
+In C++, the pointer has type `RcppTskit_treeseq_xptr`,
+and the tree sequence memory is released by the `Rcpp::XPtr`
+finaliser when the pointer is garbage-collected in R.
 
 ## For typical use cases
 
@@ -256,9 +260,9 @@ ts$num_individuals() # 2 (if you have ran the above Python code)
 #| label: use_case_3
 # Write a C++ function as multi-line character string
 codeString <- '
-  #include <tskit.h>
+  #include <RcppTskit.hpp>
   int ts_num_individuals(SEXP ts) {
-    Rcpp::XPtr<tsk_treeseq_t> ts_xptr(ts);
+      RcppTskit_treeseq_xptr ts_xptr(ts);
     return (int) tsk_treeseq_get_num_individuals(ts_xptr);
   }'
 
@@ -285,28 +289,33 @@ ts$num_individuals()
 
 ### 4) Call `tskit` C API in C++ code in another R package
 
-To call the `tskit` C API in your own R package via `Rcpp` you can leverage `RcppTskit`.
-Just follow the steps below and check how these were implemented in
-the test R package `RcppTskitTestPkgLinkingTo` at TODO.
+To call the `tskit` C API in your own R package via `Rcpp`
+you can leverage `RcppTskit`, which will simplify your installation
+and enable you to quickly call
+To do this, follow the steps below and check how these were implemented in
+the test R package `RcppTskitTestLinkingTo` at https://github.com/HighlanderLab/RcppTskitTestLinking.
 
-a) Open `DESCRIPTION` file and add `RcppTskit` to the `LinkingTo:` field,
-  TODO: likely also `Imports:` field.
+a) Open `DESCRIPTION` file and
+  add `RcppTskit` to the `Imports:` and `LinkingTo:` field, and further
+  add `Rcpp` to `LinkingTo:` field as a minimum.
 
-  TODO: And Rcpp too?
+b) Create `R/YourPackage-package.R` file and add to it at a minimum:
+  `#' @import RcppTskit` in one line and `"_PACKAGE"` in another line,
+  so that `devtools` will manage your package `NAMESPACE` imports.
 
-b) Add `#include <tskit.h>` as needed to your C++ header files in `src` directory.
+c) Add `#include <RcppTskit.hpp>` as needed to your C++ header files in `src` directory.
 
-c) Add `// [[Rcpp::depends(RcppTskit)]]` to your C++ files in `src` directory.
+d) Add `// [[Rcpp::depends(RcppTskit)]]` to your C++ files in `src` directory.
 
-d) Add `// [[Rcpp::plugins(RcppTskit)]]` to your C++ files in `src` directory.
+e) Add `// [[Rcpp::plugins(RcppTskit)]]` to your C++ files in `src` directory.
 
-e) Call `tskit` C API as needed in your C++ code in `src` directory.
+f) Call `RcppTskit` C++ API and `tskit` C API as needed in your C++ files in `src` directory.
 
-f) Configure your package build to use the `RcppTskit` library file
+g) Configure your package build to use the `RcppTskit` library file
   with the following steps:
 
   - Add `src/Makevars.in` and `src/Makevars.win.in` files with
-    `PKG_LIB = @RCPPTSKIT_LIB@` flag, in addition to other flags.
+    `PKG_LIBS = @RCPPTSKIT_LIB@` flag, in addition to other flags.
 
   - Add `tools/configure.R` file,
     which will replace `@RCPPTSKIT_LIB@` in `src/Makevars.in` and `src/Makevars.win.in`
@@ -319,7 +328,7 @@ f) Configure your package build to use the `RcppTskit` library file
   - Add `cleanup` and `cleanup.win` scripts (and make them executable)
     to remove `src/Makevars` and `src/Makevars.win` as well as compilation files.
 
-g) You should now be ready to build, check, and install your package using
+h) You should now be ready to build, check, and install your package using
   `devtools::build()`, `devtools::check()`, and `devtools::install()`
   or their `R CMD` equivalents.