\Header{validObject}{Test the Validity of an Object}
\alias{getValidity}{validObject}
\alias{setValidity}{validObject}
\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}).

The functions \code{getValidity} and \code{setValidity} get and set
the validity method of a class.  This method is 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)

getValidity(ClassDef)
setValidity(ClassDef, method)
\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}] If \code{test} is \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{ClassDef}] The name of the class whose validity method is to be
set.
\item[\code{method}] A validity method;  that is, either \code{NULL} or a
function of one argument (the \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.

Note that validity methods do not have to check validity of any
slots or 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{\Link{getValidity}}:  it should \emph{not} call
\code{validObject}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Validity testing takes place ``bottom up'':  first the validity of the
object's slots, if any, is tested.  Then for each of the classes that
this class extends (the ``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.\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{Author}\relax
John Chambers\end{Author}
\begin{References}\relax
The web page \url{http://www.omegahat.org/RSMethods/index.html}
is the primary documentation.

The functions in this package emulate the facility for classes
and methods described in \emph{Programming with Data} (John
M. Chambers, Springer, 1998).  See this book for further details and
examples.\end{References}
\begin{SeeAlso}\relax
\code{\Link{setClass}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  setClass("track",
    representation(x="numeric", y = "numeric"))
  t1 <- new("track", x=1:10, y=sort(rnorm(10)))
  ## A valid "track" object has the same number of x, y values
  validTrackObject <- function(x){
    if(length(x@x) == length(x@y)) TRUE
    else paste("Unequal x,y lengths: ", length(x@x), ", ", length(x@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
  t1@x <- 1:20
  ## This should generate an error
  try(validObject(t1))
\end{ExampleCode}
\end{Examples}

