setMethod              package:methods              R Documentation

_C_r_e_a_t_e _a_n_d _S_a_v_e _a _M_e_t_h_o_d

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

     Create and save a formal method for a given function and list of
     classes.

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

     setMethod(f, signature=character(), definition, where=1, valueClass)

     removeMethod(f, signature, where)

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

       f: The character-string name of the generic function. 

signature: A match of formal argument names for `f' with the
          character-string names of corresponding classes.  This
          argument can also just be the vector of class names, in which
          case the first name corresponds to the first formal argument,
          the next to the second formal argument, etc.

definition: A function definition, which will become the method called
          when the arguments in a call to `f' match the classes in
          `signature', directly or through inheritance. 

   where: The database in which to store the definition of the method;
          by default, the current global environment.

          For `removeMethod', the default is the location of the
          (first) instance of the method for this signature.

valueClass: If supplied, this argument asserts that the method will
          return a value of this class.  (At present this argument is
          stored but not explicitly used.) 

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

     R methods for a particular generic function are stored in an
     object of class `MethodsList', which in turn is stored with the
     definition of the generic function.  The effect of calling
     `setMethod' is to store `definition'  in a `MethodsList' object in
     a definition of the generic function on database `where'.   If no
     such function exists (on that database) one will be created, by
     copying the generic function from where it is found in the current
     search list.  Finally, if `f' doesn't exist as a generic function,
     but there is an ordinary function of the same name and the same
     formal arguments, a new generic function is created, and the
     previous non-generic version of `f' becomes the default method.

     Methods are stored in a hierarchical structure, by formal
     arguments to `f':  see `MethodsList' for details.  The class names
     in the signature can be any formal class, plus predefined basic
     classes such as `"numeric"', `"character"', and `"matrix"'.  Two
     additional special class names can appear: `"ANY"', meaning that
     this argument can have any class at all; and `"missing"', meaning
     that this argument must not appear in the call in order to match
     this signature.  Don't confuse these two:  if an argument isn't
     mentioned in a signature, it corresponds implicitly to class
     `"ANY"', not to `"missing"'.  See the example below.

     While `f' can correspond to methods defined on several packages or
     environments, the underlying model is that these together make up
     the definition for a single generic function.  When R proceeds to
     select and evaluate methods for `f', the methods on the current
     search list are merged to form a single generic.  In particular,
     all the versions of `f' and all the methods must correspond to the
     same formal arguments (including, in the present definition, the
     same default expressions for the arguments).  For compatibility
     with S-Plus, the current implementation enforces this partly with
     a warning and a reconstruction of a method that fails to match,
     but don't count on this for the future:  Make the formal arguments
     of `definition' match those of the generic..

_V_a_l_u_e:

     These functions exist for their side-effect, in setting or
     removing a method in the object defining methods for the specified
     generic.

     The value returned by `removeMethod' is `TRUE' if a method was
     found to be removed.

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

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

     Methods, `MethodsList' for details of the implementation

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

     ## methods for plotting track objects (see the example for setClass)
     ##
     ## First, with only one object as argument:
     setMethod("plot", signature(x="track", y="missing"),
       function(x,  y, ...) plot(slot(x, "x"), slot(x, "y"), ...)
     )
     ## Second, plot the data from the track on the y-axis against anything
     ## as the x data.
     setMethod("plot", signature(y = "track"),
      function(x, y, ...) plot(x, slot(y, "y"), ...)
     )
     ## and similarly with the track on the x-axis (using the short form of
     ## specification for signatures)
     setMethod("plot", "track",
      function(x, y, ...) plot(slot(x, "y"), y,  ...)
     )
     t1 <- new("track", x=1:20, y=(1:20)^2)
     tc1 <- new("trackCurve", t1)
     slot(tc1, "smooth") <- smooth.spline(slot(tc1, "x"), slot(tc1, "y"))$y #$
     plot(t1)
     plot(qnorm(ppoints(20)), t1)
     ## An example of inherited methods, and of conforming method arguments
     ## (note the dotCurve argument in the method, which will be pulled out
     ## of ... in the generic.
     setMethod("plot", c("trackCurve", "missing"),
     function(x, y, dotCurve = FALSE, ...) {
       plot(as(x, "track"))
       if(length(slot(x, "smooth") > 0))
         lines(slot(x, "x"), slot(x, "smooth"),
              lty = if(dotCurve) 2 else 1)
       }
     )
     ## the plot of tc1 alone has an added curve; other uses of tc1
     ## are treated as if it were a "track" object.
     plot(tc1, dotCurve = TRUE)
     plot(qnorm(ppoints(20)), tc1)

     ## defining methods for a special function.
     ## Although "[" and "length" are not ordinary functions
     ## methods can be defined for them.
     setMethod("[", "track",
       function(x, i, j, ..., drop) {
         x@x <- x@x[i]; x@y <- x@y[i]
         x
       })
     plot(t1[1:15])

     setMethod("length", "track", function(x)length(x@y))
     length(t1)

     ## methods can be defined for missing arguments as well
     setGeneric("summary") ## make the function into a generic

     ## A method for summary()
     ## The method definition can include the arguments, but
     ## if they're omitted, class "missing" is assumed.

     setMethod("summary", "missing", function() "<No Object>")

