EVOLUTION-MANAGER
Edit File: stopifnot.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Ensure the Truth of R Expressions</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for stopifnot {base}"><tr><td>stopifnot {base}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Ensure the Truth of R Expressions</h2> <h3>Description</h3> <p>If any of the expressions (in <code>...</code> or <code>exprs</code>) are not <code><a href="all.html">all</a></code> <code>TRUE</code>, <code><a href="stop.html">stop</a></code> is called, producing an error message indicating the <em>first</em> expression which was not (<code><a href="all.html">all</a></code>) true. </p> <h3>Usage</h3> <pre> stopifnot(..., exprs, local = TRUE) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>..., exprs</code></td> <td> <p>any number of (typically but not necessarily <code><a href="logical.html">logical</a></code>) <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> expressions, which should each evaluate to (a logical vector of all) <code><a href="logical.html">TRUE</a></code>. Use <em>either</em> <code>...</code> <em>or</em> <code>exprs</code>, the latter typically an unevaluated expression of the form </p> <pre>{ expr1 expr2 .... }</pre> </td></tr> <tr valign="top"><td><code>local</code></td> <td> <p>(only when <code>exprs</code> is used:) indicates the <code><a href="environment.html">environment</a></code> in which the expressions should be evaluated; by default the one where <code>stopifnot()</code> has been called from.</p> </td></tr> </table> <h3>Details</h3> <p>This function is intended for use in regression tests or also argument checking of functions, in particular to make them easier to read. </p> <p><code>stopifnot(A, B)</code> or equivalently <code>stopifnot(exprs= {A ; B})</code> are conceptually equivalent to </p> <pre> { if(any(is.na(A)) || !all(A)) stop(...); if(any(is.na(B)) || !all(B)) stop(...) }</pre> <p>Since <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> version 3.6.0, <code>stopifnot()</code> no longer handles potential errors or warnings (by <code><a href="conditions.html">tryCatch</a>()</code> etc) for each single expression and may use <code><a href="sys.parent.html">sys.call</a>(<n>)</code> to get a meaningful and short error message in case an expression did not evaluate to all TRUE. This provides considerably less overhead. </p> <p>Since <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> version 3.5.0, expressions <em>are</em> evaluated sequentially, and hence evaluation stops as soon as there is a “non-TRUE”, as indicated by the above conceptual equivalence statement. Further, when such an expression signals an error or <code><a href="warning.html">warning</a></code>, the message produced no longer contains the full <code>stopifnot</code> call, but just the erroneous expression. </p> <p>Also, since <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> version 3.5.0, <code>stopifnot(exprs = { ... })</code> can be used alternatively and may be preferable in the case of several expressions, as they are more conveniently evaluated interactively (“no extraneous <code>,</code> ”). </p> <p>Since <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> version 3.4.0, when an expression (from <code>...</code>) is not true <em>and</em> is a call to <code><a href="all.equal.html">all.equal</a></code>, the error message will report the (first part of the) differences reported by <code><a href="all.equal.html">all.equal</a>(*)</code>. </p> <h3>Value</h3> <p>(<code><a href="NULL.html">NULL</a></code> if all statements in <code>...</code> are <code>TRUE</code>.) </p> <h3>Note</h3> <p>Trying to use the <code>stopifnot(exprs = ..)</code> version via a shortcut, say, </p> <pre> assertWRONG <- function(exprs) stopifnot(exprs = exprs) </pre> <p>is delicate and the above is <em>not a good idea</em>. Contrary to <code>stopifnot()</code> which takes care to evaluate the parts of <code>exprs</code> one by one and stop at the first non-TRUE, the above short cut would typically evaluate all parts of <code>exprs</code> and pass the result, i.e., typically of the <em>last</em> entry of <code>exprs</code> to <code>stopifnot()</code>. </p> <p>However, a more careful version, </p> <pre> assert <- function(exprs) eval.parent(substitute(stopifnot(exprs = exprs))) </pre> <p>may be a nice short cut for <code>stopifnot(exprs = *)</code> calls using the more commonly known verb as function name. </p> <h3>See Also</h3> <p><code><a href="stop.html">stop</a></code>, <code><a href="warning.html">warning</a></code>; <code><a href="../../tools/html/assertCondition.html">assertCondition</a></code> in package <span class="pkg">tools</span> complements <code>stopifnot()</code> for testing warnings and errors. </p> <h3>Examples</h3> <pre> 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 </pre> <hr /><div style="text-align: center;">[Package <em>base</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>