validObject             package:methods             R Documentation

Test the Validity of an Object

Description:

     The validity of `object' related to its class definition is
     tested.  If the object is valid, `TRUE' is returned; otherwise,
     either a vector of strings describing validity failures is
     returned, or an error is generated (according to whether `test' is
     `TRUE').

     The functions `getValidity' and `setValidity' get and set the
     validity method of a class.  This method is a function of one
     object that returns `TRUE' or a description of the non-validity.

Usage:

     validObject(object, test)

     getValidity(ClassDef)
     setValidity(ClassDef, method)

Arguments:

  object: Any object, but not much will happen unless the object's
          class has a formal definition.

    test: If `test' is `TRUE', and validity fails the function returns
          a vector of strings describing the problems.  If `test' is
          `FALSE' (the default) validity failure generates an error.

ClassDef: The name of the class whose validity method is to be set.

  method: A validity method;  that is, either `NULL' or a function of
          one argument (the `object').  Like `validObject', the
          function should return `TRUE' if the object is valid, and one
          or more descriptive strings if any problems are found. 
          Unlike `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 `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 `getValidity':  it should not call
          `validObject'.

Details:

     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 `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.

Value:

     `validObject' returns `TRUE' if the object is valid.  Otherwise a
     vector of strings describing problems found, except that if `test'
     is `FALSE', validity failure generates an error, with the
     corresponding strings in the error message.

Author(s):

     John Chambers

References:

     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 Programming with Data, (John M. Chambers,
     Springer, 1998). See this book for further details and examples.

See Also:

     `setClass'.

Examples:

       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))

