The R Project SVN R

% File src/library/methods/man/initialize-methods.Rd

% Part of the R package, https://www.R-project.org

% Copyright 1995-2007 R Core Team

% Distributed under GPL 2 or later

\name{initialize-methods}

\docType{methods}

\title{Methods to Initialize New Objects from a Class}

\alias{initialize-methods}

\alias{initialize,ANY-method}

\alias{initialize,traceable-method}

\alias{initialize,signature-method}

\alias{initialize,environment-method}

\alias{initialize,.environment-method}

\description{

  The arguments to function \code{\link{new}} to create an object from a

  particular class can be interpreted specially for that class, by the

  definition of a method for function \code{initialize} for the class.

  This documentation describes some existing methods, and also outlines

  how to write new ones.

}

\section{Methods}{

  \describe{

    \item{\code{signature(.Object = "ANY")}}{

      The default method for \code{initialize} takes either named or

      unnamed arguments.  Argument names must be the names of slots in

      this class definition, and the corresponding arguments must be

      valid objects for the slot (that is, have the same class as

      specified for the slot, or some superclass of that class).  If the

      object comes from a superclass, it is not coerced strictly, so

      normally it will retain its current class (specifically,

      \code{\link{as}(object, Class, strict = FALSE)}).

      Unnamed arguments must be objects of this class, of one of its

      superclasses, or one of its subclasses (from the class, from a

      class this class extends, or from a class that extends this

      class). If the object is from a superclass, this normally defines

      some of the slots in the object.  If the object is from a

      subclass, the new object is that argument, coerced to the current

      class.

      Unnamed arguments are processed first, in the order they appear.

      Then named arguments are processed.  Therefore, explicit values

      for slots always override any values inferred from superclass or

      subclass arguments.

    }

    \item{\code{signature(.Object = "traceable")}}{

      Objects of a class that extends \code{traceable} are used to

      implement debug tracing (see class \linkS4class{traceable} and

      \code{\link{trace}}).

      The \code{initialize} method for these classes takes special

      arguments \code{def, tracer, exit, at, print}.  The first of these

      is the object to use as the original definition (e.g., a

      function).  The others correspond to the arguments to

      \code{\link{trace}}.

    }

    \item{\code{signature(.Object = "environment")}, \code{signature(.Object = ".environment")}}{

      The \code{initialize} method for environments takes a named list

      of objects to be used to initialize the environment.  Subclasses

      of \code{"environment"} inherit an initialize method through

      \code{".environment"}, which has the additional effect of

      allocating a new environment.  If you define your own method for

      such a subclass, be sure either to call the existing method via

      \code{\link{callNextMethod}} or allocate an environment in your

      method, since environments are references and are not duplicated

      automatically.

    }

    \item{\code{signature(.Object = "signature")}}{

      This is a method for internal use only.

      It takes an optional \code{functionDef} argument to provide a

      generic function with a \code{signature} slot to define the

      argument names.  See \link{Methods_Details} for details.

    }

  }

}

\section{Writing Initialization Methods}{

  Initialization methods provide a general mechanism corresponding to

  generator functions in other languages.

  The arguments to \code{\link{initialize}} are \code{.Object} and

  \dots. Nearly always, \code{initialize} is called from \code{new},

  not directly.  The \code{.Object} argument is then the

  prototype object from the class.

  Two techniques are often appropriate for \code{initialize} methods:

  special argument names and \code{callNextMethod}.

  You may want argument names that are more natural to your users than

  the (default) slot names.  These will be the formal arguments to

  your method definition, in addition to \code{.Object} (always) and

  \dots (optionally).  For example, the method for class

  \code{"traceable"} documented above would be created by a call to

  \code{\link{setMethod}} of the form:

\preformatted{    setMethod("initialize", "traceable",

      function(.Object, def, tracer, exit, at, print) \dots

    )

}

  In this example, no other arguments are meaningful, and the resulting

  method will throw an error if other names are supplied.

  When your new class extends another class, you may want to call the

  initialize method for this superclass (either a special method or the

  default).  For example, suppose you want to define a method for your

  class, with special argument \code{x}, but you also want users to be

  able to set slots specifically.  If you want \code{x} to override the

  slot information, the beginning of your method definition might look

  something like this:

\preformatted{    function(.Object, x, ...) \{

      Object <- callNextMethod(.Object, ...)

      if(!missing(x)) \{ # do something with x

}

  You could also choose to have the inherited method override, by first

  interpreting \code{x}, and then calling the next method.

}

\keyword{methods}

\keyword{programming}