R: Test the Validity of an Object

validObject {methods} | R Documentation

## Test the Validity of an Object

### Description

`validObject()` tests the validity of `object` related to its class definition; specifically, it checks that all slots specified in the class definition are present and that the object in the slot is from the required class or a subclass of that class.

If the object is valid, `TRUE` is returned; otherwise, an error is generated, reporting all the validity failures encountered. If argument `test` is `TRUE`, the errors are returned as a character vector rather than generating an error.

When an object from a class is initialized, the default method for `initialize()` calls `validObject`.

A class definition may have a validity method, set by a call to the function `setValidity`, in the package or environment that defines the class (or via the `validity` argument to `setClass`). The method should be a function of one object that returns `TRUE` or a character-string description of the non-validity. If such a method exists, it will be called from `validObject` and any strings from failure will be included in the result or the error message. Any validity methods defined for superclasses (from the `contains=` argument to `setClass`), will also be called.

### Usage

    validObject(object, test = FALSE, complete = FALSE)

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

    getValidity(ClassDef)

### Arguments

`object` | any object, but not much will happen unless the object's class has a formal definition.
`test` | logical; if `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.
`complete` | logical; if `TRUE`, `validObject` is called recursively for each of the slots. The default is `FALSE`.
`Class` | the name or class definition of the class whose validity method is to be set.
`ClassDef` | a class definition object, as from `getClassDef`.
`method` | a validity method; that is, either `NULL` or a function of one argument (`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` | an environment to store the modified class definition. Should be omitted, specifically for calls from a package that defines the class. The definition will be stored in the namespace of the package.

### Details

Validity testing takes place ‘bottom up’, checking the slots, then the superclasses, then the object's own validity method, if there is one.

For each slot and superclass, the existence of the specified class is checked. For each slot, the object in the slot is tested for inheritance from the corresponding class. If `complete` is TRUE, `validObject` is called recursively for the object in the slot.

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.

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

### Validity methods

A validity method must be a function of one argument; formally, that argument should be named `object`. If the argument has a different name, `setValidity` makes the substitution but in obscure cases that might fail, so it's wiser to name the argument `object`.

A good method checks all the possible errors and returns a character vector citing all the exceptions found, rather than returning after the first one. `validObject` will accumulate these errors in its error message or its return value.

Note that validity methods do not have to check validity of superclasses: `validObject` calls such methods explicitly.

### References

Chambers, John M. (2016) Extending R, Chapman & Hall. (Chapters 9 and 10.)

### See Also

`setClass`; class `classRepresentation`.

### Examples

    setClass("track",
              slots = c(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", contains = "track",
             slots = c(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", slots = c(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))

[Package methods version 4.0.5 Index]