setClass               package:methods               R Documentation

_C_r_e_a_t_e _a _C_l_a_s_s _D_e_f_i_n_i_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     Create a formally defined class with specified slots and/or
     relationships to other classes.  Also functions to remove a class
     definition, to test whether a class has been defined, to test
     whether an object is a class definition, and to reset the internal
     definition of a class.

_U_s_a_g_e:

     setClass(Class, representation, prototype, contains=character(), validity, 
              access, where=1, version=FALSE, sealed, package)

     removeClass(Class, where=-1, removeSubclassLinks = TRUE)

     isClass(Class, formal=TRUE)
     isClassDef(object)

     getClasses(where)

     findClass(Class)

     resetClass(Class, resetSubclasses = TRUE)

_A_r_g_u_m_e_n_t_s:

   Class: character string name for the class 

representation: the slots that the new class should have and/or other
          classes that this class extends.  Usually a call to the
          `representation' function. 

prototype: an object (usually a list) providing the default data for
          the slots specified in the representation. 

contains: what classes does this class extend?  (These are called
          superclasses in some languages.)  When these classes have
          slots, all their slots will be contained in the new class as
          well. 

   where: What environment to use to store or remove the definition (as
          metadata). By default, uses the global environment for
          `setClass' and searches for a definition to remove, for
          `removeClass'. 

validity, access, version: Control arguments included for compatibility
          with the S-Plus API, but not currently used.  

  sealed: If `TRUE', the class definition will be sealed, so that
          another call to `setClass' will fail on this class name. 

 package: An optional package name for the class.  By default (and
          usually) the package where the class definition is assigned
          will be used. 

       x: an arbitrary object.

  formal: Should a formal definition be required? 

  object: any R object. 

removeSubclassLinks: When a class is removed, any links to that class
          from other classes will become invalid.  If this argument is
          not supplied as `FALSE', then `removeClass' will search for
          all such links and delete them. You can omit the  argument,
          or supply it as the positions in the search list to look for
          these links (by default all attached object tables will be
          searched).

resetSubclasses: Should `resetClass' also reset all known subclasses. 
          Usually `TRUE', unless you know from the context these will
          be reset elsewhere.

_D_e_t_a_i_l_s:

     These are the functions that create and manipulate formal class
     definitions.  Brief documentation is provided below.  See the
     references for an introduction and for more details.

     `_s_e_t_C_l_a_s_s': Define `Class' to be an S-style class.  The effect is
          to create an object, of class `"classRepEnvironment"', and
          store this (hidden) in the specified environment or database.
           Objects can be created from the class (e.g., by calling
          `new'), manipulated (e.g., by accessing the object's slots),
          and methods may be defined including the class name in the
          signature (see `setMethod').


     `_r_e_m_o_v_e_C_l_a_s_s': Remove the definition of this class.  Calling this
          always resets the version of the class cached for the
          session.  If `where=0', that's all it does.  Otherwise, it
          removes the version from the specified environment or
          database (from the global environment by default).


     `_i_s_C_l_a_s_s': Is this a the name of a formally defined class?
          (Argument `formal' is for compatibility and is ignored.)


     `_i_s_C_l_a_s_s_D_e_f': Is this object a class definition (it will be, for
          example, if it is the value of a call to `getClass', the
          complete definition of a class with its extensions, or to
          `getClassDef', the local definition of the class).


     `_g_e_t_C_l_a_s_s_e_s': The names of all the classes formally defined on
          `where'.  If called with no argument, all the classes
          currently known in the session (which does not include
          classes that may be defined on one of the attached packages,
          but have not yet been used in the session).

     `_f_i_n_d_C_l_a_s_s': Where on the current search list the class named
          `Class' is defined.  (If there is more than one definition,
          all corresponding elements of the search list are returned.)


     `_u_n_c_l_a_s_s': Returns the object containing the values of all the
          slots in this object's class definition (specifically, if the
          returned object has attributes corresponding to each slot),
          in the case that the object's class is formally defined with
          slots.  For classes that extend a single other class (e.g., a
          basic class such as `"numeric"') the result is an object of
          that class.


     `_r_e_s_e_t_C_l_a_s_s': Reset the internal definition of a class.  The
          effect is that the next time the definition of this class is
          needed, it will be recomputed from the information in the
          currently attached packages.

          This function is called when aspects of the class definition
          are changed.  You would need to call it explicitly if you
          changed the definition of a class that this class extends
          (but doing that in the  middle of a session is living
          dangerously, since it may invalidate existing objects).


_I_n_h_e_r_i_t_a_n_c_e _a_n_d _P_r_o_t_o_t_y_p_e_s:

     Defining new classes that inherit from (``extend'') other classes
     is a powerful technique, but has to be used carefully and not
     over-used. Otherwise, you will often get unintended results when
     you start to compute with objects from the new class.

     As shown in the examples below, the simplest and safest form of
     inheritance is to start with an explicit class, with some slots,
     that does not extend anything else.  It only does what we say it
     does.

     Then extensions will add some new slots and new behavior.

     Another variety of extension starts with one of the basic classes,
     perhaps with the intension of modifying R's standard behavior for
     that class.  Perfectly legal and sometimes quite helpful, but you
     may need to be more careful in this case:  your new class will
     inherit much of the behavior of the basic (informally defined)
     class, and the results can be surprising.  Just proceed with
     caution and plenty of testing.

     As an example, the class `"matrix"' is included in the pre-defined
     classes, to behave essentially as matrices do without formal class
     definitions.  Suppose we don't like all of this; in particular, we
     want the default matrix to have 0 rows and columns (not 1 by 1 as
     it is now).

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

     The arguments above illustrate two short-cuts relevant to such
     examples.  We abbreviated the `representation' argument to the
     single superclass, because the new class doesn't add anything to
     the representation of class `"matrix"'.  Also, we provided an
     object from the superclass as the prototype, not a list of slots.

_R_e_f_e_r_e_n_c_e_s:

     The R package `methods' implements, with a few exceptions, the
     programming interface for classes and methods in the book
     Programming with Data (John M. Chambers, Springer, 1998), in
     particular sections 1.6, 2.7, 2.8, and chapters 7 and 8.

     While the programming interface for the methods package follows
     the reference, the R software is an original implementation, so
     details in the reference that reflect the S4 implementation may
     appear differently in R.  Also, there are extensions to the
     programming interface developed more recently than the reference. 
     For a discussion of details and ongoing development, see the web
     page  <URL: http://developer.r-project.org/methodsPackage.html>
     and the pointers from that page.

_S_e_e _A_l_s_o:

     `Methods', `makeClassRepresentation'

_E_x_a_m_p_l_e_s:

     ## A simple class with two slots
     setClass("track",
                 representation(x="numeric", y="numeric"))
     ## A class extending the previous, adding one more slot
     setClass("trackCurve",
                 representation("track", smooth = "numeric"))
     ## A class similar to "trackCurve", but with different structure
     ## allowing matrices for the "y" and "smooth" slots
     setClass("trackMultiCurve", representation(x="numeric", y="matrix", smooth="matrix"),
               prototype = list(x=numeric(), y=matrix(0,0,0), smooth= matrix(0,0,0)))
     ##
     ## Suppose we want  trackMultiCurve to be like trackCurve when there's only
     ## one column
     ## First, the wrong way. 
     try(setIs("trackMultiCurve", "trackCurve",
       test = function(obj) {ncol(slot(obj, "y")) == 1}))

     ## why didn't that work?  You can only override the slots "x", "y", and "smooth"
     ## if you provide an explicit coerce function to correct any inconsistencies:

     setIs("trackMultiCurve", "trackCurve",
       test = function(obj) {ncol(slot(obj, "y")) == 1},
       coerce = function(obj) { new("trackCurve", x = slot(obj, "x"),
             y = as.numeric(slot(obj,"y")), smooth = as.numeric(slot(obj, "smooth")))})

