| % File src/library/base/man/UseMethod.Rd | |
| % Part of the R package, https://www.R-project.org | |
| % Copyright 1995-2022 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 | |
| \emph{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")}. | |
| Function \code{\link{.class2}(x)} (since \R 4.0.x) returns the full | |
| implicit (or explicit) class vector of \code{x}. | |
| When a function calling \code{UseMethod("fun")} is applied to an | |
| object with class vector \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}} incl \code{\link{.class2}()}; | |
| \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} |