blob: eb6f52b48db12dbcd298beb95c1dd087b0fa7a08 [file] [log] [blame]
% File src/library/base/man/all.equal.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2018 R Core Team
% Distributed under GPL 2 or later
\name{all.equal}
\title{Test if Two Objects are (Nearly) Equal}
\alias{all.equal}
\alias{all.equal.default}
\alias{all.equal.numeric}
\alias{all.equal.character}
\alias{all.equal.environment}
\alias{all.equal.envRefClass}
\alias{all.equal.factor}
\alias{all.equal.formula}
\alias{all.equal.list}
\alias{all.equal.language}
\alias{all.equal.POSIXt}
\alias{all.equal.raw}
\alias{attr.all.equal}
\concept{numerical equality}
\concept{approximately equal}
\concept{equality testing}
\usage{
all.equal(target, current, \dots)
\method{all.equal}{numeric}(target, current,
tolerance = sqrt(.Machine$double.eps), scale = NULL,
countEQ = FALSE,
formatFUN = function(err, what) format(err),
\dots, check.attributes = TRUE)
\method{all.equal}{list}(target, current, \dots,
check.attributes = TRUE, use.names = TRUE)
\method{all.equal}{environment}(target, current, all.names=TRUE, \dots)
\method{all.equal}{POSIXt}(target, current, \dots, tolerance = 1e-3, scale)
attr.all.equal(target, current, \dots,
check.attributes = TRUE, check.names = TRUE)
}
\arguments{
\item{target}{\R object.}
\item{current}{other \R object, to be compared with \code{target}.}
\item{\dots}{further arguments for different methods, notably the
following two, for numerical comparison:}
\item{tolerance}{numeric \eqn{\ge} 0. Differences smaller than
\code{tolerance} are not reported. The default value is close to
\code{1.5e-8}.}
\item{scale}{\code{NULL} or numeric > 0, typically of length 1 or
\code{length(target)}. See \sQuote{Details}.}
\item{countEQ}{logical indicating if the \code{target == current}
cases should be counted when computing the mean (absolute or
relative) differences. The default, \code{FALSE} may seem
misleading in cases where \code{target} and \code{current} only
differ in a few places; see the extensive example.}
\item{formatFUN}{a \code{\link{function}} of two arguments,
\code{err}, the relative, absolute or scaled error, and
\code{what}, a character string indicating the \emph{kind} of error;
maybe used, e.g., to format relative and absolute errors differently.}
\item{check.attributes}{logical indicating if the
\code{\link{attributes}} of \code{target} and \code{current}
(other than the names) should be compared.}
\item{use.names}{logical indicating if \code{\link{list}} comparison
should report differing components by name (if matching) instead of
integer index. Note that this comes after \code{\dots} and so must
be specified by its full name.}
\item{all.names}{logical passed to \code{\link{ls}} indicating if
\dQuote{hidden} objects should also be considered in the environments.}
\item{check.names}{logical indicating if the \code{\link{names}(.)}
of \code{target} and \code{current} should be compared.}
}
\description{
\code{all.equal(x, y)} is a utility to compare \R objects \code{x}
and \code{y} testing \sQuote{near equality}. If they are different,
comparison is still made to some extent, and a report of the
differences is returned. Do not use \code{all.equal} directly in
\code{if} expressions---either use \code{isTRUE(all.equal(....))} or
\code{\link{identical}} if appropriate.
}
\details{
\code{all.equal} is a generic function, dispatching methods on the
\code{target} argument. To see the available methods, use
\code{\link{methods}("all.equal")}, but note that the default method
also does some dispatching, e.g.\sspace{}using the raw method for logical
targets.
Remember that arguments which follow \code{\dots} must be specified by
(unabbreviated) name. It is inadvisable to pass unnamed arguments in
\code{\dots} as these will match different arguments in different
methods.
Numerical comparisons for \code{scale = NULL} (the default) are
typically on \emph{relative difference} scale unless the target values
are close to zero: First, the mean absolute difference of the two
numerical vectors is computed. If this is smaller than
\code{tolerance} or not finite, absolute differences are used,
otherwise relative differences scaled by the mean absolute
\code{target} value.
Note that these comparisons are computed only for those vector elements
where \code{target} is not \code{\link{NA}} and differs from \code{current}.
If \code{countEQ} is true, the equal and \code{NA} cases are
\emph{counted} in determining \dQuote{sample} size.
If \code{scale} is numeric (and positive), absolute comparisons are
made after scaling (dividing) by \code{scale}.
For complex \code{target}, the modulus (\code{\link{Mod}}) of the
difference is used: \code{all.equal.numeric} is called so arguments
\code{tolerance} and \code{scale} are available.
The \code{\link{list}} method compares components of
\code{target} and \code{current} recursively, passing all other
arguments, as long as both are \dQuote{list-like}, i.e., fulfill
either \code{\link{is.vector}} or \code{\link{is.list}}.
The \code{\link{environment}} method works via the \code{list} method,
and is also used for reference classes (unless a specific
\code{all.equal} method is defined).
The methods for the date-time classes by default allow a tolerance of
\code{tolerance = 0.001} seconds, and ignore \code{scale}.
\code{attr.all.equal} is used for comparing
\code{\link{attributes}}, returning \code{NULL} or a
\code{character} vector.
}
\value{
Either \code{TRUE} (\code{NULL} for \code{attr.all.equal}) or a vector
of \code{\link{mode}} \code{"character"} describing the differences
between \code{target} and \code{current}.
}
\references{
Chambers, J. M. (1998)
\emph{Programming with Data. A Guide to the S Language}.
Springer (for \code{=}).
}
\seealso{\code{\link{identical}}, \code{\link{isTRUE}}, \code{\link{==}}, and
\code{\link{all}} for exact equality testing.
}
\examples{
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), tolerance = 0) # to see difference
## advanced: equality of environments
ae <- all.equal(as.environment("package:stats"),
asNamespace("stats"))
stopifnot(is.character(ae), length(ae) > 10,
## were incorrectly "considered equal" in R <= 3.1.1
all.equal(asNamespace("stats"), asNamespace("stats")))
## A situation where 'countEQ = TRUE' makes sense:
x1 <- x2 <- (1:100)/10; x2[2] <- 1.1*x1[2]
## 99 out of 100 pairs (x1[i], x2[i]) are equal:
plot(x1,x2, main = "all.equal.numeric() -- not counting equal parts")
all.equal(x1,x2) ## "Mean relative difference: 0.1"
mtext(paste("all.equal(x1,x2) :", all.equal(x1,x2)), line= -2)
##' extract the 'Mean relative difference' as number:
all.eqNum <- function(...) as.numeric(sub(".*:", '', all.equal(...)))
set.seed(17)
## When x2 is jittered, typically all pairs (x1[i],x2[i]) do differ:
summary(r <- replicate(100, all.eqNum(x1, x2*(1+rnorm(x1)*1e-7))))
mtext(paste("mean(all.equal(x1, x2*(1 + eps_k))) {100 x} Mean rel.diff.=",
signif(mean(r), 3)), line = -4, adj=0)
## With argument countEQ=TRUE, get "the same" (w/o need for jittering):
mtext(paste("all.equal(x1,x2, countEQ=TRUE) :",
signif(all.eqNum(x1,x2, countEQ=TRUE), 3)), line= -6, col=2)
}
\keyword{programming}% is.*
\keyword{utilities}
\keyword{logic}
\keyword{arith}