Description

Formally defined methods and classes for R objects, plusother programming tools, as described in the references.

Details

This package provides the “S4” or “S version 4”approach to methods and classes in a functional language.

For basic use of the techniques, start withIntroduction andfollow the links there to the key functions for programming, notablysetClass andsetMethod.

Some specific topics:

Classes:

Creating one, seesetClass;examining definitions, seegetClassDef andclassRepresentation; inheritance and coercing,seeis andas

Generic functions:

Basic programming, seesetGeneric; the class of objects, seegenericFunction; other functions to examine ormanipulate them, seeGenericFunctions.

S3:

Using classes, seesetOldClass; methods,seeMethods_for_S3.

Reference classes:

SeeReferenceClasses.

Class unions; virtual classes

SeesetClassUnion.

These pages will have additional links to related topics.

For a completelist of functions and classes, uselibrary(help="methods").

Author(s)

R Core Team

Maintainer: R Core Team[email protected]

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (Chapter 10 has some additional details.)

Description

A named list providing instructions for turning builtin and specialfunctions into generic functions.

Functions in R that are defined as.Primitive(<name>) are notsuitable for formal methods, because they lack the basic reflectanceproperty. You can't find the argument list for these functions byexamining the function object itself.

Future versions of R may fix this by attaching a formal argument listto the corresponding function. While generally the names of argumentsare not checked by the internal code implementing the function, thenumber of arguments frequently is.

In any case, some definition of a formal argument list is needed ifusers are to define methods for these functions. In particular, ifmethods are to be merged from multiple packages, the different setsof methods need to agree on the formal arguments.

In the absence of reflectance, this list provides the relevantinformation via a dummy function associated with each of the knownspecials for which methods are allowed.

At the same, the list flags those specials for which methods aremeaningless (e.g.,for) or just a very bad idea (e.g.,.Primitive).

A generic function created viasetMethod, forexample, for one of these special functions will have the argumentlist from.BasicFunsList. If no entry exists, the argumentlist(x, ...) is assumed.

Description

Coerce an object to a given class.

Usage

as(object, Class, strict=TRUE, ext)as(object, Class)<- value

Arguments

Description

as(object)returns the version of this object coerced to be the givenClass. When used in the replacement form on the left ofan assignment, the portion of the object corresponding toClass is replaced byvalue.

The operation ofas() in either form depends on thedefinition of coerce methods. Methods are defined automaticallywhen the two classes are related by inheritance; that is, whenone of the classes is a subclass of the other.

Coerce methods are also predefined for basic classes (including allthe types of vectors, functions and a few others).

Beyond these two sources of methods, further methods are definedby calls to thesetAs function. See thatdocumentation also for details of how coerce methods work. UseshowMethods(coerce) for a list of all currently defined methods, as in theexample below.

Basic Coercion Methods

Methods are pre-defined for coercing any object to one of the basicdatatypes. For example,as(x, "numeric") uses the existingas.numeric function. These and all other existing methodscan be listed as shown in the example.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

See Also

If you think of usingtry(as(x, cl)), considercanCoerce(x, cl) instead.

Examples

## Show all the existing methods for as()showMethods("coerce")

Description

Formal classes exist corresponding to the basic R object types, allowingthese types to be used in method signatures, as slots in classdefinitions, and to be extended by new classes.

Usage

### The following are all basic vector classes.### They can appear as class names in method signatures,### in calls to as(), is(), and new()."character""complex""double""expression""integer""list""logical""numeric""single""raw"### the class"vector"### is a virtual class, extended by all the above### the class"S4"### is an object type for S4 objects that do not extend### any of the basic vector classes.  It is a virtual class.### The following are additional basic classes"NULL"#  NULL objects"function"#  function objects, including primitives"externalptr"# raw external pointers for use in C code"ANY"# virtual classes used by the methods package itself"VIRTUAL""missing""namedList"# the alternative to "list" that preserves# the names attribute

Objects from the Classes

If a class is not virtual (see section inClasses_Details),objects can be created by calls of the formnew(Class, ...),whereClass is the quoted class name, and the remainingarguments if any are objects to be interpreted as vectors of thisclass. Multiple arguments will be concatenated.

The class"expression" is slightly odd, in that the ...arguments willnot be evaluated; therefore, don't enclose themin a call toquote().

Note that class"list" is a pure vector. Although lists withnames go back to the earliest versions of S, they are an extensionof the vector concept in that they have an attribute (which can nowbe a slot) and which is eitherNULL or a character vector ofthe same length as the vector. If you want to guarantee that listnames are preserved, use class"namedList", rather than"list". Objects from this class must have a names attribute,corresponding to slot"names",of type"character". Internally, R treats names forlists specially, which makes it impractical to have the corresponding slot inclass"namedList" be a union of character names andNULL.

Classes and Types

The basic classes include classes for the basic R types. Note thatobjects of these types will not usually be S4 objects(isS4 will returnFALSE), although objects fromclasses that contain the basic class will be S4 objects, still withthe same type. The type asreturned bytypeof will sometimes differ from the class,either just from a choice of terminology (type"symbol" andclass"name", for example) or because there is not a one-to-onecorrespondence between class and type (most of the classes thatinherit from class"language" have type"language", for example).

Extends

The vector classes extend"vector", directly.

Methods

coerce

Methods are defined to coerce arbitrary objects tothe vector classes, by calling the corresponding basic function, forexample,as(x, "numeric") callsas.numeric(x).

Description

A call tocallGeneric can only appear inside a methoddefinition. It then results in a call to the current genericfunction. The value of that call is the value ofcallGeneric.While it can be called from any method, it is useful and typicallyused in methods for group generic functions.

Usage

callGeneric(...)

Arguments

Details

The name and package of the current generic function is stored in theenvironment of the method definition object. This name is looked upand the corresponding function called.

The statement that passing no arguments tocallGeneric causesthe generic function to be called with the current arguments ismore precisely as follows. Arguments that were missing in the currentcall are still missing (remember that"missing" is a validclass in a method signature). For a formal argument, sayx, thatappears in the original call, there is a corresponding argument in thegenerated call equivalent tox = x. In effect, thismeans that the generic function sees the same actual arguments, butarguments are evaluated only once.

UsingcallGeneric with no arguments is prone to creatinginfinite recursion, unless one of the arguments in the signature hasbeen modified in the current method so that a different method is selected.

Value

The value returned by the new call.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (Section 10.4 for some details.)

See Also

GroupGenericFunctions for other informationabout group generic functions;Methods_Details for the general behaviorof method dispatch

Examples

## the method for group generic function Ops## for signature( e1="structure", e2="vector")function(e1, e2){    value<- callGeneric(e1@.Data, e2)if(length(value)== length(e1)){        e1@.Data<- value        e1}else value}## For more examples## Not run:showMethods("Ops", includeDefs=TRUE)## End(Not run)

Description

A call tocallNextMethod can only appear inside a methoddefinition. It then results in a call to the first inherited methodafter the current method, with the arguments to the current methodpassed down to the next method. The value of that method call is thevalue ofcallNextMethod.

Usage

callNextMethod(...)

Arguments

Details

The ‘next’ method (i.e., the first inherited method) is definedto be that method whichwould have been called if the currentmethod did not exist. This is more-or-less literally what happens: Thecurrent method (to be precise, the method with signature given by thedefined slot of the method from whichcallNextMethod iscalled) is deleted from a copy of the methods for the current generic,andselectMethod is called to find the next method (theresult is cached in the method object where the call occurred, so the search typicallyhappens only once per session per combination of argument classes).

The next method is defined from thesignature of the currentmethod, not from the actual classes of the arguments.In particular, modifying any of the arguments has no effect on theselection.As a result, the selected next method can be called with invalidarguments if the calling function assigns objects of a differentclass before thecallNextMethod() call.Be careful of any assignments to such arguments.

It is possible for the selection of the next method to be ambiguous,even though the original set of methods was consistent.See the section “Ambiguous Selection”.

The statement that the method is called with the current arguments ismore precisely as follows. Arguments that were missing in the currentcall are still missing (remember that"missing" is a validclass in a method signature). For a formal argument, sayx, thatappears in the original call, there is a corresponding argument in thenext method call equivalent tox = x. In effect, thismeans that the next method sees the same actual arguments, butarguments are evaluated only once.

Value

The value returned by the selected method.

Ambiguous Selection

There are two fairly common situations in which the choice of a nextmethod is ambiguous, even when the original set of methods uniquelydefines all method selection unambiguously.In these situations,callNextMethod() should be replaced,either by a call to a specific function or by recalling the genericwith different arguments.

The most likely situation arises with methods for binary operators,typically through one of the group generic functions.See the example for class"rnum" below.Examples of this sort usually require three methods: two for the casethat the first or the second argument comes from the class, and athird for the case that both arguments come from the class.If that last method usescallNextMethod, the other two methodsare equally valid. The ambiguity is exactly the same that requireddefining the two-argument method in the first place.

In fact, the two possibilities are equally valid conceptually as wellas formally.As in the example below, the logic of the application usually requiresselecting a computation explicitly or else calling the genericfunction with modified arguments to select an appropriate method.

The other likely source of ambiguity arises from a class that inheritsdirectly from more than one other class (a “mixin” in standardterminology).If the generic has methods corresponding to both superclasses, amethod for the current class is again needed to resolve ambiguity.UsingcallNextMethod will again reimpose the ambiguity.Again, some explicit choice has to be made in the calling methodinstead.

These ambiguities are not the result of bad design, but they dorequire workarounds.Other ambiguities usually reflect inconsistencies in the tree ofinheritances, such as a class appearing in more than one place amongthe superclasses.Such cases should be rare, but with the independent definition ofclasses in multiple packages, they can't be ruled out.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

See Also

callGeneric to call the generic function with thecurrent dispatch rules (typically for a group generic function);Methods_Details for the general behavior of method dispatch.

Examples

## callNextMethod() used for the Math, Math2 group generic functions## A class to automatically round numeric results to "d" digitsrnum<- setClass("rnum", slots= c(d="integer"), contains="numeric")## Math functions operate on the rounded numbers, return a plain## vector.  The next method will always be the default, usually a primitive.setMethod("Math","rnum",function(x)              callNextMethod(round(as.numeric(x), x@d)))setMethod("Math2","rnum",function(x, digits)              callNextMethod(round(as.numeric(x), x@d), digits))## Examples of callNextMethod with two arguments in the signature.## For arithmetic and one rnum with anything, callNextMethod with no arguments## round the full accuracy result, and return as plain vectorsetMethod("Arith", c(e1="rnum"),function(e1, e2)              as.numeric(round(callNextMethod(), e1@d)))setMethod("Arith", c(e2="rnum"),function(e1, e2)              as.numeric(round(callNextMethod(), e2@d)))## A method for BOTH arguments from "rnum" would be ambiguous## for callNextMethod(): the two methods above are equally valid.## The method chooses the smaller number of digits,## and then calls the generic function, postponing the method selection## until it's not ambiguous.setMethod("Arith", c(e1="rnum", e2="rnum"),function(e1, e2){if(e1@d<= e2@d)                  callGeneric(e1, as.numeric(e2))else                  callGeneric(as.numeric(e1), e2)})## For comparisons, callNextMethod with the rounded argumentssetMethod("Compare", c(e1="rnum"),function(e1, e2)              callNextMethod(round(e1, e1@d), round(e2, e1@d)))setMethod("Compare", c(e2="rnum"),function(e1, e2)              callNextMethod(round(e1, e2@d), round(e2, e2@d)))## similarly to the Arith case, the method for two "rnum" objects## can not unambiguously use callNextMethod().  Instead, we rely on## The rnum() method inhertited from Math2 to return plain vectors.setMethod("Compare", c(e1="rnum", e2="rnum"),function(e1, e2){              d<- min(e1@d, e2@d)              callGeneric(round(e1, d), round(e2, d))})set.seed(867)x1<- rnum(10*runif(5), d=1L)x2<- rnum(10*runif(5), d=2L)x1+1x2*2x1-x2## Simple examples to illustrate callNextMethod with and without argumentsB0<- setClass("B0", slots= c(s0="numeric"))## and a function to illustrate callNextMethodf<-function(x, text="default"){    str(x)# print a summary    paste(text,":", class(x))}setGeneric("f")setMethod("f","B0",function(x, text="B0"){    cat("B0 method called with s0 =", x@s0,"\n")    callNextMethod()})b0<- B0(s0=1)## call f() with 2 arguments: callNextMethod passes both to the default methodf(b0,"first test")## call f() with 1 argument:  the default "B0" is not passed by callNextMethodf(b0)## Now, a class that extends B0, with no methods for f()B1<- setClass("B1", slots= c(s1="character"), contains="B0")b1<- B1(s0=2, s1="Testing B1")## the two cases work as before, by inheriting the "B0" methodf(b1, b1@s1)f(b1)B2<- setClass("B2", contains="B1")## And, a method for "B2" that calls with explicit arguments.## Note that the method selection in callNextMethod## uses the class of the *argument* to consistently select the "B0" methodsetMethod("f","B2",function(x, text="B1 method"){    y<- B1(s0=-x@s0, s1="Modified x")    callNextMethod(y, text)})b2<- B2(s1="Testing B2", s0=10)f(b2, b2@s1)f(b2)## Be careful:  the argument passed must be legal for the method selected## Although the argument here is numeric, it's still the "B0" method that's calledsetMethod("f","B2",function(x, text="B1 method"){    callNextMethod(x@s0, text)})##  Now the call will cause an error:tryCatch(f(b2), error=function(e) cat(e$message,"\n"))

Description

Test if an object can be coerced to a given S4 class.Maybe useful insideif() to ensure that callingas(object, Class) will find a method.

Usage

canCoerce(object, Class)

Arguments

Value

a scalar logical,TRUE if there is acoerce method(as defined by e.g.setAs) for the signature(from = class(object), to = Class).

See Also

as,setAs,selectMethod,setClass,

Examples

m<- matrix(pi,2,3)canCoerce(m,"numeric")# TRUEcanCoerce(m,"array")# TRUE

Description

Combine two matrix-likeR objects by columns (cbind2)or rows (rbind2). These are (S4) generic functions with defaultmethods.

Usage

cbind2(x, y,...)rbind2(x, y,...)

Arguments

Details

The main use ofcbind2 (rbind2) is to be calledrecursively bycbind() (rbind()) when both ofthese requirements are met:

• There is at least one argument that is an S4 object, and

• S3 dispatch fails (see the Dispatch section undercbind).

The methods oncbind2 andrbind2 effectively define thetype promotion policy when combining a heterogeneous set ofarguments. The homogeneous case, where all objects derive from some S4class, can be handled via S4 dispatch on the... argument viaan externally defined S4cbind (rbind) generic.

Since (for legacy reasons) S3 dispatch is attempted first, it isgenerally a good idea to additionally define an S3 method oncbind (rbind) for the S4 class. The S3 method will beinvoked when the arguments include objects of the S4 class, along witharguments of classes for which no S3 method exists. Also, in case thereis an argument that selects a different S3 method (like the one fordata.frame), this S3 method serves to introduce an ambiguity indispatch that triggers the recursive fallback tocbind2(rbind2). Otherwise, the other S3 method would be called, whichmay not be appropriate.

Value

A matrix (or matrix like object) combining the columns (or rows) ofx andy. Note that methods must constructcolnames andrownames from thecorresponding column and row names ofx andy (but notfrom deparsing argument names such as incbind(..., deparse.level = d) for$d\ge 1$d≥1).

Methods

signature(x = "ANY", y = "ANY")

the default methodusingR's internal code.

signature(x = "ANY", y = "missing")

the default methodfor one argument usingR's internal code.

See Also

cbind,rbind

Examples

cbind2(1:3,4)m<- matrix(3:8,2,3, dimnames=list(c("a","b"), LETTERS[1:3]))cbind2(1:2, m)# keeps dimnames from m## rbind() and cbind() now make use of rbind2()/cbind2() methodssetClass("Num", contains="numeric")setMethod("cbind2", c("Num","missing"),function(x,y,...){ cat("Num-miss--meth\n"); as.matrix(x)})setMethod("cbind2", c("Num","ANY"),function(x,y,...){    cat("Num-A.--method\n"); cbind(getDataPart(x), y,...)})setMethod("cbind2", c("ANY","Num"),function(x,y,...){    cat("A.-Num--method\n"); cbind(x, getDataPart(y),...)})a<- new("Num",1:3)trace("cbind2")cbind(a)cbind(a, four=4,7:9)# calling cbind2() twicecbind(m,a, ch=c("D","E"), a*3)cbind(1,a, m)# ok with a warninguntrace("cbind2")

Description

You have navigated to an old link to documentation of S4 classes.

For basic use of classes and methods, seeIntroduction; tocreate new class definitions, seesetClass; fortechnical details on S4 classes, seeClasses_Details.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

Description

Class definitions are objects that contain the formal definition of aclass ofR objects, usually referred to as an S4 class, todistinguish them from the informal S3 classes.This document gives an overview of S4 classes; fordetails of the class representation objects, see help for the classclassRepresentation.

Metadata Information

When a class is defined, an object is stored that contains theinformation about that class. The object, known as themetadata defining the class, is not stored under the name ofthe class (to allow programmers to write generating functions ofthat name), but under a specially constructed name.To examine the class definition, callgetClass. Theinformation in the metadata object includes:

Slots:

The data contained in an object from an S4 class is defined bytheslots in the class definition.

Each slot in an object is a component of the object;like components (that is, elements) of alist, these may be extracted and set, using thefunctionslot() or more often the operator"@". However, theydiffer from list components in important ways.First, slots can only be referred to by name, not by position,and there is no partial matching of names as with list elements.

All the objects from a particular class have the same set of slotnames; specifically, the slot names that are contained in theclass definition. Each slot in each object always is an objectof theclass specified for this slot in the definition of the current class.The word “is” corresponds to theR function of the samename (is), meaning that the class of the object inthe slot must be the same as the class specified in thedefinition, or some class that extends the one in thedefinition (asubclass).

A special slot name,.Data, stands for the‘data part’ of the object. An object from a class with adata part is defined by specifying that the class contains oneof theR object types or one of the special pseudo-classes,matrix orarray, usually because the definition ofthe class, or of one of its superclasses, has included the typeor pseudo-class in itscontains argument. A secondspecial slot name,.xData, is used to enable inheritancefrom abnormal types such as"environment"See the section on inheriting from non-S4 classesfor details on the representation andfor the behavior of S3 methods with objects from these classes.

Some slot names correspond to attributes used in old-style S3objects and inR objects without an explicit class, forexample, thenames attribute. If you define a class forwhich that attribute will be set, such as a subclass of namedvectors, you should include"names" as a slot. See thedefinition of class"namedList" for an example. Using thenames() assignment to set such names will generate awarning if there is no names slot and an error if the object inquestion is not a vector type. A slot called"names" canbe used anywhere, but only if it is assigned as a slot, not viathe defaultnames() assignment.

Superclasses:

The definition of a class includes thesuperclasses —theclasses that this class extends. AclassFancy, say, extends a classSimple if anobject from theFancy class has all the capabilities oftheSimple class (and probably some more as well). Inparticular, and very usefully, any method defined to work for aSimple object can be applied to aFancy object aswell.

This relationship is expressed equivalently by saying thatSimple is a superclass ofFancy, or thatFancy is a subclass ofSimple.

The direct superclasses of a class are those superclassesexplicitly defined. Direct superclasses can be defined inthree ways. Most commonly, the superclasses are listed in thecontains= argument in the call tosetClassthat creates the subclass. In this case the subclass willcontain all the slots of the superclass, and the relationbetween the class is calledsimple, as it in fact is.Superclasses can also be definedexplicitly by a call tosetIs; in this case, therelation requires methods to be specified to go from subclass tosuperclass. Thirdly, a class union is a superclass of all themembers of the union. In this case too the relation is simple,but notice that the relation is defined when the superclass iscreated, not when the subclass is created as with thecontains= mechanism.

The definition of a superclass will also potentially containits own direct superclasses. These are considered (and shown) assuperclasses at distance 2 from the original class; their directsuperclasses are at distance 3, and so on. All these arelegitimate superclasses for purposes such as method selection.

When superclasses are defined by including the names ofsuperclasses in thecontains= argument tosetClass, an object from the class will have all theslots defined for its own classand all the slots definedfor all its superclasses as well.

The information about the relation between a class and aparticular superclass is encoded as an object of classSClassExtension. A list of such objects forthe superclasses (and sometimes for the subclasses) is included inthe metadata object defining the class. If you need to computewith these objects (for example, to compare the distances), callthe functionextends with argumentfullInfo=TRUE.

Prototype:

The objects from a class created by a call toneware defined by theprototype object for the class and byadditional arguments in the call tonew, which arepassed to a method for that class for the functioninitialize.

Each class representation object contains a prototype objectfor the class (although for a virtual class the prototype may beNULL). The prototype object must have values for all theslots of the class.By default, these are the prototypes of the corresponding slotclasses. However, the definition of the class can specify anyvalid object for any of the slots.

Basic classes

There are a number of ‘basic’ classes, corresponding to theordinary kinds of data occurring inR. For example,"numeric" is a class corresponding to numeric vectors.The other vector basic classes are"logical","integer","complex","character","raw","list"and"expression".The prototypes forthe vector classes are vectors of length 0 of the correspondingtype. Notice that basic classes are unusual in that theprototype object is from the class itself.

In addition to the vector classes there are also basic classescorresponding to objects in thelanguage, such as"function" and"call".These classes are subclasses of the virtual class"language".Finally, there are object types and corresponding basic classes for“abnormal” objects, such as"environment" and"externalptr".These objects do not follow thefunctional behavior of the language; in particular, they are notcopied and so cannot have attributes or slots defined locally.

All these classes can be used as slots or assuperclasses for any other class definitions, although they donot themselves come with an explicit class. For the abnormalobject types, a special mechanism is used to enable inheritanceas described below.

Inheriting from non-S4 Classes

A class definition can extend classes other thanregular S4 classes, usually by specifying them in thecontains= argument tosetClass. Three groupsof such classes behave distinctly:

1. S3 classes, which must have been registered by a previous call tosetOldClass (you can check that this has been doneby callinggetClass, which should return a class thatextendsoldClass);

2. One of theR object types, typically a vector type, which thendefines the type of the S4 objects, but also a type such asenvironment that can not be used directly as a typefor an S4 object. Seebelow.

3. One of the pseudo-classesmatrixandarray, implying objects witharbitrary vector types plus thedim anddimnamesattributes.

This section describes the approach to combining S4 computationswith older S3 computations by using such classes as superclasses. Thedesign goal is to allow the S4 class to inherit S3 methods anddefault computations in as consistent a form as possible.

As part of a general effort to make the S4 and S3 code in R moreconsistent, when objects from an S4 class are used as the firstargument to a non-default S3 method, either for an S3 generic function(one that callsUseMethod) or for one of the primitivefunctions that dispatches S3 methods, an effort is made to provide avalid object for that method. In particular, if the S4 class extendsan S3 class ormatrix orarray, and there is an S3method matching one of these classes, the S4 object will be coerced toa valid S3 object, to the extent that is possible given that there isno formal definition of an S3 class.

For example, suppose"myFrame" is an S4 class that includes theS3 class"data.frame" in thecontains= argument tosetClass. If an object from this S4 class is passed toa function, sayas.matrix, that has an S3 method for"data.frame", the internal code forUseMethodwill convert the object to a data frame; in particular, to an S3object whose class attribute will be the vector corresponding to theS3 class (possibly containing multiple class names). Similarly for anS4 object inheriting from"matrix" or"array", the S4object will be converted to a valid S3 matrix or array.

Note that the conversion isnot applied when an S4 object ispassed to the default S3 method. Some S3 generics attempt to dealwith general objects, including S4 objects. Also, no transformationis applied to S4 objects that do not correspond to a selected S3method; in particular, to objects from a class that does not containeither an S3 class or one of the basic types. SeeasS4for the transformation details.

In addition to explicit S3 generic functions, S3 methods aredefined for a variety of operators and functions implemented asprimitives. These methods are dispatched by some internal Ccode that operates partly through the same code as real S3generic functions and partly via special considerations (forexample, both arguments to a binary operator are examined whenlooking for methods). The same mechanism for adapting S4objects to S3 methods has been applied to these computations aswell, with a few exceptions such as generating an error if an S4object that does not extend an appropriate S3 class or type ispassed to a binary operator.

The remainder of this section discusses the mechanisms forinheriting from basic object types. Seematrixorarrayfor inhering from the matrix and arraypseudo-classes, or from time-series. For thecorresponding details for inheritancefrom S3 classes, seesetOldClass.

An object from a class that directly and simply contains oneof the basic object types inR, has implicitly a corresponding.Data slot of that type, allowing computations to extractor replace the data part while leaving other slotsunchanged. If the type is one that can accept attributes and isduplicated normally, the inheritance also determines the type of theobject; if the class definition has a.Data slotcorresponding to a normal type, the class of theslot determines the type of the object (that is, the value oftypeof(x)).For such classes,.Data is a pseudo-slot; thatis, extracting or setting it modifies the non-slot data in theobject. The functionsgetDataPart andsetDataPart are a cleaner, but essentiallyequivalent way to deal with the data part.

Extending a basic type this way allows objects touse old-style code for the corresponding type as well as S4methods. Any basic type can be used for.Data, buta few types are treated differently because they do not behave like ordinary objects;for example,"NULL", environments, and external pointers.Classes extend these types by having a slot,.xData,itself inherited from an internally defined S4 class. Thisslot actually contains an object of the inherited type, toprotect computations from the reference semantics of the type.Coercing to the nonstandard object type then requires anactual computation, rather than the"simple" inclusionfor other types and classes. The intent is that programmerswill not need to take account of the mechanism, but oneimplication is that you shouldnot explicitly use thetype of an S4 object to detect inheritance from an arbitraryobject type. Useis and similar functions instead.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

See Also

Methods_Details for analogous discussion of methods,setClass for details of specifying class definitions,is,as,new,slot

Description

Given a vector of class names or a list of class definitions, thefunction returns an adjacency matrix of the superclasses of theseclasses; that is, a matrix with class names as the row and columnnames and with element [i, j] being 1 if the class in column j is adirect superclass of the class in row i, and 0 otherwise.

The matrix has the information implied by thecontains slot ofthe class definitions, but in a form that is often more convenient forfurther analysis; for example, an adjacency matrix is used in packagesand other software to construct graph representations of relationships.

Usage

classesToAM(classes, includeSubclasses=FALSE,       abbreviate=2)

Arguments

Details

For each of the classes, the calculation gets all the superclassnames from the class definition, and finds the edges in those classes'definitions; that is, all the superclasses at distance 1. Thecorresponding elements of the adjacency matrix are set to 1.

The adjacency matrices for the individual class definitions aremerged. Note two possible kinds of inconsistency, neither of whichshould cause problems except possibly with identically named classes fromdifferent packages. Edges are computed from each superclassdefinition, so that information overrides a possible inference fromextension elements with distance > 1 (and it should). Whenmatrices from successive classes in the argument are merged, thecomputations do not currently check for inconsistencies—this isthe area where possible multiple classes with the same name couldcause confusion. A later revision may include consistency checks.

Value

As described, a matrix with entries 0 or 1, non-zero valuesindicating that the class corresponding to the column is a directsuperclass of the class corresponding to the row. The row andcolumn names are the class names (without package slot).

See Also

extends andclassRepresentation for the underlying information from the classdefinition.

Examples

## the super- and subclasses of "standardGeneric"## and "derivedDefaultMethod"am<- classesToAM(list(class(show), class(getMethod(show))),TRUE)am## Not run:## the following function depends on the Bioconductor package RgraphvizplotInheritance<-function(classes, subclasses=FALSE,...){if(!require("Rgraphviz", quietly=TRUE))      stop("Only implemented if Rgraphviz is available")    mm<- classesToAM(classes, subclasses)    classes<- rownames(mm); rownames(mm)<- colnames(mm)    graph<-  new("graphAM", mm,"directed",...)    plot(graph)    cat("Key:\n", paste(abbreviate(classes)," = ", classes,", ",        sep=""),  sep="", fill=TRUE)    invisible(graph)}## The plot of the class inheritance of the package "graph"require(graph)plotInheritance(getClasses("package:graph"))## End(Not run)

Description

The functionclassName() generates avalid references to a class, including the name of the packagecontaining the class definition. The object returned, from class"className", is theunambiguous way to refer to a class, for example when callingsetMethod, just in case multiple definitions of theclass exist.

Function"multipleClasses" returns information about multipledefinitions of classes with thesame name from different packages.

Usage

className(class, package)multipleClasses(details=FALSE)

Arguments

Details

The table of class definitions used internally can maintain multipledefinitions for classes with the same name but coming from differentpackages.If identical class definitions are encountered, only one classdefinition is kept; this occurs most often with S3 classes that havebeen specified in calls tosetOldClass. For trueclasses, multiple class definitions are unavoidable in general if twopackages happen to have used the same name, independently.

Overriding a class definition in another package with the same name deliberately is usually a badidea.AlthoughR attempts to keep and use the two definitions (as ofversion 2.14.0), ambiguities are always possible. It is moresensible to define a new class that extends an existing class but hasa different name.

Value

A call toclassName() returns an object from class"className".

A call tomultipleClasses() returns either a charactervector or a named list of class definitions. In either case, testingthe length of the returned value for being greater than0 is acheck for the existence of multiply defined classes.

Objects from the Class

The class"className" extends"character" and has a slot"package", also of class"character".

Examples

## Not run:className("vector")# will be found, from package "methods"className("vector","magic")# OK, even though the class doesn't existclassName("An unknown class")# Will cause an error## End(Not run)

Description

These are the objects that hold the definition ofclasses of objects. They are constructed and stored as meta-data bycalls to the functionsetClass. Don't manipulate themdirectly, except perhaps to look at individual slots.

Details

Class definitions are stored as metadata in various packages.Additional metadata supplies information on inheritance (the result ofcalls tosetIs). Inheritance information implied by theclass definition itself (because the class contains one or more otherclasses) is also constructed automatically.

When a class is to be used in an R session, this information isassembled to complete the class definition. The completion is asecond object of class"classRepresentation", cached for thesession or until something happens to change the information. A calltogetClass returns the completed definition of a class;a call togetClassDef returns the stored definition(uncompleted).

In particular, completion fills in the upward- and downward-pointinginheritance information for the class, in slotscontains andsubclasses respectively. It's in principle important to notethat this information can depend on which packages are installed,since these may define additional subclasses or superclasses.

Slots

slots:

A named list of the slots in this class; theelements of the list are the classes to which the slots mustbelong (or extend), and the names of the list gives thecorresponding slot names.

contains:

A named list of the classes this class‘contains’; the elements of the list are objects ofSClassExtension. The list may be only thedirect extensions or all the currently known extensions (see thedetails).

virtual:

Logical flag, set toTRUE if this isa virtual class.

prototype:

The object that represents the standardprototype for this class; i.e., the data and slots returned by acall tonew for this class with no specialarguments. Don't mess with the prototype object directly.

validity:

Optionally, a function to be used to testthe validity of objects from this class.SeevalidObject.

access:

Access control information. Not currently used.

className:

The character string name of the class.

package:

The character string name of the package towhich the class belongs. Nearly always the package on which themetadata for the class is stored, but in operations such asconstructing inheritance information, the internal package namerules.

subclasses:

A named list of the classes known toextend this class'; the elements of the list are objects of classSClassExtension. The list is currently onlyfilled in when completing the class definition (see the details).

versionKey:

Object of class"externalptr";eventually will perhaps hold some versioning information, but notcurrently used.

sealed:

Object of class"logical"; is thisclass sealed? If so, no modifications are allowed.

See Also

See functionsetClass to supply the information in theclass definition.SeeClasses_Details for a more basic discussion of class information.

Description

Special documentation can be supplied to describe theclasses and methods that are created by the software in the methodspackage. Techniques to access this documentation and to create itin R help files are described here.

Getting documentation on classes and methods

You can ask for on-line help for class definitions, for specificmethods for a generic function, and for general discussion ofmethods for a generic function. These requests use the?operator (seehelp for a general description ofthe operator). Of course, you are at the mercy of the implementeras to whether thereis any documentation on the correspondingtopics.

Documentation on a class uses the argumentclass on the leftof the?, and the name of the class on the right; forexample,

class ? genericFunction

to ask for documentation on the class"genericFunction".

When you want documentation for the methods defined for a particularfunction, you can ask either for a general discussion of the methodsor for documentation of a particular method (that is, the method thatwould be selected for a particular set of actual arguments).

Overall methods documentation is requested bycalling the? operator withmethods as the left-sideargument and the name of the function as the right-side argument. Forexample,

methods ? initialize

asks for documentation on the methods for theinitializefunction.

Asking for documentation on a particular method is done by giving afunction call expression as the right-hand argument to the"?"operator. There are two forms, depending on whether you prefer togive the class names for the arguments or expressions that you intendto use in the actual call.

If you planned to evaluate a function call, saymyFun(x, sqrt(wt))and wanted to find out something about the method that would be usedfor this call, put the call on the right of the"?" operator:

?myFun(x, sqrt(wt))

A method will be selected, as it would be for the call itself, anddocumentation for that method will be requested. IfmyFun isnot a generic function, ordinary documentation for the function willbe requested.

If you know the actual classes for which you would like methoddocumentation, you can supply these explicitly in place of theargument expressions. In the example above, if you want methoddocumentation for the first argument having class"maybeNumber"and the second"logical", call the"?" operator, thistime with a left-side argumentmethod, and with a function callon the right using the class names as arguments:

method ? myFun("maybeNumber", "logical")

Once again, a method will be selected, this time corresponding to thespecified classes, and method documentation will be requested. Thisversion only works with generic functions.

The two forms each have advantages. The version with actual argumentsdoesn't require you to figure out (or guess at) the classes of thearguments.On the other hand, evaluating the arguments may take some time,depending on the example.The version with class names does require you to pick classes, butit's otherwise unambiguous. It has a subtler advantage, in that theclasses supplied may be virtual classes, in which case no actualargument will have specifically this class. The class"maybeNumber", for example, might be a class union (see theexample forsetClassUnion).

In either form, methods will be selected as they would be in actualcomputation, including use of inheritance and group genericfunctions. SeeselectMethod for the details, since it isthe function used to find the appropriate method.

Writing Documentation for Methods

The on-line documentation for methods and classes uses some extensionsto the R documentation format to implement the requests for class andmethod documentation described above. See the documentWritingR Extensions for the available markup commands (you shouldhave consulted this document already if you are at the stage ofdocumenting your software).

In addition to the specific markup commands to be described, you cancreate an initial, overall file with a skeleton of documentation forthe methods defined for a particular generic function:

promptMethods("myFun")

will create a file, ‘myFun-methods.Rd’ with a skeleton ofdocumentation for the methods defined for functionmyFun.The output frompromptMethods is suitable if you want todescribe all or most of the methods for the function in one file,separate from the documentation of the generic function itself.Once the file has been filled in and moved to the ‘man’subdirectory of your source package, requests for methodsdocumentation will use that file, both for specific methodsdocumentation as described above, and for overall documentationrequested by

methods ? myFun

You are not required to usepromptMethods, and if you do, youmay not want to use the entire file created:

• If you want to document the methods in the file containing thedocumentation for the generic function itself, you cancut-and-paste to move the⁠\alias⁠ lines and theMethods section from the file created bypromptMethods to the existing file.

• On the other hand, if these are auxiliary methods, and you onlywant to document the added or modified software, you should stripout all but the relevant⁠\alias⁠ lines for the methods ofinterest, and remove all but the corresponding⁠\item⁠entries in theMethods section. Note that in this case youwill usually remove the first⁠\alias⁠ line as well, sincethat is the marker for general methods documentation on thisfunction (in the example, ‘⁠\alias{myfun-methods}⁠’).

If you simply want to direct documentation for one or more methods toa particular R documentation file, insert the appropriate alias.

Description

The “...” argument inR functions is treated specially, in that itmatches zero, one or more actual arguments (and so, objects). Amechanism has been added toR to allow “...” as the signature of ageneric function. Methods defined for such functions will beselected and called whenall the arguments matching “...”are from the specified class or from some subclass of that class.

Using "..." in a Signature

Beginning with version 2.8.0 ofR, S4 methods can be dispatched(selected and called) corresponding to the special argument “...”.Currently, “...” cannot be mixed with other formal arguments:either the signature of the generic function is “...” only, or itdoes not contain “...”. (This restriction may be lifted in a futureversion.)

Given a suitable generic function, methods are specified in theusual way by a call tosetMethod. The methoddefinition must be written expecting all the arguments correspondingto “...” to be from the class specified in the method's signature,or from a class that extends that class (i.e., a subclass of thatclass).

Typically the methods will pass “...” down to another function orwill create a list of the arguments and iterate over that. See theexamples below.

When you have a computation that is suitable for more than one existingclass, a convenient approach may be to define a union of theseclasses by a call tosetClassUnion. See the examplebelow.

Method Selection and Dispatch for "..."

SeeMethods_Details for a general discussion. The following assumesyou have read the “Method Selection and Dispatch” section ofthat documentation.

A method selecting on “...” is specified by a single class in thecall tosetMethod. If all the actual argumentscorresponding to “...” have this class, the corresponding method isselected directly.

Otherwise, the class of each argument and that class' superclasses arecomputed, beginning with the first “...” argument. For the firstargument, eligible methods are those for any of the classes. Foreach succeeding argument that introduces a class not considered previously, the eligible methods are furtherrestricted to those matching the argument's class orsuperclasses. If no further eligible classes exist, the iterationbreaks out and the default method, if any, is selected.

At the end of the iteration, one or more methods may be eligible.If more than one, the selection looks for the method with the leastdistance to the actual arguments. For each argument, any inheritedmethod corresponds to a distance, available from thecontainsslot of the class definition. Since the same class can arise formore than one argument, there may be several distances associatedwith it. Combining them is inevitably arbitrary: the currentcomputation uses the minimum distance. Thus, for example, if amethod matched one argument directly, one as first generationsuperclass and another as a second generation superclass, thedistances are 0, 1 and 2. The current selection computation woulduse distance 0 for thismethod. In particular, this selection criterion tends to use a method thatmatches exactly one or more of the arguments' class.

As with ordinary method selection, there may be multiple methodswith the same distance. A warning message is issued and one of themethods is chosen (the first encountered, which in this case israther arbitrary).

Notice that, while the computation examines all arguments, theessential cost of dispatch goes up with the number ofdistinct classes among the arguments, likely to be muchsmaller than the number of arguments when the latter is large.

Implementation Details

Methods dispatching on “...” were introduced in version 2.8.0 ofR. The initial implementation of the corresponding selection anddispatch is in an R function, for flexibility while the newmechanism is being studied. In this implementation, a local versionofstandardGeneric is inserted in the generic function'senvironment. The local version selects a method according to thecriteria above and calls that method, from the environment of thegeneric function. This is slightly different from the action takenby the C implementation when “...” is not involved. Aside from theextra computing time required, the method is evaluated in a truefunction call, as opposed to the special context constructed by theC version (which cannot be exactly replicated in R code.) However,situations in which different computational results wouldbe obtained have not been encountered so far, and seem veryunlikely.

Methods dispatching on arguments other than “...” arecached by storingthe inherited method in the table of all methods, where it will befound on the next selection with the same combination of classesin the actual arguments (but not used for inheritance searches).Methods based on “...” are also cached, but not found quiteas immediately. As noted, the selected method depends only on theset of classes that occur in the “...” arguments. Each ofthese classes can appear one or more times, so many combinations ofactual argument classes will give rise to the same effectivesignature. The selection computation first computes and sorts thedistinct classes encountered. This gives a label that will becached in the table of all methods, avoiding any further search forinherited classes after the first occurrence. A call toshowMethods will expose such inherited methods.

The intention is that the “...” features will be added to thestandard C code when enough experience with them has been obtained.It is possible that at the same time, combinations of “...” withother arguments in signatures may be supported.

References

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (For the R version.)

Chambers, John M. (1998)Programming with DataSpringer (For the original S4 version.)

See Also

For the general discussion of methods, seeMethods_Details and linksfrom there.

Examples

cc<-function(...)c(...)setGeneric("cc")setMethod("cc","character",function(...)paste(...))setClassUnion("Number", c("numeric","complex"))setMethod("cc","Number",function(...) sum(...))setClass("cdate", contains="character", slots= c(date="Date"))setClass("vdate", contains="vector", slots= c(date="Date"))cd1<- new("cdate","abcdef", date= Sys.Date())cd2<- new("vdate","abcdef", date= Sys.Date())stopifnot(identical(cc(letters, character(), cd1),           paste(letters, character(), cd1)))# the "character" methodstopifnot(identical(cc(letters, character(), cd2),                    c(letters, character(), cd2)))# the default, because "vdate" doesn't extend "character"stopifnot(identical(cc(1:10,1+1i), sum(1:10,1+1i)))# the "Number" methodstopifnot(identical(cc(1:10,1+1i,TRUE), c(1:10,1+1i,TRUE)))# the defaultstopifnot(identical(cc(), c()))# no arguments implies the default methodsetGeneric("numMax",function(...)standardGeneric("numMax"))setMethod("numMax","numeric",function(...)max(...))# won't work for complex datasetMethod("numMax","Number",function(...) paste(...))# should not be selected w/o complex argsstopifnot(identical(numMax(1:10, pi,1+1i), paste(1:10, pi,1+1i)))stopifnot(identical(numMax(1:10, pi,1), max(1:10, pi,1)))try(numMax(1:10, pi,TRUE))# should be an error:  no default method## A generic version of paste(), dispatching on the "..." argument:setGeneric("paste", signature="...")setMethod("paste","Number",function(..., sep, collapse) c(...))stopifnot(identical(paste(1:10, pi,1), c(1:10, pi,1)))

Description

A formal class for R environments.

Objects from the Class

Objects can be created by calls of the formnew("environment", ...).The arguments in ..., if any, should be named and will be assigned tothe newly created environment.

Methods

coerce

signature(from = "ANY", to = "environment"):callsas.environment.

initialize

signature(object = "environment"):Implements the assignments in the new environment. Note that theobject argument is ignored; a new environment isalways created, since environments are not protected by copying.

See Also

new.env

Description

Support Class to Implement R Objects using Reference Semantics

NOTE:

The software described here is an initial version. The eventual goalis to support reference-style classes with software inR itselfor using inter-system interfaces. The current implementation (Rversion 2.12.0) is preliminary and subject to change, and currentlyincludes only theR-only implementation. Developers are encouragedto experiment with the software, but the description here is more thanusually subject to change.

Purpose of the Class

This class implements basic reference-style semantics forRobjects. Objects normally do not come directly from this class, butfrom subclasses defined by a call tosetRefClass.The documentation below is technical background describing the implementation, but applicationsshould use the interface documented undersetRefClass,in particular the$ operator and field accessor functions asdescribed there.

A Basic Reference Class

The design of reference classes forR divides those classes upaccording to the mechanism used for implementing references, fields,and class methods.Each version of this mechanism is defined by abasic referenceclass, which must implement a set of methods and provide somefurther information used bysetRefClass.

The required methods are for operators$ and$<- toget and set a field in an object, and forinitialize toinitialize objects.

To support these methods, the basic reference class needs to have someimplementation mechanism to store and retrieve data from fields in theobject.The mechanism needs to be consistent with reference semantics; thatis, changes made to the contents of an object are global, seen by anycode accessing that object, rather than only local to the functioncall where the change takes place.As described below, classenvRefClass implements referencesemantics through specialized use ofenvironmentobjects.Other basic reference classes may use an interface to a language suchas Java or C++ using reference semantics for classes.

Usually, theR user will be able to invoke class methods on theclass, using the$ operator. The basic reference classmethod for$ needs to make this possible. Essentially, theoperator must return anR function corresponding to the object andthe class method name.

Class methods may include an implementation of data abstraction, inthe sense that fields are accessed by “get” and “set”methods. The basic reference class provides this facility by settingthe"fieldAccessorGenerator" slot in its definition to afunction of one variable.This function will be called bysetRefClass with thevector of field names as arguments.The generator function must return a list of defined accessorfunctions.An element corresponding to a get operation is invoked with noarguments and should extract the corresponding field; an element for aset operation will be invoked with a single argument, the value to beassigned to the field.The implementation needs to supply the object, since that is not anargument in the method invocation.The mechanism used currently byenvRefClass is described below.

Support Classes

Two virtual classes are supplied to test for reference objects:is(x, "refClass") tests whetherx comes from a classdefined using the reference class mechanism described here;is(x, "refObject") tests whether the object has referencesemantics generally, including the previous classes and also classesinheriting from theR types with reference semantics, such as"environment".

Installed class methods are"classMethodDefinition" objects,with slots that identify the name of the function as a class methodand the other class methods called from this method.The latter information is determined heuristically when the class isdefined by using thecodetools recommended package. Thispackage must be installed when reference classes are defined, but isnot needed in order to use existing reference classes.

Author(s)

John Chambers

Description

Definitions of functions and/or methods from a source file areinserted into a package, using thetrace mechanism.Typically, this allows testing or debugging modified versions of a fewfunctions without reinstalling a large package.

Usage

evalSource(source, package="", lock=TRUE, cache=FALSE)insertSource(source, package="", functions=, methods=,           force=)

Arguments

Details

Thesource file is parsed and evaluated, suppressing by defaultthe actual caching of method and class definitions contained in it, sothat functions and methods can be tested out in a reversible way.The result, if all goes well, is an environment containing theassigned objects and metadata corresponding to method and class definitionsin the source file.

From this environment, the objects are inserted into the package, intoits namespace if it has one, for use during the current session oruntil reverting to the original version by a call tountrace.The insertion is done by calls to the internal version oftrace, to make reversion possible.

Because the trace mechanism is used, only function-type objects willbe inserted, functions themselves or S4 methods.

When thefunctions andmethods arguments are bothomitted,insertSource selects all suitable objects from theresult of evaluating thesource file.

In all cases,only objects in the source file that differ fromthe corresponding objects in the package are inserted.The definition of “differ” is that either the argument list(including default expressions) or the body of the function is notidentical.Note that in the case of a method, there need be no specific methodfor the corresponding signature in the package: the comparison is madeto the method that would be selected for that signature.

Nothing in the computation requires that the source file supplied bethe same file as in the original package source, although that case isboth likely and sensible if one is revising the package. Nothing inthe computations compares source files: the objects generated byevaluatingsource are compared as objects to the content of the package.

Value

An object from class"sourceEnvironment", a subclass of"environment" (see the section on the class)The environment contains the versionsofall object resulting from evaluation of the source file.The class also has slots for the time of creation, the source fileand the package name.Future extensions may use these objects for versioning or other code tools.

The object returned can be used in debugging (see the section on thattopic) or as thesourceargument in a future call toinsertSource. If only some of therevised functions were inserted in the first call, others can beinserted in a later call without re-evaluating the source file, bysupplying the environment and optionally suitablefunctionsand/ormethods argument.

Debugging

Once a function or method has been inserted into a package byinsertSource, it can be studied by the standard debugging tools;for example,debug or the various versions oftrace.

Calls totrace should take the extra argumentedit= env, whereenv is the value returned by the call toevalSource.The trace mechanism has been used to install the revised version fromthe source file, and supplying the argument ensures that it is thisversion, not the original, that will be traced. See the examplebelow.

To turn tracing off, but retain the source version, usetrace(x,edit = env) as in the example. To return to the original versionfrom the package, useuntrace(x).

Class"sourceEnvironment"

Objects from this class can be treated as environments, to extract theversion of functions and methods generated byevalSource.The objects also have the following slots:

packageName:

The character-string name of the packageto which the source code corresponds.

dateCreated:

The date and time that the source file wasevaluated (usually from a call toSys.time).

sourceFile:

The character-string name of the source fileused.

Note that using the environment does not change thedateCreated.

See Also

trace for the underlying mechanism, and also for theedit= argument that can be used for somewhat similar purposes;that function and alsodebug andsetBreakpoint, for techniques more oriented totraditional debugging styles.The present function is directly intended for the case that one ismodifying some of the source for an existing package, although it canbe used as well by inserting debugging code in the source (more usefulif the debugging involved is non-trivial). As noted in the detailssection, the sourcefile need not be the same one in the original package source.

Examples

## Not run:## Suppose package P0 has a source file "all.R"## First, evaluate the source, and from it## insert the revised version of methods for summary()  env<- insertSource("./P0/R/all.R", package="P0",     methods="summary")## now test one of the methods, tracing  the version from the source  trace("summary", signature="myMat", browser, edit= env)## After testing, remove the browser() call but keep the source  trace("summary", signature="myMat", edit= env)## Now insert all the (other) revised functions and methods## without re-evaluating the source file.## The package name is included in the object env.  insertSource(env)## End(Not run)

Description

Functions to find classes:isClass tests for a class;findClass returns the name(s) of packages containing theclass;getClasses returns the names of all the classes in anenvironment, typically a namespace. To examine the definition of a class, usegetClass.

Usage

isClass(Class, formal=TRUE, where)getClasses(where, inherits= missing(where))findClass(Class, where, unique="")## The remaining functions are retained for compatibility## but not generally recommendedremoveClass(Class, where)resetClass(Class, classDef, where)sealClass(Class, where)

Arguments

Functions

isClass:

Is this the name of a formally defined class?

getClasses:

The names of all the classes formally defined onwhere. Ifcalled with no argument, all the classes visible from thecalling function (if called from the top-level, all the classesin any of the environments on the search list). Thewhere argument is used to search only in a particular package.

findClass:

The list of environments inwhich a class definition ofClass is found. Ifwhere is supplied, a list is still returned, either emptyor containing the environment corresponding towhere.By default when called from theR session, the globalenvironment and all the currentlyattached packages are searched.

Ifunique is supplied as a character string,findClass will warn if there is more than one definitionvisible (using the string to identify the purpose of the call),and will generate an error if no definition can be found.

The remaining functions are retained forback-compatibility and internal use, but not generally recommended.

removeClass:

Remove the definition of this class. This can't be used if theclass is in another package, and would rarely be needed insource code defining classes in a package.

resetClass:

Reset the internal definition of a class. Not legitimate for aclass definition not in this package and rarely needed otherwise.

sealClass:

Seal the current definition of the specifiedclass, to prevent further changes, by setting the correspondingslot in the class definition. This is rarely used, sinceclasses in loaded packages are sealed by locking their namespace.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (Chapter 9 has some details not in the later reference.)

See Also

getClass,Classes_Details,Methods_Details,makeClassRepresentation

Description

The functionfindMethods converts the methods defined in a table for a genericfunction (as used for selection of methods) into a list, for study ordisplay. The list is actually from the classlistOfMethods(see the section describing the class, below).

The list will be limitedto the methods defined in environmentwhere if that argument issupplied and limited to those including one or more of thespecifiedclasses in the method signature if that argument issupplied.

To see the actual table (anenvironment) usedfor methods dispatch, callgetMethodsForDispatch.The names of the list returned byfindMethods are the names ofthe objects in the table.

The functionfindMethodSignatures returns a character matrixwhose rows are the class names from the signature of the correspondingmethods; it operates either from a list returned byfindMethods, or by computing such a list itself, given the samearguments asfindMethods .

The functionhasMethods returnsTRUE orFALSEaccording to whether there is a non-empty table of methods forfunctionf in the environment or search positionwhere(or for the generic function generally ifwhere is missing).

The deprecated functiongetMethods (defunct for defaulttable=FALSE)is an older alternative tofindMethods , returning information in the form of an object ofclassMethodsList, previously used for method dispatch. Thisclass of objects is deprecated generally and will disappear in afuture version of R.

Usage

findMethods(f, where, classes= character(), inherited=FALSE,      package="")findMethodSignatures(..., target=TRUE, methods=)hasMethods(f, where, package)## Deprecated in 2010 and defunct in 2015 for 'table = FALSE':getMethods(f, where, table=FALSE)# deprecated -> use getMethodsForDispatch()

Arguments

Details

The functions obtain a table of the defined methods, either from thegeneric function or from the stored metadata object in the environmentspecified bywhere. In a call togetMethods, the information in the table is convertedas described above to produce the returned value, except with thetable argument.

Note thathasMethods, but not the other functions, can be usedeven if no generic function of this name is currently found. In thiscasepackage must either be supplied as an argument or includedas an attribute off, since the package name is part of theidentification of the methods tables.

The Class for lists of methods

The class"listOfMethods" returns the methods as a named listof method definitions (or a primitive function, see the slotdocumentation below). The namesare the strings used to store the corresponding objects in theenvironment from which method dispatch is computed.The current implementation uses the names of the corresponding classesin the method signature, separated by"#" if more than oneargument is involved in the signature.

Slots

.Data:

Object of class"list" The methoddefinitions.

Note that these may include the primitive functionitself as default method,when the generic corresponds to a primitive. (Basically, becauseprimitive functions are abnormal R objects, which cannot currently beextended as method definitions.) Computations that use the returnedlist to derive other information need to take account of thispossibility. See the implementation offindMethodSignaturesfor an example.

arguments:

Object of class"character". Thenames of the formal arguments in the signature of the generic function.

signatures:

Object of class"list". A list ofthe signatures of the individual methods. This is currently theresult of splitting thenames according to the"#"separator.

If the object has been constructed from a table, as when returned byfindMethods, the signatures will all have the same length.However, a list rather than a character matrix is used forgenerality. CallingfindMethodSignatures as in the examplebelow will always convert to the matrix form.

generic:

Object of class"genericFunction".The generic function corresponding to these methods. Thereare plans to generalize this slot to allow reference to the function.

names:

Object of class"character". Thenames as noted are the class names separated by"#" .

Extends

Class"namedList", directly.

Class"list", by class"namedList", distance 2.

Class"vector", by class"namedList", distance 3.

See Also

showMethods,selectMethod,Methods_Details

Examples

mm<-  findMethods("Ops")findMethodSignatures(methods= mm)

Description

Beginning with R version 1.8.0, the class of an object contains theidentification of the package in which the class is defined. ThefunctionfixPre1.8 fixes and re-assigns objects missing that information(typically because they were loaded from a file saved with a previousversion of R.)

Usage

fixPre1.8(names, where)

Arguments

Details

The named object will be saved where it was found. Its classattribute will be changed to the full form required by R 1.8;otherwise, the contents of the object should be unchanged.

Objects will be fixed and re-assigned only if all the followingconditions hold:

1. The named object exists.

2. It is from a defined class (not a basic datatype whichhas no actual class attribute).

3. The object appears to be from an earlier version of R.

4. The class is currently defined.

5. The object is consistent with the current class definition.

If any condition except the second fails, a warning message isgenerated.

Note thatfixPre1.8 currently fixesonly the change inclass attributes. In particular, it will not fix binary versions ofpackages installed with earlier versions of R if these useincompatible features. Such packages must be re-installed fromsource, which is the wise approach always when major version changesoccur in R.

Value

The names of all the objects that were in fact re-assigned.

Description

Generic functions (objects from or extending classgenericFunction) are extended function objects,containing information used in creating and dispatching methods forthis function. They also identify the package associated with thefunction and its methods.

Objects from the Class

Generic functions are created and assigned bysetGeneric orsetGroupGeneric and, indirectly, bysetMethod.

As you might expectsetGeneric andsetGroupGeneric create objects of class"genericFunction" and"groupGenericFunction" respectively.

Slots

.Data:

Object of class"function", thefunction definition of the generic, usually createdautomatically as a call tostandardGeneric.

generic:

Object of class"character", thename of the generic function.

package:

Object of class"character", thename of the package to which the function definition belongs(andnot necessarily where the generic function isstored). If the package is not specified explicitly in thecall tosetGeneric, it is usually the package on whichthe corresponding non-generic function exists.

group:

Object of class"list", the group orgroups to which this generic function belongs. Empty by default.

valueClass:

Object of class"character"; ifnot an empty character vector, identifies one or more classes. It isasserted that all methods for this function return objectsfrom these class (or from classes that extend them).

signature:

Object of class"character", thevector of formal argument names that can appear in thesignature of methods for this generic function. By default,it is all the formal arguments, except for .... Ordermatters for efficiency: the most commonly used arguments inspecifying methods should come first.

default:

Object of class"optionalMethod"(a union of classes"function" and"NULL"), containingthe default method for this function if any. Generatedautomatically and used to initialize method dispatch.

skeleton:

Object of class"call", a slot usedinternally in method dispatch. Don't expect to use itdirectly.

Extends

Class"function", from data part.
Classes"optionalMethod","PossibleMethod", and"OptionalFunction" by class"function".

Methods

Generic function objects are used in the creation and dispatch offormal methods; information from the object is used to create methodslist objects and to merge or update the existing methods for thisgeneric.

Description

The functions documented here manage collections of methods associatedwith a generic function, as well as providing information about thegeneric functions themselves.

Usage

isGeneric(f, where, fdef, getName=FALSE)isGroup(f, where, fdef)removeGeneric(f, where)dumpMethod(f, signature, file, where, def)findFunction(f, generic=TRUE, where= topenv(parent.frame()))dumpMethods(f, file, signature, methods, where)signature(...)removeMethods(f, where= topenv(parent.frame()), all= missing(where))setReplaceMethod(f,..., where= topenv(parent.frame()))getGenerics(where, searchForm=FALSE)

Arguments

Summary of Functions

isGeneric:

Iffdef isNULL, then test if there is a formalgeneric function namedf in the current search path or inthe position specified bywhere.

Iffdef is non-NULL, then test if it is a formalgeneric function, with name matchingf iff is notmissing.

ThegetName argument allows a function to find the namefrom a function definition. If it isTRUE then the name ofthe generic is returned, orFALSE if this is not a genericfunction definition.

The behavior ofisGeneric andgetGeneric forprimitive functions is slightly different. These functions don'texist as formal generic function objects (for efficiency andhistorical reasons), regardless of whether methods have beendefined for them. For a primitive function,isGenerictests whether methods have been defined, whereasgetGeneric returns what the formal generic functionobject would be, even if no methods have been defined.

removeGeneric,removeMethods:

Remove all the methods for the generic function of thisname. In addition,removeGeneric removes the functionitself;removeMethods restores the non-generic functionwhich was the default method. If there was no default method,removeMethods leaves a generic function with no methods.

standardGeneric:

Dispatches a method from the current function call for the genericfunctionf. It is an error to callstandardGeneric anywhere except in the body of thecorresponding generic function.

Note thatstandardGeneric is a primitive function inthebase packagefor efficiency reasons, but rather documented here where it belongs naturally.

dumpMethod:

Dump the method for this generic function and signature.

findFunction:

return a list of either the positions on the search list, or thecurrent top-level environment, on which a function objectforname exists. The returned value isalways alist, use the first element to access the first visible versionof the function. See the example.

NOTE: Use this rather thanfind withmode="function", which is not as meaningful, and has a fewsubtle bugs from its use of regular expressions. Also,findFunction works correctly in the code for a packagewhen attaching the package via a call tolibrary.

dumpMethods:

Dump all the methods for this generic.

signature:

Returns a named list of classes to be matched to arguments of ageneric function.

getGenerics:

returns the names of the genericfunctions that have methods defined onwhere; thisargument can be an environment or an index into the searchlist. By default, the whole search list is used.

The methods definitions are stored withpackage qualifiers; for example, methods for function"initialize" might refer to two different functionsof that name, on different packages. The package namescorresponding to the method list object are contained in theslotpackage of the returned object. The form ofthe returned name can be plain (e.g.,"base"), or inthe form used in the search list ("package:base")according to the value ofsearchForm

Details

isGeneric:

If thefdef argument is supplied, take this as thedefinition of the generic, and test whether it is really ageneric, withf as the name of the generic. (This argumentis not available in S-Plus.)

removeGeneric:

Ifwhere supplied, just remove the version on this elementof the search list; otherwise, removes the first versionencountered.

standardGeneric:

Generic functions should usually have a call tostandardGeneric as their entire body. They can, however,do any other computations as well.

The usualsetGeneric (directly or through callingsetMethod) creates a function with a call tostandardGeneric.

dumpMethod:

The resulting source file will recreate the method.

findFunction:

Ifgeneric isFALSE, ignore generic functions.

dumpMethods:

Ifsignature is supplied only the methods matching thisinitial signature are dumped. (This feature is not found inS-Plus: don't use it if you want compatibility.)

signature:

The advantage of usingsignature is to provide a check onwhich arguments you meant, as well as clearer documentation inyour method specification. In addition,signature checksthat each of the elements is a single character string.

removeMethods:

ReturnsTRUE iff was a generic function,FALSE (silently) otherwise.

If there is a default method, the function will be re-assigned asa simple function with this definition.Otherwise, the generic function remains but with no methods (soany call to it will generate an error). In either case, afollowing call tosetMethod will consistentlyre-establish the same generic function as before.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

See Also

getMethod (also forselectMethod),setGeneric,setClass,showMethods

Examples

require(stats)# for lm## get the function "myFun" -- throw an error if 0 or > 1 versions visible:findFuncStrict<-function(fName){  allF<- findFunction(fName)if(length(allF)==0)    stop("No versions of ",fName," visible")elseif(length(allF)>1)    stop(fName," is ambiguous: ", length(allF)," versions")else    get(fName, allF[[1]])}try(findFuncStrict("myFun"))# Error: no versionlm<-function(x) x+1try(findFuncStrict("lm"))#    Error: 2 versionsfindFuncStrict("findFuncStrict")# just 1 versionrm(lm)## method dumping ------------------------------------setClass("A", slots= c(a="numeric"))setMethod("plot","A",function(x,y,...){ cat("A meth\n")})dumpMethod("plot","A", file="")## Not run:setMethod("plot","A",function(x, y,...){    cat("AAAAA\n")})## End(Not run)tmp<- tempfile()dumpMethod("plot","A", file=tmp)## now remove, and see if we can parse the dumpstopifnot(removeMethod("plot","A"))source(tmp)stopifnot(is(getMethod("plot","A"),"MethodDefinition"))## same with dumpMethods() :setClass("B", contains="A")setMethod("plot","B",function(x,y,...){ cat("B ...\n")})dumpMethods("plot", file=tmp)stopifnot(removeMethod("plot","A"),          removeMethod("plot","B"))source(tmp)stopifnot(is(getMethod("plot","A"),"MethodDefinition"),          is(getMethod("plot","B"),"MethodDefinition"))

Description

Get the definition of a class.

Usage

getClass(Class, .Force=FALSE, where)getClassDef(Class, where, package, inherits=TRUE)

Arguments

Details

Class definitions are stored in metadata objects in a packagenamespace or other environment where they are defined. Whenpackages are loaded, the class definitions in the package are cached in an internaltable. Therefore, most calls togetClassDef will find theclass in the cache or fail to find it at all, unlessinheritsisFALSE, in which case only the environment(s) defined bypackage orwhere are searched.

The class cache allows for multiple definitions of thesame class name in separate environments, with of course thelimitation that the package attribute or package name must beprovided in the call to

Value

The object defining the class. If the class definition is not found,getClassDef returnsNULL, whilegetClass, whichcallsgetClassDef, either generates an error or, if.Force isTRUE, returns a simple definition for theclass. The latter case is used internally, but is not typicallysensible in user code.

The non-null returned value is an object of classclassRepresentation.

Use functions such assetClass andsetClassUnion to create class definitions.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

See Also

classRepresentation,setClass,isClass.

Examples

getClass("numeric")## a built in classcld<- getClass("thisIsAnUndefinedClass", .Force=TRUE)cld## a NULL prototype## If you are really curious:utils::str(cld)## Whereas these generate errors:try(getClass("thisIsAnUndefinedClass"))try(getClassDef("thisIsAnUndefinedClass"))

Description

The functionselectMethod() returns the method thatwould be selected for a call to functionf if the arguments hadclasses as specified bysignature. Failing to find a methodis an error, unless argumentoptional = TRUE, in which caseNULL is returned.

The functionfindMethod() returns a list ofenvironments that contain a method for the specified function and signature; bydefault, these are a subset of the packages in the current searchlist. See section “UsingfindMethod()” for details.

The functiongetMethod() returns the method corresponding to thefunction and signature supplied similarly toselectMethod, butwithout using inheritance or group generics.

The functionshasMethod() andexistsMethod() test whetherselectMethod() orgetMethod(), respectively, finds a matching method.

Usage

selectMethod(f, signature, optional=FALSE, useInherited=,             mlist=, fdef=, verbose=, doCache=)  findMethod(f, signature, where)  getMethod(f, signature= character(), where, optional=FALSE,             mlist, fdef)  existsMethod(f, signature= character(), where)  hasMethod(f, signature= character(), where)

Arguments

Details

Thesignature argument specifies classes, corresponding toformal arguments of the generic function; to be precise, to thesignature slot of the generic function object. The argumentmay be a vector of strings identifying classes, and may be named ornot. Names, if supplied, match the names of those formal argumentsincluded in the signature of the generic. That signature is normallyall the arguments except .... However, generic functions can bespecified with only a subset of the arguments permitted, or with thesignature taking the arguments in a different order.

It's a good idea to name the arguments in the signature to avoidconfusion, if you're dealing with a generic that does somethingspecial with its signature. In any case, the elements of thesignature are matched to the formal signature by the same rules usedin matching arguments in function calls (seematch.call).

The strings in the signature may be class names,"missing" or"ANY". SeeMethods_Details for the meaning of these in methodselection. Arguments not supplied in the signature implicitlycorrespond to class"ANY"; in particular, giving an emptysignature means to look for the default method.

A call togetMethod returns the method for a particularfunction and signature. The search for the method makes no use ofinheritance.

The functionselectMethod also looks for a method given thefunction and signature, but makes full use of the method dispatchmechanism; i.e., inherited methods and group generics are taken intoaccount just as they would be in dispatching a method for thecorresponding signature, with the one exception that conditionalinheritance is not used. LikegetMethod,selectMethodreturnsNULL or generates an error ifthe method is not found, depending on the argumentoptional.

BothselectMethod andgetMethod will normally use thecurrent version of the generic function in the R session, which has atable of the methods obtained from all the packages loaded in thesession. Optional arguments can cause a search for the generic function from aspecified environment, but this is rarely a useful idea. In contrast,findMethod has a different default and the optionalwhere= argument may be needed. See the section “UsingfindMethod()”.

The functionsexistsMethod andhasMethod returnTRUE orFALSE according to whether a method is found,the first corresponding togetMethod (no inheritance) and thesecond toselectMethod.

Value

The call toselectMethod orgetMethod returns the selected method, ifone is found.(This class extendsfunction, so you can use the resultdirectly as a function if that is what you want.)Otherwise an error is thrown ifoptional isFALSE andNULL is returned ifoptional isTRUE.

The returned method object is aMethodDefinition object,except that the default method for a primitive function is required to be the primitive itself.Note therefore that the only reliable test that the search failed isis.null().

The returned value offindMethod is a list ofenvironments in which a corresponding method was found; that is, atable of methods including the one specified.

UsingfindMethod()

As its name suggests, this function is intended to behave likefind, which produces a list of the packages on thecurrent search list which have, and have exported, the object named.That's whatfindMethod does also, by default. The“exported” part in this case means that the package's namespacehas anexportMethods directive for this generic function.

An important distinction is that the absence of such a directive doesnot prevent methods from the package from being called once thepackage is loaded. Otherwise, the code in the package could not useun-exported methods.

So, if your question is whether loading packagethisPkg will define amethod for this function and signature, you need to ask that questionabout the namespace of the package:

findMethod(f, signature, where = asNamespace("thisPkg"))

If the package did not export the method, attaching it and callingfindMethod with nowhere argument will not find themethod.

Notice also that the length of the signature must be what thecorresponding package used. IfthisPkg had only methods forone argument, only length-1 signatures will match (no trailing"ANY"), even if another currently loaded package had signatureswith more arguments.

Methods foras()

The functionsetAs allows packages to define methods forcoercing one class of objects to another class. This works internallyby defining methods for the generic functioncoerce(from,to),which can not be called directly.

TheR evaluator selectsmethods for this purpose using a different form of inheritance. Whilemethods can be inherited for the object being coerced, they cannotinherit for the target class, since the result would not be a validobject from that class.If you want toexamine the selection procedure, you must supply the optional argumentuseInherited = c(TRUE, FALSE) toselectMethod.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (Section 10.6 for some details of method selection.)

See Also

Methods_Details for the details of methodselection;GenericFunctions for other functionsmanipulating methods and generic function objects;MethodDefinition for the class that representsmethod definitions.

Examples

testFun<-function(x)xsetGeneric("testFun")setMethod("testFun","numeric",function(x)x+1)hasMethod("testFun","numeric")# TRUEhasMethod("testFun","integer")#TRUE, inheritedexistsMethod("testFun","integer")#FALSEhasMethod("testFun")# TRUE, default methodhasMethod("testFun","ANY")

Description

The functions below produce the package associated with a particularenvironment or position on the search list, or of the packagecontaining a particular function. They are primarily used to supportcomputations that need to differentiate objects on multiple packages.

Usage

getPackageName(where, create=TRUE)setPackageName(pkg, env)packageSlot(object)packageSlot(object)<- value

Arguments

Details

Package names are normally installed during loading of the package,by theINSTALL script or by thelibraryfunction. (Currently, the name is stored as the object.packageName but don't trust this for the future.)

Value

getPackageName returns the character-string name of the package(without the extraneous"package:" found in the search list).

packageSlot returns or sets the package name slot (currentlyan attribute, not a formal slot, but this may change someday).

setPackageName can be used to establish a package name in anenvironment that would otherwise not have one. Thisallows you to create classes and/or methods in an arbitraryenvironment, but it is usually preferable to create packages by thestandardR programming tools (package.skeleton, etc.)

See Also

search,packageName

Examples

## all the following usually return "base"getPackageName(length(search()))getPackageName(baseenv())getPackageName(asNamespace("base"))getPackageName("package:base")

Description

ReturnsTRUE ifname corresponds to an argument in thecall, either a formal argument to the function, or a component of..., andFALSE otherwise.

Usage

hasArg(name)

Arguments

Details

The expressionhasArg(x), for example, is similar to!missing(x), with two exceptions. First,hasArg will look foran argument namedx in the call ifx is not a formalargument to the calling function, but... is. Second,hasArg never generates an error if given a name as an argument,whereasmissing(x) generates an error ifx is not aformal argument.

Value

AlwaysTRUE orFALSE as described above.

See Also

missing

Examples

ftest<-function(x1,...) c(hasArg(x1), hasArg("y2"))ftest(1)## c(TRUE, FALSE)ftest(1,2)## c(TRUE, FALSE)ftest(y2=2)## c(FALSE, TRUE)ftest(y=2)## c(FALSE, FALSE) (no partial matching)ftest(y2=2, x=1)## c(TRUE, TRUE) partial match x1

Description

The implicit generic mechanism stores generic versions offunctionsin a table in a package. The package does not want the currentversion of the function to be a generic, however, and retains thenon-generic version.

When a call tosetMethod orsetGeneric creates a generic version for one of thesefunctions, the object in the table is used.This mechanism is only needed if special arguments were used tocreate the generic; e.g., thesignature or thevalueClassoptions.

FunctionimplicitGeneric() returns the implicitgeneric version,setGenericImplicit() turns a generic implicit,prohibitGeneric() prevents your function from being madegeneric, andregisterImplicitGenerics() saves a set of implicitgeneric definitions in the cached table of the current session.

Usage

implicitGeneric(name, where, generic)setGenericImplicit(name, where, restore=TRUE)prohibitGeneric(name, where)registerImplicitGenerics(what, where)

Arguments

Details

Multiple packages may define methods for the same function, to applyto classes defined in that package. Arithmetic and other operators,plot() and many other basic computations are typicalexamples. It's essential that all such packages write methods forthesame definition of the generic function. So long as thatgeneric uses the default choice for signature and other parameters,nothing needs to be done.

If the generic has special properties, these need to be ensured forall packages creating methods for it. The simplest solution is justto make the function generic in the package that originally ownedit. If for some reason the owner(s) of that package are unwillingto do this, the alternative is to define the correct generic,save it in a special table and restore the non-generic version bycallingsetGenericImplicit.

Note that the package containing the function can define methods for the implicit generic aswell; when the implicit generic is made a real generic, those methodswill be included.

The usual reason for having anon-default implicit generic is to provide a non-default signature,and the usual reason forthat is to allow lazy evaluation ofsome arguments. All arguments in the signature of ageneric function must be evaluated at the time the function needs toselect a method.In the base functionwith() in the example below, evaluation of the argumentexpr must be delayed; therefore, it is excluded from the signature.

If you want to completely prohibit anyone from turning your functioninto a generic, callprohibitGeneric().

FunctionimplicitGeneric() returns the implicit genericversion of the named function. If there is no table of these or ifthis function is not in the table, the result of a simple callsetGeneric(name) is returned.

Value

FunctionimplicitGeneric() returns the implicit genericdefinition (and caches that definition the first time if it has toconstruct it).

The other functions exist for their side effect and return nothinguseful.

Implicit Generics for Base Functions

Implicit generic versions exist for some functions in the packagessupplied in the distribution ofR itself. These are stored in the‘methods’ package itself and will always be available.

As emphasized repeatedly in the documentation,setGeneric() calls for a function in another packageshould never have non-default settings for arguments such assignature.The reasoning applies specially to functions in supplied packages,since methods for these are likely to exist in multiple packages.A call toimplicitGeneric() will show the generic version.

See Also

setGeneric

Examples

### How we would make the function with() into a generic:## Since the second argument, 'expr' is used literally, we want## with() to only have "data" in the signature.## Not run:setGeneric("with", signature="data")## Now we could predefine methods for "with" if we wanted to.## When ready, we store the generic as implicit, and restore theoriginalsetGenericImplicit("with")## End(Not run)implicitGeneric("with")# (This implicit generic is stored in the 'methods' package.)

Description

For a class (or class definition, seegetClass andthe description of classclassRepresentation),give the names which are inherited from “above”, i.e., superclasses, rather than by this class' definition itself.

Usage

inheritedSlotNames(Class, where= topenv(parent.frame()))

Arguments

Value

character vector of slot names, orNULL.

See Also

slotNames,slot,setClass, etc.

Examples

.srch<- search()library(stats4)inheritedSlotNames("mle")if(require("Matrix", quietly=TRUE)) withAutoprint({  inheritedSlotNames("Matrix")# NULL## whereas  inheritedSlotNames("sparseMatrix")# --> Dim & Dimnames##  i.e. inherited from "Matrix" class  cl<- getClass("dgCMatrix")# six slots, etc  inheritedSlotNames(cl)# *all* six slots are inherited})## Not run:## detach package we've attached above:for(nin rev(which(is.na(match(search(), .srch)))))   try( detach(pos= n))## End(Not run)

Description

The arguments to functionnew to create an object from aparticular class can be interpreted specially for that class, by thedefinition of a method for functioninitialize for the class.This documentation describes some existing methods, and also outlineshow to write new ones.

Methods

signature(.Object = "ANY")

The default method forinitialize takes either named orunnamed arguments. Argument names must be the names of slots inthis class definition, and the corresponding arguments must bevalid objects for the slot (that is, have the same class asspecified for the slot, or some superclass of that class). If theobject comes from a superclass, it is not coerced strictly, sonormally it will retain its current class (specifically,as(object, Class, strict = FALSE)).

Unnamed arguments must be objects of this class, of one of itssuperclasses, or one of its subclasses (from the class, from aclass this class extends, or from a class that extends thisclass). If the object is from a superclass, this normally definessome of the slots in the object. If the object is from asubclass, the new object is that argument, coerced to the currentclass.

Unnamed arguments are processed first, in the order they appear.Then named arguments are processed. Therefore, explicit valuesfor slots always override any values inferred from superclass orsubclass arguments.

signature(.Object = "traceable")

Objects of a class that extendstraceable are used toimplement debug tracing (see classtraceable andtrace).

Theinitialize method for these classes takes specialargumentsdef, tracer, exit, at, print. The first of theseis the object to use as the original definition (e.g., afunction). The others correspond to the arguments totrace.

signature(.Object = "environment"),signature(.Object = ".environment")

Theinitialize method for environments takes a named listof objects to be used to initialize the environment. Subclassesof"environment" inherit an initialize method through".environment", which has the additional effect ofallocating a new environment. If you define your own method forsuch a subclass, be sure either to call the existing method viacallNextMethod or allocate an environment in yourmethod, since environments are references and are not duplicatedautomatically.

signature(.Object = "signature")

This is a method for internal use only.It takes an optionalfunctionDef argument to provide ageneric function with asignature slot to define theargument names. SeeMethods_Details for details.

Writing Initialization Methods

Initialization methods provide a general mechanism corresponding togenerator functions in other languages.

The arguments toinitialize are.Object and.... Nearly always,initialize is called fromnew,not directly. The.Object argument is then theprototype object from the class.

Two techniques are often appropriate forinitialize methods:special argument names andcallNextMethod.

You may want argument names that are more natural to your users thanthe (default) slot names. These will be the formal arguments toyour method definition, in addition to.Object (always) and... (optionally). For example, the method for class"traceable" documented above would be created by a call tosetMethod of the form:

    setMethod("initialize", "traceable",      function(.Object, def, tracer, exit, at, print) { .... }    )

In this example, no other arguments are meaningful, and the resultingmethod will throw an error if other names are supplied.

When your new class extends another class, you may want to call theinitialize method for this superclass (either a special method or thedefault). For example, suppose you want to define a method for yourclass, with special argumentx, but you also want users to beable to set slots specifically. If you wantx to override theslot information, the beginning of your method definition might looksomething like this:

    function(.Object, x, ...) {      Object <- callNextMethod(.Object, ...)      if(!missing(x)) { # do something with x

You could also choose to have the inherited method override, by firstinterpretingx, and then calling the next method.

Description

The majority of applications using methods and classes will be inRpackages implementing new computations for an application, using newclassesof objects that represent the data and results.Computations will be implemented usingmethods that implementfunctional computations when one or more of the arguments is an objectfrom these classes.

Calls to the functionssetClass() define the new classes;calls tosetMethod define the methods.These, along with ordinaryR computations, are sufficient to getstarted for most applications.

Classes are defined in terms of the data in them and what otherclasses of data they inherit from.Section ‘Defining Classes’ outlines the basic design of new classes.

Methods areR functions, often implementing basic computations asthey apply to the new classes of objects.Section ‘Defining Methods’ discusses basic requirements andspecial tools for defining methods.

The classes discussed here are the original functional classes.R also supports formal classes and methods similar to those in otherlanguages such as Python, in which methods are part of classdefinitions and invoked on an object.These are more appropriate when computations expect references toobjects that are persistent, making changes to the object over time.SeeReferenceClasses and Chapter 9 of the reference for thechoice between these and S4 classes.

Defining Classes

All objects inR belong to a class; ordinary vectors and other basicobjects are built-in (builtin-class).A new class is defined in terms of the namedslots that is hasand/or in terms of existing classes that it inherits from, orcontains (discussed in ‘Class Inheritance’ below).A call tosetClass() names a new class and uses the corresponding arguments todefine it.

For example, suppose we want a class of objects to represent acollection of positions, perhaps from GPS readings.A natural way to think of these inR would have vectors of numeric values forlatitude, longitude and altitude.A class with three corresponding slots could be defined by:

Pos <- setClass("Pos", slots = c(latitude = "numeric", longitude = "numeric", altitude = "numeric"))

The value returned is a function, typically assigned as here with thename of the class. Calling this function returns an object from theclass; its arguments are named with the slot names.If a function in the class had read the corresponding data, perhapsfrom a CSV file or from a data base, it could return an object fromthe class by:

Pos(latitude = x, longitude = y, altitude = z)

The slots are accessed by the@ operator; for example, ifg is an object fromthe class,g@latitude.

In addition to returning a generator function the call tosetClass() assigns a definition of the class in aspecial metadata object in the package's namespace.When the package is loaded into anR session, the class definition isadded to a table of known classes.

To make the class and the generating function publicly available, thepackage should includePOS inexportClasses() andexport() directives in itsNAMESPACE file:

exportClasses(Pos); export(Pos)

Defining Methods

Defining methods for anR function makes that functiongeneric.Instead of a call to the function always being carried out by the samemethod, there will be several alternatives.These are selected by matching the classes of the arguments in the call to atable in the generic function, indexed by classes for one or more formal arguments to thefunction, known as thesignatures for the methods.

A method definition then specifies three things: the name of thefunction, the signature and the method definition itself.The definition must be a function with the same formal arguments asthe generic.

For example, a method to make a plot of an object from class"Pos" could be defined by:

setMethod("plot", c("Pos", "missing"), function(x, y, ...) { plotPos(x, y) })

This method will match a call toplot() if the firstargument is from class"Pos" or a subclass of that.The second argument must be missing; only a missing argument matchesthat class in the signature.Any object will match class"ANY" in the corresponding positionof the signature.

Class Inheritance

A class may inherit all the slots and methods of one or more existingclasses by specifying the names of the inherited classes in thecontains = argument tosetClass().

To define a class that extends class"Pos" to a class"GPS" with a slot for the observation times:

GPS <- setClass("GPS", slots = c(time = "POSIXt"), contains = "Pos")

The inherited classes may be S4 classes, S3classes or basic data types.S3 classes need to be identified as such by a call tosetOldClass(); most S3 classes in the base package andmany in the other built-in packages are already declared, as is"POSIXt".If it had not been, the application package should contain:

setOldClass("POSIXt")

Inheriting from one of theR types is special. Objects from the newclass will have the same type. A classCurrency that contains numeric data plus a slot"unit"would be created by

Currency <- setClass("Currency", slots = c(unit = "character"), contains = "numeric")

Objects created from this class will have type"numeric" andinherit all the builtin arithmetic and other computations for thattype.Classes can only inherit from at most one such type; if the class doesnot inherit from a type, objects from the class will have type"S4".

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

Description

Functions to test inheritance relationships between an object and aclass or between two classes (extends).

Usage

is(object, class2)extends(class1, class2, maybe=TRUE, fullInfo=FALSE)

Arguments

Selecting Superclasses

A call toselectSuperClasses(cl) returns a list ofsuperclasses, similarly toextends(cl). Additional arguments restrict the class namesreturned to direct superclasses and/or to non-virtual classes.

Either way, programming with the result, particularly usingsapply, can be useful.

To find superclasses with more generally defined properties, one can programwith the result returned byextends when called with oneclass as argument.By default, the call returns a character vector including the name of the classitself and of all its superclasses.Alternatively,ifextends is called withfullInfo = TRUE, the return value is a named list, its names being the previouscharacter vector. The elements of the list corresponding tosuperclasses are objects of classSClassExtension. Of the information in these objects, one piece can be useful:the number of generations between the classes, given by the"distance" slot.

Programming with the result of the call toextends, particularly usingsapply, can select superclasses.The programming technique is to define a test function that returnsTRUE for superclasses or relationships obeying somerequirement. For example, to find only next-to-direct superclasses,use this function with the list of extension objects:

function(what) is(what, "SClassExtension") && what@distance == 2

or, to find only superclasses from"myPkg", use this functionwith the simple vector of names:

function(what) getClassDef(what)@package == "myPkg"

Giving such functions as an argument tosapply called on the output ofextends allows you to findsuperclasses with desired properties. See the examples below.

Note that the function using extension objects must test the class of its argument since,unfortunately for this purpose, the list returned byextends includesclass1 itself, as the objectTRUE.

Note

Prior toR 4.2.0 the code used the first elements ofclass1andclass2, silently, These are now required to be length-onecharacter vectors.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

See Also

Althoughinherits is defined for S3 classes, it hasbeen modified so that the result returned is nearly always equivalent tois, both for S4 and non-S4 objects. Since it is implementedin C, it is somewhat faster.The only non-equivalences arise from use ofsetIs,which should rarely be encountered.

Examples

## Not run:## this example can be run if package XRPython from CRAN is installed.supers<- extends("PythonInterface")## find all the superclasses from package XRfromXR<- sapply(supers,function(what) getClassDef(what)@package=="XR")## print themsupers[fromXR]## find all the superclasses at distance 2superRelations<- extends("PythonInterface", fullInfo=TRUE)dist2<- sapply(superRelations,function(what) is(what,"SClassExtension")&& what@distance==2)## print themnames(superRelations)[dist2]## End(Not run)

Description

These functions check for either a method or a class that has beensealed when it was defined, and which therefore cannot bere-defined.

Usage

isSealedMethod(f, signature, fdef, where)isSealedClass(Class, where)

Arguments

Details

In theR implementation of classes and methods, it is possible toseal the definition of either a class or a method. The basicclasses (numeric and other types of vectors, matrix and array data)are sealed. So also are the methods for the primitive functions onthose data types. The effect is that programmers cannot re-definethe meaning of these basic data types and computations. Moreprecisely, for primitive functions that depend on only one dataargument, methods cannot be specified for basic classes. Forfunctions (such as the arithmetic operators) that depend on twoarguments, methods can be specified ifone of those argumentsis a basic class, but not if both are.

Programmers can seal other class and method definitions by using thesealed argument tosetClass orsetMethod.

Value

The functions returnFALSE if the method or class is notsealed (including the case that it is not defined);TRUE ifit is.

References

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (For the R version.)

Chambers, John M. (1998)Programming with DataSpringer (For the original S4 version.)

Examples

## these are both TRUEisSealedMethod("+", c("numeric","character"))isSealedClass("matrix")setClass("track", slots= c(x="numeric", y="numeric"))## but this is FALSEisSealedClass("track")## and so is thisisSealedClass("A Name for an undefined Class")## and so are these, because only one of the two arguments is basicisSealedMethod("+", c("track","numeric"))isSealedMethod("+", c("numeric","track"))

Description

The virtual class"language" and the specificclasses that extend it represent unevaluated objects, as produced forexample by the parser or by functions such asquote.

Usage

### each of these classes corresponds to an unevaluated object### in the S language.### The class name can appear in method signatures,### and in a few other contexts (such as some calls to as())."(""<-""call""for""if""repeat""while""name""{"### Each of the classes above extends the virtual class"language"

Objects from the Class

"language" is a virtual class; no objects may be created fromit.

Objects from the other classes can be generated by a call tonew(Class, ...), whereClass is the quoted class name, andthe ... arguments are either empty or asingle object that isfrom this class (or an extension).

Methods

coerce

signature(from = "ANY", to = "call"). A methodexists foras(object, "call"), callingas.call().

Examples

showClass("language")is( quote(sin(x)))# "call"  "language"(ff<- new("if")); is(ff)# "if" "language"(ff<- new("for")); is(ff)# "for" "language"

Description

A version of methods lists that has been ‘linearized’for producing summary information. The actual objects from class"MethodsList" used for method dispatch are defined recursivelyover the arguments involved.

Objects from the Class

The functionlinearizeMlist converts an ordinary methodslist object into the linearized form.

Slots

methods:

Object of class"list", the methoddefinitions.

arguments:

Object of class"list", thecorresponding formal arguments, namely as many of the argumentsin the signature of the generic function as are active in therelevant method table.

classes:

Object of class"list", thecorresponding classes in the signatures.

generic:

Object of class"genericFunction";the generic function to which the methods correspond.

Future Note

The current version oflinearizeMlist does not take advantage oftheMethodDefinition class, and therefore does more work for lesseffect than it could. In particular, we may move to redefine both thefunction and the class to take advantage of the stored signatures.Don't write code depending precisely on the present form, although allthe current information will be obtainable in the future.

See Also

FunctionlinearizeMlist for the computation,and classMethodsList for the original, recursiveform.

Description

Local reference classes are modifiedReferenceClasses thatisolate the objects to the local frame. Therefore, they donotpropagate changes back to the calling environment. At the same time,they use the reference field semantics locally, avoiding the automaticduplication applied to standardR objects.

The current implementation has no special construction. To create alocal reference class, callsetRefClass() with acontains= argument that includes"localRefClass". Seethe example below.

Local reference classes operate essentially as do regular, functionalclasses inR; that is, changes are made by assignment and take placein the local frame.The essential difference is that replacement operations (like thechange to thetwiddle field in the example) do not causeduplication of the entire object, as would be the case for a formalclass or for data with attributes or in a named list.The purpose is to allow large objects in some fields that are notchanged along with potentially frequent changes to other fields, butwithout copying the large fields.

Usage

setRefClass(Class, fields=, contains= c("localRefClass",....),     methods=, where=,...)

Details

Localization of objects is only partially automated in the current implementation.Replacement expressions using the$<- operator are safe.

However, if reference methods for the class themselves modify fields,using<<-, for example, then one must ensure that the object is local to the relevant frame beforeany such method is called.Otherwise, standard reference class behavior still prevails.

There are two ways to ensure locality. The direct way is to invokethe specialmethodx$ensureLocal() on the object.The other way is to modify a field explicitly byx$field <- ...It'sonly necessary that one or the other of these happensonce for each object, in order to trigger the shallow copy thatprovides locality for the references. In the example below, we showboth mechanisms.

However it's done, localization must occurbefore any methods make changes. (Eventually, some use of codetools should at least largely automate this process, although it maybe difficult to guarantee success under arbitrary circumstances.)

Author(s)

John Chambers

Examples

## class "myIter" has a BigData field for the real (big) data## and a "twiddle" field for some parameters that it twiddles## ( for some reason)myIter<- setRefClass("myIter", contains="localRefClass",  fields= list(BigData="numeric", twiddle="numeric"))tw<- rnorm(3)x1<- myIter(BigData= rnorm(1000), twiddle= tw)# OK, not REALLY bigtwiddler<-function(x, n){  x$ensureLocal()# see the Details.  Not really needed in this examplefor(iin seq_len(n)){      x$twiddle<- x$twiddle+ rnorm(length(x$twiddle))## then do something ....## Snooping in gdb, etc will show that x$BigData is not copied}  return(x)}x2<- twiddler(x1,10)stopifnot(identical(x1$twiddle, tw),!identical(x1$twiddle, x2$twiddle))

Description

Constructs an object of classclassRepresentationto describe a particular class. Mostly a utility function, but you cancall it to create a class definition without assigning it, assetClass would do.

Usage

makeClassRepresentation(name, slots=list(), superClasses=character(),                        prototype=NULL, package, validity, access,                        version, sealed, virtual=NA, where)

Arguments

References

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (For the R version.)

Chambers, John M. (1998)Programming with DataSpringer (For the original S4 version.)

See Also

setClass

Description

This function writes a source file containing a call tosetMethod to define a method for the generic functionand signature supplied. By default the method definition is in linein the call, but can be made an external (previously assigned) function.

Usage

method.skeleton(generic, signature, file, external=FALSE, where)

Arguments

Value

Thefile argument, invisibly, but the function is used for its side effect.

See Also

setMethod,package.skeleton

Examples

setClass("track", slots= c(x="numeric", y="numeric"))method.skeleton("show","track")## writes show_track.Rmethod.skeleton("Ops", c("track","track"))## writes "Ops_track_track.R"## write multiple method skeletons to one filecon<- file("./Math_track.R","w")method.skeleton("Math","track", con)method.skeleton("exp","track", con)method.skeleton("log","track", con)close(con)

Description

These classes extend the basic class"function" whenfunctions are to be stored and used as method definitions.

Details

Method definition objects are functions with additional informationdefining how the function is being used as a method. Thetarget slot is the class signature for which the method willbe dispatched, and thedefined slot the signature for whichthe method was originally specified (that is, the one that appearedin some call tosetMethod).

Objects from the Class

The action of setting a method by a call tosetMethod creates an object of this class. It'sunwise to create them directly.

The class"SealedMethodDefinition" is created by a call tosetMethod with argumentsealed = TRUE. It hasthe same representation as"MethodDefinition".

Slots

.Data:

Object of class"function"; the datapart of the definition.

target:

Object of class"signature"; thesignature for which the method was wanted.

defined:

Object of class"signature"; thesignature for which a method was found. If the method wasinherited, this will not be identical totarget.

generic:

Object of class"character"; the functionfor which the method was created.

Extends

Class"function", from data part.
Class"PossibleMethod", directly.
Class"optionalMethod", by class"function".

See Also

classMethodsList for the objectsdefining sets of methods associated with a particular genericfunction. The individual method definitions stored in these objectsare from classMethodDefinition, or an extension.ClassMethodWithNext for an extension used bycallNextMethod.

Description

You have navigated to an old link to documentation of S4 methods.

For basic use of classes and methods, seeIntroduction; tocreate new method definitions, seesetMethod; fortechnical details on S4 methods, seeMethods_Details.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

Description

This documentation covers some general topics on how methodswork and how themethods package interacts with the rest ofR. Theinformation is usually not needed to get started with methods andclasses, but may be helpful for moderately ambitious projects, or whensomething doesn't work as expected.

For additional information see documentation forthe important steps: (setMethod(),setClass() andsetGeneric()). AlsoMethods_for_Nongenerics on defining formal methods forfunctions that are not currently generic functions;Methods_for_S3 for the relation to S3 classes and methods;Classes_Details for class definitions andChapters 9 and 10 of the reference.

How Methods Work

A call to a generic function selects a method matching the actualarguments in the call. The body of the method is evaluated in theframe of the call to the generic function.A generic function is identified by its name and by the package towhich it correspond. Unlike ordinary functions, the generic has aslot that specifies its package.

In anR session, there is one version of each such generic,regardless of where the call to that generic originated, andthe generic function has a table of all the methods currentlyavailable for it; that is, all the methodsin packages currently loaded into the session.

Methods are frequently defined for functions that are non-generic intheir original package,.for example, for functionplot() inpackagegraphics.An identical version of the corresponding generic function may existin several packages. All methods will be dispatched consistentlyfrom theR session.

EachR package with a call tosetMethod in its source codewill include a methods metadata object for that generic.When the package is loaded into anR session, the methods for eachgeneric function arecached, that is, added to theenvironment of the generic function. This merged table of methods is used todispatch or select methods from the generic, using class inheritanceand possibly group generic functions (seeGroupGenericFunctions) to find an applicable method.See the “Method Selection and Dispatch” section below.The caching computations ensure that only one version of eachgeneric function is visible globally; although different attachedpackages may contain a copy of the generic function, these behaveidentically with respect to method selection.

In contrast, it is possible for the same function name to refer tomore than one generic function, when these have differentpackage slots. In the latter case,R considers thefunctions unrelated: A generic function is defined by thecombination of name and package. See the “Generic Functions”section below.

The methods for a generic are stored according to thecorrespondingsignature in the call tosetMethodthat defined the method. The signature associates oneclass name with each of a subset of the formal arguments to thegeneric function. Which formal arguments are available, and theorder in which they appear, are determined by the"signature"slot of the generic function itself. By default, the signature of thegeneric consists of all the formal arguments except ..., in theorder they appear in the function definition.

Trailing arguments in the signature of the generic will beinactive if nomethod has yet been specified that included those arguments in its signature.Inactive arguments are not needed or used in labeling the cachedmethods. (The distinction does not change which methods aredispatched, but ignoring inactive arguments improves theefficiency of dispatch.)

All arguments in the signature of the generic function will be evaluated when thefunction is called, rather than using lazyevaluation. Therefore, it's important toexcludefrom the signature any arguments that need to be dealt withsymbolically (such as theexpr argument to functionwith). Note that only actual arguments areevaluated, not default expressions.A missing argument enters into the method selection as class"missing".

The cached methods are stored in anenvironment object. The names used for assignment are aconcatenation of the class names for the active arguments in the method signature.

Method Selection: Details

When a call to a generic function is evaluated, a method is selected correspondingto 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 bythe string value ofclass(x) for each non-missingargument, and"missing" for each missing argument.If no method is found directly for the actual arguments in a call to ageneric function, an attempt is made to match the available methods tothe arguments by using the superclass information about the actualclasses.A method found by this search is cachedin the generic function so that future calls with the same argument classes willnot require repeating the search. In any likely application, thesearch for inherited methods will be a negligible overhead.

Each class definition may include a list of one or more directsuperclasses of the new class.The simplest and most common specification is by thecontains= argument inthe call tosetClass.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 whichit is a member.Class unions are created bya call tosetClassUnion.Additional members can be added to the union by a simple call tosetIs.Superclasses specified by either mechanism are thedirect superclasses.

Inheritance specified in either of these forms issimple in thesense that all the information needed for the superclass is assertedto be directly available from the object.R inherited from S a more general form of inheritance in whichinheritance may require some transformation or be conditional on atest.This more general form has not proved to be useful in generalpractical situations. Since it also adds some computational costsnon-simple inheritance is not recommended. SeesetIsfor the general version.

The direct superclasses themselves mayhave direct superclasses andsimilarly through further generations. Putting all this information together producesthe full list of superclasses for this class.The superclass list is included in the definition of the class that iscached during theR session.Thedistance between the two classes is defined to be thenumber of generations:1 for direct superclasses (regardless of which mechanismdefined them), then2 for the direct superclasses of thoseclasses, and so on.To see all the superclasses, with their distance, print the classdefinition by callinggetClass.In addition, any class implicitly has class"ANY" as a superclass. Thedistance to"ANY" is treated as larger than the distance to anyactual class.The special class"missing" corresponding to missing argumentshas only"ANY" as a superclass, while"ANY" has nosuperclasses.

When a method is to be selected by inheritance, a search is made inthe table for all methods corresponding to a combination ofeither the direct class or one of its superclasses, for each argumentin the active signature.For an example, suppose there is only one argument in the signature and that the class ofthe corresponding object was"dgeMatrix" (from the recommended packageMatrix).This class has (currently) three direct superclasses and through theseadditional superclasses at distances 2 through 4.A method that had been defined for any of these classes or for class"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 willgenerate a similar list of inherited classes.The possible matches are now all the combinations of classes from eachargument (think of the functionouter generating an array ofall possible combinations).The search now finds all the methods matching any of this combinationof classes.For each argument, the distance to the superclass defines whichmethod(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) foreach argument.

The end result is that zero, one or more methods may be “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 isprinted noting which method was selected (the first methodlexicographically in the ordering) and what other methods could havebeen 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 ambiguousinheritance by callingtestInheritedMethods.

Cached inherited selections arenot themselves used in future inheritance searches, since that could resultin invalid selections.If you want inheritance computations to be done again (for example,because a newly loaded package has a more direct method than onethat has already been used in this session), callresetGeneric. Because classes and methods involvingthem tend to come from the same package, the current implementationdoes not reset all generics every time a new package is loaded.

Besides being initiated through calls to the generic function, methodselection can be done explicitly by calling the functionselectMethod.Note that some computations may use this function directly, withoptional arguments.The prime example is the use ofcoerce() methods byfunctionas().There has been some confusion from comparing coerce methods to a calltoselectMethod with other options.

Method Evaluation: Details

Once a method has been selected, the evaluator creates a new contextin which a call to the method is evaluated.The context is initialized with the arguments from the call to thegeneric function.These arguments are not rematched. All the arguments in the signatureof the generic will have been evaluated (including any that arecurrently inactive); arguments that are not in the signature will obeythe usual lazy evaluation rules of the language.If an argument was missing in the call, its default expression if anywillnot have been evaluated, since method dispatch always usesclassmissing for such arguments.

A call to a generic function therefore has two contexts: one for thefunction and a second for the method.The argument objects will be copied to the second context, but not anylocal objects created in a nonstandard generic function.The other important distinction is that the parent(“enclosing”) environment of the second context is the environmentof the method as a function, so that allR programming techniquesusing such environments apply to method definitions as ordinary functions.

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

Generic Functions

In principle, a generic function could be any function that evaluatesa call tostandardGeneric(), the internal function that selectsa method and evaluates a call to the selected method. In practice,generic functions are special objects that in addition to being from asubclass of class"function" also extend the classgenericFunction. Such objects have slots to defineinformation needed to deal with their methods. They also havespecialized environments, containing the tables used in methodselection.

The slots"generic" and"package" in the object are thecharacter string names of the generic function itself and of thepackage from which the function is defined.As with classes, generic functions are uniquely defined inR by thecombination of the two names.There can be generic functions of the same name associated withdifferent packages (although inevitably keeping such functions cleanlydistinguished is not always easy).On the other hand,R will enforce that only one definition of ageneric function can be associated with a particular combination offunction and package name, in the current session or other activeversion ofR.

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 changeduring a session, as additional packages are loaded.Each table must be consistent in the signature assumed for the genericfunction.

R distinguishesstandard andnonstandard genericfunctions, with the former having a function body that does nothingbut dispatch a method.For the most part, the distinction is just one of simplicity: knowingthat a generic function only dispatches a method call allows someefficiencies and also removes some uncertainties.

In most cases, the generic function is the visible functioncorresponding to that name, in the corresponding package.There are two exceptions,implicit genericfunctions and the special computations required to deal withR'sprimitive functions.Packages can contain a table of implicit generic versions of functionsin the package, if the package wishes to leave a function non-genericbut to constrain what the function would be like if it were generic.Such implicit generic functions are created during the installation ofthe package, essentially by defining the generic function andpossibly methods for it, and then reverting the function to itsnon-generic form. (SeeimplicitGeneric for how this is done.)The mechanism is mainly used for functions in the older packages inR, which may prefer to ignore S4 methods.Even in this case, the actual mechanism is only needed if somethingspecial has to be specified.All functions have a corresponding implicit generic version definedautomatically (an implicit, implicit generic function one might say).This function is a standard generic with the same arguments as thenon-generic function, with the non-generic version as the default (and only)method, and with the generic signature being all the formal argumentsexcept ....

The implicit generic mechanism is needed only to override some aspectof the default definition.One reason to do so would be to remove some arguments from thesignature.Arguments that may need to be interpreted literally, or for which thelazy evaluation mechanism of the language is needed, mustnotbe included in the signature of the generic function, since allarguments in the signature will be evaluated in order to select amethod.For example, the argumentexpr to the functionwith is treated literally and must therefore be excludedfrom the signature.

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

Generic functions will also be defined but not obviously visible forfunctions implemented asprimitive functions in the basepackage.Primitive functions look like ordinary functions when printed but arein fact not function objects but objects of two types interpreted bytheR evaluator to call underlying C code directly.Since their entire justification is efficiency,R refuses to hideprimitives behind a generic function object.Methods may be defined for most primitives, and corresponding metadataobjects will be created to store them.Calls to the primitive still go directly to the C code, which willsometimes check for applicable methods.The definition of “sometimes” is that methods must have beendetected for the function in some package loaded in the session andisS4(x) isTRUE for the first argument (or for thesecond argument, in the case of binary operators).You can test whether methods have been detected by callingisGeneric for the relevant function and you can examinethe generic function by callinggetGeneric, whether ornot methods have been detected.For more on generic functions, see the references and also section 2of theR Internals document supplied withR.

Method Definitions

All method definitions are stored as objects from theMethodDefinition class.Like the class of generic functions, this class extends ordinaryRfunctions with some additional slots:"generic", containing thename and package of the generic function, and two signature slots,"defined" and"target", the first being the signature supplied whenthe method was defined by a call tosetMethod.The"target" slot starts off equal to the"defined"slot. When an inherited method is cached after being selected, asdescribed above, a copy is made with the appropriate"target" signature.Output fromshowMethods, for example, includes bothsignatures.

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

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (Section 10.5 for some details.)

See Also

For more specific information, seesetGeneric,setMethod, andsetClass.

For the use of ... in methods, seedotsMethods.

Description

In writing methods for anR package, it's common for these methods toapply to a function (in another package) that is not generic in thatpackage; that is, there are no formal methods for the function in itsown package, although it may have S3 methods.The programming in this case involves one extra step, to callsetGeneric() to declare that the functionisgeneric in your package.

Calls to the function in your package will then use all methodsdefined there or in any other loaded package that creates the samegeneric function. Similarly, calls to the function in those packageswill use your methods.

The original version, however, remains non-generic. Callsin that package or in other packages that use that version will not dispatch your methodsexcept for special circumstances:

1. If the function is one of the primitive functions that acceptmethods, the internal C implementation will dispatch methods if oneof the arguments is an S4 object, as should be the case.

2. If the other version of the function dispatches S3 methodsand your methods are also registered as S3 methods, themethod will usually be dispatched as that S3 method.

3. Otherwise, you will need to ensure that all calls to thefunction come from a package in which the function is generic,perhaps by copying code to your package.

Details and the underlying reasons are discussed in the following sections.

Generic and Non-Generic Calls

Creating methods for a function (any function) in a package means thatcalls to the function in that package will select methods according tothe actual arguments.However, if the function was originally a non-generic in anotherpackage, calls to the function from that package willnotdispatch methods.In addition, calls from any third package that imports the non-generic versionwill also not dispatch methods.This section considers the reason and how one might deal with theconsequences.

The reason is simply theR namespace mechanism and its role inevaluating function calls.When a name (such as the name of a function) needs to be evaluated ina call to a function from some package, the evaluator looks first in the frame of the call,then in the namespace of the package and then in the imports to thatpackage.

Defining methods for a function in a package ensures that calls to thefunction in that package will select the methods, because a genericversion of the function is created in the namespace.Similarly, calls from another package that has or imports the genericversion will select methods.Because the generic versions are identical, all methods will beavailable in all these packages.

However, calls from any package that imports the old version or justselects it from the search list will usuallynot select methods.

As an example, consider the functiondata.frame() in the base package.This function takes any number of objects as arguments and attempts to combinethem as variables into a data frame object.It does this by callingas.data.frame(), also in thebase package, for each of the objects.

A reasonable goal would be to extend the classes of objects that canbe included in a data frame by defining methods foras.data.frame().But calls todata.frame(),will still use the version of that function in the base package, whichcontinues to call the non-genericas.data.frame() inthat package.

The details of what happens and options for dealing with it depend onthe form of the function: a primitive function; a function thatdispatches S3 methods; or an ordinaryR function.

Primitive functions are not actualR function objects.They go directly to internal C code.Some of them, however, have been implemented to recognize methods.These functions dispatch both S4 and S3 methods fromthe internal C code.There is no explicit generic function, either S3 or S4.The internal code looks for S4 methods if the firstargument, or either of the arguments in the case of a binary operator,is an S4 object.If no S4 method is found, a search is made for an S3 method.So defining methods for these functions works as long as the relevantclasses have been defined, which should always be the case.

A function dispatches S3 methods by callingUseMethod(), which doesnot look forformal methods regardless of whether the first argument is an S4object or not.This applies to theas.data.frame() example above.To have methods called in this situation, your package must also define themethod as an S3 method, if possible. See section ‘S3“Generic” Functions’.

In the third possibility, the function is defined with no expectationof methods.For example, the base package has a number of functions that computenumerical decompositions of matrix arguments.Some, such aschol() andqr()are implemented to dispatch S3 methods; others, such assvd() are implemented directly as a specificcomputation.A generic version of the latter functions can be written and calleddirectly to define formal methods, but no code in another package thatdoes not import this generic version will dispatch such methods.

In this case, you need to have the generic version used in all the indirect calls to thefunction supplying arguments that should dispatch methods.This may require supplying new functions that dispatch methods andthen call the function they replace.For example, if S3 methods did not work foras.data.frame(), one could call a function thatapplied the generic version to all its arguments and then calleddata.frame() as a replacement for that function.If all else fails, it might be necessary to copy over the relevantfunctions so that they would find the generic versions.

S3 “Generic” Functions

S3 method dispatch looks at the class of the firstargument.S3 methods are ordinary functions with the same arguments as thegeneric function.The “signature” of an S3 method is identified by the name towhich the method is assigned, composed of the name of thegeneric function, followed by".", followed by the name of the class.For details, seeUseMethod.

To implement a method for one of these functions corresponding to S4classes, there are two possibilities: either an S4 method or an S3 method with theS4 class name.The S3 method is only possible if the intended signature has thefirst argument and nothing else.In this case,the recommended approach is to define the S3 method and also supply theidentical function as the definition of the S4 method.If the S3 generic function wasf3(x, ...) and the S4 class forthe new method was"myClass":

f3.myClass <- function(x, ...) { ..... }

setMethod("f3", "myClass", f3.myClass)

Defining both methods usually ensures that all calls to the originalfunction will dispatch the intended method.The S4 method alone would not be called from other packages using theoriginal version of the function.On the other hand,an S3 method alone will not be called if there isanyeligible non-default S4 method.

S4 and S3 method selection are designed to follow compatible rules ofinheritance, as far as possible.S3 classes can be used for any S4 method selection, provided that theS3 classes have been registered by a call tosetOldClass, with that call specifying the correct S3inheritance pattern.S4 classes can be used for any S3 method selection; when an S4 objectis detected, S3 method selection uses the contents ofextends(class(x)) as the equivalent of the S3inheritance (the inheritance is cached after the first call).

An existing S3 method may not behave as desired for an S4 subclass, inwhich case utilities such asasS3 andS3Part may be useful. If the S3 method fails on the S4object,asS3(x) may be passed instead; if the object returnedby the S3 method needs to be incorporated in the S4 object, thereplacement function forS3Part may be useful.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

See Also

Methods_for_S3 for suggested implementation of methodsthat work for both S3 and S4 dispatch.

Examples

## A class that extends a registered S3 class inherits that class' S3## methods.setClass("myFrame", contains="data.frame",         slots= c(timestamps="POSIXt"))df1<- data.frame(x=1:10, y= rnorm(10), z= sample(letters,10))mydf1<- new("myFrame", df1, timestamps= Sys.time())## "myFrame" objects inherit "data.frame" S3 methods; e.g., for `[`mydf1[1:2,]# a data frame object (with extra attributes)## a method explicitly for "myFrame" classsetMethod("[",    signature(x="myFrame"),function(x, i, j,..., drop=TRUE){        S3Part(x)<- callNextMethod()        x@timestamps<- c(Sys.time(), as.POSIXct(x@timestamps))        x})mydf1[1:2,]setClass("myDateTime", contains="POSIXt")now<- Sys.time()# class(now) is c("POSIXct", "POSIXt")nowLt<- as.POSIXlt(now)# class(nowLt) is c("POSIXlt", "POSIXt")mCt<- new("myDateTime", now)mLt<- new("myDateTime", nowLt)## S3 methods for an S4 object will be selected using S4 inheritance## Objects mCt and mLt have different S3Class() values, but this is## not used.f3<-function(x)UseMethod("f3")# an S3 generic to illustrate inheritancef3.POSIXct<-function(x)"The POSIXct result"f3.POSIXlt<-function(x)"The POSIXlt result"f3.POSIXt<-function(x)"The POSIXt result"stopifnot(identical(f3(mCt), f3.POSIXt(mCt)))stopifnot(identical(f3(mLt), f3.POSIXt(mLt)))## An S4 object selects S3 methods according to its S4 "inheritance"setClass("classA", contains="numeric",         slots= c(realData="numeric"))Math.classA<-function(x){(getFunction(.Generic))(x@realData)}setMethod("Math","classA", Math.classA)x<- new("classA", log(1:10), realData=1:10)stopifnot(identical(abs(x),1:10))setClass("classB", contains="classA")y<- new("classB", x)stopifnot(identical(abs(y), abs(x)))# (version 2.9.0 or earlier fails here)## an S3 generic: just for demonstration purposesf3<-function(x,...) UseMethod("f3")f3.default<-function(x,...)"Default f3"## S3 method (only) for classAf3.classA<-function(x,...)"Class classA for f3"## S3 and S4 method for numericf3.numeric<-function(x,...)"Class numeric for f3"setMethod("f3","numeric", f3.numeric)## The S3 method for classA and the closest inherited S3 method for classB## are not found.f3(x); f3(y)# both choose "numeric" method## to obtain the natural inheritance, set identical S3 and S4 methodssetMethod("f3","classA", f3.classA)f3(x); f3(y)# now both choose "classA" method## Need to define an S3 as well as S4 method to use on an S3 object## or if called from a package without the S4 genericMathFun<-function(x){# a smarter "data.frame" method for Math groupfor(iin seq_len(ncol(x))[sapply(x, is.numeric)])    x[, i]<-(getFunction(.Generic))(x[, i])  x}setMethod("Math","data.frame", MathFun)## S4 method works for an S4 class containing data.frame,## but not for data.frame objects (not S4 objects)try(logIris<- log(iris))#gets an error from the old method## Define an S3 method with the same computationMath.data.frame<- MathFunlogIris<- log(iris)

Description

The S3 and S4 software inR are two generations implementingfunctional 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 requiremore programming.

In modernR, the two versions attempt to work together. Thisdocumentation outlines how to write methods for both systems bydefining an S4 method for a function that dispatches S3 methods.

The systems can also be combined by using an S3 class with S4 methoddispatch or in S4 class definitions. SeesetOldClass.

S3 Method Dispatch

TheR evaluator will ‘dispatch’ a method from a function calleither when the body of the function calls the special primitiveUseMethod or when the call is to one of the builtinprimitives such as themath functions or the binary operators.

S3 method dispatch looks at the class of the firstargument or the class of eitherargument in a call to one of the primitive binary operators.In pure S3 situations, ‘class’ in this context means the classattribute or the implied class for a basic data type such as"numeric".The first S3 method that matches a name in the class is called and thevalue of that call is the value of the original function call.For details, seeS3Methods.

In modernR, a functionmeth in a package is registered as an S3 methodfor functionfun and classClass byincluding in the package'sNAMESPACE file the directive

S3method(fun, Class, meth)

By default (and traditionally), the third argument is taken to be thefunctionfun.Class; that is,the name of thegeneric function, followed by".", followed by the name of theclass.

As with S4 methods, a method that has been registered will be added toa table of methods for this function when the corresponding package isloaded into the session.Older versions ofR, copying the mechanism in S, looked for themethod in the current search list, but packages should now alwaysregister S3 methods rather than requiring the package to be attached.

Methods for S4 Classes

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

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

As an example, suppose an S4 class"uncased" is defined,extending"character" and intending to ignore upper- andlower-case.The base functionunique dispatches S3 methods.To define the class and a method for this function:

setClass("uncased", contains = "character")

unique.uncased <- function(x, incomparables = FALSE, ...) nextMethod(tolower(x))

setMethod("unique", "uncased", unique.uncased)

In addition, theNAMESPACE for the package should contain:

S3method(unique, uncased)

exportMethods(unique)

The result is to define identical S3 and S4 methods and ensure that allcalls tounique will dispatch that method when appropriate.

Details

The reasons for defining both S3 and S4 methods are as follows:

1. An S4 method alone will not be seen if the S3 generic functionis called directly. This will be the case, for example, if somefunction callsunique() from a package that does not makethat function an S4 generic.

   However, primitive functions and operatorsare exceptions: The internal C code will look for S4 methodsif and only if the object is an S4 object. S4 method dispatchwould be used to dispatch any binary operator calls where eitherof the operands was an S4 object, for example.

2. An S3 method alone will not be called if there isanyeligible non-default S4 method.

   So if a package defined an S3method forunique for an S4 class but another packagedefined an S4 method for a superclass of that class, thesuperclass method would be chosen, probably not what wasintended.

S4 and S3 method selection are designed to follow compatible rules ofinheritance, as far as possible.S3 classes can be used for any S4 method selection, provided that theS3 classes have been registered by a call tosetOldClass, with that call specifying the correct S3inheritance pattern.S4 classes can be used for any S3 method selection; when an S4 objectis detected, S3 method selection uses the contents ofextends(class(x)) as the equivalent of the S3inheritance (the inheritance is cached after the first call).

For the details of S4 and S3dispatch seeMethods_Details andS3Methods.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

Description

Class of method definitions set up forcallNextMethod

Objects from the Class

Objects from this class are generated as a side-effect of calls tocallNextMethod.

Slots

.Data:

Object of class"function"; the actualfunction definition.

nextMethod:

Object of class"PossibleMethod"the method to use in response to acallNextMethod()call.

excluded:

Object of class"list"; one or moresignatures excluded in finding the next method.

target:

Object of class"signature", from class"MethodDefinition"

defined:

Object of class"signature", fromclass"MethodDefinition"

generic:

Object of class"character"; the functionfor which the method was created.

Extends

Class"MethodDefinition", directly.
Class"function", from data part.
Class"PossibleMethod", by class"MethodDefinition".
Class"optionalMethod", by class"MethodDefinition".

Methods

findNextMethod

signature(method = "MethodWithNext"):used internally by method dispatch.

show

signature(object = "MethodWithNext")

See Also

callNextMethod, andclassMethodDefinition.

Description

A call tonew returns a newly allocated object from theclass identified by the first argument. This call in turn calls themethod for the generic functioninitialize corresponding tothe specified class, passing the... arguments to thismethod.In the default method forinitialize(), named arguments providevalues for the corresponding slots and unnamed arguments must beobjects from superclasses of this class.

A call to a generating function for a class (seesetClass) will pass its ... arguments to a corresponding call tonew().

Usage

new(Class,...)initialize(.Object,...)

Arguments

Initialize Methods

The generic functioninitialize is not called directly.A call tonew begins by copying the prototype object fromthe class definition, and then callsinitialize() with thisobject as the first argument, followed by the ... arguments.

The interpretation of the... arguments in a call to agenerator function or tonew() can be specialized toparticular classes, by defining an appropriate method for"initialize".

In the default method, unnamed arguments in the... are interpreted asobjects from a superclass, and named arguments are interpreted asobjects to be assigned into the correspondingly named slots.Explicitly specified slots override inherited information for the same slot,regardless of the order in which the arguments appear.

Theinitialize methods do not have to have... astheir second argument (see the examples). Initialize methods areoften written when the natural parameters describing the new objectare not the names of the slots. If you do define such a method,you should include... as a formal argument, and your method should pass sucharguments along viacallNextMethod. This helps the definition of future subclasses of your class. If thesehave additional slots and your methoddoesnot have this argument, it will be difficult for theseslots to be included in an initializing call.

Seeinitialize-methods for a discussion of some classes with existingmethods.

Methods forinitialize can be inherited only by simpleinheritance, since it is a requirement that the method return anobject from the target class. See thesimpleInheritanceOnly argument tosetGeneric andthe discussion insetIs for the general concept.

Note that the basic vector classes,"numeric", etc. areimplicitly defined, so one can usenew for these classes.The ... arguments are interpreted as objects of this type and areconcatenated into the resulting vector.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

See Also

Classes_Details for details of class definitions, andsetOldClass for the relation to S3 classes.

Examples

## using the definition of class "track" from \link{setClass}## a new object with two slots specifiedt1<- new("track", x= seq_along(ydata), y= ydata)# a new object including an object from a superclass, plus a slott2<- new("trackCurve", t1, smooth= ysmooth)### define a method for initialize, to ensure that new objects have### equal-length x and y slots.  In this version, the slots must still be### supplied by name.setMethod("initialize","track",function(.Object,...){      .Object<- callNextMethod()if(length(.Object@x)!= length(.Object@y))      stop("specified x and y of different lengths")      .Object})### An alternative version that allows x and y to be supplied### unnamed.  A still more friendly version would make the default x### a vector of the same length as y, and vice versa.setMethod("initialize","track",function(.Object, x= numeric(0), y= numeric(0),...){              .Object<- callNextMethod(.Object,...)if(length(x)!= length(y))                  stop("specified x and y of different lengths")              .Object@x<- x              .Object@y<- y              .Object})

Description

S4 classes that are defined to extend one of the basicvector classes should contain the classstructure if they behave like structures; thatis, if they should retain their class behavior under math functionsor operators, so long as their length is unchanged.On the other hand, if their class depends on the values in theobject, not just its structure, then they should lose that classunder any such transformations. In the latter case, they should bedefined to containnonStructure.

If neither of these strategies applies, the class likely needs somemethods of its own forOps,Math, and/orother generic functions. What is not usually a good idea is to allowsuch computations to drop down to the default, base code. This isinconsistent with most definitions of such classes.

Methods

Methods are defined for operators and math functions (groupsOps,Math andMath2). Inall cases the result is an ordinary vector of the appropriate type.

References

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer.

See Also

structure

Examples

setClass("NumericNotStructure", contains= c("numeric","nonStructure"))xx<- new("NumericNotStructure",1:10)xx+1# vectorlog(xx)# vectorsample(xx)# vector

Description

This class of objects is used to represent ordinary character stringobject names, extended with apackage slot naming the packageassociated with each object.

Objects from the Class

The functiongetGenerics returns an object of this class.

Slots

.Data:

Object of class"character": theobject names.

package:

Object of class"character" thepackage names.

Extends

Class"character", from data part.
Class"vector", by class"character".

See Also

Methods for general background.

Description

Assembles all relevant slot and method information for a class, withminimal markup for Rd processing; no QC facilities at present.

Usage

promptClass(clName, filename=NULL, type="class",            keywords="classes", where= topenv(parent.frame()),            generatorName= clName)

Arguments

Details

The class definition is found on the search list. Using thatdefinition, information about classes extended and slots isdetermined.

In addition, the currently available generics with methods for thisclass are found (usinggetGenerics). Note that thesemethods need not be in the same environment as the class definition; inparticular, this part of the output may depend on which packages arecurrently in the search list.

As with other prompt-style functions, unlessfilename isNA, the documentation shell is written to a file, and a messageabout this is given. The file will need editing to give informationabout themeaning of the class. The output ofpromptClass can only contain information from the metadataabout the formal definition and how it is used.

Iffilename isNA, a list-style representation of thedocumentation shell is created and returned. Writing the shell to afile amounts tocat(unlist(x), file = filename, sep = "\n"),wherex is the list-style representation.

If a generator function is found assigned under the class name orthe optionalgeneratorName, skeleton documentation for thatfunction is added to the file.

Value

Iffilename isNA, a list-style representation of thedocumentation shell. Otherwise, the name of the file written to isreturned invisibly.

Author(s)

VJ Carey[email protected] and John Chambers

References

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (For the R version.)

Chambers, John M. (1998)Programming with DataSpringer (For the original S4 version.)

See Also

prompt for documentation of functions,promptMethods for documentation of method definitions.

For processing of the edited documentation, either useR CMDRdconv,or include the edited file in the ‘man’ subdirectory of apackage.

Examples

## Not run: > promptClass("track")A shell of class documentation has been written to thefile"track-class.Rd".## End(Not run)

Description

Generates a shell of documentation for the methods of a genericfunction.

Usage

promptMethods(f, filename=NULL, methods)

Arguments

Details

Iffilename isFALSE, the text created is returned,presumably to be inserted some other documentation file, such as thedocumentation of the generic function itself (seeprompt).

Iffilename isNA, a list-style representation of thedocumentation shell is created and returned. Writing the shell to afile amounts tocat(unlist(x), file = filename, sep = "\n"),wherex is the list-style representation.

Otherwise, the documentation shell is written to the file specified byfilename.

Value

Iffilename isFALSE, the text generated;iffilename isNA, a list-style representation of thedocumentation shell.Otherwise, the name of the file written to is returned invisibly.

References

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (For the R version.)

Chambers, John M. (1998)Programming with DataSpringer (For the original S4 version.)

See Also

prompt andpromptClass

Objects With Fields Treated by Reference (OOP-style)

Description

The software described here allows packages to definereferenceclasses that behave in the style of “OOP” languages such as Java andC++.This model forOOP differs from the functional model implemented by S4(and S3) classes and methods, in which methods are defined for genericfunctions.Methods for reference classes are “encapsulated” in the class definition.

Computations with objects from reference classes invoke methods on them andextract or set their fields, using the`$` operator inR.The field and method computations potentially modify the object.All computations referring to the objects see the modifications, in contrast tothe usual functional programming model inR.

A call tosetRefClass in the source code for a package defines the class and returns a generator object.Subsequent calls to the$methods() method of the generator will define methods for the class.As with functional classes, if the class is exported from the package,it will be available when the package is loaded.

Methods areR functions. In their usual implementation, they refer to fieldsand other methods of the class directly by name. See the section on“Writing Reference Methods”.

As with functional classes, reference classes can inherit from otherreference classes via acontains= argument tosetRefClass. Fields and methods will be inherited, except where thenew class overrides method definitions. See the section on “Inheritance”.

Usage

setRefClass(Class, fields=, contains=, methods=,     where=, inheritPackage=,...)getRefClass(Class, where=)

Arguments

Value

setRefClass() returns a generator function suitable forcreating objects from the class, invisibly. A call to this functiontakes any number of arguments,which will be passed on to the initialize method. If noinitialize method is defined for the class or one of itssuperclasses, the default method expects named arguments with thename of one of the fields and unnamed arguments, if any, that areobjects from one of the superclasses of this class (but onlysuperclasses that are themselves reference classes have any effect).

The generator function is similar to the S4 generator functionreturned bysetClass. In addition to being a generatorfunction, however, it is also a reference class generator object,with reference class methods for various utilities. See the sectionon reference class generator objects below.

getRefClass() also returns the generator function for theclass. Note that the package slot in the value is the correct packagefrom the class definition, regardless of thewhere argument,which is used only tofind the class if necessary.

Reference Objects

Normal objects inR are passed as arguments in function calls consistently withfunctional programming semantics; that is, changes made to an objectpassed as an argument are local to the function call. The object thatsupplied the argument is unchanged.

The functional model (sometimes called pass-by-value, although this isinaccurate forR) issuitable for many statistical computations and is implicit, forexample, in the basicR software for fitting statistical models.In some other situations, one would like all the code dealing with anobject to see the exact same content, so that changes made in anycomputation would be reflected everywhere.This is often suitable if the object has some “objective”reality, such as a window in a user interface.

In addition, commonly used languages, including Java, C++ and manyothers, support a version of classes and methods assuming referencesemantics.The corresponding programming mechanismis to invoke a method on an object.In theR syntax we use"$" for this operation; one invokes a method,m1 say, on an objectx by the expressionx$m1(...).

Methods in this paradigm are associated with the object, or moreprecisely with the class of the object, as opposed to methods in afunction-based class/method system, which are fundamentally associatedwith the function (inR, for example, a generic function in anRsession has a table of all its currently known methods).In this document “methods for a class” as opposed to“methods for a function” will make the distinction.

Objects in this paradigm usually have named fields on whichthe methods operate.In theR implementation, the fields are defined when the class iscreated.The field itself can optionally have a specified class, meaning that only objectsfrom this class or one of its subclasses can be assigned to the field.By default, fields have class"ANY".

Fields are accessed by reference.In particular, invoking a method may modify the content ofthe fields.

Programming for such classes involves writing new methods for aparticular class.In theR implementation, these methods areR functions, with zero ormore formal arguments.For standard reference methods, the object itself is not an explicitargument to the method.Instead, fields and methods for the class can be referred to by namein the method definition.The implementation usesR environments to make fields and other methodsavailable by name within the method.Specifically, the parent environment of the method is the object itself.See the section on “WritingReference Methods”.This special use of environments is optional. If a method is definedwith an initial formal argument.self, that will be passed inas the whole object, and the method follows the standard rules for anyfunction in a package. See the section on “External Methods”

The goal of the software described here is to provide a uniformprogramming style inR for software dealing with reference classes, whetherimplemented directly inR or through an interface to one of theOOPlanguages.

Writing Reference Methods

Reference methods are functions supplied as elements of a named list,eitherwhen invoking$methods() on a generator objectg or asthe argumentmethods in a call tosetRefClass.The two mechanisms have the same effect, but the first makes the code more readable.

Methods are written as ordinaryR functions but have some specialfeatures and restrictions in their usual form.In contrast to some other languages (e.g., Python), the object itselfdoes not need to be an argument in the method definition.The body of the function can contain calls to any other reference method,including those inherited from other reference classes and may referto methods and to fields in the object by name.

Alternatively, a method may be anexternal method.This is signalled by.self being the first formal argument to the method.The body of the method then works like any ordinary function.The methods are called like other methods (without the.selfargument, which is supplied internally and always refers to the objectitself).Inside the method, fields and other methods are accessed in the form.self$x. External methods exist so that reference classes can inherit thepackage environment of superclassesin other packages; see the section on “External Methods”.

Fields may be modified in a method by using thenon-local assignment operator,<<-, as in the$edit and$undomethods in the example below.Note that non-local assignment is required: a local assignment withthe<- operator just creates a local object in the functioncall, as it would in anyR function.When methods are installed, a heuristic check is made for localassignments to field names and a warning issued if any are detected.

Reference methods should be kept simple; if they need to do somespecializedR computation, that computation should use a separateRfunction that is called from the reference method.Specifically, methods can not use special features of theenclosing environment mechanism, since the method's environment isused to access fields and other methods.In particular, methods should not use non-exported entries in thepackage's namespace, because the methods may be inherited by areference class in another package.

Two method names are interpreted specially,initializeandfinalize. If aninitialize method is defined, itwill be invoked when an object is generated from the class. See thediscussion of method$new(...) in the section “Initialization Methods”.

If afinalize method is defined, a function will beregistered to invoke it before the environment inthe object is discarded by the garbage collector; finalizers areregistered withatexit=TRUE, and so are also run at the end ofR sessions. See the matrix viewer example for both initialize andfinalize methods.

Reference methods can not themselves be generic functions; if you wantadditional function-based method dispatch, write a separate genericfunction and call that from the method.

Two special object names are available.The entire object can be referred to in a method by the reservedname.self.The object.refClassDef contains the definition of theclass of the object.These are accessed as fields but are read-only, with one exception.In principal, the.self field can be modified in the$initialize method, because the object is still being created at this stage.This is not recommended, as it can invalidate the object with respectto its class.

The methods available include methods inherited from superclasses, asdiscussed in the section “Inheritance”.

Only methods actually used will be included in the environmentcorresponding to an individual object. To declare that a method requires aparticular other method, the first method should include a callto$usingMethods() with the name of the other method as an argument.Declaring the methods this way is essential if the other method is used indirectly (e.g., viasapply()ordo.call()).If it is called directly, code analysis will find it.Declaring the method is harmless in any case, however, and may aidreadability of the source code.

Documentation for the methods can be obtained by the$help method for the generator object.Methods for classes are not documented in theRd format usedforR functions.Instead, the$help method prints the calling sequence of the method, followed byself-documentation from the method definition, in the style of Python.If the first element of the body of the method is a literal characterstring (possibly multi-line), that string is interpreted as documentation.See the method definitions in the example.

Initialization Methods

If the class has a method defined for$initialize(), this method will be called once the reference object has beencreated. You should write such a method for a class that needs to dosome special initialization.In particular, a reference method is recommended rather than a methodfor the S4 generic functioninitialize(), because some special initialization isrequired for reference objectsbefore the initialization offields.As with S4 classes, methods are written for$initialize() and not for$new(), both for the previous reason and also because$new() is invoked on the generator object and would be a method for that class.

The default method for$initialize() is equivalent to invoking the method$initFields(...). Named arguments assign initial values to the corresponding fields.Unnamed arguments must be objects from this class or a referencesuperclass of this class.Fields will be initialized to the contents of the fields in suchobjects, but named arguments override the corresponding inheritedfields.Note that fields are simply assigned. If the field is itself areference object, that object is not copied.The new and previous object will share the reference.Also, a field assigned from an unnamed argument counts as anassignment for locked fields.To override an inherited value for a locked field, the new value mustbe one of the named arguments in the initializing call.A later assignment of the field will result in an error.

Initialization methods need some care in design.The generatorfor a reference class will be called with no arguments, for examplewhen copying the object.To ensure that these calls do not fail, the method must have defaultsfor all arguments or check formissing().The methodshould include... as an argument andpass this on via$callSuper() (or$initFields() ifyou know that your superclasses have no initialization methods).This allows future class definitions that subclass this class, withadditional fields.

Inheritance

Reference classes inherit from other reference classes by using thestandardR inheritance; that is, by including the superclasses in thecontains= argument when creating the new class.The names of the reference superclasses are in slotrefSuperClasses of the class definition.Reference classes can inherit from ordinary S4 classes also, but thisis usually a bad idea if it mixes reference fields and non-reference slots.See the comments in the section on “Implementation”.

Class fields are inherited. A class definition can override a fieldof the same name in a superclass only if the overriding class is asubclass of the class of the inherited field. This ensures that avalid object in the field remains valid for the superclass as well.

Inherited methods are installed in the same way as directlyspecified methods.The code in a method can refer to inherited methods in the sameway as directly specified methods.

A method may override a method of the same name in a superclass.The overriding method can call the superclass method bycallSuper(...) as described below.

Methods Provided for all Objects

All reference classes inherit from the class"envRefClass".All reference objects can use the following methods.

$callSuper(...)

Calls the method inherited from a reference superclass.The call is meaningful only from within another method, and will beresolved to call the inherited method of the same name.The arguments to$callSuper are passed to the superclass version.See the matrix viewer class in the example.

Note that the intended arguments for the superclass method must besupplied explicitly; there is no convention for supplying thearguments automatically, in contrast to the similar mechanism forfunctional methods.

$copy(shallow = FALSE)

Creates a copy of the object. With reference classes, unlike ordinaryR objects, merely assigning the object with a different name does notcreate an independent copy. Ifshallow isFALSE, anyfield that is itself a reference object will also be copied, andsimilarly recursively for its fields. Otherwise, while reassigning afield to a new reference object will have no side effect, modifyingsuch a field will still be reflected in both copies of the object.The argument has no effect on non-reference objects in fields. Whenthere are reference objects in some fields but it is asserted thatthey will not be modified, usingshallow = TRUE will save somememory and time.

$field(name, value)

With one argument, returns the field of the object with characterstringname. With two arguments, the corresponding field isassignedvalue. Assignment checks thatname specifies avalid field, but the single-argument version will attempt to getanything of that name from the object's environment.

The$field() method replaces the direct use of a field name, when the name of thefield must be calculated, or for looping over several fields.

$export(Class)

Returns the result of coercing the object toClass (typicallyone of the superclasses of the object's class). Calling the methodhas no side effect on the object itself.

$getRefClass();$getClass()

These return respectively the generator object and the formal classdefinition for the reference class of this object, efficiently.

$import(value, Class = class(value))

Import the objectvalue into the current object, replacing thecorresponding fields in the current object.Objectvalue must come from one of the superclasses of thecurrent object's class.If argumentClass is supplied,value is first coerced tothat class.

$initFields(...)

Initialize the fields of the object from the supplied arguments. Thismethod is usually only called from a class with a$initialize()method. It corresponds to the default initialization for referenceclasses. If there are slots and non-reference superclasses, these maybe supplied in the ... argument as well.

Typically, a specialized$initialize()method carries out its own computations, then invokes$initFields()to perform standard initialization, as shown in thematrixViewer class in the example below.

$show()

This method is called when the object is printed automatically,analogously to theshow function. A general method isdefined for class"envRefClass". User-defined referenceclasses will often define their own method: see the Example below.

Note two points in the example. As with anyshow() method, itis a good idea to print the class explicitly to allow for subclassesusing the method. Second, to call thefunctionshow()from the method, as opposed to the$show() method itself, refer tomethods::show() explicitly.

$trace(what, ...),$untrace(what)

Apply the tracing and debugging facilities of thetracefunction to the reference methodwhat.

All the arguments of thetracefunction can be supplied, except forsignature, which is notmeaningful.

The reference method can be invoked on either an object or thegenerator for the class. See the section on Debugging below for details.

$usingMethods(...)

Reference methods used by this method are named as the argumentseither quoted or unquoted. In the code analysis phase of installingthe present method, the declared methods will be included. It is essentialto declare any methods used in a nonstandard way (e.g., via an apply function).Methods called directly do not need to be declared, but it is harmless to do so.$usingMethods() does nothing at run time.

Objects also inherit two reserved fields:

.self

a reference to the entire object;

.refClassDef

the class definition.

The defined fields should not override these, and in general it isunwise to define a field whose name begins with".", since theimplementation may use such names for special purposes.

External Methods; Inter-Package Superclasses

The environment of a method in a reference class is the object itself,as an environment.This allows the method to refer directly to fields and other methods,without using the whole object and the"$" operator.The parent of that environment is the namespace of the package inwhich the reference class is defined.Computations in the method have access to all the objects in thepackage's namespace, exported or not.

When defining a class that contains a reference superclass in anotherpackage, there is an ambiguity about which package namespace shouldhave that role.The argumentinheritPackage tosetRefClass() controlswhether the environment of new objects should inherit from aninherited class in another package or continue to inherit from thecurrent package's namespace.

If the superclass is “lean”, with few methods, or existsprimarily to support a family of subclasses, then it may be better tocontinue to use the new package's environment.On the other hand, if the superclass was originally written as astandalone, this choice may invalidate existing superclass methods.For the superclass methods to continue to work, they must use onlyexported functions in their package and the new package must importthese.

Either way, some methods may need to be written that donotassume the standard model for reference class methods, but behaveessentially as ordinary functions would in dealing with referenceclass objects.

The mechanism is to recognizeexternal methods.An external method iswritten as a function in which the first argument, named.self,stands for the reference class object.This function is supplied as the definition for a reference class method.The method will be called, automatically, with the first argumentbeing the current object and the other arguments, if any, passed alongfrom the actual call.

Since an external method is an ordinary function in the source codefor its package, it has access to all the objects in the namespace.Fields and methods in the reference class must be referred to in theform.self$name.

If for some reason you do not want to use.self as the firstargument, a functionf() can be converted explicitly asexternalRefMethod(f), which returns an object of class"externalRefMethod" that can be supplied as a method for theclass.The first argument will still correspond to the whole object.

External methods can be supplied for any reference class, but there is noobvious advantage unless they are needed.They are more work to write, harder to read and (slightly) slower toexecute.

NOTE: If you are the author of a package whose referenceclasses are likely to be subclassed in other packages, you can avoidthese questions entirely by writing methods thatonly useexported functions from your package, so that all the methods willwork from another package that imports yours.

Reference Class Generators

The call tosetRefClass defines the specified class andreturns a “generator function” object for that class.This object has class"refObjectGenerator"; it inheritsfrom"function" via"classGeneratorFunction" and can becalled to generate new objects from the reference class.

The returned object is also a reference class object, although not ofthe standard construction.It can be used to invoke reference methods and access fields in the usual way, butinstead of being implemented directly as an environment it has asubsidiary generator object as a slot, astandard reference object (of class"refGeneratorSlot").Note that if one wanted to extend the reference class generatorcapability with a subclass, this should be done by subclassing"refGeneratorSlot", not"refObjectGenerator".

The fields aredef, the class definition, andclassName,the character string name of the class.Methods generate objectsfrom the class, to access help on reference methods, and todefine new reference methods for the class.The currently available methods are:

$new(...)

This method is equivalent to calling the generator function returnedbysetRefClass.

$help(topic)

Prints brief help on the topic. The topics recognizedare reference method names, quoted or not.

The information printed is the calling sequence for the method, plusself-documentation if any.Reference methods can have an initial character string or vector asthe first element in the body of the function defining the method.If so, this string is taken as self-documentation for the method (seethe section on “Writing Reference Methods” for details).

If no topic is given or if the topic is not a method name, thedefinition of the class is printed.

$methods(...)

With no arguments, returns the names of the reference methods for thisclass.With one character string argument, returns the method of that name.

Named argumentsare method definitions, which will beinstalled in the class, as if they had been supplied in themethods argument tosetRefClass().Supplying methods in this way, rather than in the call tosetRefClass(), is recommended for the sake of clearer sourcecode.See the section on “Writing Reference Methods” for details.

All methods for a class should be defined in the source code thatdefines the class, typically as part of a package.In particular, methods can not be redefined in a class in an attachedpackage with a namespace: The class method checks for a lockedbinding of the class definition.

The new methods can refer to any currently defined method by name(including other methods supplied in this call to$methods()). Note though that previously defined methods are not re-analyzedmeaning that they will not call the new method (unless it redefines anexisting method of the same name).

To remove a method, supplyNULL as its new definition.

$fields()

Returns a list of the fields, each with its corresponding class.Fields for which an accessor function was supplied in the definitionhave class"activeBindingFunction".

$lock(...)

The fields named in the arguments are locked; specifically, after thelock method is called, the field may be set once. Any further attemptto set it will generate an error.

If called with no arguments, the method returns the names of thelocked fields.

Fields that are defined by an explicit accessor function can not belocked (on the other hand, the accessor function can be defined togenerate an error if called with an argument).

All code to lock fields should normally be part of the definition of aclass; that is, the read-only nature of the fields is meant to be partof the class definition, not a dynamic property added later.In particular, fields can not be locked in a class in an attachedpackage with a namespace: The class method checks for a lockedbinding of the class definition. Locked fields can not besubsequently unlocked.

$trace(what, ..., classMethod = FALSE)

Establish a traced version of methodwhat for objects generatedfrom this class. The generator object tracing works like the$trace()method for objects from the class, with two differences.Since it changes the method definition in the class object itself,tracing applies to all objects, not just the one on which the tracemethod is invoked.

Second, the optional argumentclassMethod = TRUE allows tracingon the methods of the generator object itself.By default,what is interpreted as the name of a method in theclass for which this object is the generator.

$accessors(...)

A number ofsystems using theOOP programming paradigm recommend or enforcegetter and setter methodscorresponding to each field, rather than direct access by name.If you like this style and want to extract a field namedabcbyx$getAbc() and assign it byx$setAbc(value),the$accessors method is a convenience function that creates such getter and setter methods for thespecified fields.Otherwise there is no reason to use this mechanism. In particular, ithas nothing to do with the general ability to define fields byfunctions as described in the section on “Reference Objects”.

Implementation; Reference Classes as S4 Classes

Reference classes are implemented as S4 classes with a data part oftype"environment".Fields correspond to named objects in the environment.A field associated with a function is implemented as anactive binding.In particular, fields with a specified class are implemented as aspecial form of active binding to enforce valid assignment to thefield.

As a related feature, the element in thefields= list suppliedtosetRefClass can be anaccessorfunction, a function of one argument that returnsthe field if called with no argument or sets it to the value of theargument otherwise.Accessor functions are used internally and for inter-system interfaceapplications, but not generally recommended as they blur the conceptof fields as data within the object.

A field, saydata, can be accessed generally by an expressionof the formx$data for any object from the relevant class.In an internal method for this class, the field can be accessed by the namedata.A field that is not locked can be set by an expression of the formx$data <- value.Inside an internal method, a field can be assigned by an expression of the formx <<- value.Note thenon-local assignment operator.The standardR interpretation of this operator works to assign it inthe environment of the object.If the field has an accessor function defined, getting and settingwill call that function.

When a method is invoked on an object, the function defining the method isinstalled in the object's environment, with the same environment as theenvironment of the function.

Reference classes can have validity methods in the same sense as anyS4 class (seesetValidity).Such methods are often a good idea; they will be called by callingvalidObject and a validity method, if one is defined,will be called when a reference object is created (from version 3.4 ofR on).Just remember that these are S4 methods. The function will be calledwith theobject as its argument. Fields and methods must beaccessed using$.

Note: Slots. Because of the implementation, new reference classes can inherit fromnon-reference S4 classes as well as reference classes, and can includeclass-specific slots in the definition.This is usually a bad idea, if the slots from the non-referenceclass are thought of as alternatives to fields.Slots will as always be treated functionally.Therefore, changes to the slots and the fields will behave inconsistently,mixing the functionaland reference paradigms for properties of the same object,conceptually unclear and prone to errors.In addition, the initialization method for the class will have to sortout fields from slots, with a good chance of creating anomalousbehavior for subclasses of this class.

Inheriting from aclass union, however, is a reasonable strategy (withall members of the union likely to be reference classes).

Debugging

The standardR debugging and tracing facilities can be applied toreference methods.Reference methods can be passed todebug and itsrelatives from an object to debug further method invocations on thatobject; for example,debug(xx$edit).

Somewhat more flexible use is available for a reference method versionof thetrace function.A corresponding$trace() reference method is available foreither an object or for the reference class generator(xx$trace() ormEdit$trace() in the example below).Using$trace() on an object sets up a tracingversion for future invocations of the specified method for thatobject.Using$trace() on the generator for the class sets up atracing version for all future objects from that class (and sometimes forexisting objects from the class if the method is not declared orpreviously invoked).

In either case, all the arguments to the standardtracefunction are available, except forsignature= which ismeaningless since reference methods can not be S4 generic functions.This includes the typical styletrace(what, browser) forinteractive debugging andtrace(what, edit = TRUE) to edit thereference method interactively.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 11.)

Examples

## a simple editor for matrix objects.  Method  $edit() changes some## range of values; method $undo() undoes the last edit.mEdit<- setRefClass("mEdit",      fields= list( data="matrix",        edits="list"))## The basic edit, undo methodsmEdit$methods(     edit=function(i, j, value){## the following string documents the edit method       'Replaces the range[i, j] of the        object by value.        '         backup<-             list(i, j, data[i,j])         data[i,j]<<- value         edits<<- c(edits, list(backup))         invisible(value)},     undo=function(){       'Undoes the last edit() operation        and update the edits field accordingly.        '         prev<- editsif(length(prev)) prev<- prev[[length(prev)]]else stop("No more edits to undo")         edit(prev[[1]], prev[[2]], prev[[3]])## trim the edits list         length(edits)<<- length(edits)-2         invisible(prev)})## A method to automatically print objectsmEdit$methods(     show=function(){'Method for automatically printing matrix editors'       cat("Reference matrix editor object of class",          classLabel(class(.self)),"\n")       cat("Data: \n")       methods::show(data)       cat("Undo list is of length", length(edits),"\n")})xMat<- matrix(1:12,4,3)xx<- mEdit(data= xMat)xx$edit(2,2,0)xxxx$undo()mEdit$help("undo")stopifnot(all.equal(xx$data, xMat))utils::str(xx)# show fields and names of methods## A method to save the objectmEdit$methods(     save=function(file){       'Save the current object on the filein R external object format.       '         base::save(.self, file= file)})tf<- tempfile()xx$save(tf)## Not run:## Inheriting a reference class:  a matrix viewermv<- setRefClass("matrixViewer",    fields= c("viewerDevice","viewerFile"),    contains="mEdit",    methods= list( view=function(){        dd<- dev.cur(); dev.set(viewerDevice)        devAskNewPage(FALSE)        matplot(data, main= paste("After",length(edits),"edits"))        dev.set(dd)},        edit=# invoke previous method, then replotfunction(i, j, value){            callSuper(i, j, value)            view()}))## initialize and finalize methodsmv$methods( initialize=function(file="./matrixView.pdf",...){    viewerFile<<- file    pdf(viewerFile)    viewerDevice<<- dev.cur()    dev.set(dev.prev())    callSuper(...)},  finalize=function(){    dev.off(viewerDevice)})## debugging an object: call browser() in method $edit()xx$trace(edit, browser)## debugging all objects from class mEdit in method $undo()mEdit$trace(undo, browser)## End(Not run)

Description

Remove the method for a given function and signature. Obsolete forordinary applications: Method definitions in a package should neverneed to remove methods and it's very bad practice to remove methodsthat were defined in other packages.

Usage

removeMethod(f, signature, where)

Arguments

Value

TRUE if a methodwas found to be removed.

References

Chambers, John M. (2016)Extending R,Chapman & Hall.(Chapters 9 and 10.)

Description

These are old utility functions to construct, respectivelya list designed to represent the slots and superclasses anda list of prototype specifications. Therepresentation()function is no longer useful, since the argumentsslots andcontains tosetClass are now recommended.

Theprototype() function may still be used for thecorresponding argument, but asimple list of the same arguments works as well.

Usage

representation(...)prototype(...)

Arguments

Details

Therepresentation function applies tests for the validity ofthe arguments. Each must specify the name of a class.

The classes named don't have to exist whenrepresentation iscalled, but if they do, then the function will check for any duplicateslot names introduced by each of the inherited classes.

The arguments toprototype are usually named initial valuesfor slots, plus an optional first argument that gives the objectitself. The unnamed argument is typically useful if there is a datapart to the definition (see the examples below).

Value

The value ofrepresentation is just the list of arguments, after these have been checkedfor validity.

The value ofprototype is the object to be used as theprototype. Slots will have been set consistently with thearguments, but the construction doesnot use the classdefinition to test validity of the contents (it hardly can, sincethe prototype object is usually supplied to create the definition).

References

Chambers, John M. (2008)Software for Data Analysis: Programming with RSpringer. (For the R version.)

Chambers, John M. (1998)Programming with DataSpringer (For the original S4 version.)

See Also

setClass

Examples

## representation for a new class with a directly define slot "smooth"## which should be a "numeric" object, and extending class "track"representation("track", smooth="numeric")###  >>> This *is* old syntax -- use 'contains=*, slots=*' instead <<<###                ==========         ----------  ------   ======setClass("Character",representation("character"))setClass("TypedCharacter",representation("Character",type="character"),          prototype(character(0),type="plain"))ttt<- new("TypedCharacter","foo", type="character")setClass("num1", representation(comment="character"),         contains="numeric",         prototype= prototype(pi, comment="Start with pi"))

Description

A regular (S4) class may contain an S3 class, if that class has been registered (by callingsetOldClass). The functions described here provideinformation about contained S3 classes. See the section ‘Functions’.

In modernR, these functions are notusually needed to program with objects from the S4 class. Standard computations work as expected, including method selectionfor both S4 and S3. To coerce an object to its contained S3 class,use either of the expressions:

as(object, S3Class); as(object, "S3")

whereS3Class evaluates to the name of the contained class. Thesereturn slightly different objects, which in rare cases may need tobe distinguished. See the section “Contained S3 Objects”.

Usage

S3Part(object, strictS3=FALSE, S3Class)S3Class(object)isXS3Class(classDef)slotsFromS3(object)## the replacement versions of the functions are not recommended## Create a new object from the class or use the replacement version of as().S3Part(object, strictS3=FALSE, needClass=)<- valueS3Class(object)<-  value

Arguments