The R Project SVN – R – Diff – /trunk/src/library/methods/man/new.Rd

 % File src/library/methods/man/new.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2016 R Core Team
+% Copyright 1995-2017 R Core Team
 % Distributed under GPL 2 or later
 \name{new}
 \alias{new}
 \alias{initialize}
 \title{ Generate an Object from a Class }
 \description{
+  A call to  \code{new} returns a newly allocated object from the
-  Given the name or the definition of a class, plus optionally data
+  class identified by the first argument.  This call in turn calls the
+  method for the generic function \code{initialize} corresponding to
-  to be included in the object, \code{new} returns an object from that
+  the specified class, passing the \code{\dots} arguments to this
-  class.
+method.
+In the default method for \code{initialize()}, named arguments provide
+values for the corresponding slots and unnamed arguments must be
+objects from superclasses of this class.
+A call to a generating function for a class (see
+\code{\link{setClass}}) will pass its \dots arguments to a corresponding call to \code{new()}.
+}
 \usage{
 new(Class, ...)
 initialize(.Object, ...)
+}
 \arguments{
   \item{Class}{either the name of a class, a \code{\link{character}}
     string, (the usual case) or the object describing the class (e.g.,
-    the value returned by \code{getClass}).}
+    the value returned by \code{getClass}). Note that the character
-  \item{\dots}{data to include in the new object.  Named arguments
+    string passed from a generating function includes the package name
-    correspond to slots in the class definition. Unnamed arguments must
+  as an attribute, avoiding ambiguity if two packages have identically
+named classes.}
+  \item{\dots}{arguments to specify properties of the new object, to
-    be objects from classes that this class extends.}
+      be passed to \code{initialize()}.}
-  \item{.Object}{ An object:  see the Details section.}
+  \item{.Object}{ An object:  see the \dQuote{Initialize Methods} section.}
 }
-\details{
+\section{Initialize Methods}{
-  The function \code{new} begins by copying the prototype object from
-  the class definition.  Then information is inserted according to the
+The generic function \code{initialize} is not called directly.
-  \code{\dots} arguments, if any.  As of version 2.4 of R, the type of
+A call to \code{new} begins by copying the prototype object from
-  the prototype object, and therefore of all objects returned by
+  the class definition, and then calls \code{intialize()} with this
-  \code{new()}, is \code{"S4"} except for classes that extend
-  one of the basic types, where the prototype has that basic type.  User
+  object as the first argument, followed by the \dots{} arguments.
-  functions that depend on \code{\link{typeof}(object)} should be
-  careful to handle \code{"S4"} as a possible type.
-  Note that the \emph{name} of the first argument, \code{"Class"}
+  The interpretation of the \code{\dots} arguments in a call to a
-  entails that \code{"Class"} is an undesirable slot name in any formal
-  class: \code{new("myClass", Class = <value>)} will not work.
-  The interpretation of the \code{\dots} arguments can be specialized to
+  generator function or to \code{new()} can be specialized to
-  particular classes, if an appropriate method has been defined for the
+  particular classes, by defining an appropriate method for \code{"initialize"}.
-  generic function \code{"initialize"}.  The \code{new} function calls
-  \code{initialize} with the object generated from the prototype as the
-  \code{.Object} argument to \code{initialize}.
-  By default, unnamed arguments in the \code{\dots} are interpreted as
+  In the default method, unnamed arguments in the \code{\dots} are interpreted as
   objects from a superclass, and named arguments are interpreted as
-  objects to be assigned into the correspondingly named slots.  Thus,
+  objects to be assigned into the correspondingly named slots.
-  explicit slots override inherited information for the same slot,
+  Explicitly specified slots override inherited information for the same slot,
   regardless of the order in which the arguments appear.
   The \code{initialize} methods do not have to have \code{\dots} as
   their second argument (see the examples).  Initialize methods are
   often written when the natural parameters describing the new object
   are not the names of the slots.  If you do define such a method,
-  note the implications for future subclasses of your class.  If these
-  have additional slots, and your \code{initialize} method has
-  \code{\dots} as a formal argument, then your method should pass such
+you should include  \code{\dots} as a formal argument, and your method should pass such
-  arguments along via \code{\link{callNextMethod}}.  If your method
+  arguments along via \code{\link{callNextMethod}}.
-  does not have this argument, then either a subclass must have its
+ This helps the definition of future subclasses of your class.  If these
+  have additional slots and your method
-  own method or else the added slots must be specified by users in
+  does \emph{not} have this argument, it will be difficult for these
-  some way other than as arguments to \code{new}.
+  slots to be included in an initializing call.
-  For examples of \code{initialize} methods, see
+  See
-  \code{\link{initialize-methods}} for existing methods for
+  \code{\link{initialize-methods}} for a discussion of some classes with existing
-  classes \code{"traceable"} and \code{"environment"}, among
-  others. See the comments there on subclasses of
-  \code{"environment"}; any \code{initialize} methods for these should
-  be sure to allocate a new environment.
+  methods.
   Methods for \code{initialize} can be inherited only by simple
   inheritance, since it is a requirement that the method return an
   object from the target class.  See the
   \code{simpleInheritanceOnly} argument to \code{\link{setGeneric}} and
   the discussion in \code{\link{setIs}} for the general concept.
   Note that the basic vector classes, \code{"numeric"}, etc. are
   implicitly defined, so one can use \code{new} for these classes.
+  The \dots arguments are interpreted as objects of this type and are
+  concatenated into the resulting vector.
+}
 \references{
- Chambers, John M. (2008)
+ Chambers, John M. (2016)
- \emph{Software for Data Analysis: Programming with R}
+ \emph{Extending R},
-  Springer.  (For the R version.)
+  Chapman & Hall.
- Chambers, John M. (1998)
+(Chapters 9 and 10.)
- \emph{Programming with Data}
- Springer (For the original S4 version.)
+}
 \seealso{ \link{Classes_Details} for details of class definitions, and
   \code{\link{setOldClass}} for the relation to S3 classes. }
 \examples{
 # a new object including an object from a superclass, plus a slot
 t2 <- new("trackCurve", t1, smooth = ysmooth)
 ### define a method for initialize, to ensure that new objects have
+### equal-length x and y slots.  In this version, the slots must still be
-### equal-length x and y slots.
+### supplied by name.
-setMethod("initialize",
+setMethod("initialize", "track",
+    function(.Object, ...) {
+      .Object <- callNextMethod()
+      if(length(.Object@x) != length(.Object@y))
+      stop("specified x and y of different lengths")
-          "track",
+      .Object
+    })
+### An alternative version that allows x and y to be supplied
+### unnamed.  A still more friendly version would make the default x
+### a vector of the same length as y, and vice versa.
+setMethod("initialize", "track",
-          function(.Object, x = numeric(0), y = numeric(0)) {
+          function(.Object, x = numeric(0), y = numeric(0), ...) {
-            if(nargs() > 1) {
+              .Object <- callNextMethod(.Object, ...)
               if(length(x) != length(y))
-                stop("specified x and y of different lengths")
+                  stop("specified x and y of different lengths")
               .Object@x <- x
               .Object@y <- y
-            }
-            .Object
+              .Object
           })
-### the next example will cause an error (x will be numeric(0)),
-### because we didn't build in defaults for x,
-### although we could with a more elaborate method for initialize
-try(new("track", y = sort(stats::rnorm(10))))
-## a better way to implement the previous initialize method.
-## Why?  By using callNextMethod to call the default initialize method
-## we don't inhibit classes that extend "track" from using the general
-## form of the new() function.  In the previous version, they could only
-## use x and y as arguments to new, unless they wrote their own
-## initialize method.
+\dontshow{
-setMethod("initialize", "track", function(.Object, ...) {
+removeMethod("initialize", "track")
-    .Object <- callNextMethod()
-    if(length(.Object@x) != length(.Object@y))
-     stop("specified x and y of different lengths")
-    .Object
-  })
+}
+}
 \keyword{programming}
 \keyword{classes}

The R Project SVN R

(root)/trunk/src/library/methods/man/new.Rd – Rev 71366 → 71909