[Next] [Previous] [Up] [Top] [Contents] [Index]

12 The Built-In Functions

Constructing and Initializing Instances

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 63.

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

A 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 208.

make (singleton <vector>)
 #key size fill Þ simple-object-vector [G.F. Method]
make (singleton <simple-vector>)
 #key size fill Þ simple-object-vector [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 210 and with the <simple-vector> class on page 211.

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

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

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 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? which 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 0.

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 219.

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; the methods for limited are documented individually.

limited (singleton <integer>) #key min max Þ type [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 [G.F. Method]
limited (singleton <explicit-key-collection>)
 #key of size Þ type [G.F. Method]
limited (singleton <mutable-collection>)
 #key of size Þ type [G.F. Method]
limited (singleton <stretchy-collection>)
 #key of size Þ type [G.F. Method]
limited (singleton <mutable-explicit-key-collection>)
 #key of size Þ type [G.F. Method]
limited (singleton <sequence>)
 #key of size Þ type [G.F. Method]
limited (singleton <mutable-sequence>)
 #key of size Þ type [G.F. Method]

These methods return uninstantiable limited collection types.

limited (singleton <table>)
 #key of size Þ type [G.F. Method]
limited (singleton <object-table>)
 #key of size Þ type [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 [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 [G.F. Method]

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

limited (singleton <simple-vector>)
 #key of size Þ type [G.F. Method]
limited (singleton <stretchy-vector>)
 #key of Þ type [G.F. Method]
limited (singleton <deque>)
 #key of Þ type [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 [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 [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 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 71.

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.

Dylan Reference Manual - 17 OCT 1995
[Next] [Previous] [Up] [Top] [Contents] [Index]

Generated with Harlequin WebMaker