arg_non_null: Check NULL Argument
In arg: Clean and Simple Argument Checking

arg_non_null

R Documentation

Check NULL Argument

Description

Checks whether an argument is non-NULL (arg_non_null()) or is NULL (arg_null()). arg_non_null() throws an error when length(x) is 0. arg_null() throws an error when length(x) is not 0.

Usage

arg_non_null(x, .arg = rlang::caller_arg(x), .msg = NULL, .call)

arg_null(x, .arg = rlang::caller_arg(x), .msg = NULL, .call)

Arguments

`x`	the argument to be checked
`.arg`	the name of the argument supplied to `x` to appear in error messages. The default is to extract the argument's name using `rlang::caller_arg()`. Ignored if `.msg` is supplied.
`.msg`	an optional alternative message to display if an error is thrown instead of the default message.
`.call`	the execution environment of a currently running function, e.g. `.call = rlang::current_env()`. The corresponding function call is retrieved and mentioned in error messages as the source of the error. Passed to `err()`. Set to `NULL` to omit call information. The default is to search along the call stack for the first user-facing function in another package, if any.

Details

Here, NULL refers to any length-0 object, including NULL, logical(0L), list(), 3[FALSE], etc. arg_non_null() is useful for checking that a meaningful argument was supplied. arg_null() is primarily used for in arg_or() to denote that NULL is an allowed argument.

Value

Returns NULL invisibly if an error is not thrown.

Examples

f <- function(x = NULL, y = NULL) {
  arg_non_null(x) ## x must not be NULL
  arg_null(y)     ## y must be NULL
}

try(f(x = 1,    y = NULL)) ## No error
try(f(x = NULL, y = NULL)) ## Error: x is NULL
try(f(x = 1,    y = 1))    ## Error: y is non-NULL

# Any object of length 0 is considered NULL
try(f(x = numeric())) ## Error: x is NULL
try(f(x = list()))    ## Error: x is NULL

test <- c(1, 2)[c(FALSE, FALSE)]
try(f(x = test))      ## Error: x is NULL

# arg_null() is best used in and_or():
f2 <- function(z) {
  arg_or(z,
         arg_null(),
         arg_number())
}

try(f2(NULL)) ## No error; z can be NULL
try(f2(1))    ## No error; z can be a number
try(f2(TRUE)) ## Error: z must be NULL or a number

arg documentation built on April 9, 2026, 5:09 p.m.