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 function `setValidity` sets the validity method of a class (but more normally, this method will be supplied as the `validity` argument to `setClass`). The method should be a function of one object that returns `TRUE` or a description of the non-validity.

### Usage

    validObject(object, test = FALSE)

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

### 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.
`Class` | the name or class definition 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.
`where` | the modified class definition will be stored in this environment.

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.

### References

The R package methods implements, with a few exceptions, the programming interface for classes and methods in the book Programming with Data (John M. Chambers, Springer, 1998), in particular sections 1.6, 2.7, 2.8, and chapters 7 and 8.

While the programming interface for the methods package follows the reference, the R software is an original implementation, so details in the reference that reflect the S4 implementation may appear differently in R. Also, there are extensions to the programming interface developed more recently than the reference. For a discussion of details and ongoing development, see the web page http://developer.r-project.org/methodsPackage.html and the pointers from that page.

### 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
    ## Not run: try(validObject(t1))

[Package methods version 2.1.1 Index]