src/library/methods/man/Methods_Details.Rd - R - Git at Google

 % File src/library/methods/man/Methods.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_Details}
 \alias{Methods_Details}
 \title{General Information on Methods}
 \description{
   This documentation covers some general topics on how methods
   work and how the \pkg{methods} package interacts with the rest of \R.  The
   information is usually not needed to get started with methods and
   classes, but may be helpful for moderately ambitious projects, or when
   something doesn't work as expected.

   For additional information  see documentation for
   the important steps: (\code{\link{setMethod}()},
   \code{\link{setClass}()} and \code{\link{setGeneric}()}). Also
   \code{\link{Methods_for_Nongenerics}} on defining formal methods for
   functions  that are not currently generic functions;
   \link{Methods_for_S3} for the relation to S3 classes and methods;
   \code{\link{Classes_Details}} for class definitions and
   Chapters 9 and 10 of the reference.
 }

 \section{How Methods Work}{
   A call to a generic function selects a method matching the actual
   arguments in the call. The body of the method is evaluated in the
   frame of the call to the generic function.
   A generic function is identified by its name and by the package to
   which it correspond.  Unlike ordinary functions, the generic has a
   slot that specifies its package.

   In an \R session, there is one version of each such generic,
   regardless of where the call to that generic originated, and
   the generic function has a table of all the methods currently
   available for it; that is, all the methods
   in packages currently loaded into the session.

   Methods are frequently defined for functions that are non-generic in
   their original package,.
   for example, for function \code{plot()} in
   package \pkg{graphics}.
   An identical version of the corresponding generic function may exist
   in several packages.  All methods will be dispatched consistently
   from the \R session.

   Each \R package with a call to \code{\link{setMethod}} in its source code
   will include  a methods metadata object for that generic.
   When the package is loaded into an \R session, the methods for each
   generic function are \emph{cached}, that is, added to the
   environment of the generic function.  This merged table of methods is used to
   dispatch or select methods from the generic, using class inheritance
   and possibly group generic functions (see
   \code{\link{GroupGenericFunctions}}) to find an applicable method.
   See the \dQuote{Method Selection and Dispatch} section below.
   The caching computations ensure that only one version of each
   generic function is visible globally; although different attached
   packages may contain a copy of the generic function, these behave
   identically with respect to method selection.

   In contrast, it is possible for the same function name to refer to
   more than one generic function, when these have different
   \code{package} slots.  In the latter case, \R considers the
   functions unrelated:  A generic function is defined by the
   combination of name and package.  See the \dQuote{Generic Functions}
   section below.

   The methods for a generic are stored according to the
   corresponding \code{signature} in the call to \code{\link{setMethod}}
  that defined  the method.  The signature associates one
   class name with each of a subset of the formal arguments to the
   generic function.  Which formal arguments are available, and the
   order in which they appear, are determined by the \code{"signature"}
   slot of the generic function itself.  By default, the signature of the
   generic consists of all the formal arguments except \dots, in the
   order they appear in the function definition.

   Trailing arguments in the signature of the generic will be \emph{inactive}  if no
   method has yet been specified that included those arguments in its signature.
   Inactive arguments are not needed or used in labeling the cached
   methods.  (The distinction does not change which methods are
   dispatched, but ignoring inactive arguments improves the
   efficiency of dispatch.)

   All arguments in the signature of the generic function will be evaluated when the
   function is called, rather than using lazy
   evaluation.  Therefore, it's important to \emph{exclude}
   from the signature any arguments that need to be dealt with
   symbolically (such as the \code{expr} argument to function
   \code{\link{with}}).  Note that only actual arguments are
   evaluated, not default expressions.
   A missing argument enters into the method selection as class
   \code{"missing"}.

   The cached methods are stored in an
   environment object.  The names used for assignment are a
   concatenation of the class names for the active arguments in the method signature.

 }
 \section{Method Selection: Details}{

 When a call to a generic function is evaluated, a method is selected corresponding
 to the classes of the actual arguments in the signature.
 First, the cached methods table is searched for an  exact match;
 that is, a method stored under the signature defined by
 the string value of \code{class(x)} for each non-missing
 argument, and \code{"missing"} for each missing argument.
 If no method is found directly for the actual arguments in a call to a
 generic function, an attempt is made to match the available methods to
 the arguments by using the superclass information about the actual
 classes.
 A method found by this search is cached
 in the generic function so that future calls with the same argument classes will
 not require repeating the search.  In any likely application, the
 search for inherited methods will be a negligible overhead.

 Each class definition may include a list of  one or more direct
 \emph{superclasses} of the new class.
 The simplest and most common specification is by the \code{contains=} argument in
 the  call to \code{\link{setClass}}.
 Each class named in this argument is a superclass of the new class.
 A class will also have as a direct superclass any class union to which
 it is a member.
 Class unions are created by
 a call to \code{\link{setClassUnion}}.
 Additional members can be added to the union by a simple call to
 \code{\link{setIs}}.
 Superclasses specified by either mechanism are the \emph{direct} superclasses.


 Inheritance specified in either of these forms is \emph{simple} in the
 sense that all the information needed for the superclass is asserted
 to be directly available from the object.
 \R inherited from S a more general form of inheritance in which
 inheritance may require some transformation or be conditional on a
 test.
 This more general form has not proved to be useful in general
 practical situations.   Since it also adds some computational costs
 non-simple inheritance is not recommended.  See \code{\link{setIs}}
 for the general version.

 The direct superclasses themselves may
 have  direct superclasses and
 similarly through further generations.  Putting all this information together produces
 the full list of superclasses for this class.
 The superclass list is included in the definition of the class that is
 cached during the \R session.
 The \emph{distance} between the two classes is defined to be the
 number of generations:
 \code{1} for direct superclasses (regardless of which mechanism
 defined them), then \code{2} for the direct superclasses of those
 classes, and so on.
 To see all the superclasses, with their distance, print the class
 definition by calling \code{\link{getClass}}.
 In addition, any class implicitly has class \code{"ANY"} as a superclass.  The
 distance to \code{"ANY"} is treated as larger than the distance to any
 actual class.
 The special class \code{"missing"} corresponding to missing arguments
 has only \code{"ANY"} as a superclass, while \code{"ANY"} has no
 superclasses.

 When a method is to be selected by inheritance, a search is made in
 the table for all methods corresponding to a combination of
 either the direct class or one of its superclasses, for each argument
 in the active signature.
 For an example, suppose there is only one argument in the signature and that the class of
 the corresponding object was \code{"dgeMatrix"} (from the recommended package
 \code{Matrix}).
 This class has (currently) three direct superclasses and through these
 additional superclasses at distances 2 through 4.
 A method that had been defined for any of these classes or for class
 \code{"ANY"} (the default method) would be eligible.
 Methods for the shortest difference are preferred.
 If there is only one best method in this sense, method selection is unambiguous.

 When there are multiple arguments in the signature, each argument will
 generate a similar  list of inherited classes.
 The possible matches are now all the combinations of classes from each
 argument (think of the function \code{outer} generating an array of
 all possible combinations).
 The search now finds all the methods matching any of this combination
 of classes.
 For each argument, the distance to the superclass defines which
 method(s) are preferred for that argument.
 A method is considered best for selection if it is among the best
 (i.e., has the least distance) for
 each argument.

 The end result is that zero, one or more methods may be \dQuote{best}.
 If one, this method is selected and cached in the table of methods.
 If there is more than one best match, the selection is ambiguous and a message is
 printed noting which method was selected (the first method
 lexicographically in the ordering) and what other methods could have
 been selected.
 Since the ambiguity is usually nothing the end user could control,
 this is not a warning.
 Package authors should examine their package for possible ambiguous
 inheritance by calling \code{\link{testInheritedMethods}}.

 Cached inherited selections are
 not themselves used in future inheritance searches, since that could result
 in invalid selections.
 If you want inheritance computations to be done again (for example,
 because a newly loaded package has a more direct method than one
 that has already been used in this session), call
 \code{\link{resetGeneric}}.  Because classes and methods involving
 them tend to come from the same package, the current implementation
 does not reset all generics every time a new package is loaded.

 Besides being initiated through calls to the generic function, method
 selection can be done explicitly by calling the function
 \code{\link{selectMethod}}.
 Note that some computations may use this function directly, with
 optional arguments.
 The prime example is the use of \code{\link{coerce}()} methods by
 function \code{\link{as}()}.
 There has been some confusion from comparing coerce methods to a call
 to \code{\link{selectMethod}} with other options.
 }

 \section{Method Evaluation: Details}{

 Once a method has been selected, the evaluator creates a new context
 in which a call to the method is evaluated.
 The context is initialized with the arguments from the call to the
 generic function.
 These arguments are not rematched.  All the arguments in the signature
 of the generic will have been evaluated (including any that are
 currently inactive); arguments that are not in the signature will obey
 the usual lazy evaluation rules of the language.
 If an argument was missing in the call, its default expression if any
 will \emph{not} have been evaluated, since method dispatch always uses
 class \code{missing} for such arguments.

 A call to a generic function therefore has two contexts:  one for the
 function and a second for the method.
 The argument objects will be copied to the second context, but not any
 local objects created in a nonstandard generic function.
 The other important distinction is that the parent
 (\dQuote{enclosing}) environment of the second context is the environment
 of the method as a function, so that all \R programming techniques
 using such environments apply to method definitions as ordinary functions.


 For further discussion of method selection and dispatch,  see the
 references in the sections indicated.

 }

 \section{Generic Functions}{
 In principle, a generic function could be any function that evaluates
 a call to \code{standardGeneric()}, the internal function that selects
 a method and evaluates a call to  the selected method.  In practice,
 generic functions are special objects that in addition to being from a
 subclass of class \code{"function"} also extend the class
 \code{\linkS4class{genericFunction}}.  Such objects have slots to define
 information needed to deal with their methods.  They also have
 specialized environments, containing the tables used in method
 selection.

 The slots \code{"generic"} and  \code{"package"} in the object are the
 character string names of the generic function itself and of the
 package from which the  function is defined.
 As with classes, generic functions are uniquely defined in \R by the
 combination of the two names.
 There can be generic functions of the same name associated with
 different packages (although inevitably keeping such functions cleanly
 distinguished is not always easy).
 On the other hand, \R will enforce that only one definition of a
 generic function can be associated with a particular combination of
 function and package name, in the current session or other active
 version of \R.

 Tables of methods for a particular generic function, in this sense,
 will often be spread over several other packages.
 The total set of methods for a given generic function may change
 during a session, as additional packages are loaded.
 Each table must be consistent in the signature assumed for the generic
 function.

 \R distinguishes \emph{standard} and \emph{nonstandard} generic
 functions, with the former having a function body that does nothing
 but dispatch a method.
 For the most part, the distinction is just one of simplicity:  knowing
 that a generic function only dispatches a method call allows some
 efficiencies and also removes some uncertainties.

 In most cases, the generic function is the visible function
 corresponding to that name, in the corresponding package.
 There are two exceptions, \emph{implicit} generic
 functions and the special computations required to deal with \R's
 \emph{primitive} functions.
 Packages can contain a table of implicit generic versions of functions
 in the package, if the package wishes to leave a function non-generic
 but to constrain what the function would be like if it were generic.
 Such implicit generic functions are created during the installation of
 the package, essentially by defining the generic function and
 possibly methods for it, and then reverting the function to its
 non-generic form. (See \link{implicitGeneric} for how this is done.)
 The mechanism is mainly used for functions in the older packages in
 \R, which may prefer to ignore S4 methods.
 Even in this case, the actual mechanism is only needed if something
 special has to be specified.
 All functions have a corresponding implicit generic version defined
 automatically (an implicit, implicit generic function one might say).
 This function is a standard generic with the same arguments as the
 non-generic function, with the non-generic version as the default (and only)
 method, and with the generic signature being all the formal arguments
 except \dots.

 The implicit generic mechanism is needed only to override some aspect
 of the default definition.
 One reason to do so would be to remove some arguments from the
 signature.
 Arguments that may need to be interpreted literally, or for which the
 lazy evaluation mechanism of the language is needed, must \emph{not}
 be included in the signature of the generic function, since all
 arguments in the signature will be evaluated in order to select a
 method.
 For example, the argument \code{expr} to the function
 \code{\link{with}} is treated literally and must therefore be excluded
 from the signature.

 One would also need to define an implicit generic if the existing
 non-generic function were not suitable as the default method.
 Perhaps the function only applies to some classes of objects, and the
 package designer prefers to have no general default method.
 In the other direction, the package designer might have some ideas
 about suitable methods for some classes, if the function were generic.
 With reasonably modern packages, the simple approach in all these
 cases is just to define the function as a generic.
 The implicit generic mechanism is mainly attractive for older packages
 that do not want to require the methods package to be available.

 Generic functions will also be defined but not obviously visible for
 functions implemented as \emph{primitive} functions in the base
 package.
 Primitive functions look like ordinary functions when printed but are
 in fact not function objects but objects of two types interpreted by
 the \R evaluator to call underlying C code directly.
 Since their entire justification is efficiency, \R refuses to hide
 primitives behind a generic function object.
 Methods may be defined for most primitives, and corresponding metadata
 objects will be created to store them.
 Calls to the primitive still go directly to the C code, which will
 sometimes check for applicable methods.
 The definition of \dQuote{sometimes} is that methods must have been
 detected for the function in some package loaded in the session and
 \code{isS4(x)} is \code{TRUE} for  the first argument (or for the
 second argument, in the case of binary operators).
 You can test whether methods have been detected by calling
 \code{\link{isGeneric}} for the relevant function and you can examine
 the generic function by calling \code{\link{getGeneric}}, whether or
 not methods have been detected.
 For more on generic functions, see the references and also section 2
 of the \emph{R Internals} document supplied with \R.

 }

 \section{Method Definitions}{
 All method definitions are stored as objects from the
 \code{\linkS4class{MethodDefinition}} class.
 Like the class of generic functions, this class extends ordinary \R
 functions with some additional slots: \code{"generic"}, containing the
 name and package of the generic function, and two signature slots,
 \code{"defined"} and \code{"target"}, the first being the signature supplied when
 the method was defined by a call to \code{\link{setMethod}}.
 The  \code{"target"} slot starts off equal to the \code{"defined"}
   slot.  When an inherited method is cached after being selected, as
   described above, a copy is made with the  appropriate \code{"target"}  signature.
   Output from \code{\link{showMethods}}, for example, includes both
   signatures.

   Method definitions are required to have the same formal arguments as
   the generic function, since the method dispatch mechanism does not
   rematch arguments, for reasons of both efficiency and consistency.
 }


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

  Chambers, John M. (2008)
  \emph{Software for Data Analysis: Programming with R}
   Springer. (Section 10.5 for some details.)
 }

 \seealso{
 For more specific information, see
   \code{\link{setGeneric}}, \code{\link{setMethod}}, and
   \code{\link{setClass}}.

 For the use of \dots in methods, see  \link{dotsMethods}.
 }
 \keyword{programming}
 \keyword{classes}
 \keyword{methods}
	% File src/library/methods/man/Methods.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_Details}
	\alias{Methods_Details}
	\title{General Information on Methods}
	\description{
	This documentation covers some general topics on how methods
	work and how the \pkg{methods} package interacts with the rest of \R. The
	information is usually not needed to get started with methods and
	classes, but may be helpful for moderately ambitious projects, or when
	something doesn't work as expected.

	For additional information see documentation for
	the important steps: (\code{\link{setMethod}()},
	\code{\link{setClass}()} and \code{\link{setGeneric}()}). Also
	\code{\link{Methods_for_Nongenerics}} on defining formal methods for
	functions that are not currently generic functions;
	\link{Methods_for_S3} for the relation to S3 classes and methods;
	\code{\link{Classes_Details}} for class definitions and
	Chapters 9 and 10 of the reference.
	}

	\section{How Methods Work}{
	A call to a generic function selects a method matching the actual
	arguments in the call. The body of the method is evaluated in the
	frame of the call to the generic function.
	A generic function is identified by its name and by the package to
	which it correspond. Unlike ordinary functions, the generic has a
	slot that specifies its package.

	In an \R session, there is one version of each such generic,
	regardless of where the call to that generic originated, and
	the generic function has a table of all the methods currently
	available for it; that is, all the methods
	in packages currently loaded into the session.

	Methods are frequently defined for functions that are non-generic in
	their original package,.
	for example, for function \code{plot()} in
	package \pkg{graphics}.
	An identical version of the corresponding generic function may exist
	in several packages. All methods will be dispatched consistently
	from the \R session.

	Each \R package with a call to \code{\link{setMethod}} in its source code
	will include a methods metadata object for that generic.
	When the package is loaded into an \R session, the methods for each
	generic function are \emph{cached}, that is, added to the
	environment of the generic function. This merged table of methods is used to
	dispatch or select methods from the generic, using class inheritance
	and possibly group generic functions (see
	\code{\link{GroupGenericFunctions}}) to find an applicable method.
	See the \dQuote{Method Selection and Dispatch} section below.
	The caching computations ensure that only one version of each
	generic function is visible globally; although different attached
	packages may contain a copy of the generic function, these behave
	identically with respect to method selection.

	In contrast, it is possible for the same function name to refer to
	more than one generic function, when these have different
	\code{package} slots. In the latter case, \R considers the
	functions unrelated: A generic function is defined by the
	combination of name and package. See the \dQuote{Generic Functions}
	section below.

	The methods for a generic are stored according to the
	corresponding \code{signature} in the call to \code{\link{setMethod}}
	that defined the method. The signature associates one
	class name with each of a subset of the formal arguments to the
	generic function. Which formal arguments are available, and the
	order in which they appear, are determined by the \code{"signature"}
	slot of the generic function itself. By default, the signature of the
	generic consists of all the formal arguments except \dots, in the
	order they appear in the function definition.

	Trailing arguments in the signature of the generic will be \emph{inactive} if no
	method has yet been specified that included those arguments in its signature.
	Inactive arguments are not needed or used in labeling the cached
	methods. (The distinction does not change which methods are
	dispatched, but ignoring inactive arguments improves the
	efficiency of dispatch.)

	All arguments in the signature of the generic function will be evaluated when the
	function is called, rather than using lazy
	evaluation. Therefore, it's important to \emph{exclude}
	from the signature any arguments that need to be dealt with
	symbolically (such as the \code{expr} argument to function
	\code{\link{with}}). Note that only actual arguments are
	evaluated, not default expressions.
	A missing argument enters into the method selection as class
	\code{"missing"}.

	The cached methods are stored in an
	environment object. The names used for assignment are a
	concatenation of the class names for the active arguments in the method signature.

	}
	\section{Method Selection: Details}{

	When a call to a generic function is evaluated, a method is selected corresponding
	to the classes of the actual arguments in the signature.
	First, the cached methods table is searched for an exact match;
	that is, a method stored under the signature defined by
	the string value of \code{class(x)} for each non-missing
	argument, and \code{"missing"} for each missing argument.
	If no method is found directly for the actual arguments in a call to a
	generic function, an attempt is made to match the available methods to
	the arguments by using the superclass information about the actual
	classes.
	A method found by this search is cached
	in the generic function so that future calls with the same argument classes will
	not require repeating the search. In any likely application, the
	search for inherited methods will be a negligible overhead.

	Each class definition may include a list of one or more direct
	\emph{superclasses} of the new class.
	The simplest and most common specification is by the \code{contains=} argument in
	the call to \code{\link{setClass}}.
	Each class named in this argument is a superclass of the new class.
	A class will also have as a direct superclass any class union to which
	it is a member.
	Class unions are created by
	a call to \code{\link{setClassUnion}}.
	Additional members can be added to the union by a simple call to
	\code{\link{setIs}}.
	Superclasses specified by either mechanism are the \emph{direct} superclasses.


	Inheritance specified in either of these forms is \emph{simple} in the
	sense that all the information needed for the superclass is asserted
	to be directly available from the object.
	\R inherited from S a more general form of inheritance in which
	inheritance may require some transformation or be conditional on a
	test.
	This more general form has not proved to be useful in general
	practical situations. Since it also adds some computational costs
	non-simple inheritance is not recommended. See \code{\link{setIs}}
	for the general version.

	The direct superclasses themselves may
	have direct superclasses and
	similarly through further generations. Putting all this information together produces
	the full list of superclasses for this class.
	The superclass list is included in the definition of the class that is
	cached during the \R session.
	The \emph{distance} between the two classes is defined to be the
	number of generations:
	\code{1} for direct superclasses (regardless of which mechanism
	defined them), then \code{2} for the direct superclasses of those
	classes, and so on.
	To see all the superclasses, with their distance, print the class
	definition by calling \code{\link{getClass}}.
	In addition, any class implicitly has class \code{"ANY"} as a superclass. The
	distance to \code{"ANY"} is treated as larger than the distance to any
	actual class.
	The special class \code{"missing"} corresponding to missing arguments
	has only \code{"ANY"} as a superclass, while \code{"ANY"} has no
	superclasses.

	When a method is to be selected by inheritance, a search is made in
	the table for all methods corresponding to a combination of
	either the direct class or one of its superclasses, for each argument
	in the active signature.
	For an example, suppose there is only one argument in the signature and that the class of
	the corresponding object was \code{"dgeMatrix"} (from the recommended package
	\code{Matrix}).
	This class has (currently) three direct superclasses and through these
	additional superclasses at distances 2 through 4.
	A method that had been defined for any of these classes or for class
	\code{"ANY"} (the default method) would be eligible.
	Methods for the shortest difference are preferred.
	If there is only one best method in this sense, method selection is unambiguous.

	When there are multiple arguments in the signature, each argument will
	generate a similar list of inherited classes.
	The possible matches are now all the combinations of classes from each
	argument (think of the function \code{outer} generating an array of
	all possible combinations).
	The search now finds all the methods matching any of this combination
	of classes.
	For each argument, the distance to the superclass defines which
	method(s) are preferred for that argument.
	A method is considered best for selection if it is among the best
	(i.e., has the least distance) for
	each argument.

	The end result is that zero, one or more methods may be \dQuote{best}.
	If one, this method is selected and cached in the table of methods.
	If there is more than one best match, the selection is ambiguous and a message is
	printed noting which method was selected (the first method
	lexicographically in the ordering) and what other methods could have
	been selected.
	Since the ambiguity is usually nothing the end user could control,
	this is not a warning.
	Package authors should examine their package for possible ambiguous
	inheritance by calling \code{\link{testInheritedMethods}}.

	Cached inherited selections are
	not themselves used in future inheritance searches, since that could result
	in invalid selections.
	If you want inheritance computations to be done again (for example,
	because a newly loaded package has a more direct method than one
	that has already been used in this session), call
	\code{\link{resetGeneric}}. Because classes and methods involving
	them tend to come from the same package, the current implementation
	does not reset all generics every time a new package is loaded.

	Besides being initiated through calls to the generic function, method
	selection can be done explicitly by calling the function
	\code{\link{selectMethod}}.
	Note that some computations may use this function directly, with
	optional arguments.
	The prime example is the use of \code{\link{coerce}()} methods by
	function \code{\link{as}()}.
	There has been some confusion from comparing coerce methods to a call
	to \code{\link{selectMethod}} with other options.
	}

	\section{Method Evaluation: Details}{

	Once a method has been selected, the evaluator creates a new context
	in which a call to the method is evaluated.
	The context is initialized with the arguments from the call to the
	generic function.
	These arguments are not rematched. All the arguments in the signature
	of the generic will have been evaluated (including any that are
	currently inactive); arguments that are not in the signature will obey
	the usual lazy evaluation rules of the language.
	If an argument was missing in the call, its default expression if any
	will \emph{not} have been evaluated, since method dispatch always uses
	class \code{missing} for such arguments.

	A call to a generic function therefore has two contexts: one for the
	function and a second for the method.
	The argument objects will be copied to the second context, but not any
	local objects created in a nonstandard generic function.
	The other important distinction is that the parent
	(\dQuote{enclosing}) environment of the second context is the environment
	of the method as a function, so that all \R programming techniques
	using such environments apply to method definitions as ordinary functions.


	For further discussion of method selection and dispatch, see the
	references in the sections indicated.

	}

	\section{Generic Functions}{
	In principle, a generic function could be any function that evaluates
	a call to \code{standardGeneric()}, the internal function that selects
	a method and evaluates a call to the selected method. In practice,
	generic functions are special objects that in addition to being from a
	subclass of class \code{"function"} also extend the class
	\code{\linkS4class{genericFunction}}. Such objects have slots to define
	information needed to deal with their methods. They also have
	specialized environments, containing the tables used in method
	selection.

	The slots \code{"generic"} and \code{"package"} in the object are the
	character string names of the generic function itself and of the
	package from which the function is defined.
	As with classes, generic functions are uniquely defined in \R by the
	combination of the two names.
	There can be generic functions of the same name associated with
	different packages (although inevitably keeping such functions cleanly
	distinguished is not always easy).
	On the other hand, \R will enforce that only one definition of a
	generic function can be associated with a particular combination of
	function and package name, in the current session or other active
	version of \R.

	Tables of methods for a particular generic function, in this sense,
	will often be spread over several other packages.
	The total set of methods for a given generic function may change
	during a session, as additional packages are loaded.
	Each table must be consistent in the signature assumed for the generic
	function.

	\R distinguishes \emph{standard} and \emph{nonstandard} generic
	functions, with the former having a function body that does nothing
	but dispatch a method.
	For the most part, the distinction is just one of simplicity: knowing
	that a generic function only dispatches a method call allows some
	efficiencies and also removes some uncertainties.

	In most cases, the generic function is the visible function
	corresponding to that name, in the corresponding package.
	There are two exceptions, \emph{implicit} generic
	functions and the special computations required to deal with \R's
	\emph{primitive} functions.
	Packages can contain a table of implicit generic versions of functions
	in the package, if the package wishes to leave a function non-generic
	but to constrain what the function would be like if it were generic.
	Such implicit generic functions are created during the installation of
	the package, essentially by defining the generic function and
	possibly methods for it, and then reverting the function to its
	non-generic form. (See \link{implicitGeneric} for how this is done.)
	The mechanism is mainly used for functions in the older packages in
	\R, which may prefer to ignore S4 methods.
	Even in this case, the actual mechanism is only needed if something
	special has to be specified.
	All functions have a corresponding implicit generic version defined
	automatically (an implicit, implicit generic function one might say).
	This function is a standard generic with the same arguments as the
	non-generic function, with the non-generic version as the default (and only)
	method, and with the generic signature being all the formal arguments
	except \dots.

	The implicit generic mechanism is needed only to override some aspect
	of the default definition.
	One reason to do so would be to remove some arguments from the
	signature.
	Arguments that may need to be interpreted literally, or for which the
	lazy evaluation mechanism of the language is needed, must \emph{not}
	be included in the signature of the generic function, since all
	arguments in the signature will be evaluated in order to select a
	method.
	For example, the argument \code{expr} to the function
	\code{\link{with}} is treated literally and must therefore be excluded
	from the signature.

	One would also need to define an implicit generic if the existing
	non-generic function were not suitable as the default method.
	Perhaps the function only applies to some classes of objects, and the
	package designer prefers to have no general default method.
	In the other direction, the package designer might have some ideas
	about suitable methods for some classes, if the function were generic.
	With reasonably modern packages, the simple approach in all these
	cases is just to define the function as a generic.
	The implicit generic mechanism is mainly attractive for older packages
	that do not want to require the methods package to be available.

	Generic functions will also be defined but not obviously visible for
	functions implemented as \emph{primitive} functions in the base
	package.
	Primitive functions look like ordinary functions when printed but are
	in fact not function objects but objects of two types interpreted by
	the \R evaluator to call underlying C code directly.
	Since their entire justification is efficiency, \R refuses to hide
	primitives behind a generic function object.
	Methods may be defined for most primitives, and corresponding metadata
	objects will be created to store them.
	Calls to the primitive still go directly to the C code, which will
	sometimes check for applicable methods.
	The definition of \dQuote{sometimes} is that methods must have been
	detected for the function in some package loaded in the session and
	\code{isS4(x)} is \code{TRUE} for the first argument (or for the
	second argument, in the case of binary operators).
	You can test whether methods have been detected by calling
	\code{\link{isGeneric}} for the relevant function and you can examine
	the generic function by calling \code{\link{getGeneric}}, whether or
	not methods have been detected.
	For more on generic functions, see the references and also section 2
	of the \emph{R Internals} document supplied with \R.

	}

	\section{Method Definitions}{
	All method definitions are stored as objects from the
	\code{\linkS4class{MethodDefinition}} class.
	Like the class of generic functions, this class extends ordinary \R
	functions with some additional slots: \code{"generic"}, containing the
	name and package of the generic function, and two signature slots,
	\code{"defined"} and \code{"target"}, the first being the signature supplied when
	the method was defined by a call to \code{\link{setMethod}}.
	The \code{"target"} slot starts off equal to the \code{"defined"}
	slot. When an inherited method is cached after being selected, as
	described above, a copy is made with the appropriate \code{"target"} signature.
	Output from \code{\link{showMethods}}, for example, includes both
	signatures.

	Method definitions are required to have the same formal arguments as
	the generic function, since the method dispatch mechanism does not
	rematch arguments, for reasons of both efficiency and consistency.
	}


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

	Chambers, John M. (2008)
	\emph{Software for Data Analysis: Programming with R}
	Springer. (Section 10.5 for some details.)
	}

	\seealso{
	For more specific information, see
	\code{\link{setGeneric}}, \code{\link{setMethod}}, and
	\code{\link{setClass}}.

	For the use of \dots in methods, see \link{dotsMethods}.
	}
	\keyword{programming}
	\keyword{classes}
	\keyword{methods}