% File src/library/methods/man/new.Rd
% Part of the R package, https://www.R-project.org
% 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
  class identified by the first argument.  This call in turn calls the
  method for the generic function \code{initialize} corresponding to
  the specified class, passing the \code{\dots} arguments to this
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}). Note that the character
    string passed from a generating function includes the package name
  as an attribute, avoiding ambiguity if two packages have identically
named classes.}
  \item{\dots}{arguments to specify properties of the new object, to
      be passed to \code{initialize()}.}
  \item{.Object}{ An object:  see the \dQuote{Initialize Methods} section.}
}
\section{Initialize Methods}{
The generic function \code{initialize} is not called directly.
A call to \code{new} begins by copying the prototype object from
  the class definition, and then calls \code{intialize()} with this
  object as the first argument, followed by the \dots{} arguments. 

  The interpretation of the \code{\dots} arguments in a call to a
  generator function or to \code{new()} can be specialized to
  particular classes, by defining an appropriate method for \code{"initialize"}. 

  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.
  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,
you should include  \code{\dots} as a formal argument, and your method should pass such
  arguments along via \code{\link{callNextMethod}}. 
 This helps the definition of future subclasses of your class.  If these
  have additional slots and your method
  does \emph{not} have this argument, it will be difficult for these
  slots to be included in an initializing call.

  See
  \code{\link{initialize-methods}} for a discussion of some classes with existing
  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. (2016)
 \emph{Extending R},
  Chapman & Hall.
(Chapters 9 and 10.)
}
\seealso{ \link{Classes_Details} for details of class definitions, and
  \code{\link{setOldClass}} for the relation to S3 classes. }

\examples{
## using the definition of class "track" from \link{setClass}

\dontshow{
setClass("track", slots = c(x="numeric", y="numeric"))
setClass("trackCurve", contains = "track",
          slots = c(smooth = "numeric"))

ydata <- stats::rnorm(10); ysmooth <- 1:10
}

## a new object with two slots specified
t1 <- new("track", x = seq_along(ydata), y = ydata)

# 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
### supplied by name.

setMethod("initialize", "track", 
    function(.Object, ...) {
      .Object <- callNextMethod()
      if(length(.Object@x) != length(.Object@y))
      stop("specified x and y of different lengths")
      .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), ...) {
              .Object <- callNextMethod(.Object, ...)
              if(length(x) != length(y))
                  stop("specified x and y of different lengths")
              .Object@x <- x
              .Object@y <- y
              .Object
          })

\dontshow{
removeMethod("initialize", "track")
}
}
\keyword{programming}
\keyword{classes}