S4groupGeneric            package:methods            R Documentation

S4 Group Generic Functions

Description:

     Methods can be defined for groups of functions known as _group
     generic functions_.  These exist in both S3 (see S3groupGeneric)
     and S4 flavours, 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).

Usage:

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

Arguments:

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?

Details:

     When package 'methods' is attached (which it is by default),
     formal (S4) methods can be defined for the group generic functions
     (which are R objects which should never be called directly - a
     suitable error message will result if they are).  There are also
     S3 groups 'Math', 'Ops', 'Summary' and 'Complex', see
     '?S3groupGeneric', with no corresponding R objects.

     The functions belonging to the various groups are as follows:

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

     'Compare' '"=="', '">"', '"<"', '"!="', '"<="', '">="'

     'Logic' '"&"', '"|"', but *not* '"!"' since that has only one
          argument.  Note that this is contrary to Chambers(1998), on
          purpose.

     'Ops' '"Arith"', '"Compare"', '"Logic"'

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

     'Math2' '"round"', '"signif"'

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

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

     Note that 'Ops' merely consists of three sub groups. 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 that two members of the 'Math' group, 'log' and 'trunc', have
     more than one argument: S4 group dispatch will always pass only
     one argument to the method so if you want to handle 'base' in
     'log', set a specific method as well.

References:

     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.

See Also:

     S3groupGeneric for S3 group generics.

Examples:

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

