README.md
1# backports
2
3[](https://cran.r-project.org/package=backports)
4[](https://github.com/r-lib/backports/actions)
5[](https://cran.r-project.org/package=backports)
6
7This package provides backports of functions which have been introduced in one of the base packages in R version 3.0.1 or later.
8The backports are conditionally exported in order to let R resolve the function name to either the implemented backport, or the respective base version, if available.
9Package developers can make use of new functions or arguments by selectively importing specific backports to support older installations.
10
11## Usage
12
13### Interactively
14
15Attach the namespace via `library(backports)`.
16
17Note that it is crucial that `backports` is build against the currently running R version.
18Do not ignore these kind of warnings for this package.
19
20### In packages
211. Add backports to your DESCRIPTION under `Imports`.
222. Add or modify the function `.onLoad()` (see [here](https://stat.ethz.ch/R-manual/R-devel/library/base/html/ns-hooks.html)) to call the `import()` function of backports:
23 ```r
24 .onLoad <- function(libname, pkgname) {
25 backports::import(pkgname)
26 }
27 ```
28 You can also selectively import functions:
29 ```r
30 .onLoad <- function(libname, pkgname) {
31 backports::import(pkgname, c("get0", "dir.exists"))
32 }
33 ```
34 If you set `force = TRUE`, the provided functions will get imported, regardless of the R version:
35 ```r
36 .onLoad <- function(libname, pkgname) {
37 backports::import(pkgname, "hasName", force = TRUE)
38 }
39 ```
403. [Optional] Set `Depends` in your DESCRIPTION to require `R (>= 3.0.0)`.
41
42### Importing backports from `utils` or `tools`
43
44Backports for functions which are not in the `base` require additional steps.
45Usually, you need to to import those functions in the package NAMESPACE.
46However, this is only possible if such a function really exists, and yields a warning during `R CMD check` for older versions.
47There are three possibilities to deal with this:
48
491. Completely import the namespaces instead of selectively importing them, e.g. use `import(utils)` instead of `importFrom(utils, hasName)` in your `NAMESPACE` file.
502. Force-import the function (see above) so that you always use the backport instead of the implementation shipped with R, even for the most recent version of R.
513. Use a conditional import in your `NAMESPACE` file, e.g.
52 ```
53 if (getRversion() >= "3.4.0") {
54 importFrom(utils, hasName)
55 } else {
56 importFrom(backports, hasName)
57 }
58 ```
59Note that the braces `{}` are necessary in the
60`NAMESPACE` file, even though they wouldn't be for regular R code, and that you might get a warning
61for including `backports` in the `Imports:` section of your `DESCRIPTION` file if you never end up using it.
62
63
64## Backports for R versions prior to 3.2.0
65
66* `base::anyNA()`
67* `base::dir.exists()`
68* `base::file.size()`, `base::file.mode()` and `base::file.mtime()`
69* `base::lengths()`
70* Argument `extra_cols` for `base::file.info()`
71* Argument `repeated` for `utils::URLencode`
72* `base::isNamespaceLoaded()`
73
74## Backports for R versions prior to 3.3.0
75
76* `base::startsWith()` and `base::endsWith()`
77* `base::strrep()`
78* `base::trimws()`
79* Argument `type` for `utils::capture.output()`
80
81## Backports for R versions prior to 3.4.0
82
83* `base::.valid.factor()`
84* `utils::hasName()`
85
86## Backports for R versions prior to 3.5.0
87
88* `base::...length()`
89* `base::...elt()`
90* `base::isFALSE()`
91
92## Backports for R versions prior to 3.6.0
93
94* `base::warningCondition()`
95* `base::errorCondition()`
96* Argument `q` for `base::dQuote()` and `base::sQuote()`
97* `tools::vignetteInfo()`
98* `base::str2lang()`
99* `base::str2expression()`
100* `base::asplit()`
101* `utils::removeSource()` with the capability to strip source from language objects.
102
103## Backports for R versions prior to 4.0.0
104
105* `base::deparse1()`
106* `base::list2DF()`
107* `tools::R_user_dir()`
108* Argument `classes` for `base::suppressWarnings()` and `base::suppressMessages()`
109
110## Backports for R versions prior to 4.0.1
111* Argument `recycle0` for `base::paste()`.
112* Argument `recycle0` for `base::paste0()`.
113
114## Backports for R versions prior to 4.1.0
115* `base::...names()`
116
){kind=link}