The R Project SVN R

Rev

Rev 26082 | Rev 37404 | Go to most recent revision | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 26082 Rev 30666
Line 35... Line 35...
35 
\alias{.OldClassesList}
 35 
\alias{.OldClassesList}
36 
\alias{table-class}
 36 
\alias{table-class}
37 
\title{ Specify Names for Old-Style Classes }
 37 
\title{ Specify Names for Old-Style Classes }
38 
\description{
 38 
\description{
39 
  Register an old-style (a.k.a. `S3') class as a formally defined
 39 
  Register an old-style (a.k.a. `S3') class as a formally defined
40 
  class. The \code{Classes} argument is the character vector used as
 40 
  class. The \code{Classes} argument is the character vector used as the
41 
  the \code{class} attribute; in particular, if there is more than one string,  old-style
 41 
  \code{class} attribute; in particular, if there is more than one
42 
  class inheritance is mimiced.  Registering via \code{setOldClass}
 42 
  string,  old-style class inheritance is mimiced.  Registering via
43 
  allows S3 classes to appear as slots or in method signatures.
 43 
  \code{setOldClass} allows S3 classes to appear as slots or in method
- 
 
 44 
  signatures.
44 
}
 45 
}
45 
\usage{
 46 
\usage{
46 
setOldClass(Classes, where, test = FALSE)
 47 
setOldClass(Classes, where, test = FALSE)
47 
}
 48 
}
48 
\arguments{
 49 
\arguments{
- 
 
 50 
  \item{Classes}{
49 
  \item{Classes}{ A character vector, giving the names for old-style
 51 
    A character vector, giving the names for old-style
50 
  classes, as they would appear on the right side of an assignment of
 52 
    classes, as they would appear on the right side of an assignment of
51 
  the \code{class} attribute. }
 53 
    the \code{class} attribute.
- 
 
 54 
  }
- 
 
 55 
  \item{where}{
52 
    \item{where}{ Where to store the class definitions, the global or
 56 
    Where to store the class definitions, the global or top-level
53 
        top-level environment by default.  (When either function is called in the source
 57 
    environment by default.  (When either function is called in the
54 
        for a package, the class definitions will be included in the package's environment
 58 
    source for a package, the class definitions will be included in the
55 
        by default.)}
 59 
    package's environment by default.)
56 
 
 60 
  }
57 
    \item{test}{flag, if \code{TRUE}, inheritance must be tested
 61 
  \item{test}{flag, if \code{TRUE}, inheritance must be tested
58 
        explicitly for each object, needed if the S3 class can have a
 62 
    explicitly for each object, needed if the S3 class can have a
59 
        different set of class strings, with the same first string.
 63 
    different set of class strings, with the same first string.
60 
        See the details below.}
 64 
    See the details below.
- 
 
 65 
  }
61 
}
 66 
}
62 
\details{
 67 
\details{
63 
  Each of the names will be defined as a virtual class, extending the
 68 
  Each of the names will be defined as a virtual class, extending the
64 
  remaining classes in \code{Classes}, and the class
 69 
  remaining classes in \code{Classes}, and the class
65 
  \code{oldClass}, which is the \dQuote{root} of all old-style classes.
 70 
  \code{oldClass}, which is the \dQuote{root} of all old-style classes.
Line 90... Line 95...
90 
  never wrong to have this test, but since it adds significant
 95 
  never wrong to have this test, but since it adds significant
91 
  overhead to methods defined for the inherited classes, you should
 96 
  overhead to methods defined for the inherited classes, you should
92 
  only supply this argument if it's known that object-specific tests
 97 
  only supply this argument if it's known that object-specific tests
93 
  are needed.
 98 
  are needed.
94 
 
 99 
 
95 
   The list \code{.OldClassesList} contains the old-style classes that
 100 
  The list \code{.OldClassesList} contains the old-style classes that
96 
  are defined by the methods package.  Each element of the list is an
 101 
  are defined by the methods package.  Each element of the list is an
97 
  old-style list, with multiple character strings if inheritance is
 102 
  old-style list, with multiple character strings if inheritance is
98 
  included.
 103 
  included.
99 
  Each element of the list was passed to \code{setOldClass} when
 104 
  Each element of the list was passed to \code{setOldClass} when
100 
  creating the \pkg{methods} package; therefore, these classes can be used
 105 
  creating the \pkg{methods} package; therefore, these classes can be used
101 
  in \code{\link{setMethod}} calls, with the inheritance as implied by
 106 
  in \code{\link{setMethod}} calls, with the inheritance as implied by
102 
  the list.
 107 
  the list.
103 
}
 108 
}
104 
 
 109 
 
105 
\section{Register or Convert?}{
 110 
\section{Register or Convert?}{
106 
A call to \section{setOldClass} creates formal classes corresponding
 111 
  A call to \code{setOldClass} creates formal classes corresponding
107 
to S3 classes, allows these to be used as slots in other classes or in
 112 
  to S3 classes, allows these to be used as slots in other classes or in
108 
a signature in \code{\link{setMethod}}, and mimics the S3 inheritance.
 113 
  a signature in \code{\link{setMethod}}, and mimics the S3 inheritance.
109 
 
 114 
 
110 
However, all such classes are created as virtual classes, meaning that
 115 
  However, all such classes are created as virtual classes, meaning that
111 
you cannot generally create new objects from the class by calling
 116 
  you cannot generally create new objects from the class by calling
112 
\code{\link{new}}, and that objects cannot be coerced automatically
 117 
  \code{\link{new}}, and that objects cannot be coerced automatically
113 
from or to these classes.  All these restrictions just reflect the
 118 
  from or to these classes.  All these restrictions just reflect the
114 
fact that nothing is inherently known about the \dQuote{structure} of
 119 
  fact that nothing is inherently known about the \dQuote{structure} of
115 
S3 classes, or whether in fact they define a consistent set of
 120 
  S3 classes, or whether in fact they define a consistent set of
116 
attributes that can be mapped into slots in a formal class definition.
 121 
  attributes that can be mapped into slots in a formal class definition.
117 
 
 122 
 
118 
\emph{If} your class does in fact have a consistent structure, so that
 123 
  \emph{If} your class does in fact have a consistent structure, so that
119 
every object from the class has the same structure, you may prefer to
 124 
  every object from the class has the same structure, you may prefer to
120 
take some extra time to write down a specific definition in a call to
 125 
  take some extra time to write down a specific definition in a call to
121 
\code{\link{setClass}} to convert the class to a fully functional
 126 
  \code{\link{setClass}} to convert the class to a fully functional
122 
formal class.  On the other hand, if the actual contents of the class
 127 
  formal class.  On the other hand, if the actual contents of the class
123 
vary from one object to another, you may have to redesign most of the
 128 
  vary from one object to another, you may have to redesign most of the
124 
software using the class, in which case converting it may not be worth
 129 
  software using the class, in which case converting it may not be worth
125 
the effort.  You should still register the class via
 130 
  the effort.  You should still register the class via
126 
\code{setOldClass}, unless its class attribute is hopelessly unpredictable.
 131 
  \code{setOldClass}, unless its class attribute is hopelessly unpredictable.
127 
 
 132 
 
128 
An S3 class has consistent structure if each object has the same set
 133 
  An S3 class has consistent structure if each object has the same set
129 
of attributes, both the names and the classes of the attributes being
 134 
  of attributes, both the names and the classes of the attributes being
130 
the same for every object in the class.  In practice, you can convert
 135 
  the same for every object in the class.  In practice, you can convert
131 
classes that are slightly less well behaved.  If a few attributes
 136 
  classes that are slightly less well behaved.  If a few attributes
132 
appear in some but not all objects, you can include these optional
 137 
  appear in some but not all objects, you can include these optional
133 
attributes as slots that \emph{always} appear in the objects, if you
 138 
  attributes as slots that \emph{always} appear in the objects, if you
134 
can supply a default value that is equivalent to the attribute being
 139 
  can supply a default value that is equivalent to the attribute being
135 
missing.  Sometimes \code{NULL} can be that value: A slot (but not an
 140 
  missing.  Sometimes \code{NULL} can be that value: A slot (but not an
136 
attribute) can have the value \code{NULL}.  If \code{version}, for
 141 
  attribute) can have the value \code{NULL}.  If \code{version}, for
137 
example, was an optional attribute, the old test
 142 
  example, was an optional attribute, the old test
138 
\code{is.null(attr(x,"version")} for a missing version attribute could
 143 
  \code{is.null(attr(x,"version")} for a missing version attribute could
139 
turn into \code{is.null(x@version)} for the formal class.
 144 
  turn into \code{is.null(x@version)} for the formal class.
140 
 
 145 
 
141 
The requirement that slots have a fixed class can be satisfied
 146 
  The requirement that slots have a fixed class can be satisfied
142 
indirectly as well.  Slots \emph{can} be specified with class
 147 
  indirectly as well.  Slots \emph{can} be specified with class
143 
\code{"ANY"}, allowing an arbitrary object.  However, this eliminates
 148 
  \code{"ANY"}, allowing an arbitrary object.  However, this eliminates
144 
an important benefit of formal class definitions; namely, automatic
 149 
  an important benefit of formal class definitions; namely, automatic
145 
validation of objects assigned to a slot.  If just a few different
 150 
  validation of objects assigned to a slot.  If just a few different
146 
classes are possible, consider using \code{\link{setClassUnion}} to
 151 
  classes are possible, consider using \code{\link{setClassUnion}} to
147 
define valid objects for a slot.
 152 
  define valid objects for a slot.
148 
}
 153 
}
149 
 
 154 
 
150 
\seealso{
 155 
\seealso{
151 
  \code{\link{setClass}}, \code{\link{setMethod}}
 156 
  \code{\link{setClass}}, \code{\link{setMethod}}
152 
}
 157 
}