groupGeneric              package:base              R Documentation

_S_3 _G_r_o_u_p _G_e_n_e_r_i_c _F_u_n_c_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Group generic methods can be defined for four pre-specified groups
     of functions, 'Math', 'Ops', 'Summary' and 'Complex'. (There are
     no objects of these names in base R, but there are in the
     'methods' package.)

     A method defined for an individual member of the group takes
     precedence over a method defined for the group as a whole.

_U_s_a_g_e:

     ## S3 methods for group generics have prototypes:
     Math(x, ...)
     Ops(e1, e2)
     Complex(z)
     Summary(..., na.rm = FALSE)

_A_r_g_u_m_e_n_t_s:

x, z, e1, e2: objects.

     ...: further arguments passed to methods.

   na.rm: logical: should missing values be removed?

_D_e_t_a_i_l_s:

     There are four _groups_ for which S3 methods can be written,
     namely the '"Math"', '"Ops"', '"Summary"' and '"Complex"' groups. 
     These are not R objects, but methods can be supplied for them and
     base R contains 'factor', 'data.frame' and 'difftime' methods for
     the first three groups.  (There is also a 'ordered' method for
     'Ops', 'POSIXt' and 'Date' methods for 'Math' and 'Ops',
     'package_version' methods for 'Ops' and 'Summary', as well as a
     'ts' method for 'Ops' in package 'stats'.)

        1.  Group '"Math"':

           *  'abs', 'sign', 'sqrt', 
               'floor', 'ceiling', 'trunc',
               'round', 'signif'

           *  'exp', 'log', 
               'cos', 'sin', 'tan',
               'acos', 'asin', 'atan'

              'cosh', 'sinh', 'tanh',
               'acosh', 'asinh', 'atanh'

           *  'lgamma', 'gamma', 'gammaCody',
               'digamma', 'trigamma'

           *  'cumsum', 'cumprod', 'cummax', 'cummin'

        Members of this group dispatch on 'x'.  Not all members will
        accept more than one argument: most members have default
        methods expecting one argument.  (Specifically, 'atan' and the
        gamma functions accept only one argument and 'log', 'round' and
        'signif' accept one or two.)

        2.  Group '"Ops"':

           *  '"+"', '"-"', '"*"', '"/"', '"^"', '"%%"', '"%/%"'

           *  '"&"', '"|"', '"!"'

           *  '"=="', '"!="', '"<"', '"<="', '">="', '">"'

        This group contains both binary and unary operators ('+', '-'
        and '!'): when a unary operator is encountered the 'Ops' method
        is called with one argument and 'e2' is missing.

        The classes of both arguments are considered in dispatching any
        member of this group.  For each argument its vector of classes
        is examined to see if there is a matching specific (preferred)
        or 'Ops' method.  If a method is found for just one argument or
        the same method is found for both, it is used. If different
        methods are found, there is a warning about 'incompatible
        methods': in that case or if no method is found for either
        argument the internal method is used.

        3.  Group '"Summary"':

           *  'all', 'any'

           *  'sum', 'prod'

           *  'min', 'max'

           *  'range'

        Members of this group dispatch on the first argument supplied.

        4.  Group '"Complex"':

           *  'Arg', 'Conj', 'Im', 'Mod', 'Re'

        Members of this group dispatch on 'z'.

     Note that a method will used for either one of these groups or one
     of its members _only_ if it corresponds to a '"class"' attribute,
     as the internal code dispatches on 'oldClass' and not on 'class'. 
     This is for efficiency: having to dispatch on, say, 'Ops.integer'
     would be too slow.

     The number of arguments supplied for primitive members of the
     '"Math"' group generic methods is not checked prior to dispatch.

     There is no lazy evaluation of arguments for group-generic
     functions.

_T_e_c_h_n_i_c_a_l _D_e_t_a_i_l_s:

     The details of method dispatch and variables such as '.Generic'
     are discussed in the help for 'UseMethod'.  There are a few small
     differences:

        *  For the operators of group 'Ops', the object '.Method' is a
           length-two character vector with elements the methods
           selected for the left and right arguments respectively.  (If
           no method was selected, the corresponding element is '""'.)

        *  Object '.Group' records the group used for dispatch (if a
           specific method is used this is '""').

_R_e_f_e_r_e_n_c_e_s:

     Appendix A, _Classes and Methods_ of
      Chambers, J. M.  and Hastie, T. J. eds (1992) _Statistical Models
     in S._ Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

     'methods' for methods of non-Internal generic functions.

     S4groupGeneric for group generics for S4 methods.

_E_x_a_m_p_l_e_s:

     d.fr <- data.frame(x=1:9, y=rnorm(9))
     class(1 + d.fr) == "data.frame" ##-- add to d.f. ...

     methods("Math")
     methods("Ops")
     methods("Summary")
     methods("Complex")  # none in base R

