S3 Group Generic Functions

Description

Group generic methods can be defined for four pre-specified groups offunctions,Math,Ops,Summary andComplex.(There are no objects of these names in baseR, but there are in themethods package.)

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

Usage

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

Arguments

Details

There are fourgroups for which S3 methods can be written,namely the"Math","Ops","Summary" and"Complex" groups. These are notR objects in baseR, butmethods can be supplied for them and baseR containsfactor,data.frame anddifftime methods for the first three groups. (There isalso aordered method forOps,POSIXt andDate methods forMathandOps,package_version methods forOpsandSummary, as well as ats method forOps in packagestats.)

1. Group"Math":

   • abs,sign,sqrt,
     floor,ceiling,trunc,
     round,signif

   • exp,log,expm1,log1p,
     cos,sin,tan,
     cospi,sinpi,tanpi,
     acos,asin,atan

     cosh,sinh,tanh,
     acosh,asinh,atanh

   • lgamma,gamma,digamma,trigamma

   • cumsum,cumprod,cummax,cummin

   Members of this group dispatch onx. Most members acceptonly one argument, but memberslog,round andsignif accept one or two arguments, andtrunc acceptsone or more.

2. Group"Ops":

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

   • "&","|","!"

   • "==","!=","<","<=",">=",">"

   This group contains both binary and unary operators (+,- and!): when a unary operator is encountered theOps method is called with one argument ande2 ismissing.

   The classes of both arguments are considered in dispatching anymember of this group. For each argument its vector of classes isexamined to see if there is a matching specific (preferred) orOps method. If a method is found for just one argument orthe 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 foundfor either argument the internal method is used.

   Note that thedata.frame methods for the comparison("Compare":==,<, ...) and logic("Logic":&| and!) operators return alogicalmatrix instead of a data frame, forconvenience and back compatibility.

   If the members of this group are called as functions, any argumentnames 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.

   Note that thedata.frame methods for the"Summary" and"Math" groups require “numeric-alike”columnsx, i.e., fulfilling

         is.numeric(x) || is.logical(x) || is.complex(x)

4. Group"Complex":

   • Arg,Conj,Im,Mod,Re

   Members of this group dispatch onz.

Note that a method will be used for one of these groups or one of itsmembersonly if it corresponds to a"class" attribute,as the internal code dispatches onoldClass and not onclass. 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.

Technical Details

These functions are all primitive and internal generic.

The details of method dispatch and variables such as.Genericare discussed in the help forUseMethod. There are afew small differences:

• For the operators of groupOps, the object.Method is a length-two character vector with elements themethods selected for the left and right arguments respectively. (Ifno method was selected, the corresponding element is"".)

• Object.Group records the group used for dispatch (ifa specific method is used this is"").

Note

Packagemethods does contain objects with these names, which ithas re-used in confusing similar (but different) ways. See the helpfor that package.

References

Appendix A,Classes and Methods of
Chambers, J. M. and Hastie, T. J. eds (1992)Statistical Models in S.Wadsworth & Brooks/Cole.

See Also

methods for methods of non-internal generic functions.

S4groupGeneric for group generics for S4 methods.

Examples

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