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(es) of the first argument to the
     generic function or of 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 (and
     this can be tested by 'is.object'). 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.

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

     'UseMethod' is a primitive function so positional matching is used
     and names of supplied arguments are ignored.  It is not the only
     means of dispatch of methods, for there are internal generic and
     group generic functions.  'UseMethod' currently dispatches on the
     implicit class even for arguments that are not objects, but the
     other means of dispatch do not.

     'NextMethod' invokes the next method (determined by the class
     vector, either of the object supplied to the generic, 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.

     'NextMethod' should not be called except in methods called by
     'UseMethod' or from internal generics (see InternalGenerics).  In
     particular it will not work inside anonymous calling functions
     (e.g. '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 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.)

_T_e_c_h_n_i_c_a_l _D_e_t_a_i_l_s:

     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.

     'NextMethod' works by creating a special call frame for the next
     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'.)

     The search for methods for 'NextMethod' is slightly different from
     that for 'UseMethod'.   Finding no 'fun.default' is not
     necessarily an error, as the search continues to the generic
     itself. This is to pick up an internal generic like '[' which has
     no separate default method, and succeeds only if the generic is a
     primitive function or a wrapper for a '.Internal' function of the
     same name.  (When a primitive is called as the default method,
     argument matching may not work as described above due to the
     different semantics of primitives.)

     You will see objects such as '.Generic', '.Method', and '.Class'
     used in methods.  These are set in the environment within which
     the method is evaluated by the dispatch mechanism, which is as
     follows:

        1.  Find the context for the calling function (the generic):
           this gives us the unevaluated arguments for the original
           call.

        2.  Evaluate the object (usually an argument) to be used for
           dispatch, and find a method (possibly the default method) or
           throw an error.

        3.  Create an environment for evaluating the method and insert
           special variables (see below) into that environment.  Also
           copy any variables in the environment of the generic that
           are not formal (or actual) arguments.

        4.  Fix up the argument list to be the arguments of the call
           matched to the formals of the method.

     '.Generic' is a length-one character vector naming the generic
     function.

     '.Method' is a character vector (normally of length one) naming
     the method function.  (For functions in the group generic 'Ops' it
     is of length two.)

     '.Class' is a character vector of classes used to find the next
     method.  'NextMethod' adds an attribute '"previous"' to '.Class'
     giving the '.Class' last used for dispatch, and shifts '.Class'
     along to that used for dispatch.

     '.GenericCallEnv' and '.GenericDefEnv' are the environments of the
     call to be generic and defining the generic respectively.  (The
     latter is used to find methods registered for the generic.)

     Note that '.Class' is set when the generic is called, and is
     unchanged if the class of the dispatching argument is changed in a
     method.  It is possible to change the method that 'NextMethod'
     would dispatch by manipulating '.Class', but 'this is not
     recommended unless you understand the inheritance mechanism
     thoroughly' (Chambers & Hastie, 1992, p. 469).

_H_i_s_t_o_r_i_c_a_l _n_o_t_e:

     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.

_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', 'is.object'.

