| \name{Introduction} |
| \alias{Introduction} |
| |
| \title{Basic use of S4 Methods and Classes} |
| |
| \description{ |
| The majority of applications using methods and classes will be in \R |
| packages implementing new computations for an application, using new \emph{classes} |
| of objects that represent the data and results. |
| Computations will be implemented using \emph{methods} that implement |
| functional computations when one or more of the arguments is an object |
| from these classes. |
| |
| Calls to the functions \code{\link{setClass}()} define the new classes; |
| calls to \code{\link{setMethod}} define the methods. |
| These, along with ordinary \R computations, are sufficient to get |
| started for most applications. |
| |
| Classes are defined in terms of the data in them and what other |
| classes of data they inherit from. |
| Section \sQuote{Defining Classes} outlines the basic design of new classes. |
| |
| Methods are \R functions, often implementing basic computations as |
| they apply to the new classes of objects. |
| Section \sQuote{Defining Methods} discusses basic requirements and |
| special tools for defining methods. |
| |
| The classes discussed here are the original functional classes. |
| \R also supports formal classes and methods similar to those in other |
| languages such as Python, in which methods are part of class |
| definitions and invoked on an object. |
| These are more appropriate when computations expect references to |
| objects that are persistent, making changes to the object over time. |
| See \link{ReferenceClasses} and Chapter 9 of the reference for the |
| choice between these and S4 classes. |
| } |
| |
| \section{Defining Classes}{ |
| All objects in \R belong to a class; ordinary vectors and other basic |
| objects are built-in (\link{builtin-class}). |
| A new class is defined in terms of the named \emph{slots} that is has |
| and/or in terms of existing classes that it inherits from, or |
| \emph{contains} (discussed in \sQuote{Class Inheritance} below). |
| A call to \code{\link{setClass}()} names a new class and uses the corresponding arguments to |
| define it. |
| |
| For example, suppose we want a class of objects to represent a |
| collection of positions, perhaps from GPS readings. |
| A natural way to think of these in \R would have vectors of numeric values for |
| latitude, longitude and altitude. |
| A class with three corresponding slots could be defined by: |
| |
| \code{ |
| Pos <- setClass("Pos", slots = c(latitude = "numeric", |
| longitude = "numeric", altitude = "numeric")) |
| } |
| |
| The value returned is a function, typically assigned as here with the |
| name of the class. Calling this function returns an object from the |
| class; its arguments are named with the slot names. |
| If a function in the class had read the corresponding data, perhaps |
| from a CSV file or from a data base, it could return an object from |
| the class by: |
| |
| \code{Pos(latitude = x, longitude = y, altitude = z)} |
| |
| The slots are accessed by the |
| \code{\link{@}} operator; for example, if \code{g} is an object from |
| the class, \code{g@latitude}. |
| |
| In addition to returning a generator function the call to |
| \code{\link{setClass}()} assigns a definition of the class in a |
| special metadata object in the package's namespace. |
| When the package is loaded into an \R session, the class definition is |
| added to a table of known classes. |
| |
| To make the class and the generating function publicly available, the |
| package should include \code{POS} in \code{exportClasses()} and |
| \code{export()} directives in its \code{NAMESPACE} file: |
| |
| \code{exportClasses(Pos); export(Pos)} |
| } |
| |
| \section{Defining Methods}{ |
| Defining methods for an \R function makes that function |
| \emph{generic}. |
| Instead of a call to the function always being carried out by the same |
| method, there will be several alternatives. |
| These are selected by matching the classes of the arguments in the call to a |
| table in the generic function, indexed by classes for one or more formal arguments to the |
| function, known as the \emph{signatures} for the methods. |
| |
| |
| A method definition then specifies three things: the name of the |
| function, the signature and the method definition itself. |
| The definition must be a function with the same formal arguments as |
| the generic. |
| |
| For example, a method to make a plot of an object from class |
| \code{"Pos"} could be defined by: |
| |
| \code{setMethod("plot", c("Pos", "missing"), function(x, y, ...) \{ |
| plotPos(x, y) \})} |
| |
| This method will match a call to \code{\link{plot}()} if the first |
| argument is from class \code{"Pos"} or a subclass of that. |
| The second argument must be missing; only a missing argument matches |
| that class in the signature. |
| Any object will match class \code{"ANY"} in the corresponding position |
| of the signature. |
| } |
| |
| \section{Class Inheritance}{ |
| |
| A class may inherit all the slots and methods of one or more existing |
| classes by specifying the names of the inherited classes in the \code{contains =} argument to |
| \code{\link{setClass}()}. |
| |
| To define a class that extends class \code{"Pos"} to a class |
| \code{"GPS"} with a slot for the observation times: |
| |
| \code{GPS <- setClass("GPS", slots = c(time = "POSIXt"), contains = "Pos")} |
| |
| The inherited classes may be S4 classes, S3 |
| classes or basic data types. |
| S3 classes need to be identified as such by a call to |
| \code{\link{setOldClass}()}; most S3 classes in the base package and |
| many in the other built-in packages are already declared, as is |
| \code{"POSIXt"}. |
| If it had not been, the application package should contain: |
| |
| \code{setOldClass("POSIXt")} |
| |
| Inheriting from one of the \R types is special. Objects from the new |
| class will have the same type. A class |
| \code{Currency} that contains numeric data plus a slot \code{"unit"} |
| would be created by |
| |
| \code{Currency <- setClass("Currency", slots = c(unit = "character"), |
| contains = "numeric")} |
| |
| Objects created from this class will have type \code{"numeric"} and |
| inherit all the builtin arithmetic and other computations for that |
| type. |
| Classes can only inherit from at most one such type; if the class does |
| not inherit from a type, objects from the class will have type |
| \code{"S4"}. |
| |
| } |
| |
| |
| \references{ |
| Chambers, John M. (2016) |
| \emph{Extending R}, |
| Chapman & Hall. |
| (Chapters 9 and 10.) |
| } |
| |