OOP Overview and Base Types

The R Language Definition starts its chapter on objects with the statement that R gives no direct access to memory: it provides a number of specialised data structures called objects, referred to through symbols, and the symbols are objects too. The function typeof() returns the type of an object. Underneath, every object is a pointer to the same C structure (SEXPREC), and the different R data types are values of the C type SEXPTYPE, which decides how the rest of the structure is used (R-lang: Objects). Four questions about an object are easy to confuse, so it helps to name them once:

Source: R documentation: class

R is deliberately relaxed about the relationship between these questions. A "class" in R is not a declaration that the compiler checks; it is a character vector stored as an attribute (or computed on the fly) and read by whichever generic function happens to be called. The R Language Definition says as much in its chapter on object-oriented programming: R does not have a full-fledged object-oriented system, but a class system and a mechanism for dispatching on the class of an object, and the authors caution users to apply it in a straightforward manner (R-lang: Object-oriented programming). The rest of this page works through what that means, from the bottom (types) to the top (the five systems).

R Internals lists the internal types in a table of 24 values: types 0 to 10 and 13 to 25 are in use, and 11 and 12, which were once used for internal factors and ordered factors, have been withdrawn. The numbers are stored in saved objects, so the gap cannot be reused. The table below summarises it and adds what typeof() returns for each type (the strings come from the table in the Language Definition, which also marks the types a user cannot easily get hold of, and from the typeof() help page). R Internals names the first entry NILSXP; it is the NULL object, and the manual does not use the spelling NULLSXP.

Source: R Internals: SEXPTYPEs

Two points of the table are worth remembering. First, typeof() reports the vector type "double" for what R documentation calls "numeric", and "character" for STRSXP: the SXP names are the C names, and the R-level strings are different. Second, functions come in three types, CLOSXP, SPECIALSXP and BUILTINSXP, which the manual sometimes lumps into a pseudo-type FUNSXP with code 99 when a type is stored in an integer; the last two are the primitives that the section on primitives below explains. The script builds one object for each type that an R program can reach and prints what typeof() says.

Source: R documentation: typeof

The types that are missing from the output are the ones a user is not meant to hold: CHARSXP, PROMSXP, DOTSXP, ANYSXP, BCODESXP and WEAKREFSXP. Promises appear indirectly (every function argument is one, see Lazy Evaluation and Promises), ... is reachable through helpers such as ...length(), and compiled byte code is hidden behind the closure that owns it. The last row is the newest: the S7 class built in the script is an OBJSXP object, and typeof() returns "object" for it. The section on OBJSXP below returns to that.

The next script asks all four questions about twenty objects, one per row. The objects are written as code strings and evaluated with str2lang() so that the first column shows what was asked. Two of the objects come from the shelf scenario (shelf_today and the data frame books); the factor, the formula and the matrix stand for classes that base R and stats define.

Source: R documentation: mode

Reading the table row by row shows where the four vocabularies diverge:

mode() and storage.mode() also have replacement forms. mode(x) <- "character" changes the mode through the matching as. function, so it is only supported for modes that have one, and attributes are preserved. storage.mode(x) <- "double" is the more efficient primitive version, which works for the internal types listed under typeof(). The mode "single" is a pseudo-mode: setting it records the attribute "Csingle" and the real storage mode stays "double". The pitfalls section below shows both replacement forms in a script.

The help page for typeof() says the possible values are the entries of a table in the R sources and lists those that a user is likely to see: the vector types, "NULL", "closure", "special", "builtin", "environment" and "S4", plus the rarer "symbol", "pairlist", "promise", "object", "language", "char", "...", "any", "expression", "externalptr", "bytecode" and "weakref". Note that "object" and "S4" are both in the list; the section on OBJSXP shows when each appears.

An object without a class attribute still has a class: the implicit class. class(x) computes it, and the help page lists the rules. A matrix gets "matrix" and "array", an array gets "array", a function "function", NULL gets "NULL", and other objects get the result of typeof() (which the help page says is similar to mode()), with "integer" and "double" reported as "integer" and "numeric". For calls the class is "call", except that there are extra classes for the special calls if, for, while, (, {, <- and =.

Source: R documentation: class

The matrix has no class attribute (oldClass() is NULL, is.object() is FALSE), yet class(m) has two elements. This is the R 4.0.0 change: the NEWS entry says matrix objects now also inherit from the class "array", so that class(diag(1)) is c("matrix", "array"), and that this invalidates code that wrongly assumed class(matrix_obj) has length one; it adds that S3 methods for class "array" are now dispatched for matrix objects (R NEWS: Changes in R 4.0.0). inherits(m, "matrix") is TRUE, because inherits() works on class(x), but inherits(m, "integer") is FALSE: the implicit class used for dispatch is longer than class() says, and inherits() does not use it.

Source: R documentation: class

The longer vector is .class2(), a function R 4.0.0 added, whose NEWS entry calls it the full character vector of class names used for S3 method dispatch. The help page says it is for didactic, diagnostic or debugging use, and that using it for other reasons may be a misuse. For a matrix of integers it returns "matrix", "array", "integer", "numeric": a method for numeric can serve a matrix of integers when none for matrix, array or integer exists. For an integer it returns "integer", "numeric", and for a double "double", "numeric". The next script writes five methods for one generic and shows which one answers for which object.

Source: R documentation: UseMethod

describe(1L) is answered by the integer method and describe(2.5) by the numeric method, because "double" has no method and "numeric" is next in the implicit class; deleting describe.integer would make the integer use the numeric method too. The matrix finds describe.matrix before it finds anything for integer, and a character string, whose implicit class is "character", falls through to describe.default. A note from the help page is worth keeping in mind: UseMethod() dispatches on the class returned by class() with these interpolated implicit classes, whereas group generics dispatch on oldClass() for efficiency, and internal generics dispatch only on objects for which is.object() is true. The details of dispatch are the subject of S3 Classes and Generics.

When an object does carry a class attribute, the attribute is the class. The functions that read and write it are small, and each one answers a different question. The script below uses the book from the shelf scenario, which is a list of six length-one fields with the class "book".

Source: R documentation: class

Source: R documentation: class

After unclass() the object is a plain list: class() returns the implicit class "list", is.object() is FALSE, and the six field names are visible. Nothing about the data changed; only the label did. That is the whole mechanism of S3: objects are ordinary vectors, lists or functions, and the label decides which functions treat them specially.

Most of the functions that ship with R are written in R. Typing mean shows its source, a one-line call to UseMethod("mean"), and that is what R FAQ 7.40 means when it says that in most cases typing the name of a function prints its source code, with the exception of code that is hidden in a namespace or compiled (R FAQ 7.40). A smaller set of functions are not written in R at all: they are the C code compiled into the interpreter and called directly, and they print as .Primitive("name"). The Language Definition calls them builtin objects and special forms, and notes that, from the R language, they are just another kind of function that is.primitive() can tell apart from interpreted functions (R-lang: Builtin objects and special forms).

Source: R documentation: is.function and is.primitive

sum prints as function (..., na.rm = FALSE) .Primitive("sum") because there is no R code to print: the line is the signature R keeps for documentation and argument matching, followed by the marker. Everything an R function has is absent. formals() and body() return NULL because a primitive has neither, environment() returns NULL because it was not created in an environment, and args() is the supported way to see its interface: it returns a closure with the same formals and a NULL body. is.primitive(x) is defined as typeof(x) being either "builtin" or "special".

Primitives are not generic functions in the sense of UseMethod("mean"), because there is no R code to hold the call. Yet length, [, c, dim, as.character and many others take methods. The help page InternalMethods lists the functions that are generic in this way: the subsetting operators ([, [[, $ and their replacement forms), length, lengths, dim, dimnames, names and their replacement forms, levels<-, @, c, unlist, cbind, rbind, the as. family, is.na, anyNA, is.numeric, nchar, rep and seq.int, xtfrm and others, plus all the members of the group generics. The vector .S3PrimitiveGenerics lists the primitives that are internal generic and not group generic, and .internalGenerics those reached through .Internal.

How the dispatch works is described in R Internals under "Argument evaluation". A special primitive that is an internal generic does not evaluate its arguments on call; the C code begins with a call to DispatchOrEval, which evaluates the first argument, looks for a method based on its class (if S4 dispatch is on, S4 methods are looked for first, even for S3 classes) and, if it finds one, dispatches to it with the remaining arguments as promises. If no method is found, the remaining arguments are evaluated and control returns to the internal generic. Group generics work another way: most are builtins and their C code calls DispatchGeneric. The efficiency rule is in the help page: for efficiency, internal dispatch only occurs on objects, that is, those for which is.object() returns TRUE.

Source: R documentation: InternalMethods

length(dispossessed) counts the six fields of the list. After length.book is defined, the same call returns 1: the primitive found the class attribute and dispatched. length(unclass(dispossessed)) is 6 again, since the object is no longer an object and the primitive does not even look for a method. The next fragment of the same script makes the point with a plain list that happens to have a method defined for a class name it does not carry.

Source: R Internals: Argument evaluation

The plain list fields is not an object, so length.fields is never consulted and the result is 2; the classed copy dispatches and returns 99. The membership test shows that length, c and dim are in .S3PrimitiveGenerics while mean is not, since mean is an ordinary closure and a generic by the UseMethod() route. In practice this means two things when you write a class. A method for an internal generic such as length or [ takes effect only when the object has a class attribute, and every call on a classed object pays the (small) cost of looking for a method. And a package that defines such a method must register it for dispatch, which the S3 Classes and Generics page shows with S3method() directives in NAMESPACE.

The five systems did not arrive together, and their dates explain several of their quirks. The R FAQ dates the first two: Chambers and Hastie’s "Statistical Models in S" (1992) introduced S version 3, which added structures to facilitate statistical modelling, and Chambers’s "Programming with Data" (1998) described version 4 of S, a major revision (R FAQ 3.1). R’s S3 classes follow the first, and the methods package, which was added in R 1.4.0, implements the second. The NEWS of the later releases supply the remaining dates; the two CRAN packages are dated from the CRAN archive.

Source: R FAQ 3.1: What is S?

The dates come from these places:

The five systems are easiest to compare on one tiny object, a book with a single field, title. The script builds it in each system and asks the questions of the first half of this page about the result: what type is it, what does class() say, is it an "object" and is it an S4 object?

Source: R documentation: isS4

The book() from the scenario is an S3 object, a list with a class attribute. setClass() returns a generator function, and its objects have the type "S4"; setRefClass() objects have the same type, because a Reference Class object is an S4 object that holds an environment. An R6 object is an environment with a class vector, so typeof() says "environment". An S7 object has the type "object": it is an OBJSXP object whose S4 bit is not set. All five are objects for is.object(), and only the S4 and Reference Class objects answer TRUE to isS4().

Source: R documentation: class

R6 and S7 objects have ordinary S3 class vectors, which is how S3 generics such as print() and format() can see them, and which is why inherits(s7_book, "S7_object") works. The last call is a consequence of the R6 type: unclass() is not allowed for environments, so there is no plain-structure view of an R6 object as there is for a book.

The table summarises what the scripts showed, plus the facts that the system pages establish. "Where" says what a user has to install: S3, S4 and Reference Classes come with every R; R6 and S7 are CRAN packages with a version of their own.

Source: R documentation: Introduction (the methods package)

The "typical use" row is based on what the example below prints, not on popularity figures. Two of the cells deserve a comment. In the S4 cell (Bioconductor and Matrix), the classes of Matrix, which ships with R, are S4 classes, as the output below shows, and Bioconductor’s core packages are written with S4 too; this page checked Matrix and not Bioconductor. In the S7 cell (ggplot2 4.0), the ggplot2 NEWS records that the S3 parts of ggplot2 have been replaced with S7 pieces, and a plot object is now an S7_object.

Source: R documentation: Introduction (the methods package)

A sparse Matrix object has an S4 class with the attribute "package", and isS4() says so. A ggplot2 4.0.3 plot is an S7 object (type "object", S7_inherits() true), and its class vector still has S3 names so that old S3 code keeps working. In the next block, a Shiny mock session is an R6 object, an environment, while a fitted lm is the classical S3 case, a list with a class, and a connection is an S3-classed integer that refers to a C-level structure.

Source: R6 package documentation: R6Class

There is no single best system; there is a best system for each kind of problem. The questions below are the ones that settle most cases.

Mixing is normal. A package may use S3 for results, S4 for a few core classes and R6 for a stateful component; setOldClass() and S7’s compatibility helpers exist because of that. What does not work well is mixing semantics in one class: an S3 list with reference semantics bolted on, for example, or an R6 object that is expected to be copied by <-.

The R 4.4.0 NEWS contains an entry for C developers that matters for everyone who follows R’s object systems: the SEXP type S4SXP was renamed OBJSXP, "to support experimenting with alternative object systems". The old name can still be used in C code but is deprecated, and the change is based on contributions from the R Consortium’s Object-Oriented Programming Working Group (R NEWS: Changes in R 4.4.0). The reason is in R Internals: an S4 object is either a simple type with S4 class information or an object of type OBJSXP, and OBJSXP is for S4 and other objects which do not consist solely of a simple type (R Internals: SEXPTYPEs). The old name tied the type to S4; the new name says what the type is, a general type for objects that are not a simple vector or function, so that a package may create such objects without the S4 bit.

Source: R Internals: S4 objects

On R 4.6.1, typeof() returns "S4" for an OBJSXP object that has the S4 bit set, and "object" for one that does not. The S7 object is the second case: it is a plain OBJSXP object with a class attribute, not an S4 object (isS4() is FALSE). The Language Definition’s table of typeof() values still lists "S4" and not "object", while the typeof() help page lists both.

Source: R documentation: typeof

An S4 class that extends a basic type keeps that type: Measure extends numeric, so its instances have the type "double", with the S4 bit set (isS4() is TRUE), and the numbers are available as @.Data. An S7 object stores its class vector, a reference to the class object (S7_class) and one attribute per property. The OBJSXP type itself is the groundwork; the rest of the support for alternative object systems came in 4.3.0, in the hooks that R Core added at the request of the same working group: inherits() accepts a class object through nameOfClass(), the @ operator became an S3 generic, and chooseOpsMethod() resolves a conflict between two Ops methods (R NEWS: Changes in R 4.3.0). The R-devel NEWS, which describes the upcoming R 4.7.0, lists a further low-level function, .OBJSXP(), that enables deparsing of non-S4 objects of type "object" (R-devel NEWS); it does not exist in R 4.6.1 and is not used here.

Source: R FAQ 7.26: Where have all the methods gone?

The script shows the first two pitfalls with their real outputs. class(m) == "matrix" is TRUE FALSE, and using it as a condition fails with the message the condition has length  1. inherits(m, "matrix") and is.matrix(m) ask the intended question. The third block shows the two replacement forms from earlier: mode(x) <- "character" converted the values, while storage.mode(m) <- "double" changed the matrix from integer to double and kept its dimensions.

Source: R NEWS: Changes in R 4.0.0, 4.3.0 and 4.4.0

The R 3.5.0 entry is in the 3.x NEWS (NEWS.3) and the 1.4.0 and 2.12.0 entries are in the archived NEWS files cited in the history section.

Source: R Internals: SEXPTYPEs

For the full list of changes by release see What’s New and Migrating Older Code.