setGeneric {methods}R Documentation

Define a New Generic Function

Description

Create a new generic function of the given name, for which formal methods can then be defined.

Usage

setGeneric(name, def, group=NULL, valueClass=NULL, where=1, doAssign)

setGroupGeneric(name, def, group=NULL, valueClass=NULL, knownMembers, where=1)

Arguments

name The character string name of the generic function. In the simplest and most common case, a function of this name is already defined. The existing function may be non-generic or already a generic (see the details).
def An optional function object, defining the generic. This argument is usually only needed (and is then required) if there is no current function of this name. In that case, the formal arguments and default values for the generic are taken from def. See also argument useAsDefault.
group Optionally, a character string giving the group of generic functions to which this function belongs. Methods can be defined for the corresponding group generic, and these will then define methods for this specific generic function, if no method has been explicitly defined for the corresponding signature. See the references for more discussion.
valueClass An optional character string defining the class to asserted to be given to the value returned by this generic function. By default, the generic function can return any object. (At the moment, the assertion supplied in this argument is not enforced or checked.)
where Where to store the resulting initial methods definition, and possibly the generic function; by default, stored into the global environment.
doAssign Should a new generic version of the function be assigned? The default action depends on whether a generic version currently exists. If not, one will be assigned to where, except that primitive functions in the base package are never turned into explicit generic functions (they are dispatched from the internal code in the evaluator).
You can supply doAssign as TRUE to force assigning a generic function even if one already exists, or as FALSE to prevent assigning the generic in any case (for example, because you know one exists on another package). But the rule of not assigning generics for primitives cannot be overriden by setting doAssign to TRUE.
knownMembers (For setGroupGeneric only) The names of functions that are known to be members of this group. This information is used to reset cached definitions of the member generics when information about the group generic is changed.

Details

The setGeneric function is called to initialize a generic function in an environment (usually the global environment), as prepartion for defining some methods for that function.

The simplest and most common situation is that name is already a function, either an ordinary non-generic function or else a generic function in another environment. In the second case, essentially all you will be doing is to make a copy of the existing generic, without its methods, in the current environment. Only the name argument will be used. The new generic must agree with the current one in essentially everything except for the methods defined.

The other simple and common situation is that you already have a non-generic function (probably in the same place you plan to save the generic), and now want to turn this function into a generic. In this case, too, you will most often supply only name. The existing function becomes the default method, and the special group and valueClass properties remain unspecified.

The setGroupGeneric function behaves like setGeneric except that it constructs a group generic function, differing in two ways from an ordinary generic function. First, this function cannot be called directly, and the body of the function created will contain a stop call with this information. Second, the group generic function contains information about the known members of the group, used to keep the members up to date when the group definition changes, through changes in the search list or direct specification of methods, etc.

Value

The setGeneric function exists for its side effect: saving the generic function to allow methods to be specified later. It returns name.

Author(s)

John Chambers

References

The web page http://www.omegahat.org/RSMethods/index.html is the primary documentation.

The functions in this package emulate the facility for classes and methods described in Programming with Data, (John M. Chambers, Springer, 1998). See this book for further details and examples.

See Also

Methods for a discussion of other functions to specify and manipulate the methods of generic functions.


[Package Contents]