% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arg_element.R
\name{arg_element}
\alias{arg_element}
\alias{arg_not_element}
\title{Check Element}
\usage{
arg_element(x, values, .arg = rlang::caller_arg(x), .msg = NULL, .call)

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

\item{values}{the values to check \code{x} against.}

\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 values in an argument are all elements of some set (\code{arg_element()}) or are not all elements of a set (\code{arg_not_element()}). \code{arg_element()} throws an error when \code{all(is.element(x, values))} is \code{FALSE}, and \code{arg_not_element()} throws an error when \code{any(is.element(x, values))} is \code{TRUE}.
}
\details{
\code{arg_element()} can be useful for checking whether an argument matches one or more allowed values. It's important that a check is done beforehand to ensure \code{x} is the correct type, e.g., using \code{\link[=arg_string]{arg_string()}} or \code{\link[=arg_character]{arg_character()}} if \code{values} is a character vector. No partial matching is used; the values must match exactly. Use \code{\link[=match_arg]{match_arg()}} to allow partial matching and return the full version of the supplied argument.

\code{arg_not_element()} can be useful for ensuring there is no duplication of values between an argument and some other set.
}
\examples{
f <- function(z) {
  arg_element(z, c("opt1", "opt2", "opt3"))
}

try(f("opt1"))            # No error
try(f(c("opt1", "opt2"))) # No error, all are elements
try(f(c("opt1", "opt1"))) # No error: repeats allowed
try(f("bad_arg"))         # Error: not an element of set
try(f("opt"))             # Error: partial matching not allowed
try(f(c("opt1", "bad_arg"))) # Error: one non-match

g <- function(z) {
  arg_not_element(z, c("bad1", "bad2", "bad3"))
}

try(g("bad1"))            # Error: z is an element
try(g(c("bad1", "opt2"))) # Error: at least one bad match
try(g("opt1"))            # No error: not an element
try(g(c("opt1", "opt2"))) # No error, none are elements
}
\seealso{
\code{\link[=is.element]{is.element()}}, \code{\link[=match_arg]{match_arg()}}
}
