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)

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

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

_A_u_t_h_o_r(_s):

     John Chambers

_R_e_f_e_r_e_n_c_e_s:

     The web page <URL: http://www.omegahat.org/RSMethods/index.html>
     is the primary documentation.

     The functions in this package emulate the facility for classes and
     methods described in Programming with Data (John M. Chambers,
     Springer, 1998).  See this book for further details and examples.

_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")))})

