groupGeneric              package:base              R Documentation

_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 functions can be defined with either S3 and S4
     methods (with different groups).  Methods are defined for the
     group of functions as a whole.

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

     When package 'methods' is attached there are objects visible with
     the names of the group generics: these functions should never be
     called directly (a suitable error message will result if they
     are).

_U_s_a_g_e:

     ## S3 methods have prototypes:
     Math(x, ...)
     Ops(e1, e2)
     Complex(z)
     Summary(x, ...)
     ## S3 method for class 'data.frame':
     Summary(..., na.rm)

     ## S4 methods have prototypes:
     Arith(e1, e2)
     Compare(e1, e2)
     Ops(e1, e2)
     Math(x)
     Math2(x, digits)
     Summary(x, ..., na.rm = FALSE)
     Complex(z)

_A_r_g_u_m_e_n_t_s:

x, z, e1, e2: objects.

  digits: number of digits to be used in 'round' or 'signif'.

     ...: further arguments passed to or from methods.

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

_S_3 _G_r_o_u_p _D_i_s_p_a_t_c_h_i_n_g:

     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 are also a 'ordered' method for
     'Ops', 'POSIXt' methods for 'Math' and 'Ops', 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'


        2.  Group '"Ops"':

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

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

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


        3.  Group '"Summary"':

           *  'all', 'any'

           *  'sum', 'prod'

           *  'min', 'max'

           *  'range'


        4.  Group 'Complex':

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

     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 '"Math"' group generic
     methods is not checked prior to dispatch. (Most have default
     methods expecting one argument, but three expect two.)

     All of the members of the 'Summary' group have a last argument
     'na.rm', so a 'Summary' group method can be written with argument
     list 'function(..., na.rm)', and methods should be prepared to
     handle a 'na.rm' argument.

_S_4 _G_r_o_u_p _D_i_s_p_a_t_c_h_i_n_g:

     When package 'methods' is attached (which it is by default),
     formal (S4) methods can be defined for groups.

     The functions belonging to the various groups are as follows:

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

     '_C_o_m_p_a_r_e' '"=="', '">"', '"<"', '"!="', '"<="', '">="'

     '_O_p_s' '"Arith"', '"Compare"'

     '_M_a_t_h' '"log"', '"sqrt"', '"log10"', '"cumprod"', '"abs"',
          '"acos"', '"acosh"', '"asin"', '"asinh"', '"atan"',
          '"atanh"', '"ceiling"', '"cos"', '"cosh"', '"cumsum"',
          '"exp"', '"floor"', '"gamma"', '"lgamma"', '"sin"', '"sinh"',
          '"tan"', '"tanh"', '"trunc"'

     '_M_a_t_h_2' '"round"', '"signif"'

     '_S_u_m_m_a_r_y' '"max"', '"min"', '"range"', '"prod"', '"sum"', '"any"',
          '"all"'

     '_C_o_m_p_l_e_x' '"Arg"', '"Conj"', '"Im"', '"Mod"', '"Re"'

     Functions with the group names exist in the 'methods' package but
     should not be called directly.

     All the functions in these groups (other than the group generics
     themselves) are basic functions in R.  They are not by default S4
     generic functions, and many of them are defined as primitives,
     meaning that they do not have formal arguments.  However, you can
     still define formal methods for them.  The effect of doing so is
     to create an S4 generic function with the appropriate arguments,
     in the environment where the method definition is to be stored. 
     It all works more or less as you might expect, admittedly via a
     bit of trickery in the background.

     Note: currently those members which are not primitive functions
     must have been converted to S4 generic functions (preferably
     _before_ setting an S4 group generic method) as it only sets
     methods for known S4 generics.  This can be done by a call to
     'setGeneric', for example 'setGeneric("round", group="Math2")'.

_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.

     Chambers, J. M. (1998) _Programming with Data._ Springer, pp.
     352-4.

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

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

     if(.isMethodsDispatchOn()) {# package "methods" is attached or loaded
       methods("Math")
       methods("Ops")
       methods("Summary")

       setClass("testComplex", representation(zz = "complex"))
       ## method for whole group "Complex"
       setMethod("Complex", "testComplex",
                 function(z) c("groupMethod", callGeneric(z@zz)))
       ## exception for Arg() :
       setMethod("Arg", "testComplex",
                 function(z) c("ArgMethod", Arg(z@zz)))
       z1 <- 1+2i
       z2 <- new("testComplex", zz = z1)
       stopifnot(identical(Mod(z2), c("groupMethod", Mod(z1))))
       stopifnot(identical(Arg(z2), c("ArgMethod", Arg(z1))))
     }

