R: Generate an Object from a Class

new {methods} | R Documentation

## Generate an Object from a Class

### Description

A call to `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 `initialize` corresponding to the specified class, passing the `...` arguments to this method. In the default method for `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 `setClass`) will pass its ... arguments to a corresponding call to `new()`.

### Usage

    new(Class, ...)

    initialize(.Object, ...)

### Arguments

`Class` | either the name of a class, a `character` string, (the usual case) or the object describing the class (e.g., the value returned by `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.
`...` | arguments to specify properties of the new object, to be passed to `initialize()`.
`.Object` | An object: see the “Initialize Methods” section.

### Initialize Methods

The generic function `initialize` is not called directly. A call to `new` begins by copying the prototype object from the class definition, and then calls `intialize()` with this object as the first argument, followed by the ... arguments.

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

In the default method, unnamed arguments in the `...` 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 `initialize` methods do not have to have `...` 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 `...` as a formal argument, and your method should pass such arguments along via `callNextMethod`. This helps the definition of future subclasses of your class. If these have additional slots and your method does not have this argument, it will be difficult for these slots to be included in an initializing call.

See `initialize-methods` for a discussion of some classes with existing methods.

Methods for `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 `simpleInheritanceOnly` argument to `setGeneric` and the discussion in `setIs` for the general concept.

Note that the basic vector classes, `"numeric"`, etc. are implicitly defined, so one can use `new` for these classes. The ... arguments are interpreted as objects of this type and are concatenated into the resulting vector.

### References

Chambers, John M. (2016) Extending R, Chapman & Hall. (Chapters 9 and 10.)

### See Also

Classes_Details for details of class definitions, and `setOldClass` for the relation to S3 classes.

### Examples

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

    ## 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
              })

[Package methods version 4.0.5 Index]