The R Project SVN R

\name{is}
\alias{is}
\alias{extends}
\alias{setIs}
\title{Is an Object from a Class}
\description{
  \code{is}: 
  With two arguments, tests whether \code{object} can be treated as from
  \code{class2}.

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

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

  \code{setIs}: 
  Defines \code{class1} to be an extension of \code{class2}.
}
\usage{
is(object, class2)

extends(class1, class2, maybe=TRUE)

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

}
\arguments{
  \item{object}{Any R object.}
  \item{class1, class2}{
    The names of the classes between which \code{is} relations are to be
    defined.}
  \item{maybe}{What value to return if the relationship is conditional.}
  \item{test, coerce, replace}{
    Functions optionally supplied to test whether the relation is
    defined, to coerce the object to \code{class2}, and to alter the
    object so that \code{is(object, class2)} is identical to
    \code{value}.}
  \item{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.)}
  \item{where}{
    Where to store the metadata defining the relationship. Default is
    the global environment.}
  \item{complete}{
    Should the class definitions be completed when checking for valid
    relations. \emph{Don't} set this to anything other than
    \code{TRUE}, unless you really know why you're doing it (used by
    \code{setClass}).}
}

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

Extension may imply that a \code{class1} object contains a \code{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 \code{replace} argument is supplied as an S replacement
function, this function will be used to implement \code{as(obj, class2)
  <- value}.

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

Information about \code{setIs} relations can be stored in the metadata
for either \code{class1} (in the \code{extends} information) or in the
metadata for \code{class2} (in the \code{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
\code{\link{save.image}}.  If neither class is defined in environment
\code{where}, \code{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 \code{where}.
One exception is \code{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 \code{methods} implements, with a few exceptions, the
  programming interface for classes
  and methods in the book \emph{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 
  \url{http://developer.r-project.org/methodsPackage.html} and the
  pointers from that page.
}
\examples{
\testonly{
if(isClass("track"))
  removeClass("track")
if(isClass("trackCurve"))
  removeClass("trackCurve")
if(isClass("trackMultiCurve"))
  removeClass("trackMultiCurve")
## A simple class with two slots
setClass("track",
            representation(x="numeric", y="numeric"))
## A class extending the previous, adding one more slot
}
## 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)))
## Define a multi-curve to extend a single curve ONLY
## if the y data is one variable.
setIs("trackMultiCurve", "trackCurve", test = function(obj) {ncol(slot(obj, "y")) == 1},
      coerce = function(obj) { new("trackCurve", x = slot(obj, "x"),
        y = as.numeric(slot(obj,"y")), curve = as.numeric(slot(obj, "curve")))})

}
\keyword{programming}
\keyword{classes}
\keyword{methods}