UseMethod                package:base                R Documentation

_C_l_a_s_s _M_e_t_h_o_d_s

_D_e_s_c_r_i_p_t_i_o_n:

     R possesses a simple generic function mechanism which can be used
     for an object-oriented style of programming.  Method dispatch
     takes place based on the class of the first argument to the
     generic function or on the object supplied as an argument to
     'UseMethod' or 'NextMethod'.

_U_s_a_g_e:

     UseMethod(generic, object)
     NextMethod(generic = NULL, object = NULL, ...)

_A_r_g_u_m_e_n_t_s:

 generic: a character string naming a function (and not a built-in
          operator).  Required for 'UseMethod'.

  object: for 'UseMethod': an object whose class will determine the
          method to be dispatched.  Defaults to the first argument of
          the enclosing function.

     ...: further arguments to be passed to the next method.

_D_e_t_a_i_l_s:

     An R "object" is a data object which has a 'class' attribute. A
     class attribute is a character vector giving the names of the
     classes which the object "inherits" from. If the object does not
     have a class attribute, it has an implicit class.  Matrices and
     arrays have class '"matrix"' or'"array"' followed by the class of
     the underlying vector. Most vectors have class the result of
     'mode(x)', except that integer vectors have class 'c("integer",
     "numeric")' and real vectors have class 'c("double", "numeric")'.

     When a function calling 'UseMethod("fun")' is applied to an object
     with class attribute 'c("first", "second")', the system searches
     for a function called 'fun.first' and, if it finds it, applies it
     to the object.  If no such function is found a function called
     'fun.second' is tried.  If no class name produces a suitable
     function, the function 'fun.default' is used, if it exists, or an
     error results.  [Prior to R 2.4.0, any object of the name is
     searched for, but only if a function is found is it used.]

     Function 'methods' can be used to find out about the methods for a
     particular generic function or class.

     Now for some obscure details that need to appear somewhere.  These
     comments will be slightly different than those in Chambers(1992).
     (See also the draft 'R Language Definition'.) 'UseMethod' creates
     a "new" function call with arguments matched as they came in to
     the generic.  Any local variables defined before the call to
     'UseMethod' are retained (unlike S).  Any statements after the
     call to 'UseMethod' will not be evaluated as 'UseMethod' does not
     return.  'UseMethod' can be called with more than two arguments: a
     warning will be given and additional arguments ignored.  (They are
     not completely ignored in S.)  If it is called with just one
     argument, the class of the first argument of the enclosing
     function is used as 'object': unlike S this is the first actual
     argument passed and not the current value of the object of that
     name.

     'UseMethod' is a primitive function so positional matching is used
     and names of supplied arguments are ignored.

     'NextMethod' invokes the next method (determined by the class
     vector, either of the object supplied to 'UseMethod', or of the
     first argument to the function containing 'NextMethod' if a method
     was invoked directly).  Normally 'NextMethod' is used with only
     one argument, 'generic', but if further arguments are supplied
     these modify the call to the next method. It does this by creating
     a special call frame for that method.  If no new arguments are
     supplied, the arguments will be the same in number, order and name
     as those to the current method but their values will be promises
     to evaluate their name in the current method and environment.  Any
     named arguments matched to '...' are handled specially: they
     either replace existing arguments of the same name or are appended
     to the argument list.  They are passed on as the promise that was
     supplied as an argument to the current environment. (S does this
     differently!)  If they have been evaluated in the current (or a
     previous environment) they remain evaluated.  (This is a complex
     area, and subject to change: see the draft 'R Language
     Definition'.)

     'NextMethod' should not be called except in methods called by
     'UseMethod'. In particular it will not work inside anonymous
     calling functions (eg 'get("print.ts")(AirPassengers)').

     Name spaces can register methods for generic functions.  To
     support this, 'UseMethod' and 'NextMethod' search for methods in
     two places: first in the environment in which the generic function
     is called, and then in the registration data base for the
     environment in which the generic is defined (typically a name
     space). So methods for a generic function need to either be
     available in the environment of the call to the generic, or they
     must be registered. (It does not matter whether they are visible
     in the environment in which the generic is defined.)

_W_a_r_n_i_n_g:

     The internal code assumes that when 'UseMethod' is used that
     '"generic"' is the name of the enclosing function, and so any
     registered methods will be found in the name space defining the
     enclosing function.  This is not correct, and functions can be
     generic and dispatch on a different generic (an example is
     'coefficients'): this will only work if the other generic is
     defined in the same name space.  It also means that it is
     incorrect to use a primitive function or operator (e.g. '"$"') for
     'generic'.

     Prior to R 2.1.0 'UseMethod' accepted a call with no arguments and
     tried to deduce the generic from the context.  This was
     undocumented on the help page.  It is allowed but 'strongly
     discouraged' in S-PLUS, and is no longer allowed in R.

_N_o_t_e:

     This scheme is called _S3_ (S version 3).  For new projects, it is
     recommended to use the more flexible and robust _S4_ scheme
     provided in the 'methods' package. 

     The function '.isMethodsDispatchOn()' returns 'TRUE' if the S4
     method dispatch has been turned on in the evaluator. It is meant
     for R internal use only.

_R_e_f_e_r_e_n_c_e_s:

     Chambers, J. M. (1992) _Classes and methods: object-oriented
     programming in S._ Appendix A of _Statistical Models in S_ eds J.
     M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

     The draft 'R Language Definition'.

     'methods', 'class', 'getS3method'.

