| Title: | Header-Only 'C++' and 'R' Interface |
|---|---|
| Description: | Provides a header only, 'C++' interface to 'R' with enhancements over 'cpp11'. Enforces copy-on-write semantics consistent with 'R' behavior. Offers native support for ALTREP objects, 'UTF-8' string handling, modern 'C++' features and idioms, and reduced memory requirements. Allows for vendoring, making it useful for restricted environments. Compared to 'cpp11', it adds support for converting 'C++' maps to 'R' lists, 'Roxygen' documentation directly in 'C++' code, proper handling of matrix attributes, support for nullable external pointers, bidirectional copy of complex number types, flexibility in type conversions, use of nullable pointers, and various performance optimizations. |
| Authors: | Mauricio Vargas Sepulveda [aut, cre] (ORCID: <https://orcid.org/0000-0003-1017-7574>), Posit Software, PBC [aut] (Original cpp11 package) |
| Maintainer: | Mauricio Vargas Sepulveda <[email protected]> |
| License: | Apache License (>= 2) |
| Version: | 1.1.0 |
| Built: | 2026-07-25 14:30:21 UTC |
| Source: | https://github.com/pachadotdev/cpp4r |
Provides a header only, 'C++' interface to 'R' with enhancements over 'cpp11'. Enforces copy-on-write semantics consistent with 'R' behavior. Offers native support for ALTREP objects, 'UTF-8' string handling, modern 'C++' features and idioms, and reduced memory requirements. Allows for vendoring, making it useful for restricted environments. Compared to 'cpp11', it adds support for converting 'C++' maps to 'R' lists, 'Roxygen' documentation directly in 'C++' code, proper handling of matrix attributes, support for nullable external pointers, bidirectional copy of complex number types, flexibility in type conversions, use of nullable pointers, and various performance optimizations.
Copies a package template into a new directory. The template includes a DESCRIPTION file, a minimal R/ directory and placeholders with instructions. You can then edit these files to customize your new package.
pkg_template(path = NULL, pkgname = NULL)pkg_template(path = NULL, pkgname = NULL)
path |
Path to the new project |
pkgname |
Name of the new package |
The file path to the copied template (invisibly).
# create a new directory dir <- tempdir() dir.create(dir) # copy the package template into the directory pkg_template(dir, "mynewpkg")# create a new directory dir <- tempdir() dir.create(dir) # copy the package template into the directory pkg_template(dir, "mynewpkg")
Functions decorated with [[cpp4r::register]] in files
ending in '.cc', '.cpp', '.h' or '.hpp' will be wrapped in generated code
and registered to be called from R. Decorating a function only makes it
callable via '.Call()'; it does not export or document it. See the
"Package skeleton" vignette for how to export a registered function.
register(path = NULL, quiet = !is_interactive(), extension = c(".cpp", ".cc"))register(path = NULL, quiet = !is_interactive(), extension = c(".cpp", ".cc"))
path |
The path to the package root directory. The default is 'NULL', |
quiet |
If 'TRUE' suppresses output from this function |
extension |
The file extension to use for the generated src/cpp4r file. '.cpp' by default, but '.cc' is also supported. |
The paths to the generated R and C++ source files (in that order).
# create a minimal package dir <- tempfile() dir.create(dir) writeLines("Package: testPkg", file.path(dir, "DESCRIPTION")) writeLines("useDynLib(testPkg, .registration = TRUE)", file.path(dir, "NAMESPACE")) # create a C++ file with a decorated function dir.create(file.path(dir, "src")) writeLines("[[cpp4r::register]] int one() { return 1; }", file.path(dir, "src", "one.cpp")) # register the functions in the package register(dir) # Files generated by registration file.exists(file.path(dir, "R", "cpp4r.R")) file.exists(file.path(dir, "src", "cpp4r.cpp")) # cleanup unlink(dir, recursive = TRUE)# create a minimal package dir <- tempfile() dir.create(dir) writeLines("Package: testPkg", file.path(dir, "DESCRIPTION")) writeLines("useDynLib(testPkg, .registration = TRUE)", file.path(dir, "NAMESPACE")) # create a C++ file with a decorated function dir.create(file.path(dir, "src")) writeLines("[[cpp4r::register]] int one() { return 1; }", file.path(dir, "src", "one.cpp")) # register the functions in the package register(dir) # Files generated by registration file.exists(file.path(dir, "R", "cpp4r.R")) file.exists(file.path(dir, "src", "cpp4r.cpp")) # cleanup unlink(dir, recursive = TRUE)
This function removes the vendored cpp4r headers from your package by automatically finding the vendored headers.
unvendor(path = NULL)unvendor(path = NULL)
path |
The directory with the vendored headers. It is recommended to use '"./src/vendor"'. The default is 'NULL'. |
The path to the unvendored code (invisibly).
# create a new directory dir <- paste0(tempdir(), "/", gsub("\\s+|[[:punct:]]", "", Sys.time())) dir.create(dir, recursive = TRUE) # vendor the cpp4r headers into the directory vendor(dir) # unvendor the cpp4r headers from the directory unvendor(dir) # cleanup unlink(dir, recursive = TRUE)# create a new directory dir <- paste0(tempdir(), "/", gsub("\\s+|[[:punct:]]", "", Sys.time())) dir.create(dir, recursive = TRUE) # vendor the cpp4r headers into the directory vendor(dir) # unvendor the cpp4r headers from the directory unvendor(dir) # cleanup unlink(dir, recursive = TRUE)
Vendoring is the act of making your own copy of the 3rd party packages your project is using. It is often used in the go language community.
This function vendors cpp4r into your package by copying the cpp4r headers into the ‘inst/include' folder of your package and adding ’cpp4r version: XYZ' to the top of the files, where XYZ is the version of cpp4r currently installed on your machine.
Vendoring places the responsibility of updating the code on you. Bugfixes and new features in
cpp4r will not be available for your code until you run cpp_vendor() again.
vendor(path = NULL)vendor(path = NULL)
path |
The directory with the vendored headers. It is recommended to use '"./src/vendor"'. The default is 'NULL'. |
The path to the vendored code (invisibly).
# create a new directory dir <- paste0(tempdir(), "/", gsub("\\s+|[[:punct:]]", "", Sys.time())) dir.create(dir, recursive = TRUE, showWarnings = FALSE) # vendor the cpp4r headers into the directory vendor(dir) list.files(dir, recursive = TRUE) # cleanup unlink(dir, recursive = TRUE)# create a new directory dir <- paste0(tempdir(), "/", gsub("\\s+|[[:punct:]]", "", Sys.time())) dir.create(dir, recursive = TRUE, showWarnings = FALSE) # vendor the cpp4r headers into the directory vendor(dir) list.files(dir, recursive = TRUE) # cleanup unlink(dir, recursive = TRUE)