\HeaderA{validObject}{Test the Validity of an Object}{validObject}
\aliasA{getValidity}{validObject}{getValidity}
\aliasA{setValidity}{validObject}{setValidity}
\keyword{programming}{validObject}
\keyword{classes}{validObject}
\begin{Description}\relax
The validity of \code{object} related to its class definition is
tested.  If the object is valid, \code{TRUE} is returned; otherwise,
either a vector of strings describing validity failures is returned,
or an error is generated (according to whether \code{test} is
\code{TRUE}).  Optionally, all slots in the object can also be validated.

The function \code{setValidity} sets the validity method of a class
(but more normally, this method will be supplied as the
\code{validity} argument to \code{\LinkA{setClass}{setClass}}).  The method
should be a function of one object that returns \code{TRUE} or a
description of the non-validity.
\end{Description}
\begin{Usage}
\begin{verbatim}
validObject(object, test = FALSE, complete = FALSE)

setValidity(Class, method, where = topenv(parent.frame()) )

getValidity(ClassDef)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] any object, but not much will happen unless the
object's class has a formal definition.
\item[\code{test}] logical; if \code{TRUE} and validity fails, the
function returns a vector of strings describing the problems.  If
\code{test} is \code{FALSE} (the default) validity failure generates
an error.
\item[\code{complete}] logical; if \code{TRUE}, validity methods will be
applied recursively to any of the slots that have such methods.
\item[\code{Class}] the name or class definition of the class whose validity
method is to be set.
\item[\code{ClassDef}] a class definition object, as from
\code{\LinkA{getClassDef}{getClassDef}}.
\item[\code{method}] a validity method;  that is, either \code{NULL} or a
function of one argument (\code{object}).  Like
\code{validObject}, the function should return \code{TRUE} if the
object is valid, and one or more descriptive strings if any problems
are found.  Unlike \code{validObject}, it should never generate an
error.

\item[\code{where}] the modified class definition will be stored in this
environment.
\end{ldescription}


Note that validity methods do not have to check validity of
superclasses: the logic of \code{validObject} ensures these tests are
done once only.  As a consequence, if one validity method wants to use
another, it should extract and call the method from the other
definition of the other class by calling \code{getValidity()}: it
should \emph{not} call \code{validObject}.
\end{Arguments}
\begin{Details}\relax
Validity testing takes place \sQuote{bottom up}: Optionally, if
\code{complete=TRUE}, the validity of the object's slots, if any, is
tested.  Then, in all cases, for each of the classes that this class
extends (the \sQuote{superclasses}), the explicit validity method of
that class is called, if one exists.  Finally, the validity method of
\code{object}'s class is called, if there is one.

Testing generally stops at the first stage of finding an error, except
that all the slots will be examined even if a slot has failed its
validity test.

The standard validity test (with \code{complete=FALSE}) is applied
when an object is created via \code{\LinkA{new}{new}} with any optional
arguments (without the extra arguments the result is just the class
prototype object).

An attempt is made to fix up the definition of a validity method if
its argument is not \code{object}.
\end{Details}
\begin{Value}
\code{validObject} returns \code{TRUE} if the object is valid.
Otherwise a vector of strings describing problems found, except that
if \code{test} is \code{FALSE}, validity failure generates an error,
with the corresponding strings in the error message.
\end{Value}
\begin{References}\relax
Chambers, John M. (2008)
\emph{Software for Data Analysis: Programming with R}
Springer.  (For the R version.)

Chambers, John M. (1998)
\emph{Programming with Data}
Springer (For the original S4 version.)
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{setClass}{setClass}};
class \code{\LinkA{classRepresentation}{classRepresentation.Rdash.class}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
setClass("track",
          representation(x="numeric", y = "numeric"))
t1 <- new("track", x=1:10, y=sort(stats::rnorm(10)))
## A valid "track" object has the same number of x, y values
validTrackObject <- function(object) {
    if(length(object@x) == length(object@y)) TRUE
    else paste("Unequal x,y lengths: ", length(object@x), ", ",
               length(object@y), sep="")
}
## assign the function as the validity method for the class
setValidity("track", validTrackObject)
## t1 should be a valid "track" object
validObject(t1)
## Now we do something bad
t2 <- t1
t2@x <- 1:20
## This should generate an error
## Not run: try(validObject(t2))


setClass("trackCurve",
         representation("track", smooth = "numeric"))

## all superclass validity methods are used when validObject
## is called from initialize() with arguments, so this fails
## Not run: trynew("trackCurve", t2)


setClass("twoTrack", representation(tr1 = "track", tr2 ="track"))

## validity tests are not applied recursively by default,
## so this object is created (invalidly)
tT  <- new("twoTrack", tr2 = t2)

## A stricter test detects the problem
## Not run: try(validObject(tT, complete = TRUE))

\end{ExampleCode}
\end{Examples}

