Chapter 11

The Built-In Classes

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

class simple-object-vector class unicode-string class byte-string class simple-vector class stretchy-vector class pair class empty-list class vector class object-table class string class deque class list class array class table class range class mutable-sequence class mutable-explicit-key-collection class stretchy-collection class sequence class mutable-collection class explicit-key-collection class collection class object Collection Class Hierarchy
S – Sealed P – Primary C – Concrete I – Instantiable
O – Open F – Free A – Abstract U – Uninstantiable

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 K2 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 K1 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