is {methods}

R Documentation

Is an Object from a Class

Description

is: With two arguments, tests whether object can be treated as from class2.

With one argument, returns all the super-classes of this object's class.

extends: Does the first class extend the second class? Returns maybe if the extension includes a test.

setIs: Defines class1 to be an extension of class2.

Usage

is(object, class2)

extends(class1, class2, maybe=TRUE)

setIs(class1, class2, test=NULL, coerce=NULL, replace=NULL,
      by = NULL, where = 1, classDef)

Arguments

object	Any R object.
class1, class2	The names of the classes between which is relations are to be defined.
maybe	What value to return if the relationship is conditional.
test, coerce, replace	Functions optionally supplied to test whether the relation is defined, to coerce the object to class2, and to alter the object so that is(object, class2) is identical to value.
by	The name of an intermediary class. Coercion will proceed by first coercing to this class and from there to the target class. (The intermediate coercions have to be valid.)
where	Where to store the metadata defining the relationship. Default is the global environment.
classDef	Optional class definition for class , required internally when setIs is called during the initial definition of the class by a call to setClass. Don't use this argument, unless you really know why you're doing so.

Details

setIs:

The relationship can be conditional, if a function is supplied as the test argument. If a function is supplied as the coerce argument, this function will be applied to any class1 object in order to turn it into a class2 object. If the relationship is to be defined indirectly through a third class, this class can be named in the by argument.

Extension may imply that a class1 object contains a class2 object. The default sense of containing is that all the slots of the simpler class are found in the more elaborate one. If the replace argument is supplied as an S replacement function, this function will be used to implement as(obj, class2) <- value.

The coerce, replace, and by arguments behave as described for the setAs function. It's unlikely you would use the by argument directly, but it is used in defining cached information about classes. The value returned (invisibly) by setIs is the extension information, as a list.

Information about setIs relations can be stored in the metadata for either class1 (in the extends information) or in the metadata for class2 (in the subclasses information). For the information to be retained for a future session, one of these classes must be defined in the global environment, since only objects assigned there are saved by save.image. If neither class is defined in environment where, setIs generates an error.

Because only global environment information is saved, it rarely makes sense to give a value other than the default for argument where. One exception is where=0, which modifies the cached (i.e., session-scope) information about the class. Class completion computations use this version, but don't use it yourself unless you are quite sure you know what you're doing.

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.

Examples

## a class definition (see \link{setClass} for the example)
setClass("trackCurve",
         representation("track", smooth = "numeric"))
## A class similar to "trackCurve", but with different structure
## allowing matrices for the "y" and "smooth" slots
setClass("trackMultiCurve",
         representation(x="numeric", y="matrix", smooth="matrix"),
         prototype = structure(list(), x=numeric(), y=matrix(0,0,0),

                               smooth= matrix(0,0,0)))
## Automatically convert an object from class "trackCurve" into
## "trackMultiCurve", by making the y, smooth slots into 1-column matrices
setIs("trackCurve",
      "trackMultiCurve",
      coerce = function(obj) {
        new("trackMultiCurve",
            x = obj@x,
            y = as.matrix(obj@y),
            curve = as.matrix(obj@smooth))
      },
      replace = function(obj, value) {
        obj@y <- as.matrix(value@y)
        obj@x <- value@x
        obj@smooth <- as.matrix(value@smooth)
        obj})

## Automatically convert the other way, but ONLY
## if the y data is one variable.
setIs("trackMultiCurve",
      "trackCurve",
      test = function(obj) {ncol(obj@y) == 1},
      coerce = function(obj) {
        new("trackCurve",
            x = slot(obj, "x"),
            y = as.numeric(obj@y),
            smooth = as.numeric(obj@smooth))
      },
      replace = function(obj, value) {
        obj@y <- matrix(value@y, ncol=1)
        obj@x <- value@x
        obj@smooth <- value@smooth
        obj})

---