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 despatch
     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. Required for
          'UseMethod'.

  object: 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 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)', expect that integer vectors have class 'c("integer",
     "numeric")' and real vectors have class 'c("double", "numeric")'.

     When a generic function '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, applied 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.

     Now for some obscure details that need to appear somewhere.  These
     comments will be slightly different than those in Appendix A of
     the White S Book. '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' invokes the next method (determined by the class). 
     It does this by creating a special call frame for that method. 
     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
     arguments matched to '...' are handled specially.  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.

     '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:

     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:

     'methods', 'class', 'getS3method'

