UseMethod {base}R Documentation

Class Methods

Description

R possesses a simple generic function mechanism which can be used for an object-oriented style of programming. Method dispatch takes place based on the class of the first argument to the generic function or on the object supplied as an argument to UseMethod or NextMethod.

Usage

UseMethod(generic, object)
NextMethod(generic = NULL, object = NULL, ...)

Arguments

generic a character string naming a function. Required for UseMethod.
object an object whose class will determine the method to be dispatched. Defaults to the first argument of the enclosing function.
... further arguments to be passed to the method.

Details

An R “object” is a data object which has a class attribute. A class attribute is a character vector giving the names of the classes which the object “inherits” from. If the object does not have a class attribute, it has an implicit class. Matrices and arrays have class "matrix" or"array" followed by the class of the underlying vector. Most vectors have class the result of mode(x), except that integer vectors have class c("integer", "numeric") and real vectors have class c("double", "numeric").

When a generic function fun is applies to an object with class attribute c("first", "second"), the system searches for a function called fun.first and, if it finds it, applied it to the object. If no such function is found a function called fun.second is tried. If no class name produces a suitable function, the function fun.default is used, if it exists, or an error results.

Function methods can be used to find out about the methods for a particular generic function or class.

Now for some obscure details that need to appear somewhere. These comments will be slightly different than those in Appendix A of the White S Book. UseMethod creates a “new” function call with arguments matched as they came in to the generic. Any local variables defined before the call to UseMethod are retained (unlike S). Any statements after the call to UseMethod will not be evaluated as UseMethod does not return. UseMethod can be called with more than two arguments: a warning will be given and additional arguments ignored. (They are not completely ignored in S.) If it is called with just one argument, the class of the first argument of the enclosing function is used as object: unlike S this is the first actual argument passed and not the current value of the object of that name.

UseMethod is a primitive function so positional matching is used and names of supplied arguments are ignored.

NextMethod invokes the next method (determined by the class). It does this by creating a special call frame for that method. The arguments will be the same in number, order and name as those to the current method but their values will be promises to evaluate their name in the current method and environment. Any arguments matched to ... are handled specially. They are passed on as the promise that was supplied as an argument to the current environment. (S does this differently!) If they have been evaluated in the current (or a previous environment) they remain evaluated.

NextMethod should not be called except in methods called by UseMethod. In particular it will not work inside anonymous calling functions (eg get("print.ts")(AirPassengers)).

Name spaces can register methods for generic functions. To support this, UseMethod and NextMethod search for methods in two places: first in the environment in which the generic function is called, and then in the registration data base for the environment in which the generic is defined (typically a name space). So methods for a generic function need to either be available in the environment of the call to the generic, or they must be registered. It does not matter whether they are visible in the environment in which the generic is defined.

Warning

Prior to R 2.1.0 UseMethod accepted a call with no arguments and tried to deduce the generic from the context. This was undocumented on the help page. It is allowed but ‘strongly discouraged’ in S-PLUS, and is no longer allowed in R.

Note

This scheme is called S3 (S version 3). For new projects, it is recommended to use the more flexible and robust S4 scheme provided in the methods package.

The function .isMethodsDispatchOn() returns TRUE if the S4 method dispatch has been turned on in the evaluator. It is meant for R internal use only.

References

Chambers, J. M. (1992) Classes and methods: object-oriented programming in S. Appendix A of Statistical Models in S eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole.

See Also

methods, class, getS3method


[Package base version 2.2.1 Index]