Classes               package:methods               R Documentation

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 themselves, see 'class?classRepresentation'
     ('classRepresentation-class').

Details:

     When a class is defined, an object is stored that contains the
     information about that class, including:

     Slots: The data contained in an object from an S4 class is defined
          by the _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 'slot()' or more often
          the operator '"@"'.  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 has
          the same class; again, this is defined by the overall class
          definition. The phrase "has the same class" means 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.

          One class name is special, '.Data'.  This stands for the
          'data part' of the object.  Any class that contains one of
          the basic data types in R{}, has implicitly a corresponding
          '.Data' slot of that type, allowing computations to extract
          or replace the data part while leaving other slots unchanged.
          The '.Data' slot also determines the type of the object; if
          'x' has a '.Data' slot, the type of the slot is the type of
          the object (that is, the value of 'typeof(x)'.  Otherwise the
          type of the object is '"S4"'.  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 '.Data', with the exception of a few that do not
          behave like ordinary objects; namely, '"NULL"', environments,
          and external pointers.

          Classes exist for which there are no actual objects, the
          _virtual_ classes, in fact a very important programming tool.
           They are used to group together ordinary classes that want
          to share some programming behavior, without necessarily
          restricting how the behavior is implemented. Virtual class
          definitions may if you want include slots (to provide some
          common behavior without fully defining the object-see
          traceable-class for an example).

          A simple and useful form of virtual class is the _class
          union_, a virtual class that is defined in a call to
          'setClassUnion' by listing one or more of subclasses (classes
          that extend the class union).  Class unions can include as
          subclasses basic data types (whose definition is otherwise
          sealed).


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

          This relationship is expressed equivalently by saying that
          'Simple' is a superclass of 'Fancy', or that 'Fancy' is a
          subclass of '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 'contains=' argument in the call to '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 _simple_, as it in fact is.
          Superclasses can also be defined explicitly by a call to
          '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 '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 'contains=' argument to 'setClass',   an
          object from the class will have all the slots defined for its
          own class _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
          '"SClassExtension"' (see SClassExtension-class).  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
          'extends' with argument 'fullInfo=TRUE'.


     Objects: The objects from a class, typically created by a call to
          'new' or by assigning another object from the class, are
          defined by the _prototype_ object for the class and by
          additional arguments in the call to 'new', which are passed
          to a method for that class for the function 'initialize'.

          Each class definition contains a prototype object for the
          class.  This must have values for all the slots defined by
          the class definition. By default, these are the prototypes of
          all the slot classes, if those are not virtual classes. 
          However, the definition of the class can specify any valid
          object for any of the slots.

          There are a number of 'basic' classes, corresponding to the
          ordinary kinds of data occurring in R.  For example,
          '"numeric"' is a class corresponding to numeric vectors.
          There are also basic classes corresponding to objects in the
          language, such as '"function"' and '"call"', and for
          specialized objects, such as '"environment"' These classes
          are predefined and can then be used as slots or as
          superclasses for any other class definitions.  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.

          There are also a few basic virtual classes, the most
          important being '"vector"', grouping together all the vector
          classes; and '"language"', grouping together all the types of
          objects making up the R language.

References:

     The functions in this package emulate the facility for classes and
     methods described in _Programming with Data_ (John M. Chambers,
     Springer, 1998).  See this book for further details and examples.

See Also:

     'Methods', 'setClass', 'is', 'as', 'new', 'slot'

