| validObject {methods} | R Documentation |
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.
validObject(object, test = FALSE, complete = FALSE) setValidity(Class, method, where = topenv(parent.frame()) ) getValidity(ClassDef)
object |
any object, but not much will happen unless the object's class has a formal definition. |
test |
logical; if |
complete |
logical; if |
Class |
the name or class definition of the class whose validity method is to be set. |
ClassDef |
a class definition object, as from
|
method |
a validity method; that is, either |
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. |
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.
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.
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.
Chambers, John M. (2016) Extending R, Chapman & Hall. (Chapters 9 and 10.)
setClass;
class classRepresentation.
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))