is                  package:methods                  R Documentation

_I_s _a_n _O_b_j_e_c_t _f_r_o_m _a _C_l_a_s_s

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

     `is':  With two arguments, tests whether `object' can be treated
     as from `class2'.

     With one argument, returns all the super-classes of this object's
     class.

     `extends':  Does the first class extend the second class? Returns
     `maybe' if the extension includes a test.

     `setIs':  Defines `class1' to be an extension of `class2'.

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

     is(object, class2)

     extends(class1, class2, maybe=TRUE)

     setIs(class1, class2, test=NULL, coerce=NULL, replace=NULL,
           by = NULL, where = 1, complete = TRUE)

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

  object: Any R object.

class1, class2: The names of the classes between which `is' relations
          are to be defined.

   maybe: What value to return if the relationship is conditional.

test, coerce, replace: Functions optionally supplied to test whether
          the relation is defined, to coerce the object to `class2',
          and to alter the object so that `is(object, class2)' is
          identical to `value'.

      by: The name of an intermediary class.  Coercion will proceed by
          first coercing to this class and from there to the target
          class.  (The intermediate coercions have to be valid.)

   where: Where to store the metadata defining the relationship.
          Default is the global environment.

complete: Should the class definitions be completed when checking for
          valid relations. Don't set this to anything other than
          `TRUE', unless you really know why you're doing it (used by
          `setClass').

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

     `setIs': 

     The relationship can be conditional, if a function is supplied as
     the `test' argument.  If a function is supplied as the `coerce'
     argument, this function will be applied to any `class1' object in
     order to turn it into a `class2' object. If the relationship is to
     be defined indirectly through a third class, this class can be
     named in the `by' argument.

     Extension may imply that a `class1' object contains a `class2'
     object.  The default sense of containing is that all the slots of
     the simpler class are found in the more elaborate one.  If the
     `replace' argument is supplied as an S replacement function, this
     function will be used to implement `as(obj, class2) <- value'.

     The `coerce', `replace', and `by' arguments behave as described
     for the `setAs' function. It's  unlikely you would use the `by'
     argument directly, but it is used in defining cached information
     about classes. The value returned (invisibly) by `setIs' is the
     extension information, as a list.

     Information about `setIs' relations can be stored in the metadata
     for either `class1' (in the `extends' information) or in the
     metadata for `class2' (in the `subclasses' information).  For the
     information to be retained for a future session, one of these
     classes must be defined in the global environment, since only
     objects assigned there are saved by `save.image'.  If neither
     class is defined in environment `where', `setIs' generates an
     error.

     Because only global environment information is saved, it rarely
     makes sense to give a value other than the default for argument
     `where'. One exception is `where=0', which modifies the cached
     (i.e., session-scope) information about the class.  Class
     completion computations use this version, but don't use it
     yourself unless you are quite sure you know what you're doing.

_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.

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

     ## a class definition (see setClass for the example)
     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 = structure(list(), x=numeric(), y=matrix(0,0,0), smooth= matrix(0,0,0)))
     ## Define a multi-curve to extend a single curve ONLY
     ## if the y data is one variable.
     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")), curve = as.numeric(slot(obj, "curve")))})

