| Title: | Functions and Utilities for Jordan |
|---|---|
| Description: | Provides core functions and utilities for packages and other code developed by Jordan Mark Barbone. |
| Authors: | Jordan Mark Barbone [aut, cph, cre] (ORCID: <https://orcid.org/0000-0001-9788-3628>) |
| Maintainer: | Jordan Mark Barbone <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.2.9011 |
| Built: | 2026-05-16 20:17:18 UTC |
| Source: | https://github.com/jmbarbone/fuj |
Arithmetic wrappers
See base::Arithmetic
add(7, 2) # + subtract(7, 2) # - multiply(7, 2) # * divide(7, 2) # / raise_power(7, 2) # ^ remainder(7, 2) # %% divide_int(7, 2) # %/%add(7, 2) # + subtract(7, 2) # - multiply(7, 2) # * divide(7, 2) # / raise_power(7, 2) # ^ remainder(7, 2) # %% divide_int(7, 2) # %/%
Extract and replace aliases
See base::Extract
df <- quick_df(list(a = 1:5, b = 6:10)) # alias of `[` subset1(df, 1) subset1(df, 1, ) subset1(df, , 1) subset1(df, , 1, drop = FALSE) # alias of `[[` subset2(df, 1) subset2(df, 1, 2) # alias of `$` subset3(df, a) subset3(df, "b") subset3(df, "foo") # alias of `[<-` subassign1(df, "a", , 2)df <- quick_df(list(a = 1:5, b = 6:10)) # alias of `[` subset1(df, 1) subset1(df, 1, ) subset1(df, , 1) subset1(df, , 1, drop = FALSE) # alias of `[[` subset2(df, 1) subset2(df, 1, 2) # alias of `$` subset3(df, a) subset3(df, "b") subset3(df, "foo") # alias of `[<-` subassign1(df, "a", , 2)
Simple wrapper for concatenating strings
collapse(..., sep = "")collapse(..., sep = "")
... |
one or more R objects, to be converted to character vectors. |
sep |
a character string to separate the terms. Not
|
A character vector of concatenated values. See base::paste for
more details.
collapse(1:10) collapse(list("a", b = 1:2)) collapse(quick_df(list(a = 1:3, b = 4:6)), sep = "-")collapse(1:10) collapse(list("a", b = 1:2)) collapse(quick_df(list(a = 1:3, b = 4:6)), sep = "-")
Get an object from a namespace
package %::% name package %:::% name package %colons% namepackage %::% name package %:::% name package %colons% name
package |
Name of the package |
name |
Name to retrieve |
The functions mimic the use of :: and ::: for extracting values
from namespaces. %colons% is an alias for %::%.
The variable name from package package
To reiterate from other documentation: it is not advised to
use ::: in your code as it will retrieve non-exported objects that may be
more likely to change in their functionality that exported objects.
help("::")
identical("base" %::% "mean", base::mean) "fuj" %:::% "colons_example" # unexported valueidentical("base" %::% "mean", base::mean) "fuj" %:::% "colons_example" # unexported value
Low-level encoding and factor building
encode(x, from, to, strict = FALSE, exclude = NULL) fact(x, levels = NULL, exclude = NULL)encode(x, from, to, strict = FALSE, exclude = NULL) fact(x, levels = NULL, exclude = NULL)
x |
A vector of values |
from, to
|
Vectors of the same length. Values in |
strict |
If |
exclude |
Values in |
levels |
A vector of unique values. If |
encode() A vector of the same length as x with values
replaced according to from and to.
fact() A factor vector with levels corresponding to the
unique values in x (or levels if provided).
fact(strsplit("factor function", "")[[1L]]) # encode() can be used to for the same utility as factor(x, levels, labels) en <- encode( strsplit("jordan", "")[[1L]], from = c("a", "o"), to = "*", ) en fact(en)fact(strsplit("factor function", "")[[1L]]) # encode() can be used to for the same utility as factor(x, levels, labels) en <- encode( strsplit("jordan", "")[[1L]], from = c("a", "o"), to = "*", ) en fact(en)
Get the exact attributes of an object
exattr(x, which) x %attr% whichexattr(x, which) x %attr% which
x |
an object whose attributes are to be accessed. |
which |
a non-empty character string specifying which attribute is to be accessed. |
See base::attr
foo <- struct(list(), "foo", aa = TRUE) attr(foo, "a") # TRUE : partial match successful exattr(foo, "a") # NULL : partial match failed exattr(foo, "aa") # TRUE : exact matchfoo <- struct(list(), "foo", aa = TRUE) attr(foo, "a") # TRUE : partial match successful exattr(foo, "a") # NULL : partial match failed exattr(foo, "aa") # TRUE : exact match
Flip an object.
flip(x, ...) ## Default S3 method: flip(x, ...) ## S3 method for class 'matrix' flip(x, by = c("rows", "columns"), keep_rownames = NULL, ...) ## S3 method for class 'data.frame' flip(x, by = c("rows", "columns"), keep_rownames = NULL, ...)flip(x, ...) ## Default S3 method: flip(x, ...) ## S3 method for class 'matrix' flip(x, by = c("rows", "columns"), keep_rownames = NULL, ...) ## S3 method for class 'data.frame' flip(x, by = c("rows", "columns"), keep_rownames = NULL, ...)
x |
An object |
... |
Additional arguments passed to methods |
by |
Flip by |
keep_rownames |
Logical, if |
A vector of values, equal length of x that is reversed or a
data frame with flipped rows/columns
flip(letters[1:3]) flip(seq.int(9, -9, by = -3)) flip(head(iris)) flip(head(iris), keep_rownames = TRUE) flip(head(iris), by = "col")flip(letters[1:3]) flip(seq.int(9, -9, by = -3)) flip(head(iris)) flip(head(iris), keep_rownames = TRUE) flip(head(iris), by = "col")
is_path() checks for either a file_path class or an
fs_path, the latter useful for the fs package.
file_path() is an alias for fp() and is_file_path() is
an alias for is_path().
set_file_ext() changes the file extension of a file path, removing
any existing extension first. file_ext<-() serves as an alias.
np() will normalize the file path, always
using "/" as the path separator, and without signaling errors or warnings
for non-existent paths.
Paths can be constructed with / and + methods:
fp("here") / "subdir" + "ext"
This will create a file path for here/subdir.ext, with the extension
added after. Note: fp() can be replaced with
np().
fp(...) np(...) file_path(...) norm_path(...) is_path(x) is_file_path(x) set_file_ext(x, value, compression = TRUE) file_ext(x, compression = TRUE) <- valuefp(...) np(...) file_path(...) norm_path(...) is_path(x) is_file_path(x) set_file_ext(x, value, compression = TRUE) file_ext(x, compression = TRUE) <- value
... |
Path components, passed to |
x |
An object to test |
value |
The new file extension. When |
compression |
If |
Lightweight file path functions
fp()/file_path(): A character vector with a "file_path"
class
np()/norm_path(): A character vector with a "file_path"
class, with normalized paths
is_path()/is_file_path(): A TRUE or FALSE value
set_file_ext()/file_ext<-(): The file path with the updated
extension
fp("here") fp("~/there") fp("back\\slash") fp("remove//extra\\\\slashes") fp("a", c("b", "c"), "d") # supports / and + (x <- fp("here") / "subdir" + "ext") # change file extension file_ext(x) <- "txt" x file_ext(x) <- ".txt.gz" x file_ext(x) <- NULL xfp("here") fp("~/there") fp("back\\slash") fp("remove//extra\\\\slashes") fp("a", c("b", "c"), "d") # supports / and + (x <- fp("here") / "subdir" + "ext") # change file extension file_ext(x) <- "txt" x file_ext(x) <- ".txt.gz" x file_ext(x) <- NULL x
Hold or Toss
hold(x, i, na = c("drop", "keep")) toss(x, i, na = c("keep", "drop"))hold(x, i, na = c("drop", "keep")) toss(x, i, na = c("keep", "drop"))
x |
A vector of values |
i |
An indication of which subset values to action. This can be a
logical vector, an integer vector, or a function that takes |
na |
How to handle |
x <- c(1, NA, 3, 4, Inf, 6) twos <- function(x) x %% 2 == 0 hold(x, twos) # 4, 6 toss(x, twos) # 1, 3, NA, Inf hold(x, twos, na = "keep") # NA, 4, Inf, 6 toss(x, twos, na = "drop") # 1, 3 i <- c(1:3, NA) x <- letters[1:5] hold(x, i) toss(x, i)x <- c(1, NA, 3, 4, Inf, 6) twos <- function(x) x %% 2 == 0 hold(x, twos) # 4, 6 toss(x, twos) # 1, 3, NA, Inf hold(x, twos, na = "keep") # NA, 4, Inf, 6 toss(x, twos, na = "drop") # 1, 3 i <- c(1:3, NA) x <- letters[1:5] hold(x, i) toss(x, i)
NULL or no lengthReplace if NULL or not length
x %||% y x %|||% y x %len% yx %||% y x %|||% y x %len% y
x, y
|
If |
A mostly copy of rlang's %||% except does not use rlang::is_null(),
which, currently, calls the same primitive base::is.null function.
Note: %||% is copied from {base} if available (R versions >= 4.4)
x if it is not NULL or has length, depending on check
# replace NULL (for R < 4.4) NULL %||% 1L 2L %||% 1L # replace empty "" %|||% 1L NA %|||% 1L double() %|||% 1L NULL %|||% 1L # replace no length logical() %len% TRUE FALSE %len% TRUE# replace NULL (for R < 4.4) NULL %||% 1L 2L %||% 1L # replace empty "" %|||% 1L NA %|||% 1L double() %|||% 1L NULL %|||% 1L # replace no length logical() %len% TRUE FALSE %len% TRUE
include() checks whether or not the namespace has been loaded
to the base::search() path. It uses the naming convention
include:{package} to denote the differences from loading via
base::library() or base::require(). When exports is NULL, the
environment is detached from the search path if found. When exports is
not NULL,
Note: This function has the specific purpose of affecting the search
path. Use options(fuj.verbose = TRUE) or options(verbose = TRUE) for
more information.
include(package, exports = NULL, lib = .libPaths(), pos = 2L, warn = NULL)include(package, exports = NULL, lib = .libPaths(), pos = 2L, warn = NULL)
package |
A package name. This can be given as a name or a character
string. See section |
exports |
A character vector of exports. When named, these exports will be aliases as such. |
lib |
See |
pos |
An integer specifying the position in the |
warn |
See |
Include (attach) a package and specific exports to Search Path
The attached environment, invisibly.
package class handlingWhen package is a name or AsIs,
assumed an installed package. When package is a file path (via
is_path()) then package is assumed a file path. When just a string, a
viable path is checked first; if it doesn't exist, then it is assumed a
package.
When the package is source()'d the name of the environment defaults to
the base name of x (file extension removed). However, if the object
.AttachName is found in the sourced file, then that is used as the
environment name for the search() path.
Note: include() won't try to attach an environment a second time,
however, when package is a path, it must be source()ed each time to
check for the .AttachName object. If there are any side effects, they
will be repeated each time include(path) is called.
# include(package) will ensure that the entire package is attached include(fuj) head(ls("include:fuj"), 20) detach("include:fuj", character.only = TRUE) # include a single export include(fuj, "collapse") # include multiple exports, and alias include(fuj, c( no_names = "remove_names", match_any = "any_match" )) # include an export where the alias has a warn conflict include(fuj, c(attr = "exattr")) # note that all 4 exports are included ls("include:fuj") # all exports are the same identical(collapse, fuj::collapse) identical(no_names, fuj::remove_names) identical(match_any, fuj::any_match) identical(attr, fuj::exattr)# include(package) will ensure that the entire package is attached include(fuj) head(ls("include:fuj"), 20) detach("include:fuj", character.only = TRUE) # include a single export include(fuj, "collapse") # include multiple exports, and alias include(fuj, c( no_names = "remove_names", match_any = "any_match" )) # include an export where the alias has a warn conflict include(fuj, c(attr = "exattr")) # note that all 4 exports are included ls("include:fuj") # all exports are the same identical(collapse, fuj::collapse) identical(no_names, fuj::remove_names) identical(match_any, fuj::any_match) identical(attr, fuj::exattr)
Tries to not complain about empty arguments
list0(...) lst(...)list0(...) lst(...)
... |
Arguments to collect in a list |
If options(fuj.list.active = FALSE) is set to prior to package loading,
this function becomes an alias for base::list(), disabling the special
behavior.
A list of ...
try(list(1, )) list0(1, ) try(list(a = 1, )) list0(a = 1, ) try(list(a = 1, , c = 3, )) list0(a = 1, , c = 3, )try(list(1, )) list0(1, ) try(list(a = 1, )) list0(a = 1, ) try(list(a = 1, , c = 3, )) list0(a = 1, , c = 3, )
Much like base::match.arg() with a few key differences:
Will not perform partial matching (by default)
Will not return error messages with curly quotations
Special handling for NULL values
Allows recoding of values via named lists or lists of formulas
match_arg( arg, choices, multiple = FALSE, partial = getOption("fuj.match_arg.partial", FALSE), null = c("error", "first", "all", "null") )match_arg( arg, choices, multiple = FALSE, partial = getOption("fuj.match_arg.partial", FALSE), null = c("error", "first", "all", "null") )
arg |
The argument |
choices |
The available choices; named lists will return the name (a character) for when matched to the value within the list element. A list of formula objects (preferred) retains the LHS of the formula as the return value when matched to the RHS of the formula. |
multiple |
If |
partial |
If |
null |
Controls how |
Argument matching for an argument
A single value from arg matched on choices
fruits <- function(x = c("apple", "banana", "orange")) { match_arg(x) } fruits() # apple try(fruits("b")) # must be exact fruits("banana") pfruits <- function(x = c("apple", "apricot", "banana")) { match_arg(x, partial = TRUE) } pfruits() # apple try(pfruits("ap")) # fuj:arg_match_error pfruits("app") # apple afruits <- function(x = c("apple", "banana", "orange")) { match_arg(x, multiple = TRUE) } afruits() # apple, banana, orange # can have multiple responses how_much <- function(x = list(too_few = 0:2, ok = 3:5, too_many = 6:10)) { match_arg(x) } how_much(1) how_much(3) how_much(9) # use a list of formulas instead ls <- list(1L ~ 0:1, 2L, 3L ~ 3:5) sapply(0:5, match_arg, choices = ls)fruits <- function(x = c("apple", "banana", "orange")) { match_arg(x) } fruits() # apple try(fruits("b")) # must be exact fruits("banana") pfruits <- function(x = c("apple", "apricot", "banana")) { match_arg(x, partial = TRUE) } pfruits() # apple try(pfruits("ap")) # fuj:arg_match_error pfruits("app") # apple afruits <- function(x = c("apple", "banana", "orange")) { match_arg(x, multiple = TRUE) } afruits() # apple, banana, orange # can have multiple responses how_much <- function(x = list(too_few = 0:2, ok = 3:5, too_many = 6:10)) { match_arg(x) } how_much(1) how_much(3) how_much(9) # use a list of formulas instead ls <- list(1L ~ 0:1, 2L, 3L ~ 3:5) sapply(0:5, match_arg, choices = ls)
Non matching alternatives and supplementary functions.
is_in(x, table) is_out(x, table) x %out% table is_within(x, table) x %wi% table is_without(x, table) x %wo% table no_match(x, table) any_match(x, table)is_in(x, table) is_out(x, table) x %out% table is_within(x, table) x %wi% table is_without(x, table) x %wo% table no_match(x, table) any_match(x, table)
x |
vector or |
table |
vector or |
Contrast with base::match(), base::intersect(), and
base::%in%() The functions of %wi% and %wo% can be used
in lieu of base::intersect() and base::setdiff(). The primary
difference is that the base functions return only unique values, which may
not be a desired behavior.
%out%: A logical vector of equal length of x, table
any_match(), no_match(): TRUE or FALSE
is_in(): see base::%in%()
1:10 %in% c(1, 3, 5, 9) 1:10 %out% c(1, 3, 5, 9) letters[1:5] %wo% letters[3:7] letters[1:5] %wi% letters[3:7] # base functions only return unique values c(1:6, 7:2) %wo% c(3, 7, 12) # -> keeps duplicates setdiff(c(1:6, 7:2), c(3, 7, 12)) # -> unique values c(1:6, 7:2) %wi% c(3, 7, 12) # -> keeps duplicates intersect(c(1:6, 7:2), c(3, 7, 12)) # -> unique values1:10 %in% c(1, 3, 5, 9) 1:10 %out% c(1, 3, 5, 9) letters[1:5] %wo% letters[3:7] letters[1:5] %wi% letters[3:7] # base functions only return unique values c(1:6, 7:2) %wo% c(3, 7, 12) # -> keeps duplicates setdiff(c(1:6, 7:2), c(3, 7, 12)) # -> unique values c(1:6, 7:2) %wi% c(3, 7, 12) # -> keeps duplicates intersect(c(1:6, 7:2), c(3, 7, 12)) # -> unique values
Aliases for base::suppressMessages() and base::suppressWarnings()
muffle(expr, fun, classes = "message") wuffle(expr, fun, classes = "warning")muffle(expr, fun, classes = "message") wuffle(expr, fun, classes = "warning")
expr |
An expression to evaluate |
fun |
A function to muffle (or wuffle) |
classes |
A character vector if classes to suppress |
The result of expr or a function wrapping fun
# load function foo <- function(...) { message("You entered :", paste0(...)) c(...) } # wrap around function or muffle the function ti's muffle(foo(1, 2)) muffle(fun = foo)(1, 2) sapply(1:3, muffle(fun = foo)) # silence warnings wuffle(as.integer("a")) sapply(list(1, "a", "0", ".2"), wuffle(fun = as.integer))# load function foo <- function(...) { message("You entered :", paste0(...)) c(...) } # wrap around function or muffle the function ti's muffle(foo(1, 2)) muffle(fun = foo)(1, 2) sapply(1:3, muffle(fun = foo)) # silence warnings wuffle(as.integer("a")) sapply(list(1, "a", "0", ".2"), wuffle(fun = as.integer))
Sets or removes names
set_names(x, nm = x) remove_names(x) x %names% nm is_named(x, zero_ok = TRUE)set_names(x, nm = x) remove_names(x) x %names% nm is_named(x, zero_ok = TRUE)
x |
A vector of values |
nm |
A vector of names |
zero_ok |
If |
x with nm values assigned to names (if x is NULL, NULL is
returned)
set_names(1:5) set_names(1:5, c("a", "b", "c", "d", "e")) x <- c(a = 1, b = 2) remove_names(x) x %names% c("c", "d") is_named(x)set_names(1:5) set_names(1:5, c("a", "b", "c", "d", "e")) x <- c(a = 1, b = 2) remove_names(x) x %names% c("c", "d") is_named(x)
not() is an alias for base::!. negate() is
a variation of base::Negate() with an extra steps to preserve the original
function and maintain the function formals.
not(x) negate(fun)not(x) negate(fun)
x |
An object |
fun |
A function |
Negate an outcome or function
negate() A function, which is the negation of fun
identical(not(TRUE), FALSE) different <- negate(identical) different(formals(identical), formals(identical))identical(not(TRUE), FALSE) different <- negate(identical) different(formals(identical), formals(identical))
Template for a new condition. See more at base::conditions
new_condition( message = "", class = "fuj_condition", type = c("condition", "error", "warning", "message"), ..., call = NULL, package = find_package(), msg, pkg )new_condition( message = "", class = "fuj_condition", type = c("condition", "error", "warning", "message"), ..., call = NULL, package = find_package(), msg, pkg )
message |
A message to print |
class |
Character string of a single condition class. If |
type |
The type (additional class) of condition: |
... |
Ignored |
call |
A call expression |
package |
Control or adding package name to condition. If |
msg |
Deprecated, see |
pkg |
Deprecated, see |
The use of .packageName when package = TRUE may not be valid
during active development. When the attempt to retrieve the .packageName
object is unsuccessful, the error is quietly ignored. However, this should
be successful once the package is build and functions can then utilize this
created object.
A condition with the classes specified from class and type
# empty condition x <- new_condition( "informative error message", class = "foo", type = "error" ) try(stop(x)) # with pkg x <- new_condition("msg", class = "foo", type = "error", package = "bar") # class contains multiple identifiers, including a "bar:fooError" class(x) # message contains package information at the end try(stop(x))# empty condition x <- new_condition( "informative error message", class = "foo", type = "error" ) try(stop(x)) # with pkg x <- new_condition("msg", class = "foo", type = "error", package = "bar") # class contains multiple identifiers, including a "bar:fooError" class(x) # message contains package information at the end try(stop(x))
Determine operating systems
is_windows() is_macos() is_linux()is_windows() is_macos() is_linux()
TRUE or FALSE
is_windows() is_macos() is_linux()is_windows() is_macos() is_linux()
This is a speedier implementation of base::as.data.frame() but does not
provide the same sort of checks. It should be used with caution.
quick_df(x = NULL) empty_df() quick_dfl(...)quick_df(x = NULL) empty_df() quick_dfl(...)
x |
A list or |
... |
Columns as |
A data.frame; if x is NULL a data.frame with 0 rows and 0
columns is returned (similar to calling base::data.frame() but faster).
empty_df() returns a data.frame with 0 rows and 0 columns.
# unnamed will use make.names() x <- list(1:10, letters[1:10]) quick_df(x) # named is preferred names(x) <- c("numbers", "letters") quick_df(x) # empty data.frame empty_df() # or quick_df(NULL)# unnamed will use make.names() x <- list(1:10, letters[1:10]) quick_df(x) # named is preferred names(x) <- c("numbers", "letters") quick_df(x) # empty data.frame empty_df() # or quick_df(NULL)
Require namespace
require_namespace(package, ...)require_namespace(package, ...)
package, ...
|
Package names |
TRUE (invisibly) if found; otherwise errors
isTRUE(require_namespace("base")) # returns invisibly try(require_namespace("1package")) # (using a purposefully bad name) require_namespace("base", "utils") try(require_namespace("base>=3.5", "utils>4.0", "fuj==10.0"))isTRUE(require_namespace("base")) # returns invisibly try(require_namespace("1package")) # (using a purposefully bad name) require_namespace("base", "utils") try(require_namespace("base>=3.5", "utils>4.0", "fuj==10.0"))
Create simple structures
struct(x, class, ..., .keep_attr = FALSE)struct(x, class, ..., .keep_attr = FALSE)
x |
An object; if |
class |
A vector of classes; can also be |
... |
Named attributes to set to |
.keep_attr |
Control for keeping attributes from |
Unlike base::structure() this does not provide additional checks
for special names, performs no base::storage.mode() conversions for
factors (x therefor has to be an integer), attributes from x are
not retained, and class is specified outside of other attributes and
assigned after base::attributes() is called.
Essentially, this is just a wrapper for calling base::attributes() then
base::class().
Note that base::structure() provides a warning when the first argument is
NULL. struct() does not. The coercion from NULL to list() is
done, and documented, in base::attributes().
An object with class defined as class and attributes ...
x <- list(a = 1, b = 2) # structure() retains the $names attribute of x but struct() does not structure(x, class = "data.frame", row.names = 1L) struct(x, "data.frame", row.names = 1L) struct(x, "data.frame", row.names = 1L, names = names(x)) # structure() corrects entries for "factor" class # but struct() demands the data to be an integer structure(1, class = "factor", levels = "a") try(struct(1, "factor", levels = "a")) struct(1L, "factor", levels = "a") # When first argument is NULL -- attributes() coerces try(structure(NULL)) # NULL, no call to attributes() struct(NULL, NULL) # list(), without warning x <- NULL attributes(x) <- NULL x # NULL attributes(x) <- list() # struct() always grabs ... into a list x # list() # Due to the use of class() to assign class, you may experience some # other differences between structure() and struct() x <- structure(1, class = "integer") y <- struct(1, "integer") str(x) str(y) all.equal(x, y) # Be careful about carrying over attributes x <- quick_df(list(a = 1:2, b = 3:4)) # returns empty data.frame struct(x, "data.frame", new = 1) # safely changing names without breaking rownames struct(x, "data.frame", names = c("c", "d")) # breaks struct(x, "data.frame", names = c("c", "d"), .keep_attr = TRUE) struct(x, "data.frame", names = c("c", "d"), .keep_attr = "row.names") # safely adds comments struct(x, "data.frame", comment = "hi", .keep_attr = TRUE) struct(x, "data.frame", comment = "hi", .keep_attr = c("names", "row.names")) # assignment in ... overwrites attributes struct(x, "data.frame", names = c("var1", "var2"), .keep_attr = TRUE)x <- list(a = 1, b = 2) # structure() retains the $names attribute of x but struct() does not structure(x, class = "data.frame", row.names = 1L) struct(x, "data.frame", row.names = 1L) struct(x, "data.frame", row.names = 1L, names = names(x)) # structure() corrects entries for "factor" class # but struct() demands the data to be an integer structure(1, class = "factor", levels = "a") try(struct(1, "factor", levels = "a")) struct(1L, "factor", levels = "a") # When first argument is NULL -- attributes() coerces try(structure(NULL)) # NULL, no call to attributes() struct(NULL, NULL) # list(), without warning x <- NULL attributes(x) <- NULL x # NULL attributes(x) <- list() # struct() always grabs ... into a list x # list() # Due to the use of class() to assign class, you may experience some # other differences between structure() and struct() x <- structure(1, class = "integer") y <- struct(1, "integer") str(x) str(y) all.equal(x, y) # Be careful about carrying over attributes x <- quick_df(list(a = 1:2, b = 3:4)) # returns empty data.frame struct(x, "data.frame", new = 1) # safely changing names without breaking rownames struct(x, "data.frame", names = c("c", "d")) # breaks struct(x, "data.frame", names = c("c", "d"), .keep_attr = TRUE) struct(x, "data.frame", names = c("c", "d"), .keep_attr = "row.names") # safely adds comments struct(x, "data.frame", comment = "hi", .keep_attr = TRUE) struct(x, "data.frame", comment = "hi", .keep_attr = c("names", "row.names")) # assignment in ... overwrites attributes struct(x, "data.frame", names = c("var1", "var2"), .keep_attr = TRUE)
Apply a function over elements of a vector.
vap(x, f, ...) vapi(x, f, ...) vap2(x, y, f, ...) vap3(x, y, z, f, ...) vapp(p, f, ...) vap_vec(x, f, ...) vap_lgl(x, f, ...) vap_int(x, f, ...) vap_dbl(x, f, ...) vap_chr(x, f, ...) vap_raw(x, f, ...) vap_cpl(x, f, ...) vap_date(x, f, ...) vap_dttm(x, f, ...) vapi_lgl(x, f, ...) vapi_int(x, f, ...) vapi_dbl(x, f, ...) vapi_chr(x, f, ...) vapi_raw(x, f, ...) vapi_cpl(x, f, ...) vapi_date(x, f, ...) vapi_dttm(x, f, ...) vap2_lgl(x, y, f, ...) vap2_int(x, y, f, ...) vap2_dbl(x, y, f, ...) vap2_chr(x, y, f, ...) vap2_raw(x, y, f, ...) vap2_cpl(x, y, f, ...) vap2_date(x, y, f, ...) vap2_dttm(x, y, f, ...) vap3_lgl(x, y, z, f, ...) vap3_int(x, y, z, f, ...) vap3_dbl(x, y, z, f, ...) vap3_chr(x, y, z, f, ...) vap3_raw(x, y, z, f, ...) vap3_cpl(x, y, z, f, ...) vap3_date(x, y, z, f, ...) vap3_dttm(x, y, z, f, ...) vapp_lgl(p, f, ...) vapp_int(p, f, ...) vapp_dbl(p, f, ...) vapp_chr(p, f, ...) vapp_raw(p, f, ...) vapp_cpl(p, f, ...) vapp_date(p, f, ...) vapp_dttm(p, f, ...) with_vap_progress(expr) with_vap_handlers(expr)vap(x, f, ...) vapi(x, f, ...) vap2(x, y, f, ...) vap3(x, y, z, f, ...) vapp(p, f, ...) vap_vec(x, f, ...) vap_lgl(x, f, ...) vap_int(x, f, ...) vap_dbl(x, f, ...) vap_chr(x, f, ...) vap_raw(x, f, ...) vap_cpl(x, f, ...) vap_date(x, f, ...) vap_dttm(x, f, ...) vapi_lgl(x, f, ...) vapi_int(x, f, ...) vapi_dbl(x, f, ...) vapi_chr(x, f, ...) vapi_raw(x, f, ...) vapi_cpl(x, f, ...) vapi_date(x, f, ...) vapi_dttm(x, f, ...) vap2_lgl(x, y, f, ...) vap2_int(x, y, f, ...) vap2_dbl(x, y, f, ...) vap2_chr(x, y, f, ...) vap2_raw(x, y, f, ...) vap2_cpl(x, y, f, ...) vap2_date(x, y, f, ...) vap2_dttm(x, y, f, ...) vap3_lgl(x, y, z, f, ...) vap3_int(x, y, z, f, ...) vap3_dbl(x, y, z, f, ...) vap3_chr(x, y, z, f, ...) vap3_raw(x, y, z, f, ...) vap3_cpl(x, y, z, f, ...) vap3_date(x, y, z, f, ...) vap3_dttm(x, y, z, f, ...) vapp_lgl(p, f, ...) vapp_int(p, f, ...) vapp_dbl(p, f, ...) vapp_chr(p, f, ...) vapp_raw(p, f, ...) vapp_cpl(p, f, ...) vapp_date(p, f, ...) vapp_dttm(p, f, ...) with_vap_progress(expr) with_vap_handlers(expr)
x, y, z
|
Values to map over |
f |
Function or specification of function to apply. |
... |
Additional arguments passed to |
p |
A list of values (i.e., parameters) to map over |
expr |
The expression to evaluate. |
Like lapply(), mapply(), and family, the vap functions provide
a means of applying a function to each element of a vector, and
controlling return types. The vap family provides extra tools and
controls, as well as date outputs (i.e., _date, _dttm variants that
work with Date and POSIXct types).
vap() uses a single x argument
vapi() uses a single x argument and passes the names (when available,
otherwise index) as the second argument
vap2(), vap3() use two and three arguments, respectively
vapp() uses a pairlist of arguments
For vap(), vapi(), returns a list with length of x. For
vap2(), vap3(), and vap(), return length is determined by how ...
is recycled inside mapply().
All have type variants (e.g., vap_chr(), vapi_int(), vap3_dbl())
which return a vector of the corresponding class, with the same length of
x, or following the same recycling rules as mapply() for multiple
inputs. These returns are coerced, rather than checked, and may result
in unexpected outputs. Likely, warnings or errors will be signaled
accordingly.
vap_vec() is a variant of vap() that returns a flattened vector. This
has similar behavior as base::sapply(), in that a list will be returned
if the base::unlist()'d output has multiple values in an element.
with_vap_progress() sets an option vap.progress to TRUE for the
duration of expr, which causes a progress bar to be displayed for any
vap* calls inside expr.
with_vap_handlers() sets an options(vap.indexed_errors = TRUE) for the
duration of expr, which causes errors inside vap calls to include the
index at which the error occurred.
Two helper functions are provided to set options for a
progress bars (options(fuj.vap.progress)) and reporting an index during
and error (options(fuj.vap.index_error)). Two wrapper functions are
provided: with_vap_progress() and with_vap_handlers(), respectively;
the latter may include other handlers in the future. These are not turned
on by default (or rather, the option settings are set to FALSE within
{fuj}) as they incur some additional overhead.
fruits <- c("apple", "banana", "pear") vap(fruits, toupper) vapi(fruits, function(x, i) paste0(i, ": ", toupper(x))) vap_int(set_names(month.name, month.abb), nchar) vap2_dbl(1:5, 6:10, `+`) vapp_int(list(x = 1:5, y = 6:10, z = 11:15), sum) # return type is coerced: vap_int(1:5, paste0, "9") # character -> integer vap_date(month.name, nchar) # integer -> Date # when f is a character or number, subsetting is performed x <- list(list(a = 1, b = 3), list(a = 2, b = 4)) vap_int(x, "a") vap_int(x, 2) # wrap in [with_vap_progress()] to show a progress bar invisible( with_vap_progress( vap(1:10 / 20, Sys.sleep) ) ) # wrap in [with_vap_handlers()] to report index on error try( with_vap_handlers( vap(10:1, function(x) if (x == 3) stop("bad")) ) )fruits <- c("apple", "banana", "pear") vap(fruits, toupper) vapi(fruits, function(x, i) paste0(i, ": ", toupper(x))) vap_int(set_names(month.name, month.abb), nchar) vap2_dbl(1:5, 6:10, `+`) vapp_int(list(x = 1:5, y = 6:10, z = 11:15), sum) # return type is coerced: vap_int(1:5, paste0, "9") # character -> integer vap_date(month.name, nchar) # integer -> Date # when f is a character or number, subsetting is performed x <- list(list(a = 1, b = 3), list(a = 2, b = 4)) vap_int(x, "a") vap_int(x, 2) # wrap in [with_vap_progress()] to show a progress bar invisible( with_vap_progress( vap(1:10 / 20, Sys.sleep) ) ) # wrap in [with_vap_handlers()] to report index on error try( with_vap_handlers( vap(10:1, function(x) if (x == 3) stop("bad")) ) )
Simple verbose condition handling
verbose( ..., .fill = getOption("fuj.verbose.fill"), .label = getOption("fuj.verbose.label"), .verbose = getOption("fuj.verbose", getOption("verbose")) ) make_verbose(opt)verbose( ..., .fill = getOption("fuj.verbose.fill"), .label = getOption("fuj.verbose.label"), .verbose = getOption("fuj.verbose", getOption("verbose")) ) make_verbose(opt)
... |
A message to display. When |
.fill |
When |
.label |
A label to prefix the message with (controlled through
|
.verbose |
When |
opt |
An option to use in lieu of |
verbose() can be safely placed in scripts to signal additional
message conditions. verbose() can be controlled with
options("verbose") (the default) and an override,
options("fuj.verbose"). The latter can be set to a function whose result
will be used for conditional evaluation.
make_verbose() allows for the creation of a custom verbose function.
None, called for its side-effects. When conditions are met, will
signal a verbose_message condition.
op <- options(verbose = FALSE) verbose("will not show") options(verbose = TRUE) verbose("message printed") verbose("multiple lines ", "will be ", "combined") options(op) op <- options(fuj.verbose = function() TRUE) verbose("function will evaluate") verbose(NULL) # nothing verbose(NULL, "something") verbose(if (FALSE) { "`if` returns `NULL` when not `TRUE`, which makes for additional control" }) options(op) # make your own verbose verb <- make_verbose("fuj.foo.bar") verb("will not show") options(fuj.foo.bar = TRUE) verb("will show")op <- options(verbose = FALSE) verbose("will not show") options(verbose = TRUE) verbose("message printed") verbose("multiple lines ", "will be ", "combined") options(op) op <- options(fuj.verbose = function() TRUE) verbose("function will evaluate") verbose(NULL) # nothing verbose(NULL, "something") verbose(if (FALSE) { "`if` returns `NULL` when not `TRUE`, which makes for additional control" }) options(op) # make your own verbose verb <- make_verbose("fuj.foo.bar") verb("will not show") options(fuj.foo.bar = TRUE) verb("will show")
Prompts the user to make a yes/no selection
yes_no(..., na = NULL, n_yes = 1, n_no = 2, noninteractive_error = TRUE)yes_no(..., na = NULL, n_yes = 1, n_no = 2, noninteractive_error = TRUE)
... |
text to display |
na |
Text for an NA response. When NULL, will not provide a possible NA response. When |
n_yes, n_no
|
The number of yes/no selections |
noninteractive_error |
While |