setClassUnion            package:methods            R Documentation

Classes Defined as the Union of Other Classes

Description:

     A class may be defined as the _union_ of other classes; that is,
     as a virtual class defined as a superclass of several other
     classes. Class unions are useful in method signatures or as slots
     in other classes, when we want to allow one of several classes to
     be supplied.

Usage:

     setClassUnion(name, members, where)
     isClassUnion(Class)

Arguments:

    name: the name for the new union class. 

 members: the classes that should be members of this union.

   where: where to save the new class definition; by default, the
          environment of the package in which the 'setClassUnion' call
          appears, or the global environment if called outside of the
          source of a package.

   Class: the name or definition of a class. 

Details:

     The classes in 'members' must be defined before creating the
     union.  However, members can be added later on to an existing
     union, as shown in the example below. Class unions can be members
     of other class unions.

     Class unions are the only way to create a class that is extended
     by a class whose definition is sealed (for example, the basic
     datatypes or other classes defined in the base or methods package
     in R are sealed).  You cannot say 'setIs("function", "other")'
     unless '"other"' is a class union.  In general, a 'setIs' call of
     this form changes the definition of the first class mentioned
     (adding '"other"' to the list of superclasses contained in the
     definition of '"function"').

     Class unions get around this by not modifying the first class
     definition, relying instead on storing information in the
     subclasses slot of the class union.  In order for this technique
     to work, the internal computations for expressions such as
     'extends(class1, class2)' work differently for class unions than
     for regular classes; specifically, they test whether any class is
     in common between the superclasses of 'class1' and the subclasses
     of 'class2'.

     The different behavior for class unions is made possible because
     the class definition object for class unions has itself a special
     class, '"ClassUnionRepresentation"', an extension of
     '"classRepresentation"' (see classRepresentation-class).

References:

     The R package 'methods' implements, with a few exceptions, the
     programming interface for classes and methods in the book
     _Programming with Data_ (John M. Chambers, Springer, 1998), in
     particular sections 1.6, 2.7, 2.8, and chapters 7 and 8.

     While the programming interface for the 'methods' package follows
     the reference, the R software is an original implementation, so
     details in the reference that reflect the S4 implementation may
     appear differently in R.  Also, there are extensions to the
     programming interface developed more recently than the reference. 
     For a discussion of details see '?Methods' and the links from that
     documentation.

Examples:

     ## a class for either numeric or logical data
     setClassUnion("maybeNumber", c("numeric", "logical"))

     ## use the union as the data part of another class
     setClass("withId", representation("maybeNumber", id = "character"))

     w1 <- new("withId", 1:10, id = "test 1")
     w2 <- new("withId", sqrt(w1)%%1 < .01, id = "Perfect squares")

     ## add class "complex" to the union "maybeNumber"
     setIs("complex", "maybeNumber")

     w3 <- new("withId", complex(real = 1:10, imaginary = sqrt(1:10)))

     ## a class union containing the existing class  union "OptionalFunction"
     setClassUnion("maybeCode",
         c("expression", "language", "OptionalFunction"))

     is(quote(sqrt(1:10)), "maybeCode")  ## TRUE

