Supplementary Idiomatic Utilities and Extensions

Miscellaneous supplementary functions designed to follow idiomatic 'R' conventions. Some functions are simple wrappers that reduce repetitive code, while others address common tasks or extend existing 'R' functions.

suppr

Supplementary utilities and extensions to R that are idiomatic in style.

Installation

Install the latest release of suppr from CRAN:

install.packages("suppr")

You can install the development version of suppr from GitHub:

# install.packages("pak")
pak::pak("LJ-Jenkins/suppr")

Reference

suppr provides miscellaneous supplementary functions for R: some are simple wrappers that save a few keystrokes, others address common tasks, and others provide new functionality through suppr versions of existing R functions. All are intended to be idiomatic R, as if they were part of the base R packages.

Much of suppr is directly amended from the R source code - all credit to the authors for their great work!

Infix Operators

• %''% or %""% - if the lhs is ““, return the rhs, else return the lhs.
• %!||% - if the lhs is NULL, return the lhs, else return the rhs.
• %0% - if the lhs is of length 0, return the rhs, else return the lhs.
• %allin%, %anyin%, %nonein%, %onein% and %notin% - base::%in% variants.

"" %''% "a"
#> [1] "a"
NULL %!||% "a"
#> NULL
c() %0% "a"
#> [1] "a"
c("a", "b") %allin% c("a", "b", "c")
#> [1] TRUE
c("a", "d") %anyin% c("a", "b", "c")
#> [1] TRUE
c("a", "d") %nonein% c("a", "b", "c")
#> [1] FALSE
c("a", "d") %onein% c("a", "b", "c")
#> [1] TRUE
c("a", "d") %notin% c("a", "b", "c")
#> [1] FALSE  TRUE

Character Operators

• bckQuote() - backquotes a string.
• collapse() and collapse0() - collapse a vector (or vectors) into a single string, optionally ‘recursively’ (in the sense of collapse each argument individually and then collapse the results).
• listing() - turns a character vector into a human-readable list (in the grammatical sense), optionally with quoting and/or a conjunction like “and” or “or”.
• cat0() - base::cat() with sep = "".
• grepf(), grepi(), greplf(), grepli(), grepvf(), grepvi(), subf(), subi(), gsubf() and gsubi() - strongly typed variants of base::grep(), base::grepl(), base::grepv(), base::sub() and base::gsub() for the common fixed = TRUE and ignore.case = TRUE cases.
• anyZchar() - returns the 1-based index of the first zero character element if any, otherwise 0.
• anyWS() - returns the 1-based index of the first all whitespace element if any, otherwise 0. Optionally, zero character elements can be treated as all whitespace.
• rm.prefix() and rm.suffix() - remove a specified prefix or suffix from each element of a character vector.

bckQuote(c("a", "b"))
#> [1] "`a`" "`b`"
collapse(c("a", "b", "c"))
#> [1] "abc"
listing(c("a", "b", "c"))
#> [1] "a, b and c."
cat0("a", "b", "c")
#> abc
greplf("foo", c("foo", "Foo", "bar"))
#> [1]  TRUE FALSE FALSE
grepli("foo", c("foo", "Foo", "bar"))
#> [1]  TRUE  TRUE FALSE
anyZchar(c("hi", "bye", " ", ""))
#> [1] 4
anyWS(c("hi", "bye", " ", ""))
#> [1] 3
rm.prefix(c("x_apple", "x_banana"), "x_")
#> [1] "apple"  "banana"
rm.suffix(c("apple_x", "banana_x"), "_x")
#> [1] "apple"  "banana"

Dots (...) Operators

• checkDots() - version of base::chkDots() that can error, not just warn.
• dotsNames() - returns the names of ... arguments, returning all "" if unnamed (like methods::allNames() but without evaluating ...).
• subDots() - substitutes ... arguments, returning a list of the substituted expressions.
• dp1Dots() - substitutes ... arguments, before applying base::deparse1() to each, returning a character vector of the dot arguments.

f <- function(fn, ...) fn(...)
f(checkDots, a = 1, b = 2)
#> Error:
#> ! In f(checkDots, a = 1, b = 2) :
#>  extra named arguments 'a', 'b' are not allowed.
f(dotsNames, 1, 2)
#> [1] "" ""
f(subDots, x = a + b, y = a * b)
#> $x
#> a + b
#> 
#> $y
#> a * b
f(dp1Dots, x = a + b, y = a * b)
#>       x       y 
#> "a + b" "a * b"

Warnings and Errors

• match.argv() - matches function argument input to a list of valid values, not just strings like base::match.arg().
• stop2(), warning2() and stopifnot2() - wrappers for base::stop(), base::warning() and base::stopifnot() that enable the inclusion of any call on the stack in the error message via a more flexible call. argument.
• warningifnot() - a wrapper for stopifnot2() that produces a warning instead of an error.
• stopifnot.with() - a wrapper for stopifnot2() that evaluates expressions in a specified environment/data object (like base::with()).

match.argv(1:3, list(c("a", "b"), list(1:3), 1:3))
#> [1] 1 2 3
f1 <- function(call.) stop2("error", call. = call.)
f2 <- function(call.) f1(call. = call.)
f2(call. = 2)
#> Error in `f2()`:
#> ! error
f1 <- function(call.) stopifnot2(all.equal(1, 2), call. = call.)
f2(call. = 1)
#> Error in `f1()`:
#> ! 1 and 2 are not equal:
#>   Mean relative difference: 1
warningifnot(1 == 2, 3 > 4, warn.all = TRUE, call. = FALSE)
#> Warning: 1 == 2 is not TRUE
#> Warning: 3 > 4 is not TRUE
stopifnot.with(data.frame(x = 1, y = 2), x == y)
#> Error:
#> ! with data.frame(x = 1, y = 2) : x == y is not TRUE

Classes

• addClass() - adds a class/classes to an object, either preserving existing classes (by prepending given classes), or overwriting existing classes, and returning the object.
• isVector() - wrapper for base::is.vector() that allows multiple classes to be specified.
• is.Date(), is.datetype(), is.POSIXt(), is.POSIXct() and is.POSIXlt() - date type predicates.
• is.boolean(), is.string() and nzstring() - predicates for common scalar values.

x <- structure(1:3, class = c("a", "b"))
class(addClass(x, "my_new_class"))
#> [1] "my_new_class" "a"            "b"
isVector(1:3, c("character", "list", "numeric"))
#> [1] TRUE
is.Date(Sys.Date())
#> [1] TRUE
is.datetype(Sys.Date())
#> [1] TRUE
is.POSIXt(Sys.time())
#> [1] TRUE
is.POSIXct(Sys.time())
#> [1] TRUE
is.POSIXlt(Sys.time())
#> [1] FALSE
is.boolean(TRUE)
#> [1] TRUE
is.string("")
#> [1] TRUE
nzstring("")
#> [1] FALSE

Data Wrangling

Even/odd

• is.even() and is.odd() - returns logical vector indicating if elements are even or odd, respectively.

is.even(c(-2:2, NA))
#> [1]  TRUE FALSE  TRUE FALSE  TRUE FALSE
is.odd(c(1, 2, NA, Inf), noparity.na = TRUE)
#> [1]  TRUE FALSE    NA    NA

Which min/max

• whichMin() and whichMax() - wrappers for base::which.min() and base::which.max() that offer a new loc argument to alternatively return the first, last, or all, minima/maxima.

x <- c(1, 2, 3, 1, 2, 3)
whichMin(x, loc = "first")
#> [1] 1
whichMin(x, loc = "last")
#> [1] 4
whichMin(x, loc = "all")
#> [1] 1 4

NA’s

• is.nonfinite() (and alias is.nf()) - returns a logical vector indicating which elements are non-finite (i.e., NA, NaN, Inf or -Inf).
• anyNF() - returns the 1-based index of the first non-finite value if any, otherwise 0.
• whichNA() - returns the indices of NA values.
• setNA() - sets given indices to NA.
• na.vector() - returns a vector of NA values of a given length and type.
• na.refill() - for an object that has had NA values removed by stats::na.omit(), refill the NA values at the original indices, returning an object of the same size as the original.

is.nonfinite(c(1, 2, NA, Inf))
#> [1] FALSE FALSE  TRUE  TRUE
anyNF(c(1, 2, NA, Inf))
#> [1] 3
whichNA(c(1, 2, NA, Inf))
#> [1] 3
x <- c(1, 2, 3, 4)
setNA(x, c(1, 3))
#> [1] NA  2 NA  4
na.vector(5, type = "character")
#> [1] NA NA NA NA NA
x <- stats::na.omit(c(1, 2, NA, 4))
x
#> [1] 1 2 4
#> attr(,"na.action")
#> [1] 3
#> attr(,"class")
#> [1] "omit"
na.refill(x)
#> [1]  1  2 NA  4
#> attr(,"na.action")
#> [1] 3
#> attr(,"class")
#> [1] "refilled"

Wholeness

• is.integerish() - returns TRUE if elements are all ‘integerish’ or FALSE if not.
• is.whole() and is.wholenumber() - returns a single TRUE/FALSE, or a logical vector, if elements are all whole numbers or not (according to an input tolerance), respectively.

is.integerish(c(1, 1.000000001))
#> [1] FALSE
is.whole(c(1, 1.000000001))
#> [1] TRUE
is.wholenumber(c(1, 2, 3.5, 4))
#> [1]  TRUE  TRUE FALSE  TRUE

Duplicates

• repeated() - returns a logical vector indicating which elements are repeated (analogous to duplicated(x, fromLast = FALSE) | duplicated(x, fromLast = TRUE)).
• whichRepeated() - returns the indices of repeated elements.
• repeats() (and alias non.unique()) - returns repeated elements.

x <- c(1, 2, 3, 1, 2, 3, 4, 5)
repeated(x)
#> [1]  TRUE  TRUE  TRUE  TRUE  TRUE  TRUE FALSE FALSE
whichRepeated(x)
#> [1] 1 2 3 4 5 6
repeats(x)
#> [1] 1 2 3 1 2 3

Remove elements

• rm.first() and rm.last() - removes the first or last ‘n’ elements of a vector, respectively.

x <- 1:10
rm.first(x, 3)
#> [1]  4  5  6  7  8  9 10
rm.last(x, 3)
#> [1] 1 2 3 4 5 6 7

Utilities

• predapply() - applies a predicate function to each element of a vector, returning a logical vector. Option to reduce the output to a single TRUE or FALSE value.
• empty.list() - wrapper for base::vector("list", length) that returns an empty list of a given length.
• path() - wrapper for base::file.path() and base::normalizePath(). Option to specify if the path is on a shared drive, prepending .Platform$file.sep if so.
• dims() - returns the dimensions of an object, or c(length(x), 0L) if it has no dim attribute.
• enumerate() - returns a list of lists - one for each element of a vector, with the corresponding positional list containing the vector element, index and name.
• libraries() and requires() - wrappers for base::library() and base::require() that can load multiple packages at once, either from names, strings, or character vectors.

predapply(1:10, is.even, reduce = "any")
#> [1] TRUE
empty.list(2)
#> [[1]]
#> NULL
#> 
#> [[2]]
#> NULL
path("mysd", "mydir", sharedDrive = TRUE, mustWork = FALSE)
#> [1] "\\\\mysd\\mydir"
dims(1:10)
#> [1] 10  0
enumerate(c("a", el = "b"))
#> [[1]]
#> [[1]]$idx
#> [1] 1
#> 
#> [[1]]$val
#> [1] "a"
#> 
#> [[1]]$name
#> [1] ""
#> 
#> 
#> [[2]]
#> [[2]]$idx
#> [1] 2
#> 
#> [[2]]$val
#> [1] "b"
#> 
#> [[2]]$name
#> [1] "el"
libraries(stats, "utils")
x <- c("stats", "utils")
requires(x, "methods", character.only = TRUE)

Getting help

If you encounter a clear bug, please file an issue with a minimal reproducible example on GitHub.

Code of Conduct

Please note that the suppr project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.