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

---