getMethod              package:methods              R Documentation

Get or Test for the Definition of a Method

Description:

     Functions to look for a method corresponding to a given generic
     function and signature. The functions 'getMethod' and
     'selectMethod' return the method; the functions 'existsMethod' and
     'hasMethod' test for its existence.  In both cases the first
     function only gets direct definitions and the second uses
     inheritance.  In all cases, the search is in the generic function
     itself or in the package/environment specified by argument
     'where'.

     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.

Usage:

     getMethod(f, signature=character(), where, optional = FALSE,
               mlist, fdef)

     existsMethod(f, signature = character(), where)

     findMethod(f, signature, where)

     selectMethod(f, signature, optional = FALSE, useInherited =,
                  mlist = , fdef = , verbose = )

     hasMethod(f, signature=character(), where)

Arguments:

       f: A  generic function or the character-string name of one.

signature: the signature of classes to match to the arguments of 'f'. 
          See the details below.

   where: The position or environment in which to look for the
          method(s):  by default, the table of methods defined in the
          generic function itself is used.

optional: If the selection in  'selectMethod' does find a valid method
          an error is generated, unless this argument is 'TRUE'.  In
          that case, the value returned is  'NULL' if no method
          matches.

mlist, fdef, useInherited, verbose: Optional arguments  to  'getMethod'
          and 'selectMethod'.  Avoid these: some will work and others
          will not, and none of them is required for normal use of the
          functions. 

Details:

     The 'signature' argument specifies classes, corresponding to
     formal arguments of the generic function; to be precise, to the
     'signature' slot of the generic function object. 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'.

Value:

     The call to 'selectMethod' or 'getMethod' returns  the selected
     method, if one is found. (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'  and 
     'NULL' is returned if 'optional' is 'TRUE'.

     The returned method object is a 'MethodDefinition' object,
     _except_ that the default method for a primitive function is
     required to be the primitive itself. Note therefore that the only
     reliable test that the search failed is 'is.null()'.

References:

     Chambers, John M. (2008) _Software for Data Analysis: Programming
     with R_ Springer.  (For the R version.)

     Chambers, John M. (1998) _Programming with Data_ Springer (For the
     original S4 version.)

See Also:

     'Methods' for the details of method selection; 'GenericFunctions'
     for other functions manipulating methods and generic function
     objects; 'MethodDefinition' for the class that represents method
     definitions.

Examples:

     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

