1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
\name{updateObject}
\alias{updateObject}
\alias{updateObject,ANY-method}
\alias{updateObject,list-method}
\alias{updateObject,environment-method}
\alias{updateObject,formula-method}
\alias{updateObject,envRefClass-method}
\alias{updateObjectFromSlots}
\alias{getObjectSlots}
\title{Update an object to its current class definition}
\description{
\code{updateObject} is a generic function that returns an instance
of \code{object} updated to its current class definition.
}
\usage{
updateObject(object, ..., verbose=FALSE)
## Related utilities:
updateObjectFromSlots(object, objclass=class(object), ..., verbose=FALSE)
getObjectSlots(object)
}
\arguments{
\item{object}{
Object to be updated for \code{updateObject} and
\code{updateObjectFromSlots}.
Object for slot information to be extracted from for
\code{getObjectSlots}.
}
\item{...}{
Additional arguments, for use in specific \code{updateObject}
methods.
}
\item{verbose}{
\code{TRUE} or \code{FALSE}, indicating whether information about
the update should be reported. Use \code{\link[base]{message}} to
report this information.
}
\item{objclass}{
Optional character string naming the class of the object
to be created.
}
}
\details{
Updating objects is primarily useful when an object has been
serialized (e.g., stored to disk) for some time (e.g., months), and the
class definition has in the mean time changed. Because of the changed
class definition, the serialized instance is no longer valid.
\code{updateObject} requires that the class of the returned object be
the same as the class of the argument \code{object}, and that the
object is valid (see \code{\link[methods]{validObject}}). By default,
\code{updateObject} has the following behaviors:
\describe{
\item{\code{updateObject(ANY, \dots, verbose=FALSE)}}{
By default, \code{updateObject} uses heuristic methods to determine
whether the object should be the `new' S4 type (introduced in R 2.4.0),
but is not. If the heuristics indicate an update is required,
the \code{updateObjectFromSlots} function tries to update the
object. The default method returns the original S4 object or the
successfully updated object, or issues an error if an update is
required but not possible.
The optional named argument \code{verbose} causes a message to be
printed describing the action.
Arguments \code{\dots} are passed to \code{updateObjectFromSlots}.
}
\item{\code{updateObject(list, \dots, verbose=FALSE)}}{
Visit each element in \code{list}, applying
\code{updateObject(list[[elt]], \dots, verbose=verbose)}.
}
\item{\code{updateObject(environment, \dots, verbose=FALSE)}}{
Visit each element in \code{environment}, applying
\code{updateObject(environment[[elt]], \dots, verbose=verbose)}
}
\item{\code{updateObject(formula, \dots, verbose=FALSE)}}{
Do nothing; the environment of the formula may be too general
(e.g., \code{R_GlobalEnv}) to attempt an update.
}
\item{\code{updateObject(envRefClass, \dots, verbose=FALSE)}}{
Attempt to update objects from fields using a strategy like
\code{updateObjectFromSlots} Method 1.
}
}
\code{updateObjectFromSlots(object, objclass=class(object), \dots,
verbose=FALSE)} is a utility function that identifies the intersection
of slots defined in the \code{object} instance and \code{objclass}
definition. Under Method 1, the corresponding elements in
\code{object} are then updated (with \code{updateObject(elt, \dots,
verbose=verbose)}) and used as arguments to a call to \code{new(class,
\dots)}, with \code{\dots} replaced by slots from the original
object. If this fails, then Method 2 tries \code{new(class)} and
assigns slots of \code{object} to the newly created instance.
\code{getObjectSlots(object)} extracts the slot names and contents from
\code{object}. This is useful when \code{object} was created by a class
definition that is no longer current, and hence the contents of
\code{object} cannot be determined by accessing known slots.
}
\value{
\code{updateObject} returns a valid instance of \code{object}.
\code{updateObjectFromSlots} returns an instance of class
\code{objclass}.
\code{getObjectSlots} returns a list of named elements, with each
element corresponding to a slot in \code{object}.
}
\seealso{
\itemize{
\item \code{\link[Biobase]{updateObjectTo}} in the \pkg{Biobase} package
for updating an object to the class definition of a template (might
be useful for updating a virtual superclass).
\item \code{\link[methods]{validObject}} for testing the validity of an
object.
\item \code{\link[methods]{showMethods}} for displaying a summary of the
methods defined for a given generic function.
\item \code{\link[methods]{selectMethod}} for getting the definition of
a specific method.
\item \link{BiocGenerics} for a summary of all the generics defined
in the \pkg{BiocGenerics} package.
}
}
\examples{
updateObject
showMethods("updateObject")
selectMethod("updateObject", "ANY") # the default method
library(Biobase)
## update object, same class
data(sample.ExpressionSet)
obj <- updateObject(sample.ExpressionSet)
setClass("UpdtA", representation(x="numeric"), contains="data.frame")
setMethod("updateObject", "UpdtA",
function(object, ..., verbose=FALSE)
{
if (verbose)
message("updateObject object = 'A'")
object <- callNextMethod()
object@x <- -object@x
object
}
)
a <- new("UpdtA", x=1:10)
## See steps involved
updateObject(a)
removeMethod("updateObject", "UpdtA")
removeClass("UpdtA")
}
\keyword{methods}
|
