\HeaderA{setMethod}{Create and Save a Method}{setMethod}
\aliasA{removeMethod}{setMethod}{removeMethod}
\keyword{programming}{setMethod}
\keyword{classes}{setMethod}
\keyword{classes}{setMethod}
\keyword{methods}{setMethod}
\begin{Description}\relax
Create and save a formal method for a given function and list of classes.
\end{Description}
\begin{Usage}
\begin{verbatim}
setMethod(f, signature=character(), definition,
          where = topenv(parent.frame()),
          valueClass = NULL, sealed = FALSE)

removeMethod(f, signature, where)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{f}] The character-string name of the generic function. 
\item[\code{signature}] A match of formal argument names for \code{f} with
the character-string names of corresponding classes.  This
argument can also just be the vector of class names, in which case
the first name corresponds to the first formal argument, the
next to the second formal argument, etc.
\item[\code{definition}] A function definition, which will become the method
called when the arguments in a call to \code{f} match the
classes in \code{signature}, directly or through inheritance. 
\item[\code{where}] the database in which to store the definition of the
method; 

For \code{removeMethod}, the default is the location of the (first)
instance of the method for this signature.
\item[\code{valueClass}] If supplied, this argument asserts that the
method will return a value of this class.  (At present this
argument is stored but not explicitly used.) 
\item[\code{sealed}] If \code{TRUE}, the method so defined cannot be
redefined by another call to \code{setMethod} (although it can
be removed and then re-assigned).  Note that this argument is an
extension to the definition of \code{setMethod} in the reference.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
R methods for a particular generic function are stored in an object
of class \code{\LinkA{MethodsList}{MethodsList}}.  The effect of calling
\code{setMethod} is to store \code{definition}  in a \code{MethodsList}
object on database \code{where}.   If \code{f} doesn't
exist as a generic function, but there is an ordinary function of
the same name and the same formal arguments, a new generic function
is created, and the previous non-generic version of \code{f} becomes
the default method.  This is equivalent to the programmer calling
\code{\LinkA{setGeneric}{setGeneric}} for the same function; it's better practice
to do the call explicitly, since it shows that you intend to turn
\code{f} into a generic function.

Methods are stored in a hierarchical structure:  see
\LinkA{Methods}{Methods} for how the objects are used to select a method, and
\code{\LinkA{MethodsList}{MethodsList}} for functions that manipulate the objects.

The class
names in the signature can be any formal class, plus predefined basic
classes such as \code{"numeric"}, \code{"character"}, and
\code{"matrix"}.  Two additional special class names can appear:
\code{"ANY"}, meaning that this argument can have any class at all;
and \code{"missing"}, meaning that this argument \emph{must not}
appear in the call in order to match this signature.  Don't confuse
these two:  if an argument isn't mentioned in a signature, it
corresponds implicitly to class \code{"ANY"}, not to
\code{"missing"}.  See the example below.  Old-style (\dQuote{S3})
classes can also be used, if you need compatibility with these, but
you should definitely declare these classes by calling
\code{\LinkA{setOldClass}{setOldClass}} if you want S3-style inheritance to work.


While \code{f} can correspond to methods defined on several packages
or environments, the underlying model is that these together make up
the definition for a single generic function.  When R proceeds to
select and evaluate methods for \code{f}, the methods on the current
search list are merged to form a single generic function and
associated methods list.  When \code{f}
is called and a method is \dQuote{dispatched}, the evaluator matches the
classes of the actual arguments to the signatures of the available
methods.  When a match is found, the body of the corresponding
method is evaluated, but without rematching the arguments to
\code{f}.   Aside from not rematching the arguments, the computation
proceeds as if the call had been to the method.  In particular, the
lexical scope of the method is used.

Method definitions can
have default expressions for arguments.  If those arguments are then
missing in the call to the generic function, the default expression
in the method is used.  If the method definition has no default for
the argument, then the expression (if any) supplied in the definition of the
generic function itself is used.  But note that this expression will
be evaluated in the environment defined by the method.

It is possible to have some differences between the
formal arguments to a method supplied to \code{setMethod} and those
of the generic. Roughly, if the generic has \dots as one of its
arguments, then the method may have extra formal arguments, which
will be matched from the arguments matching \dots in the call to
\code{f}.  (What actually happens is that a local function is
created inside the method, with its formal arguments, and the method
is re-defined to call that local function.)

Method dispatch tries to match the class of the actual arguments in a
call to the available methods collected for \code{f}.  Roughly, for
each formal argument in turn, we look for the best match (the exact
same class or the nearest element in the value of
\code{\LinkA{extends}{extends}} for that class) for which there is any
possible method matching the remaining arguments.  See
\LinkA{Methods}{Methods} for more details.
\end{Details}
\begin{Value}
These functions exist for their side-effect, in setting or removing a
method in the object defining methods for the specified generic.

The value returned by \code{removeMethod} is \code{TRUE} if a method
was found to be removed.
\end{Value}
\begin{References}\relax
The R package \pkg{methods} implements, with a few exceptions, the
programming interface for classes and methods in the book
\emph{Programming with Data} (John M. Chambers, Springer, 1998), in
particular sections 1.6, 2.7, 2.8, and chapters 7 and 8.

While the programming interface for the \pkg{methods} package follows
the reference, the R software is an original implementation, so
details in the reference that reflect the S4 implementation may appear
differently in R.  Also, there are extensions to the programming
interface developed more recently than the reference.  For a
discussion of details and ongoing development, see the web page
\url{http://developer.r-project.org/methodsPackage.html} and the
pointers from that page.
\end{References}
\begin{SeeAlso}\relax
\LinkA{Methods}{Methods}, \code{\LinkA{MethodsList}{MethodsList}} for details of the
implementation
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}


## methods for plotting track objects (see the example for setClass)
##
## First, with only one object as argument:
setMethod("plot", signature(x="track", y="missing"),
  function(x,  y, ...) plot(slot(x, "x"), slot(x, "y"), ...)
)
## Second, plot the data from the track on the y-axis against anything
## as the x data.
setMethod("plot", signature(y = "track"),
 function(x, y, ...) plot(x, slot(y, "y"), ...)
)
## and similarly with the track on the x-axis (using the short form of
## specification for signatures)
setMethod("plot", "track",
 function(x, y, ...) plot(slot(x, "y"), y,  ...)
)
t1 <- new("track", x=1:20, y=(1:20)^2)
tc1 <- new("trackCurve", t1)
slot(tc1, "smooth") <- smooth.spline(slot(tc1, "x"), slot(tc1, "y"))$y #$
plot(t1)
plot(qnorm(ppoints(20)), t1)
## An example of inherited methods, and of conforming method arguments
## (note the dotCurve argument in the method, which will be pulled out
## of ... in the generic.
setMethod("plot", c("trackCurve", "missing"),
function(x, y, dotCurve = FALSE, ...) {
  plot(as(x, "track"))
  if(length(slot(x, "smooth") > 0))
    lines(slot(x, "x"), slot(x, "smooth"),
         lty = if(dotCurve) 2 else 1)
  }
)
## the plot of tc1 alone has an added curve; other uses of tc1
## are treated as if it were a "track" object.
plot(tc1, dotCurve = TRUE)
plot(qnorm(ppoints(20)), tc1)

## defining methods for a special function.
## Although "[" and "length" are not ordinary functions
## methods can be defined for them.
setMethod("[", "track",
  function(x, i, j, ..., drop) {
    x@x <- x@x[i]; x@y <- x@y[i]
    x
  })
plot(t1[1:15])

setMethod("length", "track", function(x)length(x@y))
length(t1)

## methods can be defined for missing arguments as well
setGeneric("summary") ## make the function into a generic

## A method for summary()
## The method definition can include the arguments, but
## if they're omitted, class "missing" is assumed.

setMethod("summary", "missing", function() "<No Object>")


\end{ExampleCode}
\end{Examples}

