S3 Classes and Generics

A class is stored in the attribute named class. class(x) reads it (and, for an object without the attribute, computes an implicit class, see below); oldClass(x) reads only the attribute and returns NULL when there is none; class(x) <- value and oldClass(x) <- value set it; unclass(x) returns a copy without it; inherits(x, what) tells whether any of the class names in what is in the class vector; is.object(x) is TRUE exactly when the object has a class attribute. structure(.Data, ...) builds an object and sets attributes in one expression, which is the usual way to write a constructor, and attr(x, "class") is the long way to read the same attribute. The help page is ?class (R documentation: class); the manual section on attributes explains that an attribute is a named piece of metadata attached to an object and that class is one of the special ones (Attributes and Names covers attributes in general).

Source: R documentation: class

A few details of the output are worth a look. Giving the integer vector a class changed nothing in its data, only added a second attribute, and oldClass(x) went from NULL to "tag". inherits(y, c("poem", "novel"), which = TRUE) returns the position of each name in the class vector, with 0 for a name that is not there; the plain form returns a single TRUE or FALSE and is the form to use in conditions. unclass() returns a copy: the original y still has its class afterwards, as every R function works on copies (see Memory and Copy Semantics). And NULL cannot carry attributes at all, so class(z) <- "tag" on NULL fails with attempt to set an attribute on NULL: an S3 class cannot be put on NULL, which matters for classes meant to represent "nothing".

The class vector may have several elements, and the order is meaningful: it runs from the most specific class to the most general, and it is the order in which methods are looked up. c("audiobook", "book") means "an audiobook, which is a kind of book", and an audiobook object can be used wherever a book is expected because print.book will be found when there is no print.audiobook. There is no declaration of this relationship anywhere: it exists only because the class vector of each object says so (the section on inheritance below builds one).

An object without a class attribute still has a class for dispatch purposes, the implicit class. class() reports a short form of it and .class2() (new in R 4.0.0) reports the full vector that UseMethod() really searches (R NEWS: Changes in R 4.0.0). For a matrix that vector is c("matrix", "array", "integer", "numeric") or the equivalent for the underlying type: the dimensions come first, then the type, then the broader category. A double vector is c("double", "numeric"), an integer vector c("integer", "numeric"), a function is "function", and a symbol, a call or NULL have the class of their type. The help page for ?class states it in these words: if the object does not have a class attribute, it has an implicit class, notably "matrix", "array", "function" or "numeric", or the result of typeof(x).

Source: R documentation: class

Since R 4.0.0 a matrix has class c("matrix", "array"), where it used to have the single class "matrix", and S3 methods for class "array" are dispatched for matrices (the 4.0.0 NEWS points out that this breaks code that wrongly assumes the class of a matrix has length one). The consequence for if (class(x) == "matrix") is covered in the section on testing classes below. .class2() is meant for teaching and debugging, as the help page points out: to find out what a call will dispatch on, ask .class2(); do not build program logic on it.

Nothing about the attribute checks the object it is attached to. structure(list(), class = "book") is a perfectly valid R object that claims to be a book and has none of a book’s fields; every method written for book objects is then free to fail in its own way. The manual’s advice is the origin of the pattern in the next section: when they are available, specific creation and coercion functions should be preferred to assigning a class by hand. The rest of this page uses three small functions per class: a low-level constructor that builds the object and checks types, a validator that checks values, and a user-facing helper that coerces and calls both. That vocabulary (constructor, validator, helper) is community practice, popularised by Hadley Wickham’s Advanced R and the R Packages book rather than defined by any R manual, but it matches how base R’s own classes work: factor() is a helper over structure() with levels and class checks.

A generic function is an ordinary function whose job is to pick a method. The Language Definition says that a generic should consist of a single statement, usually of the form foo <- function(x, ...) UseMethod("foo", x) (R-lang: Method dispatching). The generics you already use are exactly that: the bodies of print, summary, format and mean are each one call to UseMethod(). When the generic is called, UseMethod() looks at the class of the first argument, finds the best method, and calls it with the same arguments, in the same order, as the call to the generic, as if the call had been made directly to the method. Control never returns to the generic: whatever the method returns is the value of the call.

Source: R documentation: UseMethod

describe() is the whole recipe: a generic is a function that calls UseMethod("describe"); its methods are the functions describe.book and describe.default; the call describe(b) found describe.book because class(b) is "book", and the other calls fell to the default method. Three more details are visible in the output. Only the first argument takes part in the dispatch (describe(1, b) went to the default method even though b is a book), and describe(b, 1) found the book method again. A method is an ordinary function that may also be called directly, as describe.book(b) does, though that bypasses dispatch and is therefore only for testing or for calling a specific method from another method. And utils::isS3stdGeneric() recognises a standard generic, a function whose body is just a UseMethod() call: it said TRUE for print and FALSE for the primitive sum.

The .default method is the last resort, and the manual advises always writing one, because without it a call for an unexpected class is an error. The next script shows the wording of that error for a generic with only a book method:

Source: R documentation: UseMethod

The message is no applicable method for 'summarise' applied to an object of class "book" with the generic’s name and the class of the object. The class that is reported is the implicit class when there is no class attribute, and it shows the full vector that was searched: c('double', 'numeric') for a double, c('integer', 'numeric') for an integer vector, c('matrix', 'array', 'integer', 'numeric') for an integer matrix. This is the same vector that .class2() returns. If you see a message like this about an object of class NULL or function, the usual cause is not a missing method but a wrong object, for example a NULL returned by a lookup that failed.

When the generic gen is called with an object whose class vector is c("first", "second"), R searches for gen.first, then gen.second, and finally gen.default; the first function found is called. The Language Definition describes it this way: the name of the generic is combined with each element of the class attribute in turn, and if none gives a function, generic.default is used (R-lang: Method dispatching). If the object has no class attribute, the implicit class (.class2(x)) is used in the same way, and then the default. The help page ?UseMethod adds the precise places where a function called gen.first is looked for:

The relative order of the second and third place matters little in practice: the registration table is consulted after the top level environment of the caller but before its parents. That ordering was introduced in R 3.5.0 (R NEWS: Changes in R 3.5.0 announces that S3 method lookup searches the namespace registry after the top level environment of the calling environment). The consequence is the rule used throughout this page: methods for a generic need to be available in the environment of the call to the generic, or they must be registered. It does not matter whether they are visible in the environment where the generic is defined.

Source: The R Language Definition: Method dispatching

The diagram follows one call to the generic print(). The first decision is where the class vector comes from: the class attribute if the object has one, the implicit class otherwise. Each name in the vector in turn is combined with the generic’s name and looked up as a function. The first hit is called with the arguments of the call; if that method calls NextMethod(), the search resumes from the next class in the vector. When the vector is used up, the default method is the last resort, and if there is none, the error is signalled. Two details are not in the picture: the dispatch object is the first argument as it was passed (see the rules below), and the internal generics (length, [, c, as.character and others) first check that the object has a class attribute at all, because for efficiency they dispatch only on objects.

UseMethod() dispatches on the implicit class even for objects that have no class attribute, and that can surprise you in both directions. The script below defines a generic kind() with methods for the implicit classes integer, numeric, matrix, array and function:

Source: R documentation: class

Each call dispatched on the class vector that .class2() reports. An integer is handled by kind.integer because "integer" comes before "numeric"; a double has no integer class and falls to kind.numeric; a matrix of doubles uses kind.matrix (the first element of its vector), then if that method is removed kind.array, then the type (kind.integer for an integer matrix), and then kind.numeric. This is the mechanism that lets print.default and format.default deal with every atomic type, and it is also the reason why a stray function that happens to be named like a method gets called: the last part of the script defines a function called rev.numeric and rev(1:3), an integer vector, runs it, because "numeric" is part of the implicit class of an integer vector. The help page for UseMethod states the inconsistency: UseMethod dispatches on the implicit class even for arguments that are not objects, but the other means of dispatch do not.

The other means of dispatch are the internal generics: primitives and internal functions such as length, [, [[, $, c, dim, names, as.character, as.numeric, rep, is.na and unlist (the complete list is on the help page ?InternalMethods, R documentation: InternalMethods), and the group generics Ops, Math, Summary and Complex (R documentation: groupGeneric). They are implemented in C, they dispatch on the first argument (the group Ops on both), and they do so only when is.object(x) is TRUE, that is, when the argument has a class attribute.

Source: R documentation: InternalMethods

length.numeric has no effect on length(1:3) or on length(c(1.5, 2.5)), because neither vector is an object, whereas length.tag is called as soon as the vector has the class tag. The same applies to as.character.numeric, which as.character(1.5) ignores, while the closure-based rev() finds rev.numeric. The practical rule is that you can add methods for your own classes to any of the internal generics (that is how the [.shelf and c.shelf methods below work), but you cannot change how R handles a plain numeric vector by defining a method for an implicit class. Group generics, and the double dispatch of Ops, are the subject of S3 Group Generics and Operator Overloading.

UseMethod(generic, object) is a special function. Its first argument is the name of the generic (the string; if it is omitted, the name of the enclosing function is assumed), and its second is the object to dispatch on, which defaults to the first argument of the enclosing function. The manual lists the consequences (R-lang: UseMethod), and each one can be checked in a few lines.

Source: The R Language Definition: UseMethod

The help page documents one more rule that is easy to miss: UseMethod can be called with more than two arguments, a warning will be given and the additional arguments ignored. The observed behaviour on R 4.6.1 is stricter than the help page: UseMethod("g", x, 3) stops with unused argument (3), since UseMethod is a primitive that uses standard argument matching. Do not rely on either behaviour; give it one or two arguments.

The dispatch mechanism communicates with the method through special variables that it places in the evaluation frame of the method. .Generic is the name of the generic as a length-one character vector. .Method is the name of the method function (it has two elements for the Ops group generics, see the group generics page). .Class is the part of the class vector that remains to be tried by NextMethod(); the help page explains that NextMethod() adds an attribute named previous to .Class holding the value last used for dispatch, and shifts .Class along. .GenericCallEnv and .GenericDefEnv are the environment of the call to the generic and the one defining it (the latter is used to find registered methods), and for group generics there is also .Group. The values are the same for a method called through UseMethod() and one reached through NextMethod(), and you can see them evolve in a chain:

Source: R documentation: UseMethod

In the first method .Class is the whole class vector, "audio" "book"; in the second it has shifted along to "book" and carries the attribute previous; in the default method it is empty (character(0)), with the history of the earlier values nested in the attribute. A method called directly, as trace_it.default(x) was at the end of the script, has no dispatch variables: the error is object '.Method' not found. That is why the manual defines a method as a function that has been invoked via method dispatch, and why dispatch variables should be used to understand a dispatch, not to write logic. The nolint start/nolint end comments in the script exist because the static analysis done by lintr cannot know that .Generic, .Class and .Method exist at run time. Ordinary methods should not need them: NextMethod() is the supported way to continue, and the Language Definition says that the choice of the next method depends on the current values of .Generic and .Class, not on the object, which the next section demonstrates.

A method can also be called directly, and then there are no dispatch variables to read. The Language Definition says what is supposed to happen: the first argument of NextMethod() is then used to find the generic, an error is signalled if it has not been supplied, so it is a good idea to always supply it, and the class used is the class attribute of the first argument. The script below shows the actual messages, each captured with tryCatch():

Source: R documentation: UseMethod

generic function not specified is the error for NextMethod() without a name when the method was called directly. With NextMethod("tag") the continuation works if the next step is the default method (tag.c(x)), and it fails with wrong value for .Method when the chain has to hop more than once from a direct call. A method taken out of a list is called through an anonymous function, so 'NextMethod' called from an anonymous function is signalled; at top level the message is 'NextMethod' called from outside a function; and a function that is not named like a method (outside()) gives wrong value for .Method. The last message, no method to invoke, is the one for a class vector that ends without a default method and where the generic is an ordinary closure: there is nothing left to call. The practical rules are to call methods through the generic, to always write NextMethod() inside a function whose name is generic.class, and to supply the generic name only when you know that a method may be called directly.

A package that wants a method for a function that is not generic can turn it into one. The manual’s recipe is to keep the old definition as the default method and call the original through its namespace. It explicitly warns against the older advice of assigning foo.default <- base::foo, which captures the base function at the time of installation and goes out of date when R is patched or updated:

Source: Writing R Extensions: Adding new generics

The new toupper() shadows the base one in the global environment (for a package it would be exported and the base function stays reachable as base::toupper), the default method defers to the original, and the book method upper-cases the title and returns a book. The script then removes the definitions again, as the last call shows, and toupper("dune") is the base function once more. The manual notes a small performance cost: making a function generic with the old definition as the default adds a dispatch step, and it is never necessary to ask R Core to make a base function generic, because a package can take it over this way.

Because methods are ordinary functions found by name, several tools answer "what methods exist?". methods(generic.function) lists the methods of a generic and methods(class = "book") lists the generics that have a method for a class; both return an object of class MethodsFunction, which is a character vector with an attribute info (a data frame with columns generic, visible, isS4 and from) and a print method. An asterisk after a name marks a method that is not exported from its namespace, which means it is registered but not visible by name (R documentation: methods). getS3method(f, class) retrieves a method by generic and class even when it is hidden in a namespace, getAnywhere(name) reports every place where an object of that name is found and in what form, exists("print.book") is the plain-lookup test, and utils::isS3method() and utils::isS3stdGeneric() answer the yes/no questions (R documentation: getS3method, R documentation: getAnywhere).

Source: R documentation: methods

methods(class = "book") lists the three generics for which scenario.R defines a method, and methods(class = "summary.book") the single print method. methods(print) and methods(summary) are far too long to show (print has well over a hundred methods once the standard packages are loaded), which is why the script only tests their size. The result for coef shows what an installed package looks like: all methods end with an asterisk, because the stats namespace does not export them. exists("coef.aov") is FALSE and exists("print.data.frame") is TRUE, so some are visible and some are not; getS3method("coef", "aov") gets the former, and getAnywhere("coef.aov")$where explains that it is a registered S3 method for coef from the namespace stats. getS3method(..., optional = TRUE) returns NULL instead of an error when the method is missing. The info attribute shows visible = TRUE for the three book methods, because they live in the global environment. The methods() help page adds that the S3 functions listed are those that are named like methods and may not actually be methods (known exceptions are discarded), which leads to the section on naming clashes below.

An Introduction to R makes the same points with coef and getAnywhere("coef.aov"), and the 4.4.0 NEWS added an all.names argument to methods() and .S3methods() for the rare case where methods whose names start with a dot should be included (R-intro: Classes, generic functions and object orientation). The R FAQ entry for the question "Where have all the methods gone?" explains why so many S3 methods are hidden: they are in namespaces, which has the advantage that they cannot be called inadvertently with arguments of the wrong class, and the disadvantage that they are harder to view. getS3method("[", "terms") is the FAQ’s example of how to see one, and pkg:::name is the way to see an unexported function; the FAQ adds that the latter should not be used in your own code (R FAQ 7.26: Where have all the methods gone?).

The lookup rule from the dispatch section has a consequence that surprises people who define methods inside functions: a method is found if it is visible in the environment of the call to the generic, or if it is registered. Both are true of methods defined at top level or in a package namespace; neither is true of a method defined inside a function body when the generic is called from somewhere else.

Source: R documentation: UseMethod

The first call works: describe(x) is called inside direct(), so describe.foo is visible in its calling environment. When the same generic is called from vapply() the calling environment is the vapply frame, so the local method is not found and the default answers; the same happens when the call is made in a helper function defined elsewhere. local() at top level behaves like a function body: found inside, lost outside. After .S3method("describe", "foo", ...) registers a method, it is found everywhere, even from inside vapply(), but exists("describe.foo") is FALSE, because registration does not create a variable, and methods(describe) shows describe.foo* with the asterisk for "not visible". Finally a method visible in the global environment (the calling environment) beats a registered method for the same class, which is a consequence of the search order. When scripts use vapply() or lapply() over objects with local methods, define the methods at top level or register them.

A package must not rely on the global environment: the standard S3 lookup might fail to find methods defined in a package that is imported but not attached, so the methods need to be registered. In the package’s NAMESPACE file the directive is S3method(generic, class). It makes print.book available for dispatch without exporting the function (Writing R Extensions: Registering S3 methods):

Source: Writing R Extensions: Registering S3 methods

The directive takes the generic and the class; the third optional argument is the function to use as the method, for example S3method(print, shelf, print_shelf) when the function is not called print.shelf. Function and class names may be quoted, and reserved words and non-standard names such as [<- must be quoted. The generic must be visible to the package: since print is defined in base it needs no import, but for a generic from another package it must be imported with importFrom(). Export the generics, constructors and helpers, but export methods only through S3method(), not through export() or a wide exportPattern(), which would also export internal helpers. "Writing R Extensions" cautions that broad patterns are not recommended for production code (Writing R Extensions: Specifying imports and exports).

There are two more cases. For a method on a generic from a package you do not want to load until needed (a package in Suggests, for example), R 3.6.0 added delayed registration (listed in the R NEWS: Changes in R 3.6.0 among the changes to namespaces): S3method(pkg::gen, cls) registers gen.cls as a method for the generic gen of package pkg only when the namespace of pkg is loaded. The manual’s example wraps the directive in an if (getRversion() >= "3.6.0") condition for packages that must also install on older R versions. And for scripts, which have no NAMESPACE, R 4.0.0 added .S3method(generic, class, method) (listed as a new function in the 4.0.0 NEWS): the help page says that it should only be used in R scripts, and that package code should use the S3method directive. registerS3method(genname, class, method, envir) is the function that .S3method() calls (with envir set to the calling environment, so that the generic is searched first where .S3method() was called); it is documented with the namespace internals (R documentation: .S3method, R documentation: registerS3method).

Few packages write the NAMESPACE by hand: roxygen2 generates it from comments. The tag @export on a function that is recognisably a method (a name of the form generic.class where generic is a generic visible to the package) produces S3method(generic, class); on any other function it produces export(). A method for a generic from another package that should be registered lazily uses @exportS3Method pkg::gen, which produces the delayed-registration directive. The script below builds a throwaway package in a temporary directory, runs roxygen2::roxygenise() (roxygen2 8.1.1) and prints what it wrote:

Source: roxygen2 package documentation: Managing imports and exports

The NAMESPACE has the three kinds of directive: export(book) for the helper, S3method(print,book) for a method found by name, and S3method("[",shelf) for a method of an internal generic (note that the quotes are generated for the non-standard name). @exportS3Method generics::tidy generated S3method(generics::tidy,book), the delayed-registration form of the previous paragraph, for a generic that lives in another package. Under roxygen2 8.x the version is recorded in the Config/roxygen2/version field of DESCRIPTION (here 8.1.1), not in the older note-style field that many tutorials still show. The helper tagged @noRd produced no Rd file and no directive. The same NAMESPACE generated by hand would have to be kept in step with the code; regenerating it after each change (devtools::document()) is the habit that prevents a method that works in load_all() and is not found in the installed package. Packages, namespaces and the NAMESPACE file are covered in Packages, Libraries and Namespaces, package creation in Creating Packages, and the documentation tags in Documentation with Rd, roxygen2 and Vignettes.

A method also needs documentation, but the manual lets it be brief: in the Rd usage section of the generic’s page, S3 methods are written with the \method{generic}{class}(arguments) macro, which keeps the usage in step with the generic’s arguments and lets R CMD check compare them (Writing R Extensions: Documenting functions). Roxygen2 writes the macro for you.

R FAQ 7.26 explains why S3 methods are often not visible: many are hidden in namespaces, which has the advantage that they cannot be called inadvertently with arguments of the wrong class. The tools shown above (getS3method(), getAnywhere(), methods()) retrieve them, and pkg:::name reads an unexported function but should not be used in your own code. The other half of the question, "why is my method not called?", has a short checklist:

Automatic printing, which is what calls the print method, happens only for a visible value at the top level, as R FAQ 7.16 explains in the context of source(). Inside a for loop, inside a function whose value is not returned to the top level, or in a script run with source() without echo or print.eval, nothing is printed unless the code calls print() itself.

Source: R FAQ 7.16: Why is the output not printed when I source() a file?

The first expression printed the book because it was a visible value at the top level; the two forms with invisible() show that visibility, not the value, decides. The for (b in pair) b loop printed nothing at all, while print(b) printed both books. show_all() returns its argument invisibly, so calling it at top level prints once per print() inside the loop and does not print the list again; that is the idiom used by print methods (do the printing, return invisible(x)). A function whose last expression is an assignment (f()) also returns invisibly, so f(pair[[1]]) shows nothing, and wrapping the call in parentheses forces printing. source() prints top-level values only with echo = TRUE or print.eval = TRUE, which is why scripts that "work" in the console print nothing under Rscript or source(): a bare b line is not a statement that prints. See Idioms and Common Pitfalls for more of these habits.

An S3 object built on a list is read with $, and $ on a list matches names partially. A misspelt or abbreviated field name silently returns the value of a field whose name starts with the typed text:

Source: R documentation: Extract

b$pag returned the pages, b$yea the year, b$y the year again (the only field starting with y), and b$au the author; a name that matches nothing, b$publisher, is NULL, not an error, which means a typo can silently turn a number into NULL and then into a vector of length zero. [[ is exact unless asked with exact = FALSE. The option warnPartialMatchDollar makes every partial match on a $ warn: partial match of 'pag' to 'pages'. When two names match, the result is NULL (the last lines: year and yearly both start with yea). Use [[ with the full name in functions that matter, or turn the option on in tests; Subsetting and Indexing explains the rules for $ and [[ in general.

A classed list is still a list, and the list tools see through the class. identical() compares the class attribute as well as the data, so a book and its unclass() copy are not identical, and all.equal() describes the first difference it finds. The == operator has no book method, so it falls to the default for lists and stops with comparison of these types is not implemented; to compare books by value, compare unclass() copies, define a method for Ops (S3 Group Generics and Operator Overloading) or compare chosen fields. To see an object without the method getting in the way, use unclass(), str(), attributes() or print.default():

Source: R documentation: identical

all.equal(a, c2) pointed at the differing component with Component “year”: Mean relative difference: 0.0005089059, and all.equal(unclass(a), unclass(c2)) gave the same message without the class attribute. str(unclass(a)) shows the six fields, attributes(a) shows names and class and nothing else, and print.default(a) prints the raw list, ending with attr(,"class") so that the class is visible. print(unclass(a)[c("title", "year")]) prints selected fields without the method. The print.default() call is also how a method delegates to the built-in printing; NextMethod() does the same job inside a print method.

Any function named generic.class is a method, whether or not that was intended. A plain helper such as describe.list, written to describe a list of books, becomes the method for every plain list in the session, because the implicit class of a list is "list":

Source: An Introduction to R: Classes, generic functions and object orientation

describe(list(1, 2, 3)) called the helper, which the author meant for something else. A data frame is not captured by it, because it has a class attribute and the implicit class "list" is tried only for objects without one; it would be captured once a method for data.frame exists, which is what the script shows next. Base R has two well-known near-misses, t.test() (is it the t() method for class test?) and sort.list() (is it the sort() method for lists?). Neither is a method: utils::isS3method() says FALSE for both, getS3method("t", "test", optional = TRUE) is NULL and sort(list(2, 1)) reports an error from the default method rather than from sort.list(). The NEWS for R 4.3.3 records one of these: getS3method("t", "test") no longer finds t.test(). The rule that follows is the one the manuals give: do not name functions in the style generic.class unless they are meant to be methods. Use describe_list(), book_describe() or describe_books(), and when you need a name that contains dots, check the prefix against the list of generics (methods() and utils::isS3stdGeneric()).