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