\HeaderA{all.equal}{Test if Two Objects are (Nearly) Equal}{all.equal}
\methaliasA{all.equal.character}{all.equal}{all.equal.character}
\methaliasA{all.equal.default}{all.equal}{all.equal.default}
\methaliasA{all.equal.factor}{all.equal}{all.equal.factor}
\methaliasA{all.equal.formula}{all.equal}{all.equal.formula}
\methaliasA{all.equal.language}{all.equal}{all.equal.language}
\methaliasA{all.equal.list}{all.equal}{all.equal.list}
\methaliasA{all.equal.numeric}{all.equal}{all.equal.numeric}
\aliasA{attr.all.equal}{all.equal}{attr.all.equal}
\keyword{programming}{all.equal}
\keyword{utilities}{all.equal}
\keyword{logic}{all.equal}
\keyword{arith}{all.equal}
\begin{Description}\relax
\code{all.equal(x,y)} is a utility to compare \R{} objects \code{x}
and \code{y} testing \dQuote{near equality}.  If they are different,
comparison is still made to some extent, and a report of the
differences is returned.    Don't use \code{all.equal} directly in
\code{if} expressions---either use \code{isTRUE(all.equal(....))} or
\code{\LinkA{identical}{identical}} if appropriate.
\end{Description}
\begin{Usage}
\begin{verbatim}
all.equal(target, current, ...)

## S3 method for class 'numeric':
all.equal(target, current,
          tolerance = .Machine$double.eps ^ 0.5,
          scale = NULL, ...)

attr.all.equal(target, current, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{target}] \R{} object.
\item[\code{current}] other \R{} object, to be compared with \code{target}.
\item[\code{...}] Further arguments for different methods, notably the
following two, for numerical comparison:
\item[\code{tolerance}] numeric \eqn{\ge}{>=} 0.  Differences smaller than
\code{tolerance} are not considered.
\item[\code{scale}] numeric scalar > 0 (or \code{NULL}). See Details.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
There are several methods available, most of which are dispatched by
the default method, see \code{\LinkA{methods}{methods}("all.equal")}.
\code{all.equal.list} and \code{all.equal.language} provide
comparison of recursive objects.

Numerical comparisons for \code{scale = NULL} (the default) are done
by first computing the mean absolute difference of the two numerical
vectors. If this is smaller than \code{tolerance} or not finite,
absolute differences are used, otherwise relative differences scaled
by the mean absolute difference.

If \code{scale} is positive, absolute comparisons are after scaling
(dividing) by \code{scale}.

For complex arguments, the modulus \code{\LinkA{Mod}{Mod}} of the difference
is used: \code{all.numeric.numeric} is called so arguments
\code{tolerance} and \code{scale} are available.

\code{attr.all.equal} is used for comparing
\code{\LinkA{attributes}{attributes}}, returning \code{NULL} or \code{character}.
\end{Details}
\begin{Value}
Either \code{TRUE} or a vector of \code{\LinkA{mode}{mode}}
\code{"character"} describing the differences between \code{target}
and \code{current}.

Numerical differences are reported by \emph{relative} error.
\end{Value}
\begin{References}\relax
Chambers, J. M. (1998)
\emph{Programming with Data. A Guide to the S Language}.
Springer (for \code{=}).
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{identical}{identical}}, \code{\LinkA{isTRUE}{isTRUE}}, \code{\LinkA{==}{==}}, and
\code{\LinkA{all}{all}} for exact equality testing.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
all.equal(pi, 355/113) # not precise enough (default tol) > relative error

d45 <- pi*(1/4 + 1:10)
stopifnot(
all.equal(tan(d45), rep(1,10)))        # TRUE, but
all      (tan(d45) == rep(1,10))       # FALSE, since not exactly
all.equal(tan(d45), rep(1,10), tol=0)  # to see difference
\end{ExampleCode}
\end{Examples}

