Generate or handle a missing argument
These functions help using the missing argument as a regular R object.
missing_arg() generates a missing argument.
is_missing() is like base::missing() but also supports
testing for missing arguments contained in other objects like
lists.
maybe_missing() is useful to pass down an input that might be
missing to another function, potentially substituting by a
default value. It avoids triggering an "argument is missing" error.
missing_arg() is_missing(x) maybe_missing(x, default = missing_arg())
x |
An object that might be the missing argument. |
default |
The object to return if the input is missing,
defaults to |
base::quote(expr = ) is the canonical way to create a missing
argument object.
expr() called without argument creates a missing argument.
quo() called without argument creates an empty quosure, i.e. a
quosure containing the missing argument object.
The missing argument is an object that triggers an error if and
only if it is the result of evaluating a symbol. No error is
produced when a function call evaluates to the missing argument
object. This means that expressions like x[[1]] <- missing_arg()
are perfectly safe. Likewise, x[[1]] is safe even if the result
is the missing object.
However, as soon as the missing argument is passed down between
functions through an argument, you're at risk of triggering a
missing error. This is because arguments are passed through
symbols. To work around this, is_missing() and maybe_missing(x)
use a bit of magic to determine if the input is the missing
argument without triggering a missing error.
maybe_missing() is particularly useful for prototyping
meta-programming algorithms in R. The missing argument is a likely
input when computing on the language because it is a standard
object in formals lists. While C functions are always allowed to
return the missing argument and pass it to other C functions, this
is not the case on the R side. If you're implementing your
meta-programming algorithm in R, use maybe_missing() when an
input might be the missing argument object.
missing_arg() and is_missing() are stable.
Like the rest of rlang, maybe_missing() is maturing.
# The missing argument usually arises inside a function when the # user omits an argument that does not have a default: fn <- function(x) is_missing(x) fn() # Creating a missing argument can also be useful to generate calls args <- list(1, missing_arg(), 3, missing_arg()) quo(fn(!!! args)) # Other ways to create that object include: quote(expr = ) expr() # It is perfectly valid to generate and assign the missing # argument in a list. x <- missing_arg() l <- list(missing_arg()) # Just don't evaluate a symbol that contains the empty argument. # Evaluating the object `x` that we created above would trigger an # error. # x # Not run # On the other hand accessing a missing argument contained in a # list does not trigger an error because subsetting is a function # call: l[[1]] is.null(l[[1]]) # In case you really need to access a symbol that might contain the # empty argument object, use maybe_missing(): maybe_missing(x) is.null(maybe_missing(x)) is_missing(maybe_missing(x)) # Note that base::missing() only works on symbols and does not # support complex expressions. For this reason the following lines # would throw an error: #> missing(missing_arg()) #> missing(l[[1]]) # while is_missing() will work as expected: is_missing(missing_arg()) is_missing(l[[1]])
Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.