| % File src/library/base/man/UseMethod.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2014 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{UseMethod} |
| \title{Class Methods} |
| \alias{UseMethod} |
| \alias{NextMethod} |
| \alias{S3Methods} |
| \alias{.Method} |
| \alias{.Generic} |
| \alias{.Class} |
| \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(es) of the first argument to the generic function or of |
| the object supplied as an argument to \code{UseMethod} or \code{NextMethod}. |
| } |
| \usage{ |
| UseMethod(generic, object) |
| |
| NextMethod(generic = NULL, object = NULL, \dots) |
| } |
| \arguments{ |
| \item{generic}{a character string naming a function (and not a |
| built-in operator). Required for \code{UseMethod}.} |
| \item{object}{for \code{UseMethod}: an object whose class will |
| determine the method to be dispatched. Defaults to the first |
| argument of the enclosing function.} |
| \item{\dots}{further arguments to be passed to the next method.} |
| } |
| \details{ |
| An \R object is a data object which has a \code{class} |
| attribute (and this can be tested by \code{\link{is.object}}). |
| A class attribute is a character vector giving the names of |
| the classes from which the object \emph{inherits}. |
| If the object does not have a class attribute, it has an implicit |
| class. Matrices and arrays have class \code{"matrix"} |
| or\code{"array"} followed by the class of the underlying vector. |
| Most vectors have class the result of \code{\link{mode}(x)}, except |
| that integer vectors have class \code{c("integer", "numeric")} and |
| real vectors have class \code{c("double", "numeric")}. |
| |
| When a function calling \code{UseMethod("fun")} is applied to an |
| object with class attribute \code{c("first", "second")}, the system |
| searches for a function called \code{fun.first} and, if it finds it, |
| applies it to the object. If no such function is found a function |
| called \code{fun.second} is tried. If no class name produces a |
| suitable function, the function \code{fun.default} is used, if it |
| exists, or an error results. |
| |
| Function \code{\link{methods}} can be used to find out about the |
| methods for a particular generic function or class. |
| |
| \code{UseMethod} is a primitive function but uses standard argument |
| matching. It is not the only means of dispatch of methods, for there |
| are \link{internal generic} and \link{group generic} functions. |
| \code{UseMethod} currently dispatches on the implicit class even for |
| arguments that are not objects, but the other means of dispatch do |
| not. |
| |
| \code{NextMethod} invokes the next method (determined by the |
| class vector, either of the object supplied to the generic, or of |
| the first argument to the function containing \code{NextMethod} if a |
| method was invoked directly). Normally \code{NextMethod} is used with |
| only one argument, \code{generic}, but if further arguments are |
| supplied these modify the call to the next method. |
| |
| \code{NextMethod} should not be called except in methods called by |
| \code{UseMethod} or from internal generics (see |
| \link{InternalGenerics}). In particular it will not work inside |
| anonymous calling functions (e.g., \code{get("print.ts")(AirPassengers)}). |
| |
| Namespaces can register methods for generic functions. To support |
| this, \code{UseMethod} and \code{NextMethod} search for methods in |
| two places: in the environment in which the generic function |
| is called, and in the registration data base for the |
| environment in which the generic is defined (typically a namespace). |
| So methods for a generic function need to 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.) As from \R 3.5.0, the registration |
| data base is searched after the top level environment (see |
| \code{\link{topenv}}) of the calling environment (but before the |
| parents of the top level environment). |
| } |
| \section{Technical Details}{ |
| Now for some obscure details that need to appear somewhere. These |
| comments will be slightly different than those in Chambers(1992). |
| (See also the draft \sQuote{R Language Definition}.) |
| \code{UseMethod} creates a new function call with |
| arguments matched as they came in to the generic. Any local variables |
| defined before the call to \code{UseMethod} are retained (unlike S). Any |
| statements after the call to \code{UseMethod} will not be evaluated as |
| \code{UseMethod} does not return. \code{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 \code{object}: unlike S this is the first |
| actual argument passed and not the current value of the object of that |
| name. |
| |
| \code{NextMethod} works by creating a special call frame for the next |
| method. If no new arguments are supplied, 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 named arguments matched to \code{\dots} |
| are handled specially: they either replace existing arguments of the |
| same name or are appended to the argument list. 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. |
| (This is a complex area, and subject to change: see the draft |
| \sQuote{R Language Definition}.) |
| |
| The search for methods for \code{NextMethod} is slightly different |
| from that for \code{UseMethod}. Finding no \code{fun.default} is not |
| necessarily an error, as the search continues to the generic |
| itself. This is to pick up an \link{internal generic} like \code{[} |
| which has no separate default method, and succeeds only if the generic |
| is a \link{primitive} function or a wrapper for a |
| \code{\link{.Internal}} function of the same name. (When a primitive |
| is called as the default method, argument matching may not work as |
| described above due to the different semantics of primitives.) |
| |
| You will see objects such as \code{.Generic}, \code{.Method}, and |
| \code{.Class} used in methods. These are set in the environment |
| within which the method is evaluated by the dispatch mechanism, which |
| is as follows: |
| \enumerate{ |
| \item Find the context for the calling function (the generic): this |
| gives us the unevaluated arguments for the original call. |
| \item Evaluate the object (usually an argument) to be used for |
| dispatch, and find a method (possibly the default method) or throw |
| an error. |
| \item Create an environment for evaluating the method and insert |
| special variables (see below) into that environment. Also copy any |
| variables in the environment of the generic that are not formal (or |
| actual) arguments. |
| \item Fix up the argument list to be the arguments of the call |
| matched to the formals of the method. |
| } |
| \code{.Generic} is a length-one character vector naming the generic function. |
| |
| \code{.Method} is a character vector (normally of length one) naming |
| the method function. (For functions in the group generic |
| \code{\link[=S3groupGeneric]{Ops}} it is of length two.) |
| |
| \code{.Class} is a character vector of classes used to find the next |
| method. \code{NextMethod} adds an attribute \code{"previous"} to |
| \code{.Class} giving the \code{.Class} last used for dispatch, and |
| shifts \code{.Class} along to that used for dispatch. |
| |
| \code{.GenericCallEnv} and \code{.GenericDefEnv} are the environments |
| of the call to be generic and defining the generic respectively. (The |
| latter is used to find methods registered for the generic.) |
| |
| Note that \code{.Class} is set when the generic is called, and is |
| unchanged if the class of the dispatching argument is changed in a |
| method. It is possible to change the method that \code{NextMethod} |
| would dispatch by manipulating \code{.Class}, but \sQuote{this is not |
| recommended unless you understand the inheritance mechanism |
| thoroughly} (Chambers & Hastie, 1992, p.\sspace{}469). |
| } |
| \note{ |
| This scheme is called \emph{S3} (S version 3). For new projects, |
| it is recommended to use the more flexible and robust \emph{S4} scheme |
| provided in the \pkg{methods} package. |
| } |
| \seealso{ |
| The draft \sQuote{R Language Definition}. |
| |
| \code{\link{methods}}, \code{\link{class}}, |
| \code{\link{getS3method}}, \code{\link{is.object}}. |
| } |
| \references{ |
| Chambers, J. M. (1992) |
| \emph{Classes and methods: object-oriented programming in S.} |
| Appendix A of \emph{Statistical Models in S} |
| eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole. |
| } |
| \keyword{methods} |