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',  'expm1', 'log1p',
               'cos', 'sin', 'tan',
               'acos', 'asin', 'atan'

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

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

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

        Members of this group dispatch on 'x'.  Most members accept
        only one argument, but members 'log', 'round' and 'signif'
        accept one or two arguments, and 'trunc' accepts one or more.

        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.

        If the members of this group are called as functions, any
        argument names are removed to ensure that positional matching
        is always 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:

     These functions are all primitive and internal generic.

     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:

     require(utils)

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

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