| Line 5... |
Line 5... |
| 5 |
\description{
|
5 |
\description{
|
| 6 |
The validity of \code{object} related to its class definition is
|
6 |
The validity of \code{object} related to its class definition is
|
| 7 |
tested. If the object is valid, \code{TRUE} is returned; otherwise,
|
7 |
tested. If the object is valid, \code{TRUE} is returned; otherwise,
|
| 8 |
either a vector of strings describing validity failures is returned,
|
8 |
either a vector of strings describing validity failures is returned,
|
| 9 |
or an error is generated (according to whether \code{test} is
|
9 |
or an error is generated (according to whether \code{test} is
|
| 10 |
\code{TRUE}).
|
10 |
\code{TRUE}). Optionally, all slots in the object can also be validated.
|
| 11 |
|
11 |
|
| 12 |
The function \code{setValidity} sets the validity method of a class
|
12 |
The function \code{setValidity} sets the validity method of a class
|
| 13 |
(but more normally, this method will be supplied as the
|
13 |
(but more normally, this method will be supplied as the
|
| 14 |
\code{validity} argument to \code{\link{setClass}}). The method
|
14 |
\code{validity} argument to \code{\link{setClass}}). The method
|
| 15 |
should be a function of one object that returns \code{TRUE} or a
|
15 |
should be a function of one object that returns \code{TRUE} or a
|
| 16 |
description of the non-validity.
|
16 |
description of the non-validity.
|
| 17 |
}
|
17 |
}
|
| 18 |
\usage{
|
18 |
\usage{
|
| 19 |
validObject(object, test = FALSE)
|
19 |
validObject(object, test = FALSE, complete = FALSE)
|
| 20 |
|
20 |
|
| 21 |
setValidity(Class, method, where = topenv(parent.frame()) )
|
21 |
setValidity(Class, method, where = topenv(parent.frame()) )
|
| 22 |
}
|
22 |
}
|
| 23 |
\arguments{
|
23 |
\arguments{
|
| 24 |
\item{object}{ Any object, but not much will happen unless the
|
24 |
\item{object}{ Any object, but not much will happen unless the
|
| 25 |
object's class has a formal definition.}
|
25 |
object's class has a formal definition.}
|
| 26 |
\item{test}{ If \code{test} is \code{TRUE}, and validity fails the
|
26 |
\item{test}{ If \code{test} is \code{TRUE}, and validity fails the
|
| 27 |
function returns a vector of strings describing the problems. If
|
27 |
function returns a vector of strings describing the problems. If
|
| 28 |
\code{test} is \code{FALSE} (the default) validity failure generates
|
28 |
\code{test} is \code{FALSE} (the default) validity failure generates
|
| 29 |
an error.}
|
29 |
an error.}
|
| - |
|
30 |
\item{complete}{ If \code{TRUE}, validity methods will be applied
|
| - |
|
31 |
recursively to any of the slots that have such methods.
|
| - |
|
32 |
}
|
| 30 |
\item{Class}{the name or class definition of the class whose validity
|
33 |
\item{Class}{the name or class definition of the class whose validity
|
| 31 |
method is to be set.}
|
34 |
method is to be set.}
|
| 32 |
\item{method}{a validity method; that is, either \code{NULL} or a
|
35 |
\item{method}{a validity method; that is, either \code{NULL} or a
|
| 33 |
function of one argument (the \code{object}). Like
|
36 |
function of one argument (the \code{object}). Like
|
| 34 |
\code{validObject}, the function should return \code{TRUE} if the
|
37 |
\code{validObject}, the function should return \code{TRUE} if the
|
| Line 37... |
Line 40... |
| 37 |
error.
|
40 |
error.
|
| 38 |
}
|
41 |
}
|
| 39 |
\item{where}{the modified class definition will be stored in this
|
42 |
\item{where}{the modified class definition will be stored in this
|
| 40 |
environment.}
|
43 |
environment.}
|
| 41 |
|
44 |
|
| 42 |
Note that validity methods do not have to check validity of any
|
45 |
Note that validity methods do not have to check validity of superclasses: the logic of \code{validObject} ensures
|
| 43 |
slots or superclasses: the logic of \code{validObject} ensures
|
- |
|
| 44 |
these tests are done once only. As a consequence, if one validity
|
46 |
these tests are done once only. As a consequence, if one validity
|
| 45 |
method wants to use another, it should extract and call the method
|
47 |
method wants to use another, it should extract and call the method
|
| 46 |
from the other definition of the other class by calling
|
48 |
from the other definition of the other class by calling
|
| 47 |
\code{\link{getValidity}}: it should \emph{not} call
|
49 |
\code{\link{getValidity}}: it should \emph{not} call
|
| 48 |
\code{validObject}.
|
50 |
\code{validObject}.
|
| 49 |
}
|
51 |
}
|
| 50 |
\details{
|
52 |
\details{
|
| 51 |
Validity testing takes place \dQuote{bottom up}: first the validity
|
53 |
Validity testing takes place \dQuote{bottom up}: Optionally, if\code{complete=TRUE}, the validity
|
| 52 |
of the object's slots, if any, is tested. Then for each of the
|
54 |
of the object's slots, if any, is tested. Then, in all cases, for each of the
|
| 53 |
classes that this class extends (the \dQuote{superclasses}), the
|
55 |
classes that this class extends (the \dQuote{superclasses}), the
|
| 54 |
explicit validity method of that class is called, if one exists.
|
56 |
explicit validity method of that class is called, if one exists.
|
| 55 |
Finally, the validity method of \code{object}'s class is called, if
|
57 |
Finally, the validity method of \code{object}'s class is called, if
|
| 56 |
there is one.
|
58 |
there is one.
|
| 57 |
|
59 |
|
| 58 |
Testing generally stops at the first stage of finding an error, except
|
60 |
Testing generally stops at the first stage of finding an error, except
|
| 59 |
that all the slots will be examined even if a slot has failed its
|
61 |
that all the slots will be examined even if a slot has failed its
|
| 60 |
validity test.
|
62 |
validity test.
|
| - |
|
63 |
|
| - |
|
64 |
The standard validity test (with \code{complete=FALSE}) is applied
|
| - |
|
65 |
when an object is created via \code{\link{new}} with any optional
|
| - |
|
66 |
arguments (without the extra arguments the result is just the class
|
| - |
|
67 |
prototype object).
|
| 61 |
}
|
68 |
}
|
| 62 |
\value{
|
69 |
\value{
|
| 63 |
\code{validObject} returns \code{TRUE} if the object is valid.
|
70 |
\code{validObject} returns \code{TRUE} if the object is valid.
|
| 64 |
Otherwise a vector of strings describing problems found, except that
|
71 |
Otherwise a vector of strings describing problems found, except that
|
| 65 |
if \code{test} is \code{FALSE}, validity failure generates an error,
|
72 |
if \code{test} is \code{FALSE}, validity failure generates an error,
|
| Line 95... |
Line 102... |
| 95 |
## assign the function as the validity method for the class
|
102 |
## assign the function as the validity method for the class
|
| 96 |
setValidity("track", validTrackObject)
|
103 |
setValidity("track", validTrackObject)
|
| 97 |
## t1 should be a valid "track" object
|
104 |
## t1 should be a valid "track" object
|
| 98 |
validObject(t1)
|
105 |
validObject(t1)
|
| 99 |
## Now we do something bad
|
106 |
## Now we do something bad
|
| - |
|
107 |
t2 <- t1
|
| 100 |
t1@x <- 1:20
|
108 |
t2@x <- 1:20
|
| 101 |
## This should generate an error
|
109 |
## This should generate an error
|
| 102 |
\dontrun{try(validObject(t1))}
|
110 |
\dontrun{try(validObject(t2))}
|
| 103 |
\dontshow{stopifnot(is(try(validObject(t1)), "try-error"))}
|
111 |
\dontshow{stopifnot(is(try(validObject(t2)), "try-error"))}
|
| 104 |
}
|
- |
|
| 105 |
|
112 |
|
| - |
|
113 |
setClass("trackCurve",
|
| - |
|
114 |
representation("track", smooth = "numeric"))
|
| - |
|
115 |
|
| - |
|
116 |
## all superclass validity methods are used when validObject
|
| - |
|
117 |
## is called from initialize() with arguments, so this fails
|
| - |
|
118 |
\dontrun{trynew("trackCurve", t2)}
|
| - |
|
119 |
\dontshow{stopifnot(is(try(new("trackCurve", t2)), "try-error"))}
|
| - |
|
120 |
|
| - |
|
121 |
setClass("twoTrack", representation(tr1 = "track", tr2 ="track"))
|
| - |
|
122 |
|
| - |
|
123 |
## validity tests are not applied recursively by default,
|
| - |
|
124 |
## so this object is created (invalidly)
|
| - |
|
125 |
tT <- new("twoTrack", tr2 = t2)
|
| - |
|
126 |
|
| - |
|
127 |
## A stricter test detects the problem
|
| - |
|
128 |
\dontrun{try(validObject(tT, complete = TRUE))}
|
| - |
|
129 |
\dontshow{stopifnot(is(try(validObject(tT, complete = TRUE)), "try-error"))}
|
| - |
|
130 |
}
|
| 106 |
\keyword{programming}
|
131 |
\keyword{programming}
|
| 107 |
\keyword{classes}
|
132 |
\keyword{classes}
|
The R Project SVN
R