37
42
All the objects from a particular class have the same set of slot
38
43
names; specifically, the slot names that are contained in the
39
class definition. Each slot in each object always has the same
40
class; again, this is defined by the overall class definition.
41
The phrase \dQuote{has the same class} means that the class of the object in
44
class definition. Each slot in each object always is an object
46
class specified for this slot in the definition of the current class.
47
The word \dQuote{is} corresponds to the \R function of the same
48
name (\code{\link{is}}), meaning that the class of the object in
42
49
the slot must be the same as the class specified in the
43
50
definition, or some class that extends the one in the
51
definition (a \emph{subclass}).
46
53
One class name is special, \code{.Data}. This stands for the
47
54
\sQuote{data part} of the object. Any class that contains one
48
of the basic data types in \R{}, has implicitly a corresponding
55
of the basic object types in \R, has implicitly a corresponding
49
56
\code{.Data} slot of that type, allowing computations to extract
50
57
or replace the data part while leaving other slots
51
58
unchanged. The \code{.Data} slot also determines the type of the
52
59
object; if \code{x} has a \code{.Data} slot, the type of the
53
60
slot is the type of the object (that is, the value of
54
\code{\link{typeof}(x)}. Otherwise the type of the object is
55
\code{"S4"}. Extending a basic type this way allows objects to
61
\code{\link{typeof}(x)}). Extending a basic type this way allows objects to
56
62
use old-style code for the corresponding type as well as S4
57
63
methods. Any basic type can be used for \code{.Data}, with the
58
64
exception of a few that do not behave like ordinary objects;
59
65
namely, \code{"NULL"}, environments, and external pointers.
61
Classes exist for which there are no actual objects, the
62
\emph{virtual} classes, in fact a
63
very important programming tool. They are used to group together
64
ordinary classes that want to share some programming behavior,
65
without necessarily restricting how the behavior is implemented.
66
Virtual class definitions may if you want include
67
slots (to provide some common behavior without fully defining
68
the object---see the class \code{\linkS4class{traceable}} for an example).
67
There is one additional use of the data part, which is also an
68
exception to the correspondence with the object's type. The exception
69
arises from the special treatment of \code{\linkS4class{matrix}}
70
and \code{\linkS4class{array}} \dQuote{classes} in \R.
71
Matrix and array objects are managed internally and recognized
72
without regard to any class attribute; therefore, they can be
73
used as the data part of a new class. In this case, the object
74
type for the new class depends on the type of the data in the
70
A simple and useful form of virtual class is the \emph{class
71
union}, a virtual class that is defined in a call to
72
\code{\link{setClassUnion}} by listing one or
73
more of subclasses (classes that extend the class union). Class
74
unions can include as subclasses basic data types (whose
75
definition is otherwise sealed).
77
If the new class does not have a data part as described above,
78
the type of objects from the new class is
78
82
\item{Superclasses:}{
143
147
the slot classes, if those are not virtual classes. However, the
144
148
definition of the class can specify any valid object for any of
153
\section{Virtual classes; Basic classes}{
155
Classes exist for which there are no actual objects, the
156
\emph{virtual} classes, in fact a
157
very important programming tool. They are used to group together
158
ordinary classes that want to share some programming behavior,
159
without necessarily restricting how the behavior is implemented.
160
Virtual class definitions may if you want include
161
slots (to provide some common behavior without fully defining
162
the object---see the class \code{\linkS4class{traceable}} for an example).
164
A simple and useful form of virtual class is the \emph{class
165
union}, a virtual class that is defined in a call to
166
\code{\link{setClassUnion}} by listing one or
167
more of subclasses (classes that extend the class union). Class
168
unions can include as subclasses basic data types (whose
169
definition is otherwise sealed).
147
171
There are a number of \sQuote{basic} classes, corresponding to the
148
172
ordinary kinds of data occurring in R. For example,
149
173
\code{"numeric"} is a class corresponding to numeric vectors.
150
There are also basic classes corresponding to objects in the
151
language, such as \code{"function"} and \code{"call"}, and for
152
specialized objects, such as \code{"environment"}
153
These classes are predefined and can then be used as slots or as
154
superclasses for any other class definitions. The prototypes for
174
The other vector basic classes are \code{"logical"}, \code{"integer"},
175
\code{"complex"}, \code{"character"}, \code{"raw"}, \code{"list"}
176
and \code{"expression"}.
155
178
the vector classes are vectors of length 0 of the corresponding
156
179
type. Notice that basic classes are unusual in that the
157
180
prototype object is from the class itself.
159
There are also a few basic virtual classes, the most important
160
being \code{"vector"}, grouping together all the vector classes;
161
and \code{"language"}, grouping together all the types of objects
162
making up the R language.
182
In addition to the vector classes there are also basic classes corresponding to objects in the
183
language, such as \code{"function"} and \code{"call"}.
184
These classes are subclasses of the virtual class \code{"language"}.
185
Finally, there are basic classes for
186
specialized objects, such as \code{"environment"} and \code{"externalptr"}.
187
The vector and language basic classes can be used as slots or as
188
superclasses for any other class definitions.
189
The classes corresponding to other object types can be used as
190
slots but not always as superclasses, since many of them do not follow the
191
functional behavior of the language; in particular, they are not
192
copied and so cannot have attributes or slots defined locally.
195
\section{S3 Classes}{
197
Earlier, informal classes of objects (usually referred to as
198
\sQuote{S3} classes) are used by many \R functions. It is natural to
199
consider including them as the class for a slot in a formal class,
200
or even as a class to be extended by the new class. This isn't
201
prohibited but there are some disadvantages, and if you do want to
202
include S3 classes, they should be declared by including them in a
203
call to \code{\link{setOldClass}}. Here are some considerations:
206
\item Using S3 classes somewhat defeats the purpose of defining a
207
formal class: An important advantage to your users is that a formal
208
class provides guarantees of what the object contains (minimally,
209
the classes of the slots and therfore what data they contain;
210
optionally, any other requirements imposed by a validity method).
212
But there is no guarantee whatever about the data in an object from
213
an S3 class. It's entirely up to the functions that create or
214
modify such objects. If you want to provide guarantees to your
215
users, you will need a valdity method that explicitly checks the
216
contents of S3-class objects.
218
\item To get the minimal guarantee (that the object in a slot has, or
219
extends, the class for the slot) you should ensure that the S3
220
classes are known to \emph{be} S3 classes, possibly with S
221
inheritance. To do this, include a call to
222
\code{\link{setOldClass}} for the S3 classes used.
224
Otherwise, the S3 class is undefined (and the code used by
225
\code{setClass} will issue a warning). Slot assignments, for
226
example, will not then check for possible errors.
228
\item Current versions of \R (beginning with 2.8.0) try to
229
accommodate S4 classes that extend S3 classes, that is, those
230
including an S3 class in the \code{contains=} argument to
231
\code{\link{setClass}} . Specifically, objects from such classes
232
will contain the S3 class as a slot, and some S3 computations will
233
recognize the S3 class,
234
including method dispatch and the function
235
\code{\link{inherits}}. See \code{\link{S3Class}} for details.
236
The S3 classes \emph{must} have been registered by a call to \code{\link{setOldClass}}.
237
The basic caution remains true however: There is no guarantee that all S3 computations will be
238
compatible, and some are known not to be.
240
\item These caveats apply to S3 classes; that is, objects with a
241
class assigned by some \R function but without a formal class
242
definition. In contrast, the built-in vector types (\code{numeric},
243
\code{list}, etc.) are generally fine as slots or for
244
\code{contains=} classes. These object
245
types don't have formal slots, but the base code in the system
246
essentially forces them to contain the type of data they claim to
249
Objects with a \dQuote{class} of \code{matrix} or \code{array} are somewhat in
250
between. They do not have an explicit S3 class, but do have one or
251
two attributes. There is no general problem in having these as
252
slots, but because there is no guarantee of a dimnames slot, they
253
don't work as formal classes. The \code{ts} class, although also
254
ancient in the S language, is implemented in \R essentially as an
255
S3 class, with the implications noted above---not suitable for a
256
\code{contains=} argument---but with a few S4
257
methods defined. See the documentation for class \code{\linkS4class{structure}} for more details.
167
The functions in this package emulate the facility for classes and
168
methods described in \emph{Programming with Data} (John M. Chambers,
169
Springer, 1998). See this book for further details and examples.
263
Chambers, John M. (2008)
264
\emph{Software for Data Analysis: Programming with R}
265
Springer. (For the R version.)
267
Chambers, John M. (1998)
268
\emph{Programming with Data}
269
Springer (For the original S4 version.)
271
Chambers, John M. and Hastie, Trevor J. eds (1992)
272
\emph{Statistical Models in S.}
273
Wadsworth & Brooks/Cole (Appendix A for S3 classes.)
275
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
276
\emph{The New S Language}.
277
Wadsworth \& Brooks/Cole. (Out of print.) (The description of
278
vectors, matrix, array and time-series objects.)
173
\code{\link{Methods}},
174
\code{\link{setClass}},
282
\code{\link{Methods}} for analogous discussion of methods,
283
\code{\link{setClass}} for details of specifying class definitions,
175
284
\code{\link{is}},
176
285
\code{\link{as}},
177
286
\code{\link{new}},
added
removed
src/library/methods/man/Classes.Rd
