% File src/library/methods/man/Classes_Details.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2016 R Core Team
% Distributed under GPL 2 or later

\name{Classes_Details}
\alias{Classes_Details}
\alias{__ClassMetaData}
\alias{.environment-class}
\alias{.externalptr-class}
\alias{.name-class}
\alias{.NULL-class}
\title{Class Definitions}
\description{
  Class definitions are objects that contain the formal definition of a
  class of \R objects, usually referred to as an S4 class, to
  distinguish them from the informal S3 classes.
  This document gives an overview of S4 classes; for
  details of the class representation objects, see help for the class
  \code{\linkS4class{classRepresentation}}.
}
\section{Metadata Information}{
  When a class is defined, an object is stored that contains the
  information about that class.  The object, known as the
  \emph{metadata} defining the class, is not stored under the name of
  the class (to allow programmers to write generating functions of
  that name), but under a specially constructed name.
  To examine the class definition, call \code{\link{getClass}}.  The
  information in the metadata object includes:

  \describe{
    \item{Slots:}{

        The data contained in an object from an S4 class is defined by
        the \emph{slots} in the class definition.

        Each slot in an object is a component of the object;
        like components (that is, elements) of a
      list, these may be extracted and set, using the
      function \code{\link{slot}()} or more often the operator
        \code{"\link{@}"}.  However, they
      differ from list components in important ways.
      First, slots can only be referred to by name, not by position,
      and there is no partial matching of names as with list elements.

      All the objects from a particular class have the same set of slot
      names; specifically, the slot names that are contained in the
      class definition.  Each slot in each object always is an object
      of  the
      class specified for this slot in the definition of the current class.
      The word \dQuote{is} corresponds to the \R function of the same
      name (\code{\link{is}}), meaning that the class of the object in
      the slot must be the same as the class specified in the
      definition, or some class that extends the one in the
      definition (a \emph{subclass}).

      A special slot name, \code{.Data}, stands for the
      \sQuote{data part} of the object.  An object from a class with a
      data part is defined by specifying that the class contains one
      of the \R object types or one of the special pseudo-classes,
      \code{matrix} or \code{array}, usually because the definition of
      the class, or of one of its superclasses, has included the type
      or pseudo-class in its \code{contains} argument.  A second
      special slot name, \code{.xData}, is used to enable inheritance
      from abnormal types such as \code{"environment"}
      See the section on inheriting from non-S4 classes
      for details on the representation and
      for the behavior of S3 methods with objects from these classes.

      Some slot names correspond to attributes used in old-style S3
      objects and in \R objects without an explicit class, for
      example, the \code{names} attribute.  If you define a class for
      which that attribute will be set, such as a subclass of named
      vectors, you should include \code{"names"} as a slot.  See the
      definition of class \code{"namedList"} for an example.  Using the
      \code{names()} assignment to set such names will generate a
      warning if there is no names slot and an error if the object in
      question is not a vector type.  A slot called \code{"names"} can
      be used anywhere, but only if it is assigned as a slot, not via
      the default \code{names()} assignment.

    }
    \item{Superclasses:}{

      The definition of a class includes the \emph{superclasses} ---the
      classes that this class extends.  A
      class \code{Fancy}, say, extends a class \code{Simple} if an
      object from the \code{Fancy} class has all the capabilities of
      the \code{Simple} class (and probably some more as well).  In
      particular, and very usefully, any method defined to work for a
      \code{Simple} object can be applied to a \code{Fancy} object as
      well.

      This relationship is expressed equivalently by saying that
      \code{Simple} is a superclass of \code{Fancy}, or that
      \code{Fancy} is a subclass of \code{Simple}.

      The direct superclasses of a class are those superclasses
      explicitly defined.   Direct superclasses can be defined in
      three ways.  Most commonly, the superclasses are listed in the
      \code{contains=} argument in the call to \code{\link{setClass}}
      that creates the subclass.   In this case the subclass will
      contain all the slots of the superclass, and the relation
      between the class is called \emph{simple}, as it in fact is.
      Superclasses can also be defined
      explicitly by a call to \code{\link{setIs}}; in this case, the
      relation requires methods to be specified to go from subclass to
      superclass.   Thirdly, a class union is a superclass of all the
      members of the union.  In this case too the relation is simple,
      but notice that the relation is defined when the superclass is
      created, not when the subclass is created as with the
      \code{contains=} mechanism.

      The definition of a superclass will also potentially contain
      its own direct superclasses.  These are considered (and shown) as
      superclasses at distance 2 from the original class; their direct
      superclasses are at distance 3, and so on.  All these are
      legitimate superclasses for purposes such as method selection.

      When superclasses are defined  by including the names of
      superclasses in the \code{contains=} argument to
      \code{\link{setClass}}, an object from the class will have all the
      slots defined for its own class \emph{and} all the slots defined
      for all its superclasses as well.

      The information about the relation between a class and a
      particular superclass is encoded as an object of class
      \code{\linkS4class{SClassExtension}}.  A list of such objects for
      the superclasses (and sometimes for the subclasses) is included in
      the metadata object defining the class.  If you need to compute
      with these objects (for example, to compare the distances), call
      the function \code{\link{extends}} with argument \code{fullInfo=TRUE}.

    }
    \item{Prototype:}{

      The objects from a class created by a call to
      \code{\link{new}}
      are defined by the \emph{prototype} object for the class and by
      additional arguments in the call to \code{\link{new}}, which are
      passed to a method for that class for the function
      \code{\link{initialize}}.

      Each class representation object contains a prototype object
      for the class (although for a virtual class the prototype may be
      \code{NULL}). The prototype object must have values for all the
      slots of the class.
      By default, these are the prototypes of the corresponding slot
      classes.  However, the definition of the class can specify any
      valid object for any of the slots.
    }
  }
}
\section{Basic classes}{

      There are a number of \sQuote{basic} classes, corresponding to the
      ordinary kinds of data occurring in \R.  For example,
      \code{"numeric"} is a class corresponding to numeric vectors.
      The other vector basic classes are \code{"logical"}, \code{"integer"},
      \code{"complex"}, \code{"character"},  \code{"raw"}, \code{"list"}
      and \code{"expression"}.
      The prototypes for
      the vector classes are vectors of length 0 of the corresponding
      type.  Notice that basic classes are unusual in that the
      prototype object is from the class itself.

      In addition to the vector classes there are also basic classes
      corresponding to objects in the
      language, such as \code{"function"} and \code{"call"}.
      These classes are subclasses of the virtual class \code{"language"}.
      Finally, there are object types and corresponding basic classes for
      \dQuote{abnormal} objects, such as \code{"environment"} and
      \code{"externalptr"}.
      These objects do not follow the
      functional behavior of the language; in particular, they are not
      copied and so cannot have attributes or slots defined locally.

     All these classes can be used as slots or as
      superclasses for any other class definitions, although they do
      not themselves come with an explicit class.  For the abnormal
      object types, a special mechanism is used to enable inheritance
      as described below.


}
% S3 classes

\section{Inheriting from non-S4 Classes}{
  A class definition can extend classes other than
  regular S4 classes, usually by specifying them in the
  \code{contains=} argument to \code{\link{setClass}}.  Three groups
  of such classes behave distinctly:
\enumerate{
\item
S3 classes, which must have been registered by a previous call to
\code{\link{setOldClass}} (you can check that this has been done
  by calling \code{\link{getClass}}, which should return a class that
  extends \linkS4class{oldClass});

\item
  One of the \R object types, typically a vector type, which then
    defines the type of the S4 objects, but also a type such as
    \code{\link{environment}} that can not be used directly as a type
    for an S4 object.  See
    below.

\item
  One of the pseudo-classes \code{\linkS4class{matrix}}
      and \code{\linkS4class{array}}, implying objects with
      arbitrary vector types plus the \code{dim} and \code{dimnames}
      attributes.
  }

  This section describes the approach to combining S4 computations
  with older S3 computations by using such classes as superclasses. The
  design goal is to allow the S4 class to inherit S3 methods and
  default computations in as consistent a form as possible.

  As part of a general effort to make the S4 and S3 code in R more
  consistent, when objects from an S4 class are used as the first
  argument to a non-default S3 method, either for an S3 generic function
  (one that calls \code{\link{UseMethod}}) or for one of the primitive
  functions that dispatches S3 methods, an effort is made to provide a
  valid object for that method.  In particular, if the S4 class extends
  an S3 class or \code{matrix} or \code{array}, and there is an S3
  method matching one of these classes, the S4 object will be coerced to
  a valid S3 object, to the extent that is possible given that there is
  no formal definition of an S3 class.

  For example, suppose \code{"myFrame"} is an S4 class that includes the
  S3 class \code{"data.frame"} in the \code{contains=} argument to
  \code{\link{setClass}}.  If an object from this S4 class is passed to
  a function, say \code{\link{as.matrix}}, that has an S3 method for
  \code{"data.frame"}, the internal code for \code{\link{UseMethod}}
  will convert the object to a data frame; in particular, to an S3
  object whose class attribute will be the vector corresponding to the
  S3 class (possibly containing multiple class names). Similarly for an
  S4 object inheriting from \code{"matrix"} or \code{"array"}, the S4
  object will be converted to a valid S3 matrix or array.

  Note that the conversion is \emph{not} applied when an S4 object is
  passed to the default S3 method.  Some S3 generics attempt to deal
  with general objects, including S4 objects.  Also, no transformation
  is applied to S4 objects that do not correspond to a selected S3
  method; in particular, to objects from a class that does not contain
  either an S3 class or one of the basic types.  See \code{\link{asS4}}
  for the transformation details.

      In addition to explicit S3 generic functions, S3 methods are
      defined for a variety of operators and functions implemented as
      primitives.  These methods are dispatched by some internal C
      code that operates partly through the same code as real S3
      generic functions and partly via special considerations (for
      example, both arguments to a binary operator are examined when
      looking for methods).  The same mechanism for adapting S4
      objects to S3 methods has been applied to these computations as
      well, with a few exceptions such as generating an error if an S4
      object that does not extend an appropriate S3 class or type is
      passed to a binary operator.

      The remainder of this section discusses the mechanisms for
      inheriting from  basic object types. See \code{\linkS4class{matrix}}
      or \code{\linkS4class{array}}
      for inhering from the matrix and array
      pseudo-classes, or from time-series.  For the
      corresponding details for inheritance
      from S3 classes, see \code{\link{setOldClass}}.

      An object from a class that directly and simply contains one
      of the basic object types in \R, has implicitly a corresponding
      \code{.Data} slot of that type, allowing computations to extract
      or replace the data part while leaving other slots
      unchanged. If the type is one that can accept attributes and is
      duplicated normally, the inheritance also determines the type of the
      object; if the class definition has a \code{.Data} slot
      corresponding to a normal type, the class of the
      slot determines the type of the object (that is, the value of
      \code{\link{typeof}(x)}).
      For such classes,  \code{.Data} is a pseudo-slot; that
      is, extracting or setting it modifies the non-slot data in the
      object.  The functions \code{\link{getDataPart}} and
      \code{\link{setDataPart}} are a cleaner, but essentially
      equivalent way to deal with the data part.

      Extending a basic type this way allows objects to
      use old-style code for the corresponding type as well as S4
      methods.  Any basic type can be used for \code{.Data}, but
      a few types are treated differently because they do not behave like ordinary objects;
      for example, \code{"NULL"}, environments, and external pointers.
      Classes extend these types by having a slot, \code{.xData},
      itself inherited from an internally defined S4 class.  This
      slot actually contains an object of the inherited type, to
      protect computations from the reference semantics of the type.
      Coercing to the nonstandard object type then requires an
      actual computation, rather than the \code{"simple"} inclusion
      for other types and classes.  The intent is that programmers
      will not need to take account of the mechanism, but one
      implication is that you should \emph{not} explicitly use the
      type of an S4 object to detect inheritance from an arbitrary
      object type.  Use
      \code{\link{is}} and similar functions instead.
}


\references{
 Chambers, John M. (2016)
 \emph{Extending R},
  Chapman & Hall.
(Chapters 9 and 10.)
}

\seealso{
  \code{\link{Methods_Details}} for analogous discussion of methods,
  \code{\link{setClass}} for details of specifying class definitions,
  \code{\link{is}},
  \code{\link{as}},
  \code{\link{new}},
  \code{\link{slot}}
}
\keyword{programming}
\keyword{classes}
\keyword{methods}