| % 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} |