is {methods}R Documentation

Is an Object from a Class?

Description

Functions to test inheritance relationships between an object and a class or between two classes (extends).

Usage

is(object, class2)

extends(class1, class2, maybe = TRUE, fullInfo = FALSE)

Arguments

object

any R object.

class1, class2

character strings giving the names of each of the two classes between which is relations are to be examined, or (more efficiently) the class definition objects for the classes.

fullInfo

In a call to extends, with class2 missing, fullInfo is a flag, which if TRUE causes a list of objects of class SClassExtension to be returned, rather than just the names of the classes. Only the distance slot is likely to be useful in practice; see the ‘Selecting Superclasses’ section;

maybe

What to return for conditional inheritance. But such relationships are rarely used and not recommended, so this argument should not be needed.

Selecting Superclasses

A call to selectSuperClasses(cl) returns a list of superclasses, similarly to extends(cl). Additional arguments restrict the class names returned to direct superclasses and/or to non-virtual classes.

Either way, programming with the result, particularly using sapply, can be useful.

To find superclasses with more generally defined properties, one can program with the result returned by extends when called with one class as argument. By default, the call returns a character vector including the name of the class itself and of all its superclasses. Alternatively, if extends is called with fullInfo = TRUE, the return value is a named list, its names being the previous character vector. The elements of the list corresponding to superclasses are objects of class SClassExtension. Of the information in these objects, one piece can be useful: the number of generations between the classes, given by the "distance" slot.

Programming with the result of the call to extends, particularly using sapply, can select superclasses. The programming technique is to define a test function that returns TRUE for superclasses or relationships obeying some requirement. For example, to find only next-to-direct superclasses, use this function with the list of extension objects:

function(what) is(what, "SClassExtension") && what@distance == 2

or, to find only superclasses from "myPkg", use this function with the simple vector of names:

function(what) getClassDef(what)@package == "myPkg"

Giving such functions as an argument to sapply called on the output of extends allows you to find superclasses with desired properties. See the examples below.

Note that the function using extension objects must test the class of its argument since, unfortunately for this purpose, the list returned by extends includes class1 itself, as the object TRUE.

Note

Prior to R 4.2.0 the code used the first elements of class1 and class2, silently, These are now required to be length-one character vectors.

References

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

See Also

Although inherits is defined for S3 classes, it has been modified so that the result returned is nearly always equivalent to is, both for S4 and non-S4 objects. Since it is implemented in C, it is somewhat faster. The only non-equivalences arise from use of setIs, which should rarely be encountered.

Examples

## Not run: 
## this example can be run if package XRPython from CRAN is installed.
supers <- extends("PythonInterface")
## find all the superclasses from package XR
fromXR <- sapply(supers,
    function(what) getClassDef(what)@package == "XR")
## print them
supers[fromXR]

## find all the superclasses at distance 2
superRelations <- extends("PythonInterface", fullInfo = TRUE)
dist2 <- sapply(superRelations,
    function(what) is(what, "SClassExtension") && what@distance == 2)
## print them
names(superRelations)[dist2]


## End(Not run)

[Package methods version 4.4.1 Index]