// RLANG — PRIMITIVE REFERENCE

rlang v0.1.11 · 416 entries · 13 chapters · generated from rlang/docs.rs · MIT

Docs Report GitHub

>_PRIMITIVE REFERENCE

Every primitive and operator the current build implements, with its signature and what it does. Jump via the chapter index, or Ctrl+F for a name.

The 381 primitives and 35 operators below are generated from the same corpus the language server completes from, which is checked against the runtime's own tables: a function listed here exists in the build, and a function missing here raises could not find function rather than failing silently. Each signature names the arguments the implementation actually reads, in the order it reads them — where that differs from GNU R, or where the answer differs, the description says so.

Chapters

Construction and coercion

17 entries

# c

c(...)

Combine the arguments into one vector, promoting every element to the widest type present (logical, integer, double, character, list). NULL arguments are dropped and argument tags become names, so c(a = 1, b = 2) is a named vector.

# list

list(...)

Build a list holding the arguments unchanged. Tagged arguments name the elements.

# vector

vector(mode = "logical", length = 0)

A zero-filled vector of the named mode: "numeric" or "double" gives 0, "integer" gives 0L, "character" gives "", "list" gives NULLs, and any other mode gives FALSE.

# numeric

numeric(length = 0)

A double vector of `length` zeros — the usual way to preallocate a numeric result.

# integer

integer(length = 0)

An integer vector of `length` zeros, for preallocating an integer result.

# character

character(length = 0)

A character vector of `length` empty strings, for preallocating a character result.

# logical

logical(length = 0)

A logical vector of `length` FALSE values, for preallocating a logical result.

# as.numeric

as.numeric(x)

Coerce to double. Strings are parsed as numbers and become NA when they do not parse; TRUE and FALSE become 1 and 0; a list is flattened elementwise.

# as.double

as.double(x)

The same coercion as as.numeric — rlang has one double type, so the two names share an implementation.

# as.integer

as.integer(x)

Coerce to integer, truncating doubles toward zero. Non-finite values and unparseable strings become NA.

# as.character

as.character(x)

Coerce to character using R's own 7-significant-digit number formatting. A factor yields its level labels rather than its integer codes.

# as.logical

as.logical(x)

Coerce to logical: any nonzero number is TRUE, and only "TRUE", "true", "T", "FALSE", "false" and "F" convert from character — every other string is NA.

# as.vector

as.vector(x)

A copy of x with names, dim, dimnames, class and levels stripped, so a table collapses to its plain counts. R's `mode` argument is accepted and ignored: the result keeps x's own type.

# as.list

as.list(x)

A list of x's elements, keeping the names. An atomic vector becomes a list of length-1 vectors.

# call

call(name, ...)

The unevaluated call of the function named by the string `name` on the already-evaluated arguments: call("round", 10.5) is round(10.5). A call headed by an operator is that syntax, so call("+", 1, 2) prints as 1 + 2.

# as.call

as.call(x)

The call made of a list: its first element is the function and the rest, tagged by the list's names, are the arguments. A call is returned unchanged.

# unlist

unlist(x)

Flatten a list recursively into an atomic vector of the widest type, composing names the way R does: list(a = 1, b = list(2, 3)) unlists to names a, b1, b2.

Attributes and metadata

20 entries

# length

length(x)

The number of elements: 0 for NULL, the element count for a vector or list, and the number of bindings for an environment.

# lengths

lengths(x)

An integer vector of the length of each element of x, keeping x's names.

# names

names(x)

The `names` attribute, or NULL when x has none.

# setNames

setNames(object, nm)

A copy of `object` carrying `nm` as its names. Assigning all-NA names removes the attribute.

# attr

attr(x, which)

One attribute of x by name, or NULL when it is not set. Partial matching of `which` is not performed.

# attributes

attributes(x)

Every attribute of x as a named list, or NULL when x carries none.

# class

class(x)

The `class` attribute when set; otherwise the implicit class — c("matrix", "array") for a length-2 dim, else "numeric", "integer", "character", "logical", "list", "function", "environment" or "NULL".

# inherits

inherits(x, what, which = FALSE)

TRUE when any string in `what` appears in class(x). With which = TRUE, an integer vector giving each `what`'s position in class(x), 0 where it is absent.

# oldClass

oldClass(x)

The `class` attribute of x, or NULL when x has only an implicit class. oldClass(x) <- value sets it as is, a zero-length value removing it.

# unclass

unclass(x)

A copy of x with the `class` attribute removed; every other attribute survives.

# structure

structure(.Data, ...)

A copy of `.Data` with each tagged argument set as an attribute. The legacy spelling `.Names` is stored as `names`.

# typeof

typeof(x)

The internal type: "logical", "integer", "double", "character", "list", "closure", "builtin", "environment", "externalptr" for a foreign R object, or "NULL".

# mode

mode(x)

Like typeof with integer and double collapsed to "numeric" and closure and builtin collapsed to "function".

# storage.mode

storage.mode(x)

The same string typeof returns; rlang stores no distinct storage mode.

# dim

dim(x)

The `dim` attribute of a matrix or array, or NULL for a plain vector.

# nrow

nrow(x)

The first element of dim(x), or NULL when x has no dim.

# ncol

ncol(x)

The second element of dim(x), or NULL when x has no dim.

# rownames

rownames(x)

The first component of dimnames(x), or NULL when there are no row labels.

# colnames

colnames(x)

The second component of dimnames(x), or NULL when there are no column labels.

# dimnames

dimnames(x)

The `dimnames` attribute — a list of one label vector per dimension — or NULL. Assignable through dimnames(x) <- list(...), rownames(x) <- and colnames(x) <-, and also produced by matrix(dimnames = ) and the cbind/rbind seam labels.

Output and the inline-Rust FFI

25 entries

# writeLines

writeLines(text, con, sep = "\n")

Write each string of the character vector text followed by sep, returning NULL invisibly. A missing string is written as NA. A character con is a file path, truncated and written; without one the text goes to stdout. A non-character text is an error, as in R.

# .rust

.rust(code)

Compile a self-contained inline Rust block — its `pub extern "C"` exports — to a cached cdylib through fusevm's FFI bridge, and register the exports for .Call. Returns NULL invisibly; the compile happens once per distinct source hash.

# .Call

.Call(.NAME, ...)

Invoke a routine registered by .rust(). Arguments must be length-1 numeric, integer or character and are marshalled to f64, i64 and string; the returned scalar is marshalled back to a length-1 vector.

# print

print(x, digits, quote = TRUE)

Print x in R's default layout and return it invisibly. `digits` overrides the significant-digit setting for this one call, and `quote = FALSE` prints strings bare with a missing one as <NA>. A user-defined print.<class> method takes over first, for both print(x) and top-level autoprint. A closure prints its deparsed source; a class with no method is followed by its attr(,"class") block.

# cat

cat(..., sep = " ", file = "", append = FALSE)

Write every argument's elements with no quotes and no trailing newline, joined by `sep`. The separator sits between arguments as well as between elements, so a leading zero-length argument still earns its successor one: cat(NULL, "x") writes " x". A separator containing a newline also ends the output with one. With a non-empty file the text goes there instead of to stdout, truncating unless append is TRUE. A list or a function argument is an error, as in R.

# message

message(...)

Signal a `simpleMessage` condition and, if nothing catches or muffles it, write the concatenated arguments to stderr and return NULL invisibly.

# warning

warning(...)

Signal a `simpleWarning` condition and continue. Uncaught, it is queued under the default `options(warn = 0)` and the whole batch prints when the top-level statement finishes; `warn = 1` prints it at once, `warn = 2` or higher raises it as an error, `(converted from warning) msg`, carrying the warning's call, and a negative `warn` drops it.

# stop

stop(...)

Signal a `simpleError` condition with the concatenated arguments as its message. Uncaught by any `tryCatch`/`try`, it ends the script with `Rscript: <message>` on stderr and status 1.

# stopifnot

stopifnot(...)

Raise "not all arguments are TRUE" unless every argument is non-empty and all-TRUE. The message does not name the failing expression, because builtins receive values rather than expressions.

# invisible

invisible(x)

Return x with the top-level echo suppressed for this value.

# identity

identity(x)

Return the argument unchanged — useful as a default FUN in the apply family.

# force

force(x)

Return the argument, having evaluated it. Written for its effect inside a closure factory, where it forces a promise that would otherwise be evaluated after the loop variable had moved on. Like identity it passes the argument's visibility through, so force(invisible(1)) prints nothing.

# withVisible

withVisible(x)

Evaluate x and report whether its value would auto-print, as a list with elements `value` and `visible`. withVisible(invisible(1))$visible is FALSE; the list itself prints.

# paste

paste(..., sep = " ", collapse = NULL)

Join the arguments elementwise with recycling to the longest, separated by `sep`. Every argument contributes a field, so a zero-length one contributes an empty string and paste("a", NULL, "b") is "a b". A non-NULL `collapse` then joins the result into a single string, and collapsing nothing gives "". NA elements render as "NA".

# paste0

paste0(..., collapse = NULL)

paste with an empty separator: the arguments are joined elementwise with nothing between them.

# toString

toString(x)

A single string of x's elements joined by ", " — the inline form R uses when a vector has to fit in one line.

# deparse

deparse(expr, width.cutoff = 60L)

R source text for a value, one element per output line: a run of consecutive integers deparses as `a:b`, other integers carry the L suffix, strings are quoted and escaped, names are written inline (`c(a = 1)`, `list(x = "q")`) when they can be, an all-NA vector spells its type (`NA_integer_`), a list is `list(...)`, and any other attribute wraps the value in `structure(..., dim = c(2L, 2L))`. Lines wrap past `width.cutoff` (20 to 500) the way R's do: a vector's continuation is flush left, a list's is indented. A closure deparses to its source lines under R's own keep.source = FALSE layout rules.

# dput

dput(x)

Writes the deparse of `x` to stdout, one line per line, and returns `x` invisibly.

# noquote

noquote(obj)

Marks `obj` with the `noquote` class, so it prints as `print(x, quote = FALSE)` would: strings bare and a missing string as `<NA>`.

# format

format(x, trim = FALSE, nsmall = 0, digits, justify = "left", width = 0, scientific, big.mark = "")

Format to character. A numeric vector takes fixed notation when its width is no greater than the scientific width plus getOption("scipen") — the same rule print uses, so format(1e6) is "1e+06" at the default scipen of 0 — with a common decimal count, then pads to a common width: numbers right-justified, strings left. `digits` is the significant-digit count, defaulting to getOption("digits"); `nsmall` the minimum decimals (fixed notation only), `scientific` forces one notation. `trim = TRUE` drops the common width of a non-character vector; `justify` (left, right, centre, none) steers a character vector's padding. A list formats each element's unlist on its own (trim = TRUE by default) and joins its pieces with ", ". A function formats to its deparsed source lines.

# options

options(...)

Set, query or restore global options. A tagged argument sets one and the call returns the previous values as a named list, invisibly, so `old <- options(digits = 3)` then `options(old)` restores. An untagged string queries without setting and returns visibly; an untagged list restores every named element. `digits` (significant digits for printing, 1..22, default 7) and `scipen` (the penalty added to a scientific rendering's width before it is compared with the fixed one, so positive favours fixed; clamped below at -9, default 0) are the two the printing code reads, `OutDec` (a one-character string, default ".") is the decimal mark print, format and as.character write while deparse keeps the point, and `warn` decides what an uncaught warning does (see warning()); any other name is stored and read back but has no effect. A digits outside 1..22 is an error, as in R. Unlike R, options() with no arguments does not enumerate a full default set.

# getOption

getOption(x, default = NULL)

The value of option x, or default when it has never been set.

# formatC

formatC(x, width, digits, format, flag)

Build the equivalent printf spec and route it through sprintf, so sign, zero-padding and exponent rules are shared. `format` defaults to "d" for integer input and "g" for real.

# prettyNum

prettyNum(x, big.mark = "")

Insert `big.mark` between every third digit of the integer part of each formatted number, preserving sign and fraction.

# sprintf

sprintf(fmt, ...)

C-style formatting, vectorized over both the format and the arguments. Supports %d %i %s %f %e %E %g %G %a %A %x %X %o and %%, with the flags, field width and precision — including zero-padding after the sign, as C does. NA, NaN and Inf are printed through %s as R does, so the width and the - and 0 flags still apply to them. A `*` takes the width (or precision) from the preceding argument.

Sequences

13 entries

# seq_len

seq_len(n)

The integer vector running from 1 to n, empty when n is 0 or negative.

# seq_along

seq_along(along.with)

The integer vector running from 1 to the length of the argument, whatever its type.

# seq

seq(from, to, by, length.out, along.with)

Build a sequence. With one argument it is 1:from, which counts down when from < 1. The third positional argument is `by`, so seq(0, 1, 0.25) steps by a quarter; `length.out` fixes the term count instead, and `along.with` gives the indices of its argument. A `by` that cannot reach `to` is an error, as in R. The result stays integer when every element and the step are whole.

# seq.int

seq.int(from, to, by, length.out)

The same implementation as seq — rlang draws no distinction between the two.

# rep

rep(x, times = 1, each = 1)

Repeat x: each element `each` times, the whole sequence `times` times. A vector-valued `times` gives a per-element repeat count (after `each`), and `length.out` truncates or recycles the result.

# rep_len

rep_len(x, length.out)

Recycle x to exactly `length.out` elements, truncating or repeating as needed.

# rev

rev(x)

Reverse the elements, reversing the names with them.

# unname

unname(obj)

A copy of obj with the `names` attribute removed.

# all.equal

all.equal(target, current, tolerance = 1.5e-8, scale = NULL, countEQ = FALSE, check.attributes = TRUE)

TRUE, or the character vector of differences, following R's all.equal.numeric, .character, .raw, .list and .factor and attr.all.equal: names, other attributes, lengths, NA pattern, element mismatches, and the mean relative (or absolute, or scaled) difference. Only differing elements enter the scale unless countEQ = TRUE. Inside stopifnot(), a failure reads "a and b are not equal:" followed by the differences.

# head

head(x, n = 6)

The first n elements; a negative n drops the last |n| instead.

# tail

tail(x, n = 6)

The last n elements; a negative n drops the first |n| instead.

# append

append(x, values, after = length(x))

Splice values into x after position `after` (by default at the end), with c()'s type promotion; a named x keeps its labels on both sides of the splice.

# replace

replace(x, list, values)

A copy of x with the elements list selects (positions, names or a logical mask) set to values, recycled — R's x[list] <- values; x.

Ordering and sets

15 entries

# sort

sort(x, decreasing = FALSE, na.last = NA, index.return = FALSE)

The sorted values, names carried along. na.last places the missing values: NA (the default) drops them, TRUE puts them last, FALSE first. Ties keep their original order in both directions. With index.return = TRUE the result is a list of $x and the ordering $ix.

# order

order(..., decreasing = FALSE, na.last = TRUE)

The 1-based permutation that sorts the first key, later keys breaking its ties. A position missing in any key is placed by na.last: last by default, first for FALSE, dropped for NA. Ties keep their original ascending order even when decreasing.

# unique

unique(x, incomparables = FALSE, fromLast = FALSE)

The first occurrence of each distinct value (the last with fromLast), keeping the original order. Numbers compare by value, as R's hash tables do (0.1 + 0.2 and 0.3 are distinct), strings by text, list elements with identical; a matrix keeps its distinct rows.

# setdiff

setdiff(x, y)

The de-duplicated elements of x that do not occur in y, compared as match() compares them.

# union

union(x, y)

The de-duplicated elements of x followed by the elements of y not already present, compared as match() compares them.

# intersect

intersect(x, y)

The de-duplicated elements of x that also occur in y, compared as match() compares them.

# match

match(x, table, nomatch = NA_integer_, incomparables = NULL)

The first 1-based position of each element of x within `table`, nomatch where absent. Both sides are coerced to their common type first, as match5 does: character when either is text, a factor or a list, else numbers compared by value, with NA matching only NA and NaN only NaN.

# is.element

is.element(el, table)

TRUE for each element of `el` that occurs in `table` — match(el, table) reduced to a logical.

# duplicated

duplicated(x, incomparables = FALSE, fromLast = FALSE)

TRUE at each position whose value has already appeared earlier in x (later, with fromLast), under unique()'s equality; incomparables are never duplicates, and a matrix is compared by rows.

# rank

rank(x, na.last = TRUE, ties.method = "average")

Ranks with tied values sharing the average of the slots they occupy (R's default ties.method = "average", a double vector), or with ties.method = "first", "last", "min" or "max" an integer vector of the slots in appearance order, reversed, the smallest or the largest. Character input ranks in collation order. na.last places the missing values: the trailing ranks by default, the leading ones for FALSE (the rest shifted up), NA for "keep", dropped for NA. "random" is not supported.

# sort.list

sort.list(x, decreasing = FALSE, na.last = TRUE)

The 1-based permutation that sorts a single key — order() over one vector. na.last places the missing values: last by default, first for FALSE, dropped for NA, in which case the positions index the vector with the missing values already removed.

# xtfrm

xtfrm(x)

The numeric key that sorts x. A plain numeric vector is already that key and is returned unchanged, names and all; character, logical and factor input ranks in collation order with tied values sharing the lowest slot they occupy, and missing values staying NA.

# which

which(x)

The 1-based positions where x is TRUE, carrying the names of the selected elements. With `arr.ind = TRUE` an array answers one row of per-margin subscripts per hit.

# which.max

which.max(x)

The position of the first maximum, ignoring NA. An all-NA or empty vector yields an empty integer vector.

# which.min

which.min(x)

The position of the first minimum, ignoring NA.

Numeric summaries

19 entries

# weighted.mean

weighted.mean(x, w, na.rm = FALSE)

stats' default method: sum((x * w)[w != 0]) / sum(w), so a missing x under a zero weight drops out, and a missing weight makes the result NA. Without w every weight is 1. With na.rm the missing x and their weights are dropped first. x and w of different lengths is an error.

# sum

sum(..., na.rm = FALSE)

The total over every element of every argument. The result stays integer when all arguments are integer or logical, otherwise it is a double. A missing value propagates, NA outranking NaN. Integer overflow widens to a double instead of producing NA.

# prod

prod(..., na.rm = FALSE)

The product of every element of every argument, always a double.

# mean

mean(x, na.rm = FALSE)

The arithmetic mean of one vector. An empty vector gives NaN. Without na.rm a missing value propagates as the first one met, so mean(c(1, NA, NaN)) is NA and mean(c(1, NaN, NA)) is NaN, matching R's IEEE accumulation. R's `trim` argument is accepted and ignored.

# median

median(x, na.rm = FALSE)

The middle value of the sorted data, or the mean of the two middle values at even length.

# quantile

quantile(x, probs = seq(0, 1, 0.25), na.rm = FALSE, names = TRUE, type = 7, digits = 7, fuzz)

Sample quantiles, a port of R's quantile.default: all nine types (7, interpolating (1 - h) * x[lo] + h * x[hi], is the default), names from formatC(100 * probs, format = "fg", digits = digits) plus a percent sign, an empty name and a missing value for a missing prob. A missing value in x is an error unless na.rm = TRUE; an ordered factor takes type 1 or 3 and gives an ordered factor.

# summary

summary(object, maxsum, digits, quantile.type = 7)

R's summary.default: for a numeric vector the minimum, quartiles, mean and maximum (quantile type quantile.type, rounded to digits significant digits when given) and the count of NAs; for a logical one its mode and value counts; for a character one its length, distinct and blank counts and nchar range; for a factor each level's count, the least frequent pooled as (Other) past maxsum levels. All but the factor's print as a table, a numeric one to getOption("digits") - 3 significant digits. A matrix, list or data frame is summarised in the embedded R.

# cor

cor(x, y = NULL, use = "everything", method = "pearson")

The correlation of two equal-length numeric vectors, or of the column pairs of a matrix (labelled by column name), by method "pearson", "spearman" (Pearson on average ranks) or "kendall" (tau-b). `use` selects how missing values are handled: "everything", "all.obs", "complete.obs", "na.or.complete" or "pairwise.complete.obs". Zero variance in either vector, or fewer than two pairs, gives NA rather than NaN.

# cov

cov(x, y = NULL, use = "everything", method = "pearson")

The sample covariance of two equal-length numeric vectors or of the column pairs of a matrix (n-1 denominator; "kendall" is the unscaled sum of sign products), each mean refined by a correction pass as R's cov.c does. A missing value gives NA unless `use` drops it, as for cor.

# rle

rle(x)

Run-length encoding: a list of $lengths and $values for each run of equal consecutive elements, classed "rle" so it prints in R's layout.

# inverse.rle

inverse.rle(x)

Expand an rle list back into the original vector.

# var

var(x, y = NULL, na.rm = FALSE)

The sample variance with the n-1 denominator, computed in the same two-pass form as R's C code so the last printed digit agrees. With y, the covariance of two equal-length vectors, as cov(x, y). A matrix argument gives its covariance matrix.

# sd

sd(x, na.rm = FALSE)

The square root of var(x) — the sample standard deviation.

# min

min(..., na.rm = FALSE)

The smallest value across every argument. Character arguments compare lexically. With no values at all the answer is Inf, as in R, but the accompanying warning is not raised.

# max

max(..., na.rm = FALSE)

The largest value across every argument; -Inf when there are no values. NA dominates NaN, so max(c(1, NA, NaN)) is NA.

# range

range(..., na.rm = FALSE)

c(min, max) over every argument; c(Inf, -Inf) when there are no values.

# cumsum

cumsum(x)

The running total. Integer and logical input stays integer. An NA poisons every later element, since the accumulated value is no longer known.

# cumprod

cumprod(x)

The running product, always a double, with the same NA propagation as cumsum.

# diff

diff(x, lag = 1, differences = 1)

The lag-`lag` differences, applied `differences` times. Integer input stays integer; a vector shorter than the lag yields an empty result.

Elementwise math

58 entries

# abs

abs(x)

Absolute value, elementwise. An integer vector stays integer; names and dim are carried through.

# sqrt

sqrt(x)

Square root, elementwise. A negative argument gives NaN.

# exp

exp(x)

e raised to the power of each element, computed elementwise.

# log

log(x, base)

The natural logarithm, or the logarithm to `base` when a second argument is given.

# log2

log2(x)

The base-2 logarithm of each element; zero gives -Inf and a negative gives NaN.

# log10

log10(x)

The base-10 logarithm of each element; zero gives -Inf and a negative gives NaN.

# log1p

log1p(x)

log(1 + x) computed to full precision for small x.

# expm1

expm1(x)

exp(x) - 1 computed to full precision for small x.

# floor

floor(x)

The largest integer value not greater than each element.

# ceiling

ceiling(x)

The smallest integer value not less than each element.

# trunc

trunc(x)

Each element truncated toward zero, so trunc(-1.7) is -1 where floor gives -2.

# round

round(x, digits = 0)

R's fround: of x rounded down and up at `digits` decimals, the nearer in double arithmetic, and on a tie the one whose scaled value is even, so round(0.15, 1) is 0.1. A fractional `digits` rounds to the nearest whole count; negative digits round to tens, hundreds and so on. x and digits recycle against each other.

# signif

signif(x, digits = 6)

R's fprec: round to `digits` (at least 1) significant figures by scaling with an exact power of ten, nearbyint, and scaling back: signif(123.456, 2) is 120 and signif(0.0034219, 3) is 0.00342. x and digits recycle against each other.

# sign

sign(x)

-1, 0 or 1 according to the sign of each element.

# sin

sin(x)

The sine of each element, with the argument taken in radians.

# cos

cos(x)

The cosine of each element, with the argument taken in radians.

# tan

tan(x)

The tangent of each element, with the argument taken in radians.

# asin

asin(x)

The arc sine of each element, in radians; an argument outside [-1, 1] gives NaN.

# acos

acos(x)

The arc cosine of each element, in radians; an argument outside [-1, 1] gives NaN.

# atan

atan(x)

The arc tangent of each element, in radians; use atan2 when the quadrant matters.

# atan2

atan2(y, x)

The angle in radians from the positive x-axis to the point (x, y), with the arguments recycled to the longer length.

# sinh

sinh(x)

The hyperbolic sine of each element.

# cosh

cosh(x)

The hyperbolic cosine of each element.

# tanh

tanh(x)

The hyperbolic tangent of each element.

# gamma

gamma(x)

The gamma function, computed through the same system libm that R links, so the printed result matches digit for digit.

# lgamma

lgamma(x)

The natural logarithm of the absolute value of the gamma function.

# factorial

factorial(x)

gamma(x + 1), so non-integer arguments are defined too.

# lfactorial

lfactorial(x)

lgamma(x + 1) — the log factorial, finite far past the point where factorial overflows.

# choose

choose(n, k)

The binomial coefficient, computed through lgamma and recycled over both arguments. A negative k gives 0.

# beta

beta(a, b)

The beta function gamma(a)gamma(b)/gamma(a+b), computed through lgamma so intermediate values stay finite. Arguments recycle.

# lbeta

lbeta(a, b)

The natural logarithm of beta(a, b), which stays finite for large arguments.

# cummax

cummax(x)

The running maximum; an NA makes every later element NA.

# cummin

cummin(x)

The running minimum, with the same NA propagation.

# pmax

pmax(..., na.rm = FALSE)

The elementwise maximum across the arguments, recycled to the longest. The result is always a double.

# pmin

pmin(..., na.rm = FALSE)

The elementwise minimum across the arguments, recycled to the longest.

# sweep

sweep(x, MARGIN, STATS, FUN = "-", check.margin = TRUE, ...)

Apply FUN to x and STATS laid out along the MARGIN dimensions (aperm(array(STATS, dim(x)[perm]), order(perm)), margins first). check.margin warns when STATS cannot line up with those margins; MARGIN may name dimensions.

# scale

scale(x, center = TRUE, scale = TRUE)

Center the columns of as.matrix(x) on their means (or the given values) and divide them by their root-mean-square (or the given values), recording both as the scaled:center and scaled:scale attributes.

# as.matrix

as.matrix(x)

A matrix is returned as is; any other vector becomes a single column whose row names are its names.

# row

row(x)

The integer matrix of each cell's row index, for a matrix-like x.

# col

col(x)

The integer matrix of each cell's column index, for a matrix-like x.

# is.unsorted

is.unsorted(x, na.rm = FALSE, strictly = FALSE)

Whether some element sorts after the next (with strictly, not before it), in sort's order; NA when x holds a missing value and na.rm is FALSE.

# anyDuplicated

anyDuplicated(x, incomparables = FALSE, fromLast = FALSE)

The index of the first element equal to an earlier one (scanning from the end with fromLast), or 0 when every element is unique.

# kronecker

kronecker(X, Y, FUN = "*", make.dimnames = FALSE, ...)

The Kronecker product: outer(X, Y, FUN) with its dimensions interleaved so each cell of X scales a block of Y, reshaped to dim(X) * dim(Y) after padding the shorter dim with ones. make.dimnames labels each margin with the x:y pairs of the dimnames.

# rowsum

rowsum(x, group, reorder = TRUE, na.rm = FALSE)

Column sums of the rows of x (a vector is one column) within each group: one row per distinct group, sorted with missing last unless reorder = FALSE, labelled with the group as text. Integer sums that overflow are NA.

# fivenum

fivenum(x, na.rm = TRUE)

Tukey's five-number summary (minimum, lower hinge, median, upper hinge, maximum), each the mean of the order statistics either side of its depth. A missing value without na.rm, or an empty x, gives five logical NAs.

# IQR

IQR(x, na.rm = FALSE, type = 7)

The interquartile range, diff(quantile(as.numeric(x), c(0.25, 0.75), na.rm =, names = FALSE, type =)).

# mad

mad(x, center = median(x), constant = 1.4826, na.rm = FALSE, low = FALSE, high = FALSE)

The scaled median absolute deviation, constant * median(abs(x - center)); low or high takes the lo- or hi-median of an even count.

# zapsmall

zapsmall(x, digits = getOption("digits"))

round(x, max(0, digits - log10(max(abs(x))))): entries negligible next to the largest become zero. All-missing x is returned unchanged.

# tabulate

tabulate(bin, nbins = max(1L, bin, na.rm = TRUE))

The count of each integer 1..nbins occurring in `bin`, as an integer vector of length nbins. Values outside the range and NAs are ignored.

# findInterval

findInterval(x, vec, rightmost.closed = FALSE, all.inside = FALSE, left.open = FALSE, checkSorted = TRUE)

For each x, the index i of the interval vec[i] <= x < vec[i+1] of the sorted breakpoints (vec[i] < x <= vec[i+1] with left.open): 0 below the first, length(vec) past the last. rightmost.closed folds a hit on the closing breakpoint into the last interval, all.inside folds both ends in. An unsorted vec is an error.

# set.seed

set.seed(seed, kind = NULL, normal.kind = NULL, sample.kind = NULL)

Seed R's default Mersenne-Twister stream exactly as R does, so every draw after it reproduces R's numbers. Only the default kinds are implemented: kind "Mersenne-Twister", normal.kind "Inversion", and sample.kind "Rejection" or "Rounding" (which warns, as in R). The state lives on the runtime, not in a .Random.seed variable.

# runif

runif(n, min = 0, max = 1)

n uniform draws on (min, max); min and max recycle. An invalid pair gives NaN with one "NAs produced" warning. A vector n asks for length(n) draws.

# rnorm

rnorm(n, mean = 0, sd = 1)

n normal draws by inversion (two uniforms through qnorm), R's default; mean and sd recycle, a negative sd gives NaN with "NAs produced".

# sample

sample(x, size, replace = FALSE, prob = NULL)

A random permutation or sample: a single number x >= 1 samples 1:x, anything else samples the elements of x through `[`, keeping names and factor levels. Draws with R's rejection sampler, or Walker's alias and R's inversion samplers under prob.

# sample.int

sample.int(n, size = n, replace = FALSE, prob = NULL)

size integers from 1..n, as .Internal(sample()); for n > 1e7 without replacement and size <= n/2 it takes R's hashed sampler (.Internal(sample2())) as R's useHash default does.

# dnorm

dnorm(x, mean = 0, sd = 1, log = FALSE)

The normal density, ported from nmath's dnorm4; arguments recycle to the longest, whose attributes the result keeps.

# pnorm

pnorm(q, mean = 0, sd = 1, lower.tail = TRUE, log.p = FALSE)

The normal distribution function by Cody's rational approximations (nmath's pnorm5), including the upper tail and the log scale.

# qnorm

qnorm(p, mean = 0, sd = 1, lower.tail = TRUE, log.p = FALSE)

The normal quantile by Wichura's AS 241 with R's asymptotic extreme-tail series; p outside [0, 1] is NaN with "NaNs produced".

Predicates

34 entries

# is.atomic

is.atomic(x)

TRUE for a logical, integer, double or character vector. NULL is not atomic, as in R 4.4 and later, and neither is a list.

# is.null

is.null(x)

TRUE when x is NULL. A zero-length vector is not NULL and answers FALSE.

# is.matrix

is.matrix(x)

TRUE when x has a dim attribute of length 2.

# is.array

is.array(x)

TRUE when x has a dim attribute, of any length (a matrix is an array).

# is.na

is.na(x)

TRUE at each missing element. NaN counts as missing in a double vector, and a list element counts when it is itself a length-1 NA.

# is.nan

is.nan(x)

TRUE at each NaN. Only doubles can carry NaN, so every other type answers all-FALSE.

# is.finite

is.finite(x)

TRUE where the element is a finite number — never for character or list input.

# is.infinite

is.infinite(x)

TRUE at each Inf or -Inf; FALSE everywhere else, including NA.

# anyNA

anyNA(x)

TRUE when any element is NA or NaN, checked without building the full is.na vector.

# complete.cases

complete.cases(x)

TRUE at each non-missing element. Over a plain vector this is the negation of is.na; data-frame input is not supported natively.

# na.omit

na.omit(object)

na.omit.default: drops the missing elements of an atomic vector (the rows holding one, for a matrix) and records their positions, named by the dropped labels, in an omit-classed na.action attribute. A list or a higher-rank array is returned unchanged.

# is.numeric

is.numeric(x)

TRUE for a double or integer vector, and FALSE for a factor — which R excludes explicitly even though a factor is stored as an integer vector.

# is.double

is.double(x)

TRUE only for a double vector: is.double(1L) is FALSE where is.numeric(1L) is TRUE.

# is.integer

is.integer(x)

TRUE only for an integer vector, and FALSE for a factor, matching R's own factor exclusion.

# is.character

is.character(x)

TRUE for a character vector, whatever attributes it carries.

# is.logical

is.logical(x)

TRUE for a logical vector, whatever attributes it carries.

# is.list

is.list(x)

TRUE for a list, including a list carrying a class attribute.

# is.primitive

is.primitive(x)

TRUE for a function R implements as a primitive (typeof builtin or special), FALSE for a closure.

# is.environment

is.environment(x)

TRUE for an environment, FALSE for anything else.

# is.function

is.function(x)

TRUE for a closure, a primitive used as a value, or a Negate/Vectorize combinator.

# is.vector

is.vector(x)

TRUE for an atomic vector or list carrying no attribute other than `names` — a matrix, a factor, or anything with a stray attr answers FALSE, as in R.

# any

any(..., na.rm = FALSE)

TRUE when any element of any argument is TRUE. Three-valued: an NA with no TRUE present gives NA unless na.rm is set.

# all

all(..., na.rm = FALSE)

TRUE when no element is FALSE. An NA with no FALSE present gives NA unless na.rm is set.

# isTRUE

isTRUE(x)

TRUE when x is a logical of length 1 that is TRUE (attributes such as names are allowed). Nothing is coerced, so isTRUE(1) and isTRUE("TRUE") are FALSE.

# isFALSE

isFALSE(x)

TRUE when x is a logical of length 1 that is FALSE; like isTRUE, nothing is coerced.

# xor

xor(x, y)

Elementwise exclusive or, recycled to the longer argument; NA on either side gives NA.

# bitwAnd

bitwAnd(a, b)

Bitwise AND, recycled. rlang computes on 64-bit integers, so values beyond R's 32-bit range keep their bits instead of becoming NA.

# bitwOr

bitwOr(a, b)

Bitwise OR of each pair, with the arguments recycled to the longer one.

# bitwXor

bitwXor(a, b)

Bitwise exclusive OR, recycled over both arguments.

# bitwNot

bitwNot(a)

The bitwise complement of each element, computed on 64-bit integers.

# bitwShiftL

bitwShiftL(a, b)

Shift each element left by b bits, on 64-bit integers rather than R 32-bit ones.

# bitwShiftR

bitwShiftR(a, b)

Shift each element right by b bits — an arithmetic shift, so the sign bit is preserved.

# identical

identical(x, y)

TRUE when both values have the same internal type, the same names and the same elements, comparing lists recursively. Environments are identical only to themselves; a primitive or a symbol to the one of the same name; calls part by part; closures by their formals, body and environment. Attributes other than names are not compared, so a classed value can be identical to a bare one.

# ifelse

ifelse(test, yes, no)

Elementwise selection: the matching element of `yes` where test is TRUE, of `no` where it is FALSE, and NA where test is NA. Both branches recycle.

Strings and regular expressions

39 entries

# file.path

file.path(..., fsep = "/")

Join the parts element-wise with fsep, recycling to the longest part. Any zero-length part, or no parts at all, gives character(0).

# basename

basename(path)

The part of each path after its last /, ignoring trailing separators: basename("/a/b/") is "b", and the root and the empty path give "".

# dirname

dirname(path)

Each path up to its last /, ignoring trailing separators and collapsing the run of separators before the last component. A path with no / is ".", the root stays "/", and the empty path stays "".

# sQuote

sQuote(x, q = TRUE)

Each string wrapped in single quotes. q = TRUE gives the typographic pair R uses in a UTF-8 locale; q = FALSE gives plain ASCII apostrophes. The result keeps x's names and shape.

# dQuote

dQuote(x, q = TRUE)

Each string wrapped in double quotes: the typographic pair by default, plain ASCII quotes with q = FALSE. The result keeps x's names and shape.

# shQuote

shQuote(string)

Quote each string for a POSIX shell (R's type = "sh"): single quotes, unless any element holds a single quote, in which case every element is double-quoted with ", $, ` and \ escaped. The type argument is not read.

# nchar

nchar(x, type = "chars")

The size of each string in the unit `type` names: "chars" (Unicode code points, the default), "bytes" (its UTF-8 length), or "width" (terminal columns, where a CJK character counts two and a combining mark none).

# strtrim

strtrim(x, width)

The longest prefix of each string that fits in `width` terminal columns, recycling `width`. A double-width character is dropped whole rather than split.

# utf8ToInt

utf8ToInt(x)

The Unicode code points of one string, as an integer vector. NA for anything that is not a string.

# intToUtf8

intToUtf8(x, multiple = FALSE)

The inverse of utf8ToInt: one string built from all the code points, or — with multiple = TRUE — one string per code point. A 0 is dropped.

# substr

substr(x, start, stop)

The characters of each element from `start` to `stop` inclusive, 1-based. start and stop are read as single numbers; use substring to vary them per element.

# substring

substring(text, first = 1, last = 1000000)

Like substr, but text, first and last all recycle to the longest, so substring("hello", 1:3) returns three pieces.

# toupper

toupper(x)

Each string converted to upper case, one character at a time — so the result has the same number of characters as the input and toupper("straße") is "STRAßE".

# tolower

tolower(x)

Each string converted to lower case, one character at a time, so the character count is preserved.

# casefold

casefold(x, upper = FALSE)

tolower by default, toupper when upper = TRUE — one function behind a flag.

# chartr

chartr(old, new, x)

Translate the characters of `old` to the matching characters of `new`, expanding a-c ranges in both. An `old` longer than `new` is an error; a character repeated in `old` takes its last mapping.

# strtoi

strtoi(x, base = 10)

Parse each string as an integer in the given base, accepting an optional 0x or 0X prefix at base 16. Unparseable strings become NA.

# as.hexmode

as.hexmode(x)

An integer vector classed hexmode: integers as they are, whole doubles through as.integer, strings read as base-16 digits; anything else is an error. It formats (format(x, width, upper.case)), prints and converts with as.character as hexadecimal digits, zero-padded to a common width, and keeps its class when subset with [.

# strrep

strrep(x, times)

Repeat each string `times` times, with both arguments recycled.

# encodeString

encodeString(x, width = 0, quote = "", na.encode = TRUE, justify = "left")

Each string with its control characters escaped, wrapped in `quote` (whose own character is then escaped), and padded to `width` columns — the widest element for width = NA — by `justify`. NA becomes "NA" quoted or "<NA>" unquoted, or stays NA with na.encode = FALSE.

# make.unique

make.unique(names, sep = ".")

names with every repeat of an earlier element suffixed by `sep` and the lowest count that names nothing else in the vector.

# make.names

make.names(names, unique = FALSE, allow_ = TRUE)

Syntactic names: an X prefixed where a name cannot start, every invalid character replaced by a dot, a dot appended to a reserved word; unique = TRUE then applies make.unique.

# strsplit

strsplit(x, split, fixed = FALSE)

Split each string by a regular expression, returning one character vector per element in a list. An empty pattern splits into single characters; fixed = TRUE splits on the literal text. split is recycled along x, an NA pattern leaves an element whole, and the list takes names(x).

# sub

sub(pattern, replacement, x, fixed = FALSE, ignore.case = FALSE)

Replace the first match of `pattern` in each element. Back-references are written R's way, as \1..\9.

# gsub

gsub(pattern, replacement, x, fixed = FALSE, ignore.case = FALSE)

Replace every match of `pattern` in each element, with the same back-reference and flag handling as sub.

# grepl

grepl(pattern, x, fixed = FALSE, ignore.case = FALSE)

TRUE at each element of x the pattern matches, and NA where the element is NA.

# grep

grep(pattern, x, value = FALSE, fixed = FALSE, ignore.case = FALSE)

The 1-based positions of the matching elements, or the matching strings themselves when value = TRUE.

# regexpr

regexpr(pattern, text, perl = FALSE)

The 1-based character position of the first match in each element, -1 for no match or NA for an NA element, carrying the width of each match on the `match.length` attribute; with perl = TRUE and capture groups, also `capture.start`, `capture.length` and `capture.names`.

# gregexpr

gregexpr(pattern, text, perl = FALSE)

A list with every match position for each element, each vector carrying its own `match.length` (and with perl = TRUE, one capture row per match).

# regexec

regexec(pattern, text, perl = FALSE)

A list whose element per text is the first match's position followed by each capture group's (0 for a group that did not take part), with the widths on `match.length`; perl = TRUE names the positions after named groups.

# regmatches

regmatches(x, m)

The matched substrings a regexpr or gregexpr result identifies — a character vector for the former, a list for the latter. `regmatches(x, m, invert) <- value` pastes replacements in place of the matches (or, with invert = TRUE, of the text around them).

# str

str(object)

A one-line-per-level sketch of a value: its type, dimensions, first few elements and attributes.

# tempfile

tempfile(pattern = "file", tmpdir = tempdir(), fileext = "")

A path under the temporary directory that no file occupies yet — naming one does not create it.

# readLines

readLines(con, n = -1L)

The first `n` lines (all when negative) of a file, or of stdin when `con` is "stdin", as a character vector without their newlines; a final line with no newline is still a line.

# file.exists

file.exists(...)

TRUE for each path that exists, vectorized over its argument.

# unlink

unlink(x, recursive = FALSE)

Remove the named files, answering 0 when there is nothing left to remove (a missing path included) and 1 on failure. Invisible.

# trimws

trimws(x, which = "both")

Strip whitespace from both ends, or only the left or right end.

# startsWith

startsWith(x, prefix)

TRUE where the element begins with the prefix; both arguments recycle.

# endsWith

endsWith(x, suffix)

TRUE where the element ends with the suffix; both arguments recycle.

The apply family

18 entries

# lapply

lapply(X, FUN, ...)

Apply FUN to each element of X and return a list carrying X's names. Extra arguments are passed on to FUN.

# sapply

sapply(X, FUN, ...)

lapply followed by simplification: results that are all length 1 collapse to a vector, results that are all length k become a k-by-n matrix, and ragged results stay a list. A character X supplies the names.

# vapply

vapply(X, FUN, FUN.VALUE)

Apply FUN to each element and simplify like sapply. FUN.VALUE is accepted but the result is not type-checked against it, and extra arguments are not forwarded to FUN.

# Map

Map(f, ...)

mapply(FUN = f, ..., SIMPLIFY = FALSE): apply f elementwise across several vectors or lists, recycled to the longest, and return the list of answers.

# mapply

mapply(FUN, ..., MoreArgs, SIMPLIFY = TRUE, USE.NAMES = TRUE)

Call FUN once per position across the vectors or lists in ..., recycled to the longest (an empty one makes the answer empty). A tag names that argument in each call, MoreArgs adds the same arguments to every call, the answer is labelled from the first argument, and with SIMPLIFY it collapses the way sapply does.

# Reduce

Reduce(f, x, init, right = FALSE, accumulate = FALSE)

Fold x with the binary function f, left to right by default. `init` seeds the accumulator, `right = TRUE` folds as f(element, acc), and `accumulate = TRUE` returns every intermediate value in original order.

# Filter

Filter(f, x)

The elements of x for which f returns TRUE, keeping the corresponding names.

# Find

Find(f, x)

The first element for which f returns TRUE, or NULL when none does.

# Position

Position(f, x)

The 1-based position of the first element for which f returns TRUE, or integer NA.

# split

split(x, f)

Split x into a list of groups, one per distinct value of f, named by the sorted levels.

# subset

subset(x, subset, select, drop = FALSE)

R's subset.default and subset.matrix. For a vector or list, x[subset & !is.na(subset)], where subset must be logical. For a matrix, the rows where subset is TRUE (all rows when it is omitted) and the columns select names, drop = FALSE keeping the matrix shape. select is evaluated unevaluated with each column name bound to its index, so select = c(a, c), select = a:b and select = -b pick columns by name. A subset.<class> method on an object with that class is dispatched to first. Data frames are not native here, so subset.data.frame is not available.

# unsplit

unsplit(value, f, drop = FALSE)

Reverse split(): a vector as long as f (as long as its first element when f is a list) of value[[1]]'s type, each group of value written back to the positions split(x, f) took it from, value recycled when it has fewer groups. A list of data frames is reassembled in the embedded R.

# tapply

tapply(X, INDEX, FUN, ...)

Apply FUN, with the extra arguments, to each cell of the cross-classification of X by INDEX (one grouping vector, or a list of them). The answer is an array over the level grid, labelled by the levels and by INDEX's names, NA for an empty cell; it is a list array when FUN's answers are not all single atomic values. Elements with a missing group are dropped.

# modifyList

modifyList(x, val)

Replace the elements of x whose names appear in `val` and append the names that do not.

# rapply

rapply(object, f)

Apply f to every leaf of a nested list and flatten the result. Only R's how = "unlist" behaviour is implemented.

# do.call

do.call(what, args)

Call a function — given as a value or as a name — with the elements of `args` as its arguments; the list's names become argument tags.

# Negate

Negate(f)

A new function returning the logical negation of f's result. It is a runtime combinator, not a closure, so it has no body to print.

# Vectorize

Vectorize(FUN)

A new function that applies FUN elementwise over its recycled arguments and simplifies the result.

Matrices and arrays

28 entries

# NROW

NROW(x)

The number of rows: dim(x)[1] for an array, else length(x), so a vector counts as one column.

# NCOL

NCOL(x)

The number of columns: dim(x)[2] for a matrix, 0 for NULL, and 1 for any other vector.

# prop.table

prop.table(x, margin = NULL)

x divided by its total, keeping names, dim and the other attributes. With margin = 1 each entry of a matrix is divided by its row total, with margin = 2 by its column total; margins of a higher-dimensional array are not supported.

# proportions

proportions(x, margin = NULL)

The same function as prop.table, under its newer name.

# matrix

matrix(data = NA, nrow, ncol, dimnames = NULL, byrow = FALSE)

Build a matrix, filling column-major and recycling `data` to nrow*ncol. Only one of nrow and ncol is needed. `byrow` must be passed by name — a fourth positional argument is not read as byrow.

# t

t(x)

Transpose a matrix. A dimensionless vector is treated as a one-row matrix, which means t() of a plain vector returns an n-by-1 column where GNU R returns a 1-by-n row.

# array

array(data = NA, dim = length(data))

Build an N-dimensional array, recycling `data` column-major to fill the shape. dimnames are not stored for rank 3 and above.

# aperm

aperm(a, perm)

Permute the dimensions of an array; the default reverses them, which transposes a matrix.

# apply

apply(X, MARGIN, FUN)

Apply FUN over the given margins of an array, walking the remaining dimensions for each slice. A character MARGIN is matched against names(dimnames(X)), raising R's error when a name does not resolve, and a numeric one must index dim(X). A slice keeps the labels of the dimensions it spans — its dim and dimnames at rank 2 or more, its names at rank 1 — so FUN sees a named row or a matrix. Several margins with scalar results reshape into an array, and the margins' labels land on the result.

# diag

diag(x)

Three behaviours, as in R: the main diagonal of a matrix, the n-by-n identity for a length-1 number, and the diagonal matrix built from a longer vector.

# lower.tri

lower.tri(x, diag = FALSE)

A logical matrix the shape of x (a vector counts as one column), TRUE strictly below the diagonal, and on it too with diag = TRUE.

# upper.tri

upper.tri(x, diag = FALSE)

A logical matrix the shape of x, TRUE strictly above the diagonal, and on it too with diag = TRUE.

# %*%

x %*% y

The matrix product, column-major, summed in the order the reference R's BLAS sums, so results agree with R to the last bit; NA propagates. A dimensionless vector is shaped by the other operand as R's do_matprod does (a row or a column, whichever conforms; two vectors make an inner product). The result keeps x's row names and y's column names. Non-conforming shapes are an error.

# crossprod

crossprod(x, y = x)

t(x) %*% y, with R's do_matprod shaping, conformability error and dimnames (x's column names, y's column names).

# tcrossprod

tcrossprod(x, y = x)

x %*% t(y), computed through the same matrix product; y defaults to x.

# solve

solve(a, b, tol = .Machine$double.eps)

Solve a %*% x = b by LU with partial pivoting — the inverse when b is missing — as solve.default reaches LAPACK's dgesv. An exactly zero pivot and a reciprocal condition number below tol raise R's own errors; rownames of the result are colnames(a).

# det

det(x)

The determinant of a square numeric matrix, as R's sign * exp(log-modulus) from the same LU factorisation.

# determinant

determinant(x, logarithm = TRUE)

The modulus (as its log by default, carrying a logarithm attribute) and sign of the determinant, returned as a list of class "det".

# arrayInd

arrayInd(ind, .dim, .dimnames = NULL, useNames = FALSE)

Linear indices as an integer matrix of per-dimension subscripts; useNames labels the rows from the first margin's names and the columns row/col or dim1, dim2, ….

# slice.index

slice.index(x, MARGIN)

An integer array shaped like x holding each cell's index along MARGIN (a combined index for several margins).

# outer

outer(X, Y, FUN = "*")

The outer product: X and Y are tiled to nx*ny and FUN is called once on the pair, so the result keeps FUN's own type — strings from paste0, logicals from ==. FUN may be a function or the name of an operator; the default "*" is the matrix product R computes, so it is always double.

# %o%

X %o% Y

The infix spelling of outer(X, Y), with the default multiplication.

# cbind

cbind(..., deparse.level = 1)

Bind the arguments as columns, recycling each to the tallest and promoting to the widest type present, as c() does. Column names come from an argument's tag, from a matrix argument's own dimnames, or from the deparsed argument expression — a bare symbol at deparse.level 1, any expression at 2, none at 0. NULL and zero-length arguments are dropped.

# rbind

rbind(..., deparse.level = 1)

Bind the arguments as rows, with the same recycling, promotion and naming rules as cbind — so rbind(x, x) carries the rownames "x", "x". The deparsed labels come from the call site, so they are unavailable when the arguments arrive through `...`.

# rowSums

rowSums(x)

Sum along every dimension but the first, keeping the first. A 1-D result takes that margin's dimnames as its names.

# colSums

colSums(x)

Sum along the first dimension, keeping the rest — a vector for a matrix, a matrix for a 3-D array.

# rowMeans

rowMeans(x)

The mean along every dimension but the first — one value per row of a matrix.

# colMeans

colMeans(x)

The mean along the first dimension — one value per column of a matrix.

Environments and dispatch

95 entries

# mget

mget(x, envir)

A list holding the value bound to each name in x, named by x, looked up in envir (with its enclosures) or the current environment chain. An unbound name is an error. R's mode, ifnotfound and inherits arguments are not read.

# Sys.getenv

Sys.getenv(x, unset = "", names = NA)

The value of each environment variable named in x, or unset for one that is not set. The result is named by x when x has more than one element or names = TRUE. Calling it with no x, which lists the whole environment in R, is an error here.

# getwd

getwd()

The absolute path of the working directory.

# Sys.setenv

Sys.setenv(...)

Set each named argument as an environment variable of the running process, its value converted to a string. Every argument must be named. Returns a logical vector of TRUE, one per variable, invisibly.

# exists

exists(x, where, envir, inherits = TRUE)

TRUE when the name is bound in the current environment chain or names a primitive or base constant. An environment given as envir, or positionally as where, is searched instead, together with its enclosures unless inherits = FALSE; every inheriting search ends in the base bindings, so exists("sum", envir = globalenv()) is TRUE.

# match.fun

match.fun(FUN)

FUN itself when it is a function; otherwise FUN must be a single string or a symbol, and the function of that name is looked up — skipping bindings that are not functions — from parent.frame(2), the caller of the function that called match.fun, as R does. A name with no function bound raises "object 'f' of mode 'function' was not found". R's descend argument is not read.

# getS3method

getS3method(f, class, optional = FALSE, envir = parent.frame())

The S3 method f.class as a function. f must name a generic: an internal generic rlang dispatches, or a function whose body calls UseMethod (directly, in its braces or in an if branch); the method is then looked up as a function from envir. Without a generic the error is "no function 'f' could be found", without a method "S3 method 'f.class' not found"; optional = TRUE returns NULL instead of either. R's registered-methods table does not exist here, so only bound methods are found.

# get

get(x, pos, envir, inherits = TRUE)

The value bound to the name, or the primitive of that name as a function value. An environment given as envir, or positionally as pos, is searched instead, together with its enclosures unless inherits = FALSE. An unbound name raises "object 'x' not found".

# assign

assign(x, value, pos, envir)

Bind `value` to the name in the current environment, or in the environment given as envir or positionally as pos, and return it invisibly.

# rm

rm(..., list = character(), envir)

Remove the bindings named by bare symbols or strings in ... and by list from the current environment, or from envir; enclosing environments are untouched. A name with no binding there warns "object 'x' not found". Returns NULL invisibly.

# remove

remove(..., list = character(), envir)

The same function as rm.

# environment

environment()

The current environment as a value. An argument is accepted and ignored — the environment of a given closure cannot be asked for.

# new.env

new.env(hash, parent)

A fresh environment enclosed by parent, by default the environment the call is made from. Read and write it with $ and [[.

# missing

missing(x)

TRUE when the caller supplied no argument for the formal. The argument is not evaluated, so missing(v) reads the name rather than its value and answers for an unsupplied parameter that has no binding at all. A formal with a default is bound before the body runs, and missing() still reports it as absent — the default is not something the caller supplied. A formal bound to a bare symbol the caller passed on (g <- function(y) f(y)) answers for that symbol in the caller: TRUE when it was itself an omitted formal without a default, followed through any number of such hand-offs. A forwarded formal that its own default filled in reads as supplied, as in R. R accepts the quoted spelling missing("v") as well, and so does this.

# nargs

nargs()

How many arguments the caller passed to the function this is called from, counting each element of ... separately and counting nothing for a formal left to its default. Zero at top level.

# ...length

...length()

The number of arguments in the calling function's ..., found from the calling frame outward; an error where there is no ... to look in.

# ...elt

...elt(n)

The n-th argument in ..., forced — the function form of ..1, ..2, …. A non-positive n or one past the end is an error.

# ...names

...names()

The tags of the arguments in ..., with "" for an untagged one, or NULL when none is tagged.

# return

return(value = NULL)

Signal a return from the enclosing closure with the given value.

# UseMethod

UseMethod(generic, object)

S3 dispatch: look for generic.class for each class of the object — the current call's first argument when none is given — then generic.default, and return what it returns.

# NextMethod

NextMethod()

Continue S3 dispatch from inside a method: run the method for the next class in the vector UseMethod was dispatching on, falling back to the primitive behind the generic when no further method is defined.

# tryCatch

tryCatch(expr, ..., finally)

Evaluate expr with handlers installed. Each named argument other than finally is a handler for the condition class of that name (error, warning, message, condition); if expr signals a matching condition, that handler is called with the condition object and its value becomes the result. finally is evaluated on the way out either way.

# withCallingHandlers

withCallingHandlers(expr, ...)

Evaluate expr with handlers installed, spelled as tryCatch is, but without unwinding: a matching handler runs at the point the condition was signalled, and when it returns the search continues outward and evaluation resumes there. A handler ends the search by transferring to a restart, which is what invokeRestart("muffleWarning") does.

# try

try(expr, silent = FALSE)

Evaluate expr, returning its value, or on error an invisible character string of class "try-error" carrying the message (also printed to stderr unless silent is TRUE) rather than aborting.

# on.exit

on.exit(expr, add = FALSE)

Register expr to be evaluated when the enclosing closure exits, whether it returns normally or unwinds with an error. Without add = TRUE a later on.exit replaces the registered expression instead of joining it.

# geterrmessage

geterrmessage()

The last error message: the text of an error raised from a message, as it was raised (even one a tryCatch handler then took), or the whole "Error in <call> : …" line try() made for its last error; "" before any. A condition object signalled with stop(cond) and caught leaves it unchanged.

# conditionMessage

conditionMessage(c)

The message string carried by a condition object.

# conditionCall

conditionCall(c)

The call a condition was signalled from. rlang records no call, so this is always NULL.

# simpleError

simpleError(message)

Build a condition object of class c("simpleError", "error", "condition").

# simpleWarning

simpleWarning(message)

Build a condition object of class c("simpleWarning", "warning", "condition").

# simpleMessage

simpleMessage(message)

Build a condition object of class c("simpleMessage", "message", "condition").

# simpleCondition

simpleCondition(message)

Build a condition object of class c("simpleCondition", "condition").

# errorCondition

errorCondition(message, ..., class = character(), call = NULL)

Build an error condition object: a list of message, call and any further named fields, of class c(class, "error", "condition"). stop() on it signals the object itself, so a handler sees every field.

# warningCondition

warningCondition(message, ..., class = character(), call = NULL)

Build a warning condition object: a list of message, call and any further named fields, of class c(class, "warning", "condition").

# signalCondition

signalCondition(cond)

Signal a condition object: every enclosing calling handler for one of its classes runs in place, an enclosing tryCatch for one of them unwinds, and with nothing in scope the call returns NULL and evaluation continues.

# withRestarts

withRestarts(expr, ...)

Evaluate expr with restarts established. Each named argument is a restart: a handler function, a list(handler =, description =), or a description string. If invokeRestart transfers to one, its handler's value becomes the value of this call.

# invokeRestart

invokeRestart(r, ...)

Transfer control to the restart named (or held) by r, passing the remaining arguments to its handler. Does not return: cleanups registered with on.exit and tryCatch's finally still run on the way out, but no handler catches the transfer.

# computeRestarts

computeRestarts(cond = NULL)

The restarts currently established, innermost first, ending with the abort restart the evaluator always provides. warning() establishes muffleWarning around itself and message() establishes muffleMessage.

# restartDescription

restartDescription(r)

The description string a restart was established with, or NULL when it carries none.

# isRestart

isRestart(x)

Whether x is a restart object, i.e. inherits from class "restart".

# Recall

Recall(...)

Re-invoke the closure currently executing, which lets an anonymous recursive function call itself.

# factor

factor(x, levels, ordered = FALSE)

Integer codes plus a `levels` attribute and class "factor" — c("ordered", "factor") when ordered. Levels default to the sorted distinct values; values outside `levels` become NA. R's `labels` argument is not accepted.

# levels

levels(x)

The `levels` attribute of a factor, or NULL for a value that carries none.

# nlevels

nlevels(x)

The number of levels a factor carries; 0 for a value with no levels attribute.

# droplevels

droplevels(x)

Drop the levels that no longer occur and renumber the codes to match.

# as.table

as.table(x)

x as a table: the table class on an array (a vector becomes one-dimensional, named by its names), with the letters A, B, ... labelling any margin that has no dimnames. A table is returned as it is.

# ordered

ordered(x, levels, labels)

factor(x, levels, labels, ordered = TRUE): an ordered factor whose levels carry a < order.

# as.ordered

as.ordered(x)

x if it is already an ordered factor, else x as an ordered factor over its own levels (or its sorted distinct values).

# is.ordered

is.ordered(x)

TRUE when x is an ordered factor.

# is.object

is.object(x)

TRUE when x carries a class attribute.

# is

is(object, class2)

Whether object is of class class2: its class vector, plus the basic relations R's S4 table records (an integer or double is a "numeric", a function is a "function"). With one argument, the class vector.

# relevel

relevel(x, ref)

An unordered factor with ref (a level name or position) moved to the front of its levels and the codes renumbered to match. Errors on a non-factor or an ordered factor, and on a ref that is not a level.

# interaction

interaction(..., sep = ".", drop = FALSE)

The factor crossing its arguments: one level per combination, the first factor varying fastest, labelled by joining the parts with sep. drop = TRUE removes the combinations that do not occur; an NA in any argument is NA.

# margin.table

margin.table(x, margin = NULL)

Sums of an array over every dimension not in margin, keeping the table class and the kept dimensions' dimnames (and their names). With no margin, the grand total.

# marginSums

marginSums(x, margin = NULL)

margin.table under its newer name.

# max.col

max.col(m, ties.method = "random")

The column holding each row's maximum, as an integer vector; NA for a row containing NA. ties.method "first" and "last" pick the leftmost or rightmost of equal maxima; "random" takes the first, which is R's answer whenever the maximum is unique.

# sort.int

sort.int(x, decreasing = FALSE, na.last = NA, index.return = FALSE)

sort for a vector, with index.return = TRUE answering list(x = sorted, ix = the permutation that sorted it).

# cut

cut(x, breaks, labels)

Bin numeric x into a factor of right-closed intervals (a, b]. A single-number `breaks` means that many equal-width bins over the range widened by a thousandth, exactly as R computes them; default labels use R's dig.lab = 3.

# table

table(x)

Counts of each level of a factor, or of each distinct value in sorted order, named and classed "table". Cross-tabulation of two or more arguments is not implemented — extra arguments are ignored.

# library

library(package)

Load a CRAN package inside the embedded GNU R and return NULL invisibly. Needs an R installation; the package's functions then reach rlang through the bridge.

# require

require(package)

Load a package like library, returning a logical rather than loading invisibly.

# requireNamespace

requireNamespace(package)

Load the package's namespace in the embedded R, returning a logical.

# loadNamespace

loadNamespace(package)

Load the package's namespace in the embedded R.

# suppressMessages

suppressMessages(expr)

Evaluate expr with every message discarded, and return its value. The message is muffled at the point it is signalled, so expr carries on from there.

# suppressWarnings

suppressWarnings(expr)

Evaluate expr with every warning discarded, and return its value. The warning is muffled at the point it is signalled, so expr carries on from there.

# suppressPackageStartupMessages

suppressPackageStartupMessages(expr)

Return expr; package startup output is suppressed by the bridge's own suppressMessages wrapper around the load.

# .rlang_formula

.rlang_formula(src)

Internal, not user surface: what the compiler emits for `lhs ~ rhs`. It takes the deparsed R source and builds a real formula object in the embedded R, so lm, glm and aggregate receive one intact.

# .rlang_quote

.rlang_quote(src, splice)

Internal, not user surface: what the compiler emits for quote(x) and bquote(x). The argument is never compiled; its deparse rides across as a string and this parses it back into the expression the caller wrote. splice = TRUE (bquote) replaces each `.(e)` with the value of e in the caller's frame.

# quote

quote(expr)

The expression itself, unevaluated. quote(1) is the number, quote(x) is a name, and a compound expression is a call — R's own three outcomes. The result prints as its source, deparses back to it, and takes apart with length and as.character.

# bquote

bquote(expr)

The expression, unevaluated like quote, except that each `.(e)` inside it is replaced by the value of e evaluated in the calling frame: y <- 5; bquote(a + .(y)) is a + 5. A spliced call keeps its own grouping, so splicing a + b into .(z) * 2 prints (a + b) * 2, as R's deparser does. The where and splice arguments are not read.

# as.name

as.name(x)

The name (symbol) whose text is x — R's as.symbol. as.name("foo") prints as foo and has class "name".

# as.symbol

as.symbol(x)

The name (symbol) whose text is x, identical to as.name.

# is.call

is.call(x)

Whether x is an unevaluated call — TRUE for quote(f(1)) and for quote(a + b), FALSE for a name or a constant.

# is.name

is.name(x)

Whether x is a name — TRUE for quote(x) and as.name("x"), FALSE for a call or a constant. R's is.symbol.

# is.symbol

is.symbol(x)

Whether x is a name, identical to is.name.

# sys.call

sys.call(which = 0)

The call that made the frame now running, as a language object. NULL at top level. which = n > 0 names frame n from the outermost, which = -n the frame n generations above this one; one that does not exist is the error "not that many frames on the stack". A sys.call() written as an argument reports the frame whose body wrote it, not the one it is being passed to, the way R's promise does.

# sys.calls

sys.calls()

The calls of every active function frame, outermost first, as a list of language objects; NULL at top level.

# match.call

match.call()

The current call with every argument that binds to a named formal carrying that formal's name, and the arguments in formal order. Arguments absorbed by ... keep their own tag and follow.

# match.arg

match.arg(arg, choices, several.ok = FALSE)

Match arg against choices: an exact match, else a unique prefix. Without choices they are the default of the formal arg names in the calling function, evaluated there, and an argument still equal to that whole default yields its first element. several.ok = TRUE accepts several arguments; no match raises 'arg' should be one of the choices.

# formals

formals(fun)

The formals of a closure as a named list: each default as the expression written, and the empty symbol for a formal without one. Without fun, the calling function's; a string names the function; a primitive has none (NULL).

# formalArgs

formalArgs(def)

The names of a closure's formals, ... included.

# args

args(name)

A function with the formals of name and a NULL body, enclosed by the global environment — what printing it shows is the argument list. For a primitive, the formals R keeps in its stand-in table (args(sum) is function (..., na.rm = FALSE) NULL); NULL for a primitive with none, such as if. A string names the function.

# body

body(fun)

The body of a closure as the language object written: a call, a symbol or a constant. Without fun, the calling function's; a string names the function; a primitive has none (NULL).

# sys.function

sys.function(which = 0)

The closure being executed — the function itself, not its call. which selects a frame as sys.call does.

# sys.nframe

sys.nframe()

The number of function frames up to and including the one sys.nframe() was written in: 0 at top level, 1 in a function called from there. A base function that is a closure in R counts as a frame (print(f()) runs f two deep), as R counts it.

# eval

eval(expr, envir)

Run an expression that was held rather than evaluated. With envir it runs in that environment, reading and binding there; without one it runs where the caller stands, so eval(quote(v + 1)) sees the caller's v and eval(quote(w <- 7)) binds there. A value that is not an expression is already evaluated and comes back unchanged. The result keeps the visibility the expression left it with.

# .rlang_substitute

.rlang_substitute(expr, env)

Internal, not user surface: what the compiler emits for substitute(x). The first argument is never compiled; its deparse rides across as a string and this parses it back before substituting.

# substitute

substitute(expr, env)

The expression with every symbol the current frame accounts for replaced by what it stands for: a formal the caller supplied stands for the expression they wrote, anything else bound in the frame stands for its value, and a symbol neither accounts for is left alone. `...` splices back into the arguments it stands for. At top level nothing is substituted, however much is bound. With env, that table is consulted instead of the frame.

# parent.frame

parent.frame(n = 1)

The environment of the frame that called this one, so a function can read or write the caller's variables. A builtin pushes no frame, so what this finds is the calling closure. Past the outermost frame it answers the global environment, as R does.

# ls

ls(envir, all.names = FALSE)

The names bound in an environment, sorted, defaulting to the current one. Names beginning with a dot are left out unless all.names is TRUE.

# objects

objects(envir, all.names = FALSE)

The names bound in an environment, identical to ls.

# globalenv

globalenv()

The global environment — where a top-level assignment binds.

# topenv

topenv(envir, matchThisEnv)

The first environment up envir's enclosure chain that is matchThisEnv or a top level. envir defaults to the calling environment; rlang's one top level is the global environment.

# environmentName

environmentName(env)

"R_GlobalEnv" for the global environment and the empty string for any other, which is what R answers for an anonymous frame.

# evalq

evalq(expr, envir)

Run an expression, identical to eval here: rlang's arguments are eager, so there is nothing left to quote against by the time either is called.

Operators

35 entries

# +

x + y
`+`(x, y)

Addition, recycled elementwise to the longer operand. Two integer or logical operands give an integer; names and dim are carried from the longer side. Unary + returns its argument unchanged.

# -

x - y
`-`(x, y)

Subtraction, with the same recycling and integer rule as +. Called with one argument it negates.

# *

x * y
`*`(x, y)

Multiplication, recycled elementwise; integer times integer stays integer.

# /

x / y
`/`(x, y)

Division, always producing a double. Division by zero yields Inf, -Inf or NaN rather than an error.

# ^

x ^ y
`^`(x, y)

Exponentiation, recycled elementwise and always producing a double.

# %%

x %% y
`%%`(x, y)

Remainder taking the sign of the divisor: -7 %% 3 is 2 and 7 %% -3 is -2. Computed as an exact fmod against the stored divisor, so 10 %% 0.04 is 0.04; a zero divisor gives NaN.

# %/%

x %/% y
`%/%`(x, y)

Integer division, kept consistent with %% as (x - x %% y) / y. A zero divisor or non-finite dividend gives x / y directly, so 49 %/% 0 is Inf.

# ==

x == y
`==`(x, y)

Elementwise equality, recycled. If either side is character both compare as strings. NA or NaN on either side gives NA.

# !=

x != y
`!=`(x, y)

Elementwise inequality, with the same recycling and NA rules as ==.

# <

x < y
`<`(x, y)

Elementwise less-than; character operands compare lexically.

# >

x > y
`>`(x, y)

Elementwise greater-than, with the same recycling and NA rules as the other comparisons.

# <=

x <= y
`<=`(x, y)

Elementwise less-than-or-equal, with the same recycling and NA rules as the other comparisons.

# >=

x >= y
`>=`(x, y)

Elementwise greater-than-or-equal, with the same recycling and NA rules as the other comparisons.

# &

x & y
`&`(x, y)

Elementwise logical AND with R's three-valued logic: NA & FALSE is FALSE, because the answer is decided regardless of the missing value.

# |

x | y
`|`(x, y)

Elementwise logical OR with three-valued logic: NA | TRUE is TRUE.

# !

!x
`!`(x)

Elementwise logical negation, coercing its argument first; NA stays NA.

# :

from:to
`:`(from, to)

The sequence from `from` to `to` stepping by one, descending when from is greater. The result is integer when both ends are whole numbers, otherwise a double.

# [

x[i]
x[i, j]
`[`(x, i)

Subsetting, which keeps the container type and the names. Positive positions select, negative positions drop, a logical mask recycles, and a character subscript matches names. Given as many subscripts as an array has dimensions it selects a slice and drops the length-1 dimensions; a character subscript against dimnames selects nothing, unlike R. On an object with a class, a `[.<class>` method is called instead.

# [[

x[[i]]
`[[`(x, i)

Extract exactly one element, by position or by name. A name that is not present yields NULL, an out-of-range position raises "subscript out of bounds", and on an environment it reads a binding. On an object with a class, a `[[.<class>` method is called instead.

# $

x$name
`$`(x, name)

The element of a named list bound to `name` (exact match), or NULL when there is none; on an environment it reads a binding, and an atomic vector raises "$ operator is invalid for atomic vectors". On an object with a class, a `$.<class>` method is called with the name as a string.

# [<-

x[i] <- value
`[<-`(x, i, value)

Subassignment: writes value into the selected positions, recycling it, growing x past its end and promoting its type to hold value. On an object with a class, a `[<-.<class>` method is called with value tagged `value`, and its result is assigned back.

# [[<-

x[[i]] <- value
`[[<-`(x, i, value)

Replace exactly one element; a NULL value removes a list element, and NULL becomes a list when written into. On an object with a class, a `[[<-.<class>` method is called with value tagged `value`.

# $<-

x$name <- value
`$<-`(x, name, value)

Replace or add the element bound to `name`; an environment gains the binding, and an atomic vector is coerced to a list with a warning. On an object with a class, a `$<-.<class>` method is called with the name as a string.

# %in%

x %in% table
`%in%`(x, table)

TRUE for each element of x that occurs in table — match(x, table, nomatch = 0) > 0. Factors match on their labels. As a function value it is callable like any other, as in Reduce(`%in%`, …).

# if

if (cond) yes else no
`if`(cond, yes, no)

Evaluate yes when cond is TRUE, else no (invisible NULL when there is no else). cond must be one non-NA logical or number: a longer one, NA, an empty one or a string with no logical reading is an error. As a function value only the chosen branch is evaluated.

# for

for (var in seq) body
`for`(var, seq, body)

Bind var to each element of seq in turn and evaluate body; the value is invisible NULL. Callable as a function value only when written as a call, since it takes the loop variable as a name.

# while

while (cond) body
`while`(cond, body)

Evaluate body while cond is TRUE; the value is invisible NULL. Callable as a function value only when written as a call.

# repeat

repeat body
`repeat`(body)

Evaluate body until a break; the value is invisible NULL. Callable as a function value only when written as a call.

# {

{ expr1; expr2; … }
`{`(expr1, expr2, …)

Evaluate each expression in turn; the value is the last one's (NULL for none).

# (

(expr)
`(`(expr)

The value of expr, made visible: (x <- 5) prints where x <- 5 does not.

# <-

name <- value
`<-`(name, value)

Bind value to name in the current environment (or replace part of an object through a replacement function, x[i] <- v); the value is value, invisibly. Callable as a function value only when written as a call, since it takes its target unevaluated.

# <<-

name <<- value
`<<-`(name, value)

Bind value to name in the nearest enclosing environment that has it, else the global one; invisible. Callable as a function value only when written as a call.

# =

name = value

Assignment, as <-, where it is not an argument tag. Callable as a function value only when written as a call.

# &&

x && y
`&&`(x, y)

Scalar AND: FALSE when x is FALSE without evaluating y, else y, with NA when x is NA unless y is FALSE. Each operand must be one logical or number; a longer one is an error.

# ||

x || y
`||`(x, y)

Scalar OR: TRUE when x is TRUE without evaluating y, else y, with NA when x is NA unless y is TRUE. Each operand must be one logical or number; a longer one is an error.