R's missing value.

missing_value() returns R's missing object; what R uses to represent a missing argument. It is distinct from either NULL or NA.

Usage

missing_value(n)

missing_(x, unwrap = TRUE)

# S3 method for default
missing_(x, unwrap = TRUE)

# S3 method for dots
missing_(x, unwrap = TRUE)

# S3 method for quotation
missing_(x, unwrap = TRUE)

list_missing(...)

Arguments

n

Optional; a number. If provided, will return a list of missing values with this many elements.

x

a value, dots, or list.

unwrap

Whether to descend recursively through unevaluated promises using unwrap(x, TRUE)

...

Arguments evaluated normally. except those which are missing.

Value

missing_value returns the symbol with empty name, or a list of such.

missing_ returns a logical vector.

list_missing returns a list.

Details

The missing value occurs naturally in a quoted R expression that has an empty argument:

  exp <- quote( x[1, ] )
  identical(exp[[4]], missing_value()) #TRUE
  is_missing(exp[[4]]) #also TRUE

So we can use missing_value() to help construct expressions:

  substitute(f[x, y], list(x = 1, y=missing_value()))

When such an expression is evaluated and starts a function call, the missing value winds up in the promise expression.

  f <- function(x) arg_expr(x)
  identical(f(), missing_value()) # TRUE

During "normal evaluation", finding a missing value in a variable raises an error.

  m <- missing_value()
  list(m) # raises error

This means that it's sometimes tricky to work with missings:

  exp <- quote( x[1, ] )
  cols <- x[[4]]
  x <- list(missing_value(), 2, 3)     # this is ok, but...
  a <- missing_value(); b <- 2; c <- 3 # this stores missing in "cols",
  x <- list(a, b, c)                   # throws an error: "a" missing

Generally, keep your missing values wrapped up in lists or quotations, instead of assigning them to variables directly.

See also

missing is_missing

missing is_missing

Examples

# These expressions are equivalent:
function(x, y=1) {x+y}
#> function(x, y=1) {x+y}
#> <environment: 0x5645f0fdefe0>
function_(list(x=missing_value, y=1),
          quote( {x+y} ))
#> function (x = function (n) 
#> {
#>     if (missing(n)) {
#>         quote(expr = )
#>     }
#>     else {
#>         rep(list(quote(expr = )), n)
#>     }
#> }, y = 1) 
#> {
#>     x + y
#> }
#> <environment: 0x5645f0fdefe0>

# These expressions are also equivalent:
quote(df[,1])
#> df[, 1]
substitute(df[row,col],
           list(row = missing_value(), col = 1))
#> df[, 1]
# How to do the trick of `[` where it can tell which arguments are
# missing:
`[.myclass` <- function(x, ...) {
   indices <- list_missing(...)
   kept.axes <- which(missing_(indices))
   cat(paste0("Keeping axes ", kept_axes, "\n"))
   #...
}
ar <- structure(array(1:24, c(2, 3, 4)))
ar[, 3, ]
#>      [,1] [,2] [,3] [,4]
#> [1,]    5   11   17   23
#> [2,]    6   12   18   24