% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/when_supplied.R
\name{when_supplied}
\alias{when_supplied}
\alias{when_not_null}
\title{Check Arguments When Supplied}
\usage{
when_supplied(x, ..., .arg = rlang::caller_arg(x), .call)

when_not_null(x, ..., .arg = rlang::caller_arg(x), .call)
}
\arguments{
\item{x}{the argument to be checked}

\item{\dots}{\verb{arg_*()} functions or unevaluated function calls to be applied to \code{x}. See Examples.}

\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{.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{
These functions check arguments only when they are supplied (\code{when_supplied()}) or when not \code{NULL} (\code{when_not_null()}). Multiple checks can be applied in sequence. This allows arguments not to have to be supplied, but checks them only if they are.
}
\details{
An error will be thrown only if \code{x} is supplied and fails one of the supplied checks (\code{when_supplied()}) or is not \code{NULL} and fails one of the supplied checks (\code{when_not_null()}).

The \code{...} arguments can be passed either as functions, e.g.,

\if{html}{\out{<div class="sourceCode">}}\preformatted{when_supplied(x,
              arg_number,
              arg_gt)
}\if{html}{\out{</div>}}

or as unevaluated function calls with the \code{x} argument absent, e.g.,

\if{html}{\out{<div class="sourceCode">}}\preformatted{when_supplied(x,
              arg_number(),
              arg_gt(bound = 0))
}\if{html}{\out{</div>}}

or as a mixture of both.

\code{when_supplied()} only makes sense to use for an argument that has no default value but which can be omitted. \code{when_not_null()} makes sense to use for an argument with a default value of \code{NULL}.
}
\examples{
f <- function(z) {
  when_supplied(z,
                arg_number,
                arg_between(c(0, 1)))
}

try(f())    # No error: not supplied
try(f("a")) # Error: not a number
try(f(2))   # Error: not within 0-1 range
try(f(.7))  # No error: number within range

g <- function(z = NULL) {
  when_not_null(z,
                arg_number,
                arg_between(c(0, 1)))
}

try(g())     # No error: NULL okay
try(g(NULL)) # No error: NULL okay
try(g("a"))  # Error: not a number
try(g(2))    # Error: not within 0-1 range
try(g(.7))   # No error: number within range
}
\seealso{
\code{\link[=arg_or]{arg_or()}}, \code{\link[=arg_supplied]{arg_supplied()}}
}
