| % File src/library/base/man/stopifnot.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2020 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{stopifnot} |
| \title{Ensure the Truth of R Expressions} |
| \alias{stopifnot} |
| \concept{assertion} |
| \description{ |
| If any of the expressions (in \code{\dots} or \code{exprs}) are not |
| \code{\link{all}} \code{TRUE}, \code{\link{stop}} is called, producing |
| an error message indicating the \emph{first} expression which was not |
| (\code{\link{all}}) true. |
| } |
| \usage{ |
| stopifnot(\dots, exprs, local = TRUE) |
| } |
| \arguments{ |
| \item{\dots, exprs}{any number of (typically but not necessarily |
| \code{\link{logical}}) \R expressions, which should each evaluate to |
| (a logical vector of all) |
| \code{\link{TRUE}}. Use \emph{either} \code{\dots} \emph{or} |
| \code{exprs}, the latter typically an unevaluated expression of the |
| form \preformatted{\{ |
| expr1 |
| expr2 |
| .... |
| \}} |
| } |
| \item{local}{(only when \code{exprs} is used:) indicates the |
| \code{\link{environment}} in which the expressions should be |
| evaluated; by default the one where \code{stopifnot()} has been called from.} |
| } |
| \details{ |
| This function is intended for use in regression tests or also argument |
| checking of functions, in particular to make them easier to read. |
| |
| \code{stopifnot(A, B)} or equivalently \code{stopifnot(exprs= {A ; |
| B})} are conceptually equivalent to \preformatted{ \{ if(any(is.na(A)) || !all(A)) stop(...); |
| if(any(is.na(B)) || !all(B)) stop(...) \}} |
| |
| Since \R version 3.6.0, \code{stopifnot()} no longer handles potential |
| errors or warnings (by \code{\link{tryCatch}()} etc) for each single |
| expression |
| and may use \code{\link{sys.call}(<n>)} to get a meaningful and short |
| error message in case an expression did not evaluate to all TRUE. This |
| provides considerably less overhead. |
| |
| Since \R version 3.5.0, expressions \emph{are} evaluated sequentially, |
| and hence evaluation stops as soon as there is a \dQuote{non-TRUE}, as |
| indicated by the above conceptual equivalence statement. |
| %%__ Too expensive {tryCatch(), in R 3.5.x} : |
| %% Further, when such an expression signals an error or |
| %% \code{\link{warning}}, the message produced no longer |
| %% contains the full \code{stopifnot} call, but just the erroneous |
| %% expression. |
| |
| Also, since \R version 3.5.0, \code{stopifnot(exprs = { ... })} can be used |
| alternatively and may be preferable in the case of several |
| expressions, as they are more conveniently evaluated interactively |
| (\dQuote{no extraneous \code{,} }). |
| |
| Since \R version 3.4.0, when an expression (from \code{\dots}) is not |
| true \emph{and} is a call to \code{\link{all.equal}}, the error |
| message will report the (first part of the) differences reported by |
| \code{\link{all.equal}(*)}. |
| } |
| \note{ |
| Trying to use the \code{stopifnot(exprs = ..)} version via a shortcut, |
| say, \preformatted{ assertWRONG <- function(exprs) stopifnot(exprs = exprs) } |
| is delicate and the above is \emph{not a good idea}. Contrary to \code{stopifnot()} |
| which takes care to evaluate the parts of \code{exprs} one by one and |
| stop at the first non-TRUE, the above short cut would typically evaluate |
| all parts of \code{exprs} and pass the result, i.e., typically of the |
| \emph{last} entry of \code{exprs} to \code{stopifnot()}. |
| |
| However, a more careful version, \preformatted{ assert <- function(exprs) eval.parent(substitute(stopifnot(exprs = exprs))) } |
| may be a nice short cut for \code{stopifnot(exprs = *)} calls using the |
| more commonly known verb as function name. |
| } |
| \value{ |
| (\code{\link{NULL}} if all statements in \code{\dots} are \code{TRUE}.) |
| } |
| \seealso{\code{\link{stop}}, \code{\link{warning}}; |
| \code{\link{assertCondition}} in package \pkg{tools} complements |
| \code{stopifnot()} for testing warnings and errors. |
| } |
| \examples{ |
| stopifnot(1 == 1, all.equal(pi, 3.14159265), 1 < 2) # all TRUE |
| |
| m <- matrix(c(1,3,3,1), 2, 2) |
| stopifnot(m == t(m), diag(m) == rep(1, 2)) # all(.) |=> TRUE |
| |
| op <- options(error = expression(NULL)) |
| # "disabling stop(.)" << Use with CARE! >> |
| |
| stopifnot(all.equal(pi, 3.141593), 2 < 2, all(1:10 < 12), "a" < "b") |
| ## More convenient for interactive "line by line" evaluation: |
| stopifnot(exprs = { |
| all.equal(pi, 3.1415927) |
| 2 < 2 |
| all(1:10 < 12) |
| "a" < "b" |
| }) |
| |
| # long all.equal() error messages are abbreviated: |
| stopifnot(all.equal(rep(list(pi),4), list(3.1, 3.14, 3.141, 3.1415))) |
| |
| options(op) # revert to previous error handler |
| } |
| \keyword{environment} |
| \keyword{programming} |
| \keyword{error} |