S4groupGeneric            package:methods            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:

     Methods can be defined  for _group generic functions_.  Each group
     generic function has a number of _member_ generic functions
     associated with it.

     Methods  defined for a group generic function cause the same
     method to be defined for each member of the group, but a method
     explicitly defined for a  member of the group takes precedence
     over a method defined, with the same signature, for the group
     generic.

     The functions shown in this documentation page all reside in the
     'methods' package, but the mechanism is available to any
     programmer, by calling 'setGroupGeneric'.

_U_s_a_g_e:

     ## S4 group generics:
     Arith(e1, e2)
     Compare(e1, e2)
     Ops(e1, e2)
     Logic(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?

_D_e_t_a_i_l_s:

     Methods can be defined for the group generic functions by calls to
     'setMethod' in the usual way. Note that the group generic
     functions should never be called directly - a suitable error
     message will result if they are.  When metadata for a group
     generic is loaded, the methods defined become methods for the
     members of the group, but only if no method has been specified
     directly for the member function for the same signature. The
     effect is that group generic definitions are selected before
     inherited methods but after directly specified methods.  For more
     on method selection, see 'Methods'.

     There are also S3 groups 'Math', 'Ops', 'Summary' and 'Complex',
     see '?S3groupGeneric', with no corresponding R objects, but these
     are irrelevant for S4 group generic functions.

     The members of the group defined by a particular generic can be
     obtained by calling 'getGroupMembers'. For the group generic
     functions currently defined in this package the members are as
     follows:

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

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

     '_L_o_g_i_c' '"&"', '"|"'.

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

     '_M_a_t_h' '"abs"', '"sign"', '"sqrt"', '"ceiling"', '"floor"',
          '"trunc"', '"cummax"', '"cummin"', '"cumprod"', '"cumsum"',
          '"log"', '"log10"', '"log2"', '"log1p"', '"acos"', '"acosh"',
          '"asin"', '"asinh"', '"atan"', '"atanh"', '"exp"', '"expm1"',
          '"cos"', '"cosh"', '"sin"', '"sinh"', '"tan"', '"tanh"',
          '"gamma"', '"lgamma"', '"digamma"', '"trigamma"'

     '_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"'

     Note that 'Ops' merely consists of three sub groups.

     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. 
     However, you can still define formal methods for them, both
     individually and via the group generics.  It all works more or
     less as you might expect, admittedly via a bit of trickery in the
     background. See Methods for details.

     Note that two members of the 'Math' group, 'log' and 'trunc', have
     ... as an extra formal argument. Since methods for 'Math' will
     have only one formal argument, you must set a specific method for
     these functions in order to call them with the extra argument(s).

     For further details about group generic functions see section 10.5
     of _Software for Data Analysis_.

_R_e_f_e_r_e_n_c_e_s:

     Chambers, John M. (2008) _Software for Data Analysis: Programming
     with R_ Springer.  (For the R version.)

     Chambers, John M. (1998) _Programming with Data_ Springer (For the
     original S4 version).

_S_e_e _A_l_s_o:

     The function 'callGeneric' is nearly always relevant when writing
     a method for a group generic.  See the examples below and in
     section 10.5 of _Software for Data Analysis_.

     See S3groupGeneric for S3 group generics.

_E_x_a_m_p_l_e_s:

     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))))