% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arg_non_null.R
\name{arg_non_null}
\alias{arg_non_null}
\alias{arg_null}
\title{Check NULL Argument}
\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{
\item{x}{the argument to be checked}

\item{.arg}{the name of the argument supplied to \code{x} to appear in error messages. The default is to extract the argument's name using \code{\link[rlang:caller_arg]{rlang::caller_arg()}}. Ignored if \code{.msg} is supplied.}

\item{.msg}{an optional alternative message to display if an error is thrown instead of the default message.}

\item{.call}{the execution environment of a currently running function, e.g. \code{.call = rlang::current_env()}. The corresponding function call is retrieved and mentioned in error messages as the source of the error. Passed to \code{\link[=err]{err()}}. Set to \code{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.}
}
\value{
Returns \code{NULL} invisibly if an error is not thrown.
}
\description{
Checks whether an argument is non-\code{NULL} (\code{arg_non_null()}) or is \code{NULL} (\code{arg_null()}). \code{arg_non_null()} throws an error when \code{length(x)} is \code{0}. \code{arg_null()} throws an error when \code{length(x)} is not \code{0}.
}
\details{
Here, \code{NULL} refers to any length-0 object, including \code{NULL}, \code{logical(0L)}, \code{list()}, \code{3[FALSE]}, etc. \code{arg_non_null()} is useful for checking that a meaningful argument was supplied. \code{arg_null()} is primarily used for in \code{\link[=arg_or]{arg_or()}} to denote that \code{NULL} is an allowed argument.
}
\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
}
\seealso{
\code{\link[=arg_length]{arg_length()}}, \code{\link[=arg_no_NA]{arg_no_NA()}}, \code{\link[=arg_supplied]{arg_supplied()}}
}
