% File src/library/methods/man/Methods_for_S3.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2016 R Core Team
% Distributed under GPL 2 or later
\name{Methods_for_S3}
\alias{Methods_for_S3}
\title{Methods For S3 and S4 Dispatch}

\description{

The S3 and S4 software in \R are two generations implementing
functional object-oriented programming.
S3 is the original, simpler for initial programming but less general,
less formal and less open to validation.
The S4 formal methods and classes provide these features but require
more programming.

In modern \R, the two versions attempt to work together.  This
documentation outlines how to write methods for both systems by
defining an S4 method for a function that dispatches S3 methods.

The systems can also be combined by using an S3 class with S4 method
dispatch or in S4 class definitions.  See \code{\link{setOldClass}}.

}
\section{S3 Method Dispatch}{

The \R evaluator will \sQuote{dispatch} a method from a function call
either when the body of the function calls the special primitive
\code{\link{UseMethod}} or when the call is to one of the builtin
primitives such as the \code{math} functions or the binary operators.


S3 method dispatch looks at the class of the first
argument or the class of either
argument in a call to one of the primitive binary operators.
In pure S3 situations, \sQuote{class} in this context means the class
attribute or the implied class for a basic data type such as
\code{"numeric"}.
The first S3 method that matches a name in the class is called and the
value of that call is the value of the original function call.
For details, see \link{S3Methods}.

In modern \R, a function \code{meth} in a package is registered as an S3 method
for function \code{fun} and class \code{Class} by
including in the package's \code{NAMESPACE} file the directive

\code{S3method(fun, Class, meth)}

By default (and traditionally), the third argument is taken to be the
function \code{fun.Class}; that is,
the name of the
generic function, followed by \code{"."}, followed by the name of the
class.

As with S4 methods, a method that has been registered will be added to
a table of methods for this function when the corresponding package is
loaded into the session.
Older versions of \R, copying the mechanism in S, looked for the
method in the current search list, but packages should now always
register S3 methods rather than requiring the package to be attached.
}

\section{Methods for S4 Classes}{

Two possible mechanisms for implementing a method  corresponding to an
S4 class, there are two possibilities are to register it as an S3 method with the
S4 class name or to define and set an S4 method, which will have the
side effect of creating an S4 generic version of this function.

For most situations either works, but
the recommended approach is to do both: register the S3 method and supply the
identical function as the definition of the S4 method.
This ensures that the proposed method will be dispatched for any
applicable call to the function.

As an example, suppose an S4 class \code{"uncased"} is defined,
extending \code{"character"} and intending to ignore upper- and
lower-case.
The base function \code{\link{unique}} dispatches S3 methods.
To define the class and a method for this function:

\code{setClass("uncased", contains = "character")}

\code{unique.uncased <- function(x, incomparables = FALSE, ...)
  nextMethod(tolower(x))}

\code{setMethod("unique", "uncased", unique.uncased)}

In addition, the \code{NAMESPACE} for the package should contain:

\code{S3method(unique, uncased)}

\code{exportMethods(unique)}

The result is to define identical S3 and S4 methods and ensure that all
calls to \code{unique} will dispatch that method when appropriate.
}

\section{Details}{

The reasons for defining both S3 and S4 methods are as follows:
\enumerate{
  \item An S4 method alone will not be seen if the S3 generic function
    is called directly. This will be the case, for example, if some
    function calls \code{unique()} from a package that does not make
    that function  an S4 generic.

    However, primitive functions and operators
    are exceptions:  The internal C code will look for S4 methods
    if and only if the object is an S4 object.  S4 method dispatch
    would be used to dispatch any binary operator calls where either
    of the operands was an S4 object, for example.

  \item An S3 method alone will not be called if there is \emph{any}
    eligible non-default S4 method.

    So if a package defined an S3
    method for \code{unique} for an S4 class but another package
    defined an S4 method for a superclass of that class, the
    superclass method would be chosen, probably not what was
    intended.
}

S4 and S3 method selection are designed to follow compatible rules of
inheritance, as far as possible.
S3 classes can be used for any S4 method selection, provided that the
S3 classes have been registered by a call to
\code{\link{setOldClass}}, with that call specifying the correct S3
inheritance pattern.
S4 classes can be used for any S3 method selection; when an S4 object
is detected, S3 method selection uses the contents of
\code{\link{extends}(class(x))} as the equivalent of the S3
inheritance (the inheritance is cached after the first call).


For the details of S4 and S3
dispatch see \link{Methods_Details} and \link{S3Methods}.

}

\references{
 Chambers, John M. (2016)
 \emph{Extending R},
  Chapman & Hall.
(Chapters 9 and 10.)
}