Chapter 12

The Built-In Functions

Constructing and Initializing Instances

Instance creation and initialization is performed by the open generic functions make and initialize. For an overview of the allocation and initialization process, see Instance Creation and Initialization beginning on page 64.

General Constructor

make [Open Generic Function]

Returns a general instance of its first argument.

Signature:

make type #rest supplied-init-args #key #all-keys ⇒ instance

Arguments:
type

An instance of <type>.

supplied-init-args

Keyword/argument pairs.

Values:
instance

An <object>, which must be a general instance of type.

Description:

Returns an instance of type, with characteristics specified by keyword arguments.

The instance returned is guaranteed to be a general instance of type but not necessarily a direct instance of type. This liberality allows make to be called on an abstract class or other type; it can instantiate and return a direct instance of one of the concrete subtypes of the abstract class or type.

The instance returned may or may not be newly allocated. If a new instance is allocated, make will call initialize on the instance before returning it.

Programmers may customize make for particular classes by defining methods specialized by singleton specializers. These methods may obtain the default make behavior, if desired, by calling next-method.

Note that the <class> method on make returns a newly allocated direct instance of its first argument.

make class #rest supplied-init-args #key ⇒ object [G.F. Method]

The method on <class> creates an instance of class, calls initialize on the instance, and then returns the instance. An error is signaled if class is abstract.

A complete description of this method and its role in the initialization protocol is given in Instance Creation and Initialization on page 64.

make (singleton (<array>))
#key dimensions fill ⇒ array [Sealed G.F. Method]

The method on singleton(<array>) accepts dimensions and fill keyword arguments, and instantiates a concrete subclass of <array>. These arguments are described with the <array> class on page 218.

make (singleton (<deque>))
#key size fill ⇒ deque [Sealed G.F. Method]

The method on singleton(<deque>) accepts size and fill keyword arguments, and instantiates a concrete subclass of <deque>. These arguments are described with the <deque> class on page 225.

make (singleton (<range>))
#key from by to above below size ⇒ deque [Sealed G.F. Method]

The method on singleton(<range>) accepts a number of keyword arguments, and instantiates a concrete subclass of <range>. These arguments are described with the <range> class on page 230.

make (singleton (<table>))
#key size ⇒ object-table [Sealed G.F. Method]

The method on singleton(<table>) accepts size keyword argument, and instantiates <object-table>. The size argument is described with the <table> class on page 235.

make (singleton (<vector>))
#key size fill ⇒ simple-object-vector [Sealed G.F. Method]
make (singleton (<simple-vector>))
#key size fill ⇒ simple-object-vector [Sealed G.F. Method]

Methods on singleton(<vector>) and singleton(<simple-vector>) accept size and fill keyword arguments, and return an instance of <simple-object-vector>. These arguments are described with the <vector> class on page 221 and with the <simple-vector> class on page 222.

make (singleton (<list>))
#key size fill ⇒ list [Sealed G.F. Method]

A method on singleton(<list>) accepts size and fill keyword arguments. These arguments are described with the <list> class on page 227.

Initialization

initialize [Open Generic Function]

Performs instance initialization that cannot be specified declaratively by a class definition.

Signature:

initialize instance #key #all-keys ⇒ #rest objects

Arguments:
instance

An instance of <object>.

Values:
objects

Instances of <object>. The return values are ignored by make.

Description:

Provides a way for users to handle initialization of instances which cannot be expressed simply by init specifications. This is typically needed when a computation requires inputs from multiple initialization arguments or slot values, or a single computation needs to be used to initialize multiple slots.

By convention, all initialize methods should call next-method very early, to make sure that any initializations from less specific classes are performed first.

The initialize generic function permits all keywords and requires none. It does this because the keyword argument checking is performed by the default method on make.

initialize object #key ⇒ object [G.F. Method]

This method does nothing. It is present so that it is always safe for initialize methods to call next method, and so that it is safe for the default make method to call initialize.

slot-initialized? [Open Generic Function]

Tests whether a slot has been initialized.

Signature:

slot-initialized? instance getter ⇒ boolean

Arguments:
instance

An instance of <object>.

getter

An instance of <generic-function>.

Values:
boolean

An instance of <boolean>.

Description:

Returns true if the slot in instance that would be accessed by the getter generic function is initialized. If the slot is not initialized, then false is returned.

slot-initialized? will signal an error if the getter does not access a slot in the instance.

To support slot-initialized? for a virtual slot, programmers must define a method for slot-initialized? that shares a protocol with the getter of the slot.

Specific Constructors

list [Function]

Creates and returns a freshly allocated list.

Signature:

list #rest arguments ⇒ list

Arguments:
arguments

The elements of the list. Instances of <object>.

Values:
list

A freshly allocated instance of <list>.

Description:

Returns a freshly allocated list containing the arguments, in order.

pair [Function]

Creates and returns a freshly allocated pair.

Signature:

pair object1 object2 ⇒ pair

Arguments:
object1

An instance of <object>.

object2

An instance of <object>.

Values:
pair

A freshly allocated instance of <pair>.

Description:

Creates a freshly allocated pair whose head value is object1 and tail value is object2.

pair (1, 2)
  ⇒ #(1 . 2)
pair (1, #(2, 3, 4, 5))
  ⇒ #(1, 2, 3, 4, 5)

Note that while the pair returned by pair is freshly allocated, it may be the beginning of a list, portions of which are not freshly allocated.

define variable *preexisting-list* = list(2, 3, 4)
define variable *new-list* = pair(1, *preexisting-list*)
*new-list*
  ⇒ #(1, 2, 3, 4)
tail(*new-list*) == *preexisting-list*
  ⇒ #t
third(*new-list*) := 'x'
*new-list*
  ⇒ #(1, 2, x, 4)
*preexisting-list*
  ⇒ #(2, x, 4)

range [Function]

Creates and returns a range.

Signature:

range #key from to above below by size ⇒ range

Arguments:
from

An instance of <real>. The default value is 0.

to

An instance of <real>.

above

An instance of <real>.

below

An instance of <real>.

by

An instance of <real>. The default value is 1.

size

An instance of <real>.

Values:
range

An instance of <range>.

Description:

Creates an instance of <range>. The arguments correspond to the initialization arguments of <range>, described on page 230.

Errata: In the published book, an incorrect default value of 0 (zero) is given for by.

singleton [Function]

Creates and returns a singleton.

Signature:

singleton object ⇒ singleton

Arguments:
object

An instance of <object>.

Values:
singleton

An instance of <singleton>. The singleton for object.

Description:

Returns a singleton for object. singleton(object) is equivalent to make(<singleton>, object: object). If a singleton for the specified object already exists, implementations are free to return it rather than allocate a new singleton.

limited [Function]

Returns a limited subtype of a class.

Signature:

limited class #key ⇒ type

Arguments:
class

An instance of <class>.

Values:
type

An instance of <type>.

Description:

Returns a limited subtype of class. The available keyword arguments depend on the class. Not all classes support limited; those that do are documented in the method descriptions below.

Note that an implementation is not required to implement limited as a generic function, and so the behavior embodied in the following method descriptions need not actually be implemented by separate methods. The behavior is described as a set of methods for convenience of presentation only.

limited (singleton (<integer>))
#key min max ⇒ type [Sealed G.F. Method]

Returns a limited integer type, which is a subtype of <integer> whose instances are integers greater than or equal to min (if min: is specified) and less than or equal to max (if max: is specified). If no keyword arguments are specified, the result type is equivalent to <integer>. Limited integer types are not instantiable.

limited (singleton (<collection>))
#key of size ⇒ type [Sealed G.F. Method]
limited (singleton (<explicit-key-collection>))
#key of size ⇒ type [Sealed G.F. Method]
limited (singleton (<mutable-collection>))
#key of size ⇒ type [Sealed G.F. Method]
limited (singleton (<stretchy-collection>))
#key of size ⇒ type [Sealed G.F. Method]
limited (singleton (<mutable-explicit-key-collection>))
#key of size ⇒ type [Sealed G.F. Method]
limited (singleton (<sequence>))
#key of size ⇒ type [Sealed G.F. Method]
limited (singleton (<mutable-sequence>))
#key of size ⇒ type [Sealed G.F. Method]

These methods return uninstantiable limited collection types.

limited (singleton (<table>))
#key of size ⇒ type [Sealed G.F. Method]
limited (singleton (<object-table>))
#key of size ⇒ type [Sealed G.F. Method]

These two methods return types that support a size: initialization keyword with the same behavior as <table>.

limited (singleton (<array>))
#key of size dimensions ⇒ type [Sealed G.F. Method]

This method returns a type that supports dimensions: and fill: initialization keywords with the same behavior as <array>. The default for fill is #f so if instance?(#f, of) is not true and the product of the dimensions is nonzero, the fill: initialization keyword is required because the default would cause a type error.

Instantiating type with a value of dimensions that has one element will return an instance of limited(<simple-vector>, of: of).

limited (singleton (<vector>))
#key of size ⇒ type [Sealed G.F. Method]

This method returns the same types as the method on singleton(<simple-vector>).

limited (singleton (<simple-vector>))
#key of size ⇒ type [Sealed G.F. Method]
limited (singleton (<stretchy-vector>))
#key of ⇒ type [Sealed G.F. Method]
limited (singleton (<deque>))
#key of ⇒ type [Sealed G.F. Method]

These three methods return types that support size: and fill: initialization keywords with the same behavior as the collection-class argument. The default for fill is #f so if instance?(#f, of) is not true and size is nonzero, the fill: initialization keyword is required because the default would cause a type error.

All general instances of <simple-vector> provide a constant time implementation of element and element-setter.

limited (singleton (<string>))
#key of size ⇒ type [Sealed G.F. Method]

The of argument must be a subtype of <character>. This method returns a type that supports size: and fill: initialization keywords with the same behavior as <string>. The default for fill: is ' ' so if instance?(' ', of) is not true and size is nonzero, the fill: initialization keyword is required because the default would cause a type error.

There are no specified subtypes of <character>, except for unions of singletons, which makes this method rather useless for portable programs. However, the method is provided because there might be useful subtypes of <character> in a particular implementation or in future versions of Dylan.

limited (singleton (<range>))
#key of ⇒ type [Sealed G.F. Method]

The of argument must be a subtype of <real>. This method returns a type that supports from:, to:, below:, above:, by:, and size: initialization keywords with the same behavior as <range>. Make of this type signals a <type-error> if any element of the range is not an instance of of.

type-union [Function]

Returns the union of two or more types.

Signature:

type-union type1 #rest more-types ⇒ type

Arguments:
type1

An instance of <type>.

more-types

Instances of <type>.

Values:
type

An instance of <type>.

Description:

Returns a type whose instances are the instances of type1 and all the more-types. The type returned is not instantiable. A complete description of union types is given in Union Types on page 72.

define constant $my-enumerated-type = 
                    type-union(singleton(#"one"),
                               singleton(#"two"),
                               singleton(#"three"),
                               singleton(#"four"),
                               singleton(#"five"))

vector [Function]

Creates and returns a freshly allocated vector.

Signature:

vector #rest arguments ⇒ vector

Arguments:
arguments

Instances of <object>.

Values:
vector

A freshly allocated instance of <simple-object-vector>. Its elements are the arguments, in order.

Description:

Returns a vector whose elements are the arguments, in order.