missing_value: R's missing value.

View source: R/missing.R

missing_valueR Documentation

R's missing value.

Description

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)

## Default S3 method:
missing_(x, unwrap = TRUE)

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

## S3 method for class '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.

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.

Value

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

missing_ returns a logical vector.

list_missing returns a list.

See Also

missing is_missing

missing is_missing

Examples

# These expressions are equivalent:
function(x, y=1) {x+y}
function_(list(x=missing_value, y=1),
          quote( {x+y} ))

# These expressions are also equivalent:
quote(df[,1])
substitute(df[row,col],
           list(row = missing_value(), col = 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, ]

crowding/nse documentation built on Jan. 5, 2024, 12:14 a.m.