1% File src/library/methods/man/is.Rd 2% Part of the R package, https://www.R-project.org 3% Copyright 1995-2016 R Core Team 4% Distributed under GPL 2 or later 5 6\name{is} 7\alias{is} 8\alias{extends} 9\title{Is an Object from a Class?} 10\description{ 11 Functions to test inheritance relationships between an object and a 12 class or between two classes (\code{extends}). 13} 14 15\usage{ 16is(object, class2) 17 18extends(class1, class2, maybe = TRUE, fullInfo = FALSE) 19} 20\arguments{ 21 \item{object}{any \R object.} 22 \item{class1, class2}{ 23 the names of the classes between which \code{is} relations are to be 24 examined defined, or (more efficiently) the class definition 25 objects for the classes.} 26 27 \item{fullInfo}{ 28 In a call to \code{extends}, with \code{class2} missing, 29 \code{fullInfo} is a flag, which if \code{TRUE} causes a list of 30 objects of class \code{\linkS4class{SClassExtension}} to be returned, rather than 31 just the names of the classes. Only the distance slot is likely to 32 be useful in practice; see the \sQuote{Selecting Superclasses} section; 33 34 } 35 \item{maybe}{ 36 What to return for conditional inheritance. But such 37 relationships are rarely used and not recommended, so this 38 argument should not be needed. 39 } 40} 41 42\section{Selecting Superclasses}{ 43 44 A call to \code{\link{selectSuperClasses}(cl)} returns a list of 45 superclasses, similarly to 46 \code{extends(cl)}. Additional arguments restrict the class names 47 returned to direct superclasses and/or to non-virtual classes. 48 49 Either way, programming with the result, particularly using 50 \code{\link{sapply}}, can be useful. 51 52 To find superclasses with more generally defined properties, one can program 53 with the result returned by \code{extends} when called with one 54 class as argument. 55 By default, the call returns a character vector including the name of the class 56 itself and of all its superclasses. 57 Alternatively, 58 if \code{extends} is called with \code{fullInfo = 59 TRUE}, the return value is a named list, its names being the previous 60 character vector. The elements of the list corresponding to 61 superclasses are objects of class 62 \code{\linkS4class{SClassExtension}}. Of the information in these objects, one piece can be useful: 63 the number of generations between the classes, given by the 64 \code{"distance"} slot. 65 66 Programming with the result of the call to \code{extends}, particularly using 67 \code{\link{sapply}}, can select superclasses. 68 The programming technique is to define a test function that returns 69 \code{TRUE} for superclasses or relationships obeying some 70 requirement. For example, to find only next-to-direct superclasses, 71 use this function with the list of extension objects: 72 73 \code{function(what) is(what, "SClassExtension") && what@distance == 2} 74 75 or, to find only superclasses from \code{"myPkg"}, use this function 76 with the simple vector of names: 77 78 \code{function(what) getClassDef(what)@package == "myPkg"} 79 80 Giving such functions as an argument to \code{\link{sapply}} called on the output of 81 \code{extends} allows you to find 82 superclasses with desired properties. See the examples below. 83 84 Note that the function using extension objects must test the class of its argument since, 85 unfortunately for this purpose, the list returned by \code{extends} includes 86 \code{class1} itself, as the object \code{TRUE}. 87} 88 89 90\seealso{ 91 Although \code{\link{inherits}} is defined for S3 classes, it has 92 been modified so that the result returned is nearly always equivalent to 93 \code{is}, both for S4 and non-S4 objects. Since it is implemented 94 in C, it is somewhat faster. 95 The only non-equivalences arise from use of \code{\link{setIs}}, 96 which should rarely be encountered. 97 98 99 } 100 101\references{ 102 Chambers, John M. (2016) 103 \emph{Extending R}, 104 Chapman & Hall. 105(Chapters 9 and 10.) 106} 107 108\examples{ 109\dontrun{ 110## this example can be run if package XRPython from CRAN is installed. 111supers <- extends("PythonInterface") 112## find all the superclasses from package XR 113fromXR <- sapply(supers, 114 function(what) getClassDef(what)@package == "XR") 115## print them 116supers[fromXR] 117 118## find all the superclasses at distance 2 119superRelations <- extends("PythonInterface", fullInfo = TRUE) 120dist2 <- sapply(superRelations, 121 function(what) is(what, "SClassExtension") && what@distance == 2) 122## print them 123names(superRelations)[dist2] 124 125} 126} 127\keyword{programming} 128\keyword{classes} 129\keyword{methods} 130