| getMethod {methods} | R Documentation |
The functions getMethod and selectMethod get the
definition of a particular method; the functions existsMethod
and hasMethod test for the existence of a method. In both
cases the first function only gets direct definitions and the second
uses inheritance.
The function findMethod returns the package(s) in the search
list (or in the packages specified by the where argument) that
contain a method for this function and signature.
The other functions are support functions: see the details below.
getMethod(f, signature=character(), where, optional=FALSE, mlist, fdef)
findMethod(f, signature, where)
getMethods(f, where)
existsMethod(f, signature = character(), where)
hasMethod(f, signature=character(), where)
selectMethod(f, signature, optional = FALSE, useInherited = TRUE,
mlist = (if (is.null(fdef)) NULL else
getMethodsForDispatch(f, fdef)),
fdef = getGeneric(f, !optional))
MethodsListSelect(f, env, mlist, fEnv, finalDefault, evalArgs,
useInherited, fdef, resetAllowed)
f |
The character-string name of the generic function. |
signature |
the signature of classes to match to the arguments
of f. See the details below.
For selectMethod, the signature can optionally be an
environment with classes assigned to the names of the corresponding
arguments. Note: the names correspond to the names of the classes, not
to the objects supplied in a call to the generic function. (You
are not likely to find this approach convenient, but it is used
internally and is marginally more efficient.)
|
where |
The position or environment in which to look for the method(s): by default, anywhere in the current search list. |
optional |
If the selection does not produce a unique result,
an error is generated, unless this argument is TRUE. In that
case, the value returned is either a MethodsList object, if
more than one method matches this signature, or NULL if no
method matches. |
mlist |
Optionally, the list of methods in which to search. By
default, the function finds the methods for the corresponding
generic function. To restrict the search to a particular package
or environment, e.g., supply this argument as
getMethodsMetaData(f,where). For selectMethod, see
the discussion of argument fdef.
|
fdef |
Optionally, the generic function from which the method is to be retrieved. (Unlikely to be used, except internally in the package source.) |
env |
The environment in which argument evaluations are done in
MethodsListSelect. Currently must be supplied, but should
usually be sys.frame(sys.parent()) when calling the function
explicitly for debugging purposes. |
fEnv, finalDefault, evalArgs, useInherited, resetAllowed |
Internal-use arguments for the function's environment, the method to use as the overall default, whether to evaluate arguments, which arguments should use inheritance, and whether the cached methods are allowed to be reset. |
The signature argument specifies classes, in an extended
sense, corresponding to formal arguments of the generic function.
As supplied, the argument may be a vector of strings identifying
classes, and may be named or not. Names, if supplied, match the
names of those formal arguments included in the signature of the
generic. That signature is normally all the arguments except
.... However, generic functions can be specified with only a
subset of the arguments permitted, or with the signature taking
the arguments in a different order.
It's a good idea to name the arguments in the signature to avoid
confusion, if you're dealing with a generic that does something
special with its signature. In any case, the elements of the
signature are matched to the formal signature by the same rules
used in matching arguments in function calls (see
match.call).
The strings in the signature may be class names, "missing"
or "ANY". See Methods for the meaning of these in
method selection. Arguments not supplied in the signature
implicitly correspond to class "ANY"; in particular, giving
an empty signature means to look for the default method.
A call to getMethod returns the method for a particular
function and signature. As with other get functions,
argument where controls where the function looks (by default
anywhere in the search list) and argument optional controls
whether the function returns NULL or generates an error if
the method is not found. The search for the method makes no use of
inheritance.
The function selectMethod also looks for a method given the
function and signature, but makes full use of the method dispatch
mechanism; i.e., inherited methods and group generics are taken into
account just as they would be in dispatching a method for the
corresponding signature, with the one exception that conditional
inheritance is not used. Like getMethod, selectMethod
returns NULL or generates an error if
the method is not found, depending on the argument optional.
The functions existsMethod and hasMethod return
TRUE or FALSE according to whether a method is found,
the first corresponding to getMethod (no inheritance) and the
second to selectMethod.
The function getMethods returns all the methods for a
particular generic (in the form of a generic function with the
methods information in its environment). The function is called
from the evaluator to merge method information, and is not intended
to be called directly. Note that it gets all the visible
methods for the specified functions. If you want only the methods
defined explicitly in a particular environment, use the function
getMethodsMetaData instead.
The function MethodsListSelect performs a full search
(including all inheritance and group generic information: see the
Methods documentation page for details on how this works).
The call returns a possibly revised methods list object,
incorporating any method found as part of the allMethods
slot.
Normally you won't call MethodsListSelect directly, but it is
possible to use it for debugging purposes (only for distinctly
advanced users!).
Note that the statement that MethodsListSelect corresponds to the
selection done by the evaluator is a fact, not an assertion, in the
sense that the evaluator code constructs and executes a call to
MethodsListSelect when it does not already have a cached method
for this generic function and signature. (The value returned is
stored by the evaluator so that the search is not required next
time.)
The call to selectMethod or getMethod returns a
MethodDefinition-class object, the selected method, if
a unique selection exists.
(This class extends function, so you can use the result
directly as a function if that is what you want.)
Otherwise an error is thrown if optional is FALSE. If
optional is TRUE, the value returned is NULL if
no method matched, or a MethodsList object if multiple
methods matched.
The call to getMethods returns the MethodsList object
containing all the methods requested. If there are none,
NULL is returned: getMethods does not generate an
error in this case.
The R package methods implements, with a few exceptions, the programming interface for classes and methods in the book Programming with Data (John M. Chambers, Springer, 1998), in particular sections 1.6, 2.7, 2.8, and chapters 7 and 8.
While the programming interface for the methods package follows
the reference, the R software is an original implementation, so
details in the reference that reflect the S4 implementation may appear
differently in R. Also, there are extensions to the programming
interface developed more recently than the reference. For a
discussion of details see ?Methods
and the links from that documentation.
setGeneric("testFun", function(x)standardGeneric("testFun"))
setMethod("testFun", "numeric", function(x)x+1)
hasMethod("testFun", "numeric")
## Not run: [1] TRUE
hasMethod("testFun", "integer") #inherited
## Not run: [1] TRUE
existsMethod("testFun", "integer")
## Not run: [1] FALSE
hasMethod("testFun") # default method
## Not run: [1] FALSE
hasMethod("testFun", "ANY")
## Not run: [1] FALSE