---

Collections

This section describes the built-in collections, Dylan's aggregate data structures.

Collections are used to hold groups of objects. Collections support iteration as well as random access through collection keys. An overview of collections is given in Chapter 8, Collections.

Figure 11-4 shows the built-in collection classes and some of their characteristics.

Figure 11-4 The Collection Classes

Errata: In the published book, the inheritance line descending from <vector> incorrectly originates from <empty-list> in Figure 11-4.

General Collections

<collection> [Open Abstract Class]

---

The class of collections, aggregate data structures.

Superclasses:

<object>

Init-keywords:

None.

Description:

The class of collections.

<collection> is the root class of the collection class hierarchy. It provides a set of basic operations on all collections.

The element type of <collection> is indefinite ⇐ <object>.

Operations:

The class <collection> provides the following operations:

Table 11-16 Functions on <collection>

Function	Description	Page
do	Iterates over one or more collections for side effect.	327
map	Iterates over one or more collections and collects the results in a freshly allocated collection.	328
map-as	Iterates over one or more collections and collects the results in a freshly allocated collection of a specified type.	328
map-into	Iterates over one or more collections and collects the results in an existing mutable collection.	329
any?	Returns the first true value obtained by iterating over one or more collections.	330
every?	Returns true if a predicate returns true when applied to all corresponding elements of a set of collections.	331

Table 11-17 Generic Functions on <collection>

Function	Description	Page
element	Returns the collection element associated with a particular key.	300
key-sequence	Returns a sequence containing the keys of its collection argument.	299
reduce	Combines the elements of a collection and a seed value into a single value by repeatedly applying a binary function.	331
reduce1	Combines the elements of a collection into a single value by repeatedly applying a binary function, using the first element of the collection as the seed value.	332
member?	Returns true if a collection contains a particular value.	334
find-key	Returns the key in a collection such that the corresponding collection element satisfies a predicate.	335
key-test	Returns the function used by its collection argument to compare keys.	298
forward-iteration-protocol	Returns a group of functions used to iterate over the elements of a collection.	337
backward-iteration-protocol	Returns a group of functions used to iterate over the elements of a collection in reverse order.	339

Table 11-18 Methods on <collection>

Function	Description	Page
=	Compares two objects for equality.	269
empty?	Returns true if its argument is empty.	294
size	Returns the size of its argument.	295
shallow-copy	Returns a copy of its argument.	292

Table 11-19 Methods on singleton(<collection>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263

Explicit Key Collections

<explicit-key-collection> [Open Abstract Class]

---

The class of all collections that are not sequences.

Superclasses:

<collection>

Init-keywords:

None.

Description:

The class of all collections that are not sequences.

This class is disjoint from <sequence> because key-test is sealed over the domain <sequence>.

The element type of <explicit-key-collection> is indefinite ⇐ <object>.

Operations:

The class <explicit-key-collection> provides the following operation:

Table 11-20 Methods on singleton(<explicit-key-collection>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263

Sequences

<sequence> [Open Abstract Class]

---

The class of collections whose keys are consecutive integers starting from zero.

Superclasses:

<collection>

Init-keywords:

None.

Description:

The class of collections whose keys are consecutive integers starting from zero.

Sequences must be stable under iteration, and the iteration order must match the order of keys. Thus, the key associated with a sequence's iteration state can be determined by keeping a counter in parallel with the iteration state.

The default methods for add, add-new, remove, choose, choose-by, intersection, union, remove-duplicates, copy-sequence, concatenate, reverse, and sort all return new sequences that are instances of the type-for-copy of their primary sequence argument. However, more specialized methods are permitted to choose a more appropriate result class; for example, copy-sequence of a range returns another range, even though the type-for-copy value of a range is the <list> class.

<sequence> is disjoint from <explicit-key-collection> because of the sealed domain over the function key-test for <sequence>.

The element type of <sequence> is indefinite ⇐ <object>.

Operations:

The class <sequence> provides the following operations:

Table 11-21 Functions on <sequence>

Function	Description	Page
concatenate	Returns the concatenation of one or more sequences in a sequence of a type determined by the type-for-copy of its first argument.	323
concatenate-as	Returns the concatenation of one or more sequences in a sequence of a specified type.	324
first	Returns the first element of a sequence.	303
second	Returns the second element of a sequence.	304
third	Returns the third element of a sequence.	304

Table 11-22 Generic Functions on <sequence>

Function	Description	Page
add	Adds an element to a sequence.	309
add!	Adds an element to a sequence.	310
add-new	Adds a new element to a sequence.	311
add-new!	Adds a new element to a sequence.	312
remove	Removes an element from a sequence.	312
remove!	Removes an element from a sequence.	313
choose	Returns those elements of a sequence that satisfy a predicate.	333
choose-by	Returns those elements of a sequence that correspond to those in another sequence that satisfy a predicate.	333
intersection	Returns the intersection of two sequences.	319
union	Returns the union of two sequences.	320
remove-duplicates	Returns a sequence without duplicates.	321
remove-duplicates!	Returns a sequence without duplicates.	322
copy-sequence	Returns a freshly allocated copy of some subsequence of a sequence.	323
replace-subsequence!	Replaces a portion of a sequence with the elements of another sequence.	325
reverse	Returns a sequence with elements in the reverse order of its argument sequence.	316
reverse!	Returns a sequence with elements in the reverse order of its argument sequence.	317
sort	Returns a sequence containing the elements of its argument sequence, sorted.	318
sort!	Returns a sequence containing the elements of its argument sequence, sorted.	318
last	Returns the last element of a sequence.	306
subsequence-position	Returns the position where a pattern appears in a sequence.	326

Table 11-23 Methods on <sequence>

Function	Description	Page
=	Compares two objects for equality.	269
key-test	Returns the function used by its collection argument to compare keys.	298

Table 11-24 Methods on singleton(<sequence>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263

Mutable Collections

<mutable-collection> [Open Abstract Class]

---

The class of collections that may be modified.

Superclasses:

<collection>

Init-keywords:

None.

Description:

The class of collections that may be modified.

Every mutable collection is required to allow modification by implementing element-setter.

The element type of <mutable-collection> is indefinite ⇐ <object>.

Operations:

The class <mutable-collection> provides the following operations:

Table 11-25 Functions on <mutable-collection>

Function	Description	Page
map-into	Iterates over one or more collections and collects the results in an existing mutable collection.	329

Table 11-26 Generic Functions on <mutable-collection>

Function	Description	Page
element-setter	Sets the collection element associated with a particular key.	301

Table 11-27 Methods on <mutable-collection>

Function	Description	Page
type-for-copy	Returns an appropriate type for creating mutable copies of its argument.	292

Table 11-28 Methods on singleton(<mutable-collection>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263

<mutable-explicit-key-collection> [Open Abstract Class]

---

The class of explicit-key-collections that can have elements replaced.

Superclasses:

<explicit-key-collection> <mutable-collection>

Init-keywords:

None.

Description:

The class of explicit-key-collections that can have elements replaced.

The element type of <mutable-explicit-key-collection> is indefinite ⇐ <object>.

Operations:

The class <mutable-explicit-key-collection> provides the following operations:

Table 11-29 Generic Functions on <mutable-explicit-key-collection>

Function	Description	Page
remove-key!	Modifies an explicit key collection so it no longer has a particular key.	335

Table 11-30 Methods on singleton(<mutable-explicit-key-collection>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263

<mutable-sequence> [Open Abstract Class]

---

The class of sequences that may be modified.

Superclasses:

<sequence> <mutable-collection>

Init-keywords:

None.

Description:

The class of sequences that may be modified.

The element type of <mutable-sequence> is indefinite ⇐ <object>.

Operations:

The class <mutable-sequence> provides the following operations:

Table 11-31 Functions on <mutable-sequence>

Function	Description	Page
first-setter	Sets the first element of a mutable sequence.	304
second-setter	Sets the second element of a mutable sequence.	305
third-setter	Sets the third element of a mutable sequence.	305

Table 11-32 Generic Functions on <mutable-sequence>

Function	Description	Page
last-setter	Sets the last element of a mutable sequence.	306

Table 11-33 Methods on singleton(<mutable-sequence>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263

Stretchy Collections

<stretchy-collection> [Open Abstract Class]

---

The class of collections that may grow or shrink to accommodate adding or removing elements.

Superclasses:

<collection>

Init-keywords:

None.

Description:

The class of collections that may grow or shrink to accommodate adding or removing elements.

Stretchy collections allow element-setter to be called with a key that is not present in the collection, expanding the collection as necessary to add a new element in that case. Each concrete subclass of <stretchy-collection> must provide or inherit a method for element-setter that behaves as follows when there is not already an element present for the indicated key:

• If the class is a subclass of <explicit-key-collection>, adds a new element to the collection with the indicated key.
• If the class is a subclass of <sequence>, first calls size-setter on the key + 1 and the collection to expand the sequence. The key must be a non-negative integer.

The element type of <stretchy-collection> is indefinite ⇐ <object>.

Operations:

The class <stretchy-collection> provides the following operations:

Table 11-34 Methods on singleton(<stretchy-collection>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263

Arrays

<array> [Open Abstract Instantiable Class]

---

The class of sequences whose elements are arranged according to a Cartesian coordinate system.

Superclasses:

<mutable-sequence>

Init-keywords:

The make method on singleton(<array>) accepts the following keyword arguments. Note that these are not inherited by subclasses of <array>.

dimensions:

An instance of <sequence> with elements that are instances of <integer>. This argument specifies the dimensions of the array. The size of the sequence specifies the rank (number of dimensions) of the array, and each integer in the sequence specifies the size of a dimension. This argument is required.

fill:

An instance of <object> specifying an initial value for each element of the array. The default value is #f.

Description:

The class of collections whose elements are arranged according to a Cartesian coordinate system.

An array element is referred to by a (possibly empty) series of indices. The length of the series must equal the rank of the array. Each index must be a non-negative integer less than the corresponding dimension. An array element may alternatively be referred to by an integer, which is interpreted as a row-major index.

Arrays typically use space efficient representations, and the average time required to access a randomly chosen element is typically sublinear to the number of elements.

When a multi-dimensional array is created, the concrete class that is actually instantiated cannot be any of the specified subclasses of <array>, which are all one-dimensional. Every implementation must have one or more concrete subclasses of <array> that are used for this purpose. These concrete subclasses have no specified names, and their names are not exported by the Dylan module.

When a single-dimensional array is created, the array created will be an instance of <vector>.

Each concrete subclass of <array> must either provide or inherit implementations of the functions element, element-setter, and dimensions.

The element type of <array> is indefinite ⇐ <object>.

Operations:

The class <array> provides the following operations:

Table 11-35 Generic Functions on <array>

Function	Description	Page
rank	Returns the number of dimensions of an array.	296
row-major-index	Returns the row-major-index position of an array element.	297
aref	Returns the array element indicated by a set of indices.	302
aref-setter	Sets the array element indicated by a set of indices.	302
dimensions	Returns the dimensions of an array.	297
dimension	Returns the size of a specified dimension of an array.	298

Table 11-36 Methods on <array>

Function	Description	Page
size	Returns the size of its argument.	295
rank	Returns the number of dimensions of an array.	296
row-major-index	Returns the row-major-index position of an array element.	297
aref	Returns the array element indicated by a set of indices.	302
aref-setter	Sets the array element indicated by a set of indices.	302
dimension	Returns the size of a specified dimension of an array.	298

Table 11-37 Methods on singleton(<array>)

Function	Description	Page
make	Returns a general instance of its first argument.	258
limited	Returns a limited subtype of a class.	263

Vectors

<vector> [Open Abstract Instantiable Class]

---

The class of arrays of rank one (i.e., exactly one dimension).

Superclasses:

<array>

Init-keywords:

The make method on singleton(<vector>) accepts the following keyword arguments. Note that these are not inherited by subclasses of <vector>.

size:

An instance of <integer> specifying the size of the vector. The default value is 0.

fill:

An instance of <object> specifying an initial value for each element of the vector. The default value is #f.

Description:

The class of one-dimensional arrays.

<vector> has no direct instances; calling make on <vector> returns an instance of <simple-object-vector>.

Each concrete subclass of <vector> must either provide or inherit an implementation of size that shadows the method provided by <array>.

The element type of <vector> is indefinite ⇐ <object>.

Operations:

The class <vector> provides the following operations:

Table 11-38 Constructors for <vector>

Function	Description	Page
vector	Creates and returns a freshly allocated vector.	267

Table 11-39 Methods on <vector>

Function	Description	Page
dimensions	Returns the dimensions of an array.	297
element	Returns the collection element associated with a particular key.	300

Table 11-40 Methods on singleton(<vector>)

Function	Description	Page
make	Returns a general instance of its first argument.	258
limited	Returns a limited subtype of a class.	263

<simple-vector> [Sealed Abstract Instantiable Class]

---

A predefined subclass of <vector> that provides an efficient implementation of fixed-length vectors.

Superclasses:

<vector>

Init-keywords:

The make method on singleton(<simple-vector>) accepts the following keyword arguments. Note that these are not inherited by subclasses of <simple-vector>.

size:

An instance of <integer> specifying the size of the vector. The default value is 0.

fill:

An instance of <object> specifying an initial value for each element of the vector. The default value is #f.

Description:

The class of simple and efficient vectors.

The class <simple-vector> provides a constant time implementation for the element and element-setter functions. This property is shared by all subtypes of <simple-vector>.

Calling make on a <simple-vector> returns an instance of <simple-object-vector>. The size of a simple vector cannot be changed after the simple vector has been created.

Vector literals (created with the #[…] syntax) are general instances of <simple-vector>.

The element type of <simple-vector> is indefinite ⇐ <object>.

The class <simple-object-vector> and the type limited(<simple-vector>, of: <object>) have exactly the same instances, but neither is a subtype of the other. The relationship between them is simply that the make method for the type returns an instance of the class.

Operations:

The class <simple-vector> provides the following operations:

Table 11-41 Methods on <simple-vector>

Function	Description	Page
element	Returns the collection element associated with a particular key.	300
element-setter	Sets the collection element associated with a particular key.	301

Table 11-42 Methods on singleton(<simple-vector>)

Function	Description	Page
make	Returns a general instance of its first argument.	258
limited	Returns a limited subtype of a class.	263

<simple-object-vector> [Sealed Instantiable Class]

---

The class of simple vectors that may have elements of any type.

Superclasses:

<simple-vector>

Init-keywords:

The class <simple-object-vector> supports the following init-keywords:

size:

An instance of <integer> specifying the size of the vector. The default value is 0.

fill:

An instance of <object> specifying the initial value for each element. The default value is #f.

Description:

The class <simple-object-vector> represents vectors that may have elements of any type. It provides a constant time implementation for the element and element-setter functions.

The element type of <simple-object-vector> is <object>.

Operations:

None.

<stretchy-vector> [Open Abstract Instantiable Primary Class]

---

The class of vectors that are stretchy.

Superclasses:

<vector> <stretchy-collection>

Init-keywords:

The class <stretchy-vector> supports the following init-keywords:

size:

An instance of <integer> specifying the initial size of the stretchy vector. The default value is 0.

fill:

An instance of <object> specifying the initial value for each element. The default value is #f.

Description:

The class of vectors that are stretchy.

Because <stretchy-vector> is abstract and instantiable but has no specified subclasses, every implementation must provide one or more concrete subclass to instantiate. These concrete subclasses have no specified names, and their names are not exported by the Dylan module.

The element type of <stretchy-vector> is indefinite ⇐ <object>.

Errata: In the published book, the above sentence said <simple-vector> instead of <stretchy-vector>.

Operations:

The class <stretchy-vector> provides the following operations:

Table 11-43 Methods on <stretchy-vector>

Function	Description	Page
add!	Adds an element to a sequence.	309
remove!	Removes an element from a sequence.	313

Table 11-44 Methods on singleton(<stretchy-vector>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263

Deques

<deque> [Open Abstract Instantiable Primary Class]

---

The class of double-ended queues.

Superclasses:

<mutable-sequence> <stretchy-collection>

Init-keywords:

The class <deque> supports the following init-keywords:

size:

An instance of <integer> specifying the initial size of the deque. The default value is 0.

fill:

An instance of <object> specifying the initial value for each element. The default value is #f.

Description:

A subclass of sequence that supports efficient forward and backward iteration, and efficient addition and removal of elements from the beginning or end of the sequence.

Because <deque> is abstract and instantiable but has no specified subclasses, every implementation must provide one or more concrete subclasses to instantiate. These concrete subclasses have no specified names, and their names are not exported by the Dylan module.

The element type of <deque> is indefinite ⇐ <object>.

Operations:

The class <deque> provides the following operations:

Table 11-45 Generic Functions on <deque>

Function	Description	Page
push	Adds an element to the front of a deque.	314
pop	Removes and returns the first element of a deque.	315
push-last	Adds an element to the end of a deque.	315
pop-last	Removes and returns an element from the end of a deque.	315

Table 11-46 Methods on <deque>

Function	Description	Page
add!	Adds an element to a sequence.	309
remove!	Removes an element from a sequence.	313

Table 11-47 Methods on singleton(<deque>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263
make	Returns a general instance of its first argument.	258

Lists

Lists are constructed by linking together instances of <pair>. The head of a list contains an element, and the tail of the list contains a pointer to the next pair in the list. The list ends when the tail of a pair contains something besides another pair.

A proper list has a final pair with a tail containing the empty list.

An improper list does not have a final pair with a tail containing the empty list, either because the tail of its final pair is not the empty list, or because the list is circular and thus does not have a final pair. Except when their behavior on improper lists is documented explicitly, collection or sequence functions are not guaranteed to return an answer when an improper list is used as a collection or a sequence. At the implementation's option, these functions may return the correct result, signal a <type-error>, or (in the case of a circular list) fail to return.

When treated as a collection, the elements of a list are the heads of successive pairs in the list.

<list> [Sealed Instantiable Abstract Class]

---

The class of linked lists.

Superclasses:

<mutable-sequence>

Init-keywords:

The make method on singleton(<list>) accepts the following keyword arguments. Note that these are not inherited by subclasses of <list>.

size:

An instance of <integer> specifying the size of the list. The default value is 0.

fill:

An instance of <object> specifying the initial value for each element. The default value is #f.

Description:

The class of linked lists.

The <list> class is partitioned into two concrete subclasses, <pair> and <empty-list>. Calling make on <list> will return a linked list made from pairs and terminated with the empty list.

The element type of <list> is <object>.

Operations:

The class <list> provides the following operations:

Table 11-48 Constructors for <list>

Function	Description	Page
list	Creates and returns a freshly allocated list.	261
pair	Creates and returns a freshly allocated pair.	262

Table 11-49 Functions on <list>

Function	Description	Page
head	Returns the head of a list.	307
tail	Returns the tail of a list.	307

Table 11-50 Methods on <list>

Function	Description	Page
size	Returns the size of its argument.	295
=	Compares two objects for equality.	269
add!	Adds an element to a sequence.	309
remove!	Removes an element from a sequence.	313

Table 11-51 Methods on singleton(<list>)

Function	Description	Page
make	Returns a general instance of its first argument.	258

<pair> [Sealed Instantiable Class]

---

The class of lists that can have new values assigned to their heads and tails.

Superclasses:

<list>

Init-keywords:

None.

Description:

The class of lists that can have new values assigned to their heads and tails.

The element type of <pair> is <object>.

Operations:

The following operations are provided on <pair>:

Table 11-52 Functions on <pair>

Function	Description	Page
head-setter	Sets the head of a pair.	308
tail-setter	Sets the tail of a pair.	308

Table 11-53 Constructors for <pair>

Function	Description	Page
pair	Creates and returns a freshly allocated pair.	262

<empty-list> [Sealed Instantiable Class]

---

The class with only one instance, the empty list.

Superclasses:

<list>

Init-keywords:

None.

Description:

The class <empty-list> has only one instance, the empty list. The empty list is a direct instance of <empty-list> and an indirect instance of <list>. Note that <empty-list> is not == to singleton (#()).

The element type of <empty-list> is <object>.

Operations:

None.

Ranges

<range> [Open Abstract Instantiable Primary Class]

---

The class of arithmetic sequences.

Superclasses:

<sequence>

Init-keywords:

The class <range> supports the following init-keywords:

from:

An instance of <real> specifying the first value in the range. The default value is 0.

by:

An instance of <real> specifying the step between consecutive elements of the range. The default value is 1.

to:

An instance of <real> specifying an inclusive bound for the range. If by: is positive, the range will include numbers up to and including this value. If by: is negative, the range will include numbers down to and including this value.
to: cannot be specified with above: or below:.

above:

An instance of <real> specifying an exclusive lower bound for the range. The range will only include numbers above this value, regardless of the sign of by:.
above: cannot be specified with to: or below:.

below:

An instance of <real> specifying an exclusive upper bound for the range. The range will only include numbers below this value, regardless of the sign of by:.
below: cannot be specified with to: or above:.

size:

An instance of <integer> specifying the size of the range.

Description:

The class <range> is used for creating sequences of numbers. Ranges may be infinite in size, and may run from higher numbers to lower numbers.

If size: is specified and none of to:, above: or below: is specified, then the size: argument determines the size of the range.

If size: is specified and one of to:, above: or below: is specified, than it is an error if the number of elements implied by the to:, above: or below: argument (and the by: argument, if present) does not agree with the number of elements specified by the size: argument.

Because <range> in abstract and instantiable but has no specified subclasses, every implementation must provide one or more concrete subclass to instantiate. These concrete subclasses have no specified names, and their names are not exported by the Dylan module.

The element type of <range> is indefinite ⇐ <real>.

Operations:

The class <range> provides the following operations:

Table 11-54 Methods on <range>

Function	Description	Page
member?	Returns true if a collection contains a particular value.	334
size	Returns the size of its argument.	295
copy-sequence	Returns a freshly allocated copy of some subsequence of a sequence.	323
=	Compares two objects for equality.	269
reverse	Returns a sequence with elements in the reverse order of its argument sequence.	316
reverse!	Returns a sequence with elements in the reverse order of its argument sequence.	317
intersection	Returns the intersection of two sequences.	319
type-for-copy	Returns an appropriate type for creating mutable copies of its argument.	292

Table 11-55 Methods on singleton(<range>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263
make	Returns a general instance of its first argument.	258

Strings

<string> [Open Abstract Instantiable Class]

---

The class of sequences with elements that are characters.

Superclasses:

<mutable-sequence>

Init-keywords:

The class <string> supports the following init-keywords:

size:

An instance of <integer> specifying the size of the string. The default value is 0.

fill:

An instance of <character> specifying the initial value for each element. The default value is ' ' (space).

Description:

The class <string> is used for holding sequences of characters.

<string> has no direct instances; calling make on <string> will return an instance of a concrete subclass of <string>.

The element type of <string> is indefinite ⇐ <character>.

Operations:

The class <string> provides the following operations:

Table 11-56 Methods on <string>

Function	Description	Page
<	Returns true if its first operand is less than its second operand.	271
as-lowercase	Coerces an object to lowercase.	291
as-lowercase!	Coerces an object to lowercase in place.	291
as-uppercase	Coerces an object to uppercase.	290
as-uppercase!	Coerces an object to uppercase in place.	290

Table 11-57 Methods on singleton(<string>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263

<byte-string> [Sealed Instantiable Class]

---

The class of vectors with elements that are eight-bit characters.

Superclasses:

<string> <vector>

Init-keywords:

The class <byte-string> supports the following init-keywords:

size:

An instance of <integer> specifying the size of the byte string. The default value is 0.

fill:

An instance of <character> specifying the initial value for each element. The default value is ' ' (space).

Description:

The class <byte-string> represents strings with elements that are eight bit characters. It provides constant time element and element-setter methods.

The element type of <byte-string> is indefinite ⇐ K2 (where K₂ is a subtype of <character>).

Operations:

The class <byte-string> provides the following operations:

Table 11-58 Methods on <byte-string>

Function	Description	Page
element	Returns the collection element associated with a particular key.	300
element-setter	Sets the collection element associated with a particular key.	301

<unicode-string> [Sealed Instantiable Class]

---

The class of vectors with elements that are sixteen-bit Unicode characters.

Superclasses:

<string> <vector>

Init-keywords:

The class <unicode-string> supports the following init-keywords:

size:

An instance of <integer> specifying the size of the unicode string. The default value is 0.

fill:

An instance of <character> specifying the initial value for each element. The default value is ' ' (space).

Description:

The class <unicode-string> represents strings with elements that are sixteen bit Unicode characters. It provides constant time element and element-setter methods.

The element type of <unicode-string> is indefinite ⇐ K1 (where K₁ is a subtype of <character>).

Operations:

The class <unicode-string> provides the following operations:

Table 11-59 Methods on <unicode-string>

Function	Description	Page
element	Returns the collection element associated with a particular key.	300
element-setter	Sets the collection element associated with a particular key.	301

Tables

Also called a hash table, a table is an unordered mapping between arbitrary keys and elements. Tables are the only predefined collections that are unstable under iteration.

Tables are stretchy in that they allow the addition and removal of keys. <table> and its subclasses are the only predefined classes that are stretchy but are not stretchy sequences.

For a complete description of tables, see Tables on page 122.

<table> [Open Abstract Instantiable Primary Class]

---

The class of tables (also known as hash tables).

Superclasses:

<mutable-explicit-key-collection> <stretchy-collection>

Init-keywords:

The class <table> supports the following init-keyword:

size:

An instance of <integer>. If specified, this value provides a hint to the implementation as to the expected number of elements to be stored in the table, which might be used to control how much space to initially allocate for the table. The default value is unspecified.

Description:

The class <table> is the only predefined instantiable subclass of <explicit-key-collection>.

Every concrete subclass of <table> must provide or inherit a method for table-protocol. For details, see Tables on page 122.

<table> has no direct instances; calling make on <table> will return an instance of <object-table>.

The element type of <table> is indefinite ⇐ <object>.

Operations:

The class <table> provides the following operations:

Table 11-60 Generic Functions on <table>

Function	Description	Page
table-protocol	Returns functions used to implement the iteration protocol for tables.	340

Table 11-61 Methods on <table>

Function	Description	Page
forward-iteration-protocol	Returns a group of functions used to iterate over the elements of a collection.	337
table-protocol	Returns functions used to implement the iteration protocol for tables.	340
remove-key!	Modifies an explicit key collection so it no longer has a particular key.	335
element	Returns the collection element associated with a particular key.	300
element-setter	Sets the collection element associated with a particular key.	301
size	Returns the size of its argument.	295
key-test	Returns the function used by its collection argument to compare keys.	298

Table 11-62 Methods on singleton(<table>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263
make	Returns a general instance of its first argument.	258

<object-table> [Open Abstract Instantiable Class]

---

The class of tables that compare keys using ==.

Superclasses:

<table>

Init-keywords:

None.

Description:

Calling make on <table> will return a general instance of <object-table>. Because <object-table> is abstract and instantiable but has no specified subclasses, every implementation must provide one or more concrete subclasses to instantiate. These concrete subclasses have no specified names, and their names are not exported by the Dylan module.

The element type of <object-table> is indefinite ⇐ <object>.

Operations:

The class <object-table> provides the following operations:

Table 11-63 Methods on <object-table>

Function	Description	Page
table-protocol	Returns functions used to implement the iteration protocol for tables.	340

Table 11-64 Methods on singleton(<object-table>)

Function	Description	Page
limited	Returns a limited subtype of a class.	263

---

The Dylan Reference Manual - 7 Apr 1998

← Previous Next Page → Up Start Contents Index

Copyright Apple Computer, Inc. 1996. Apple® and the Apple logo are registered trademarks of Apple Computer, Inc. Used with permission. All Rights Reserved.

Originally generated with Harlequin WebMaker®, subsequently revised.