The R Project SVN R

% File src/library/methods/man/setClass.Rd

% Part of the R package, https://www.R-project.org

% Copyright 1995-2017 R Core Team

% Distributed under GPL 2 or later

\name{setClass}

\alias{setClass}

\alias{classGeneratorFunction-class}

\title{Create a Class Definition}

\description{

  Create  a class definition and return a generator function to create

  objects from the class.  Typical usage will be

  of the style:

   \code{myClass <- setClass("myClass", slots= ...., contains =....)}

 where the first argument is the name of the new class and, if supplied, the arguments    

  \code{slots=} and \code{contains=} specify the slots

  in the new class and existing classes from which the new class

  should inherit.  Calls to \code{setClass()} are normally found in the

  source of a package; when the package is loaded the class will be

  defined in the package's namespace.  Assigning the generator

  function with the name of the class is  convenient for users, but

  not a requirement.

}

\usage{

setClass(Class, representation, prototype, contains=character(),

         validity, access, where, version, sealed, package,

         S3methods = FALSE, slots)

}

\arguments{

  \item{Class}{character string name for the class.}

  \item{slots}{  The names and classes for the slots in the new class.  This argument

      must be supplied by name, \code{slots=}, in the call, for back compatibility

      with other arguments no longer recommended.

      The argument must be  vector with a names attribute, the names being those of the slots in

      the new class.  Each element of the vector specifies an

      existing class; the corresponding slot must be from this class

      or a subclass of it.  Usually, this is a character vector

      naming the classes.  It's also legal for the elements of the

      vector to be class representation objects, as returned by \code{\link{getClass}}.

    As a limiting

    case,  the argument may be an unnamed character

    vector;  the elements are  taken as slot names and all slots have

    the unrestricted class \code{"ANY"}. 

  }

  \item{contains}{ A vector specifying existing classes from which

      this class should inherit. The new class will have all the slots

      of the superclasses, with the same requirements on the classes

      of these slots.  This argument

      must be supplied by name, \code{contains=}, in the call, for back compatibility

      with other arguments no longer recommended.

      See the section \sQuote{Virtual Classes} for the special

      superclass  \code{"VIRTUAL"}.

    }

  \item{prototype, where, validity, sealed, package}{

      \emph{These arguments are currently allowed, but either they are unlikely to be

        useful or there are modern alternatives that are preferred.}

     \code{prototype}: supplies an object with the default

    data for the slots in this class.  A more flexible approach is to

    write a method for \code{\link{initialize}()}.

  \code{where}: supplies an environment in which to store the definition.

    Should not be used:  For calls to

    \code{setClass()} appearing in the source code for a package the

    definition will be stored in the namespace of the package.

  \code{validity}: supplied a validity-checking method

    for objects from this class.  For clearer code, use a separate

    call to \code{\link{setValidity}()}.

  \code{sealed}: if \code{TRUE}, the class definition will be sealed,

    so that another call to \code{setClass} will fail on this class

    name.  But the definition is automatically sealed after the

    namespace is loaded, so explicit sealing it is not needed.

  \code{package}: supplies an optional package name for the class, but

  the class attribute should be  the package in which the class

  definition is assigned, as it is by default.

  }

  \item{representation, access, version, S3methods }{\emph{All these

    arguments are deprecated from version 3.0.0 of \R and should be

    avoided}.

    \code{representation} is an argument inherited from S that

    included both \code{slots} and \code{contains}, but the use of

    the latter two arguments is clearer and recommended.

    \code{access} and \code{version} are included for

    historical compatibility with S-Plus, but ignored.

    \code{S3methods} is a flag indicating that old-style methods

    will be written involving this class; ignored now.

  }

}

\value{

  A generator function suitable for creating objects from the class is

  returned, invisibly.  A call to this function generates a call to

  \code{\link{new}} for the class.  The call takes any number of arguments,

  which will be passed on to the initialize method.  If no

  \code{initialize} method is defined for the class or one of its

  superclasses, the default method expects named arguments with the

  name of one of the slots and unnamed arguments that are objects from

  one of the contained classes.

  Typically the generator function is assigned the name of the class,

  for programming clarity.  This is not a requirement and objects

  from the class can also be generated directly from

  \code{\link{new}}.  The advantages of the generator function are a

  slightly simpler and clearer call, and that the call will contain

  the package name of the class (eliminating any ambiguity if two

  classes from different packages have the same name).

  If the class is virtual, an attempt to generate an object  from

  either the generator or \code{new()}

  will result in an error.

}

\section{Basic Use: Slots and Inheritance}{

The two essential arguments other than the class name are

\code{slots} and \code{contains}, defining the explicit slots

and the inheritance (superclasses). Together, these arguments define

all the information in an object from this class; that is, the names

of all the slots and the classes required for each of them.

The name of the class determines

which methods apply directly to objects from this class.  The

superclass information specifies which methods apply indirectly,

through inheritance.  See \link{Methods_Details} for inheritance in method

selection.

The slots in a class definition will be the union of all the slots

specified directly by \code{slots} and all the slots in all

the contained classes.

There can only be one slot with a given name.

A class may override the definition of a slot with a given name, but

\emph{only} if the newly specified class is a subclass of the

inherited one.

For example, if the contained class had a slot \code{a} with class

\code{"ANY"}, then a subclass could specify \code{a} with class

\code{"numeric"},

but if the original specification for the slot was class

\code{"character"}, the new call to \code{setClass} would generate an error.

  Slot names \code{"class"} and \code{"Class"} are not allowed.

  There are other slot names with a special meaning; these names start with

  the \code{"."} character.  To be safe, you should define all of

  your own slots with names starting with an alphabetic character.

Some inherited classes will be treated specially---object types, S3

classes and a few special cases---whether inherited

directly or indirectly.  See the next three sections.

}

\section{Virtual Classes}{

      Classes exist for which no actual objects can be created, the

      \emph{virtual} classes.

      The most common and useful form of virtual class is the \emph{class

        union}, a virtual class that is defined in a call to

      \code{\link{setClassUnion}()} rather than a call to

      \code{setClass()}.

      This call lists the \emph{members} of the union---subclasses

      that extend the new class.

      Methods that are written with the class union in the signature

      are eligible for use with objects from any of the member classes.

      Class

      unions can include as members classes whose

      definition is otherwise sealed, including basic \R data types.

      Calls to \code{setClass()} will also create a virtual class,

      either when only the \code{Class} argument is supplied (no slots

      or superclasses) or when the \code{contains=} argument includes

      the special class name \code{"VIRTUAL"}.

      In the latter case, a

      virtual class may include

      slots to provide some common behavior without fully defining

      the object---see the class \code{\linkS4class{traceable}} for an

      example.

      Note that  \code{"VIRTUAL"} does not carry over to subclasses; a

      class that contains a virtual class is not itself automatically virtual.

}

\section{Inheriting from Object Types}{

In addition to containing other S4 classes, a class definition can

contain either an S3 class (see the next section) or a built-in R pseudo-class---one

of the \R

object types or one of the special \R pseudo-classes \code{"matrix"} and

\code{"array"}.

A class can contain at most one of the object types, directly or indirectly.

When it does, that contained class determines the \dQuote{data part}

of the class.

This appears as a pseudo-slot, \code{".Data"} and can be treated as a

slot but actually determines

the type of objects from this slot.

Objects from the new class try to inherit the built in

behavior of the contained type.

In the case of normal \R data types, including vectors, functions and

expressions, the implementation is relatively straightforward.

For any object \code{x} from the class,

\code{typeof(x)} will be the contained basic type; and a special

pseudo-slot, \code{.Data}, will be shown with the corresponding class.

See the \code{"numWithId"} example below.

Classes may also inherit from \code{"vector"}, \code{"matrix"} or

\code{"array"}.

The data part of these objects can be any vector data type.

For an object from any class that does \emph{not} contain one of these

types or classes,

\code{typeof(x)} will be \code{"S4"}.

Some \R data types do not behave normally, in the sense that they are

non-local references or other objects that are not duplicated.

Examples include those corresponding to classes \code{"environment"}, \code{"externalptr"}, and \code{"name"}.

These can not be the types for objects with user-defined

classes (either S4 or S3) because setting an attribute overwrites the

object in all contexts.

It is possible to define a class that inherits from such types,

through an indirect mechanism that stores the inherited object in a

reserved slot, \code{".xData"}.

See the

example for class \code{"stampedEnv"} below.

An object from such a class does \emph{not} have a \code{".Data"} pseudo-slot.

For most computations, these classes behave transparently as if they

inherited directly from the anomalous type.

S3 method dispatch and the relevant \code{as.}\emph{type}\code{()}

functions should behave correctly, but code that uses the type of the

object directly will not.

For example, \code{as.environment(e1)} would work as expected with the

\code{"stampedEnv"} class, but \code{typeof(e1)} is \code{"S4"}.

}

\section{Inheriting from S3 Classes}{

Old-style S3 classes have no formal definition.  Objects are

\dQuote{from} the class when their class attribute contains the

character string considered to be the class name.

Using such classes with formal classes and methods is necessarily a

risky business, since there are no guarantees about the content of the

objects or about consistency of inherited methods.

Given that, it is still possible to define a class that inherits from

an S3 class, providing that class has been registered as an old class

(see \code{\link{setOldClass}}).

Broadly speaking, both S3 and S4 method dispatch try to behave

sensibly with respect to inheritance in either system.

Given an S4 object, S3 method dispatch and the \code{\link{inherits}}

function should use the S4 inheritance information.

Given an S3 object, an S4 generic function will dispatch S4 methods

using the S3 inheritance, provided that inheritance has been declared via

\code{\link{setOldClass}}.  For details, see \code{\link{setOldClass}}

and Section 10.8 of the reference.

}

\section{Classes and Packages}{

Class definitions normally belong to packages (but can be defined in

the  global environment as well, by evaluating the expression on the

command line or in a file sourced from the command line).

The corresponding package name is part of the class definition; that

is, part of the \code{\linkS4class{classRepresentation}} object holding that

definition.  Thus, two classes with the same name can exist in

different packages, for most purposes.

When a class name is supplied for a slot or a superclass in a call to

\code{setClass}, a

corresponding class definition will be found, looking from the

namespace of the current package, assuming the call in question appears directly in the source for the

package, as it should to avoid ambiguity.

The  class definition

must be already defined in this package, in the imports directives of

the package's \code{DESCRIPTION} and

\code{NAMESPACE} files or in the basic classes defined by the methods package.

(The \sQuote{methods} package must be included in the imports directives

for any package that uses

S4 methods and classes, to satisfy the

\code{"CMD check"} utility.)

If a package imports two classes of the same name from separate packages, the \code{\link{packageSlot}}

of the \code{name} argument needs to be set to the package name of the

particular class.

This should be a rare occurrence.

}

\references{

 Chambers, John M. (2016)

 \emph{Extending R},

  Chapman & Hall.

(Chapters 9 and 10.)

}

\seealso{

  \code{\link{Classes_Details}} for a general discussion of classes,

  \code{\link{Methods_Details}} for an analogous discussion of methods,

  \code{\link{makeClassRepresentation}}

}

\examples{

\dontshow{

 if(isClass("trackMultiCurve")) removeClass("trackMultiCurve")

 if(isClass("trackCurve"))      removeClass("trackCurve")

 if(isClass("track"))           removeClass("track")

}

## A simple class with two slots

track <- setClass("track", slots = c(x="numeric", y="numeric"))

## an object from the class

t1 <- track(x = 1:10, y = 1:10 + rnorm(10))

## A class extending the previous, adding one more slot

trackCurve <- setClass("trackCurve",

		slots = c(smooth = "numeric"),

		contains = "track")

## an object containing a superclass object

t1s <- trackCurve(t1, smooth = 1:10)

## A class similar to "trackCurve", but with different structure

## allowing matrices for the "y" and "smooth" slots

setClass("trackMultiCurve",

         slots = c(x="numeric", y="matrix", smooth="matrix"),

         prototype = list(x=numeric(), y=matrix(0,0,0),

                          smooth= matrix(0,0,0)))

## A class that extends the built-in data type "numeric"

numWithId <- setClass("numWithId", slots = c(id = "character"),

         contains = "numeric")

numWithId(1:3, id = "An Example")

## inherit from reference object of type "environment"

stampedEnv <- setClass("stampedEnv", contains = "environment",

                       slots = c(update = "POSIXct"))

setMethod("[[<-", c("stampedEnv", "character", "missing"),

   function(x, i, j, ..., value) {

       ev <- as(x, "environment")

       ev[[i]] <- value  #update the object in the environment

       x@update <- Sys.time() # and the update time

       x})

e1 <- stampedEnv(update = Sys.time())

e1[["noise"]] <- rnorm(10)

\dontshow{

tMC <- new("trackMultiCurve")

is.matrix(slot(tMC, "y"))

is.matrix(slot(tMC, "smooth"))

setClass("myMatrix", "matrix", prototype = matrix(0,0,0))

nrow(new("myMatrix")) # 0

nrow(new("matrix")) # 1

## simple test of prototype data

xxx <- stats::rnorm(3)

setClass("xNum", slots = c(x = "numeric"), prototype = list(x = xxx))

stopifnot(identical(new("xNum")@x, xxx))

removeClass("xNum")

removeClass("myMatrix")

## The following should not be needed.  But make check removes all files

## between example files, in a crude way that does not cause the class

## information to be reset.  There seems no way to detect this, so we

## have to remove classes ourselves

removeClass("trackMultiCurve")

removeClass("trackCurve")

removeClass("track")

}%dont show

}

\keyword{programming}

\keyword{classes}

\keyword{methods}