3
@node Types and Classes, Data and Control Flow, Evaluation and Compilation, Top
4
@chapter Types and Classes
7
* Introduction (Types and Classes)::
10
* Types and Classes Dictionary::
13
@node Introduction (Types and Classes), Types, Types and Classes, Types and Classes
16
@c including concept-type-intro
18
A @i{type} is a (possibly infinite) set of @i{objects}.
19
An @i{object} can belong to more than one @i{type}.
20
@i{Types} are never explicitly represented as @i{objects} by @r{Common Lisp}.
21
Instead, they are referred to indirectly by the use of @i{type specifiers},
22
which are @i{objects} that denote @i{types}.
24
New @i{types} can be defined using @b{deftype}, @b{defstruct},
25
@b{defclass}, and @b{define-condition}.
27
The @i{function} @b{typep}, a set membership test, is used to determine
28
whether a given @i{object} is of a given @i{type}. The function
29
@b{subtypep}, a subset test, is used to determine whether a
30
given @i{type} is a @i{subtype} of another given @i{type}. The
31
function @b{type-of} returns a particular @i{type} to
32
which a given @i{object} belongs, even though that @i{object}
33
must belong to one or more other @i{types} as well.
34
(For example, every @i{object} is of @i{type} @b{t},
35
but @b{type-of} always returns a @i{type specifier}
36
for a @i{type} more specific than @b{t}.)
38
@i{Objects}, not @i{variables}, have @i{types}.
39
Normally, any @i{variable} can have any @i{object} as its @i{value}.
40
It is possible to declare that a @i{variable} takes on only
41
values of a given @i{type} by making an explicit @i{type declaration}.
42
@i{Types} are arranged in a directed acyclic graph, except
43
for the presence of equivalences.
45
@i{Declarations} can be made about @i{types} using @b{declare},
46
@b{proclaim}, @b{declaim}, or @b{the}.
47
For more information about @i{declarations},
48
see @ref{Declarations}.
50
Among the fundamental @i{objects} of the object system are @i{classes}.
51
A @i{class} determines the structure and behavior of a set of
52
other @i{objects}, which are called its @i{instances}.
53
Every @i{object} is a @i{direct instance} of a @i{class}.
54
The @i{class} of an @i{object} determines the set of
55
operations that can be performed on the @i{object}.
56
For more information, see @ref{Classes}.
58
It is possible to write @i{functions} that have behavior @i{specialized}
59
to the class of the @i{objects} which are their @i{arguments}.
60
For more information, see @ref{Generic Functions and Methods}.
62
The @i{class} of the @i{class} of an @i{object}
63
is called its @i{metaclass}
66
For more information about @i{metaclasses},
67
see @ref{Meta-Objects}.
69
@c end of including concept-type-intro
71
@node Types, Classes, Introduction (Types and Classes), Types and Classes
74
@c including concept-types
77
* Data Type Definition::
78
* Type Relationships::
82
@node Data Type Definition, Type Relationships, Types, Types
83
@subsection Data Type Definition
85
Information about @i{type} usage is located in
86
the sections specified in @i{Figure~4--1}.
87
@i{Figure~4--7} lists some @i{classes}
88
that are particularly relevant to the object system.
89
@i{Figure~9--1} lists the defined @i{condition} @i{types}.
94
@w{ @b{Section} Data Type }
95
@w{ _________________________________________________________________________}
96
@w{ @ref{Classes} Object System types }
97
@w{ @ref{Slots} Object System types }
98
@w{ @ref{Objects} Object System types }
99
@w{ @ref{Generic Functions and Methods} Object System types }
100
@w{ @ref{Condition System Concepts} Condition System types }
101
@w{ @ref{Types and Classes} Miscellaneous types }
102
@w{ @ref{Syntax} All types---read and print syntax }
103
@w{ @ref{The Lisp Printer} All types---print syntax }
104
@w{ @ref{Compilation} All types---compilation issues }
107
@w{ Figure 4--1: Cross-References to Data Type Information }
112
@node Type Relationships, Type Specifiers, Data Type Definition, Types
113
@subsection Type Relationships
118
The @i{types} @b{cons}, @b{symbol}, @b{array}, @b{number},
119
@b{character}, @b{hash-table},
123
@b{readtable}, @b{package}, @b{pathname}, @b{stream},
124
@b{random-state}, @b{condition}, @b{restart},
125
and any single other @i{type} created by @b{defstruct},
127
@b{define-condition},
129
or @b{defclass} are @i{pairwise} @i{disjoint},
130
except for type relations explicitly established by specifying
131
@i{superclasses} in @b{defclass}
133
or @b{define-condition}
135
or the @t{:include} option of @b{destruct}.
138
Any two @i{types} created by @b{defstruct} are
140
one is a @i{supertype} of the other by virtue of
141
the @b{defstruct} @t{:include} option.
143
[Editorial Note by KMP: The comments in the source say gray suggested some change
144
from ``common superclass'' to ``common subclass'' in the following, but the
145
result looks suspicious to me.]
148
Any two @i{distinct} @i{classes} created by @b{defclass}
149
or @b{define-condition}
150
are @i{disjoint} unless they have a common @i{subclass} or
151
one @i{class} is a @i{subclass} of the other.
154
An implementation may be extended to add other @i{subtype}
155
relationships between the specified @i{types}, as long as they do
156
not violate the type relationships and disjointness requirements
157
specified here. An implementation may define additional @i{types}
158
that are @i{subtypes} or @i{supertypes} of any
159
specified @i{types}, as long as each additional @i{type} is
160
a @i{subtype} of @i{type} @b{t} and a @i{supertype} of @i{type} @b{nil} and the disjointness requirements
163
At the discretion of the implementation, either @b{standard-object}
164
or @b{structure-object} might appear in any class precedence list
165
for a @i{system class} that does not already specify either
166
@b{standard-object} or @b{structure-object}. If it does,
167
it must precede the @i{class} @b{t} and follow all other @i{standardized} @i{classes}.
171
@node Type Specifiers, , Type Relationships, Types
172
@subsection Type Specifiers
174
@i{Type specifiers} can be @i{symbols}, @i{classes}, or @i{lists}.
175
@i{Figure~4--2} lists @i{symbols} that are
176
@i{standardized} @i{atomic type specifiers}, and
177
@i{Figure~4--3} lists
178
@i{standardized} @i{compound type specifier} @i{names}.
179
For syntax information, see the dictionary entry for the corresponding @i{type specifier}.
180
It is possible to define new @i{type specifiers} using
182
@b{define-condition},
190
@w{ arithmetic-error function simple-condition }
191
@w{ array generic-function simple-error }
192
@w{ atom hash-table simple-string }
193
@w{ base-char integer simple-type-error }
194
@w{ base-string keyword simple-vector }
195
@w{ bignum list simple-warning }
196
@w{ bit logical-pathname single-float }
197
@w{ bit-vector long-float standard-char }
198
@w{ broadcast-stream method standard-class }
199
@w{ built-in-class method-combination standard-generic-function }
200
@w{ cell-error nil standard-method }
201
@w{ character null standard-object }
202
@w{ class number storage-condition }
203
@w{ compiled-function package stream }
204
@w{ complex package-error stream-error }
205
@w{ concatenated-stream parse-error string }
206
@w{ condition pathname string-stream }
207
@w{ cons print-not-readable structure-class }
208
@w{ control-error program-error structure-object }
209
@w{ division-by-zero random-state style-warning }
210
@w{ double-float ratio symbol }
211
@w{ echo-stream rational synonym-stream }
212
@w{ end-of-file reader-error t }
213
@w{ error readtable two-way-stream }
214
@w{ extended-char real type-error }
215
@w{ file-error restart unbound-slot }
216
@w{ file-stream sequence unbound-variable }
217
@w{ fixnum serious-condition undefined-function }
218
@w{ float short-float unsigned-byte }
219
@w{ floating-point-inexact signed-byte vector }
220
@w{ floating-point-invalid-operation simple-array warning }
221
@w{ floating-point-overflow simple-base-string }
222
@w{ floating-point-underflow simple-bit-vector }
225
@w{ Figure 4--2: Standardized Atomic Type Specifiers }
231
If a @i{type specifier} is a @i{list}, the @i{car} of the @i{list}
232
is a @i{symbol}, and the rest of the @i{list} is subsidiary
233
@i{type} information. Such a @i{type specifier} is called
234
a @i{compound type specifier}
235
@IGindex{compound type specifier}
237
Except as explicitly stated otherwise,
238
the subsidiary items can be unspecified.
239
The unspecified subsidiary items are indicated
240
by writing @t{*}. For example, to completely specify
241
a @i{vector}, the @i{type} of the elements
242
and the length of the @i{vector} must be present.
245
(vector double-float 100)
248
The following leaves the length unspecified:
251
(vector double-float *)
254
The following leaves the element type unspecified:
260
Suppose that two @i{type specifiers} are the same except that the first
261
has a @t{*} where the second has a more explicit specification.
262
Then the second denotes a @i{subtype}
263
of the @i{type} denoted by the first.
265
If a @i{list} has one or more unspecified items at the end,
266
those items can be dropped.
267
If dropping all occurrences of @t{*} results in a @i{singleton} @i{list},
268
then the parentheses can be dropped as well (the list can be replaced
269
by the @i{symbol} in its @i{car}).
271
@t{(vector double-float *)}
272
can be abbreviated to @t{(vector double-float)},
273
and @t{(vector * *)} can be abbreviated to @t{(vector)}
280
@w{ and long-float simple-base-string }
281
@w{ array member simple-bit-vector }
282
@w{ base-string mod simple-string }
283
@w{ bit-vector not simple-vector }
284
@w{ complex or single-float }
285
@w{ cons rational string }
286
@w{ double-float real unsigned-byte }
287
@w{ eql satisfies values }
288
@w{ float short-float vector }
289
@w{ function signed-byte }
290
@w{ integer simple-array }
293
@w{ Figure 4--3: Standardized Compound Type Specifier Names}
298
Figure 4--4 show the @i{defined names} that can be used as
299
@i{compound type specifier} @i{names}
300
but that cannot be used as @i{atomic type specifiers}.
305
@w{ and mod satisfies }
310
@w{ Figure 4--4: Standardized Compound-Only Type Specifier Names}
315
New @i{type specifiers} can come into existence in two ways.
319
Defining a structure by using @b{defstruct} without using
320
the @t{:type} specifier or defining a @i{class} by using
322
or @b{define-condition}
323
automatically causes the name of the structure
324
or class to be a new @i{type specifier} @i{symbol}.
326
@b{deftype} can be used to define @i{derived type specifiers}
327
@IGindex{derived type specifier}
329
which act as `abbreviations' for other @i{type specifiers}.
332
A @i{class} @i{object} can be used as a @i{type specifier}.
333
When used this way, it denotes the set of all members of that @i{class}.
335
Figure 4--5 shows some @i{defined names} relating to
336
@i{types} and @i{declarations}.
341
@w{ coerce defstruct subtypep }
342
@w{ declaim deftype the }
343
@w{ declare ftype type }
344
@w{ defclass locally type-of }
345
@w{ define-condition proclaim typep }
348
@w{ Figure 4--5: Defined names relating to types and declarations.}
353
Figure 4--6 shows all @i{defined names} that are @i{type specifier} @i{names},
354
whether for @i{atomic type specifiers} or @i{compound type specifiers};
355
this list is the union of the lists in @i{Figure~4--2}
361
@w{ and function simple-array }
362
@w{ arithmetic-error generic-function simple-base-string }
363
@w{ array hash-table simple-bit-vector }
364
@w{ atom integer simple-condition }
365
@w{ base-char keyword simple-error }
366
@w{ base-string list simple-string }
367
@w{ bignum logical-pathname simple-type-error }
368
@w{ bit long-float simple-vector }
369
@w{ bit-vector member simple-warning }
370
@w{ broadcast-stream method single-float }
371
@w{ built-in-class method-combination standard-char }
372
@w{ cell-error mod standard-class }
373
@w{ character nil standard-generic-function }
374
@w{ class not standard-method }
375
@w{ compiled-function null standard-object }
376
@w{ complex number storage-condition }
377
@w{ concatenated-stream or stream }
378
@w{ condition package stream-error }
379
@w{ cons package-error string }
380
@w{ control-error parse-error string-stream }
381
@w{ division-by-zero pathname structure-class }
382
@w{ double-float print-not-readable structure-object }
383
@w{ echo-stream program-error style-warning }
384
@w{ end-of-file random-state symbol }
385
@w{ eql ratio synonym-stream }
386
@w{ error rational t }
387
@w{ extended-char reader-error two-way-stream }
388
@w{ file-error readtable type-error }
389
@w{ file-stream real unbound-slot }
390
@w{ fixnum restart unbound-variable }
391
@w{ float satisfies undefined-function }
392
@w{ floating-point-inexact sequence unsigned-byte }
393
@w{ floating-point-invalid-operation serious-condition values }
394
@w{ floating-point-overflow short-float vector }
395
@w{ floating-point-underflow signed-byte warning }
398
@w{ Figure 4--6: Standardized Type Specifier Names }
403
@c end of including concept-types
405
@node Classes, Types and Classes Dictionary, Types, Types and Classes
408
@c including concept-classes
410
While the object system is general enough to describe all @i{standardized} @i{classes}
411
(including, for example, @b{number}, @b{hash-table}, and
412
@b{symbol}), Figure 4--7 contains a list of @i{classes} that are
413
especially relevant to understanding the object system.
418
@w{ built-in-class method-combination standard-object }
419
@w{ class standard-class structure-class }
420
@w{ generic-function standard-generic-function structure-object }
421
@w{ method standard-method }
424
@w{ Figure 4--7: Object System Classes }
430
* Introduction to Classes::
432
* Creating Instances of Classes::
434
* Determining the Class Precedence List::
435
* Redefining Classes::
436
* Integrating Types and Classes::
439
@node Introduction to Classes, Defining Classes, Classes, Classes
440
@subsection Introduction to Classes
444
is an @i{object} that determines the structure and behavior
445
of a set of other @i{objects}, which are called its @i{instances}
449
A @i{class} can inherit structure and behavior from other @i{classes}.
450
A @i{class} whose definition refers to other @i{classes} for the purpose
451
of inheriting from them is said to be a @i{subclass} of each of
452
those @i{classes}. The @i{classes} that are designated for purposes of
453
inheritance are said to be @i{superclasses} of the inheriting @i{class}.
455
A @i{class} can have a @i{name}. The @i{function} @b{class-name}
456
takes a @i{class} @i{object} and returns its @i{name}.
457
The @i{name} of an anonymous @i{class} is @b{nil}. A @i{symbol}
458
can @i{name} a @i{class}. The @i{function} @b{find-class} takes a
459
@i{symbol} and returns the @i{class} that the @i{symbol} names.
460
A @i{class} has a @i{proper name} if the @i{name} is a @i{symbol}
461
and if the @i{name} of the @i{class} names that @i{class}.
462
That is, a @i{class}~C has the @i{proper name}~S if S=
463
@t{(class-name C)} and C= @t{(find-class S)}.
464
Notice that it is possible for
465
@t{(find-class S_1)} = @t{(find-class S_2)}
467
If C= @t{(find-class S)}, we say that C is the @i{class} @i{named} S.
470
a @i{direct superclass}
471
@IGindex{direct superclass}
473
if C_2 explicitly designates C_1
474
as a @i{superclass} in its definition.
475
In this case C_2 is a @i{direct subclass}
476
@IGindex{direct subclass}
478
A @i{class} C_n is a @i{superclass}
481
a @i{class} C_1 if there exists a series of
482
@i{classes} C_2,...,C_@{n-1@} such that
483
C_@{i+1@} is a @i{direct superclass} of C_i for 1 <= i<n.
484
In this case, C_1 is a @i{subclass}
487
A @i{class} is considered neither a @i{superclass} nor a @i{subclass} of itself.
488
That is, if C_1 is a @i{superclass} of C_2,
490
The set of @i{classes} consisting of some given @i{class} C
491
along with all of its @i{superclasses} is called ``C and its superclasses.''
493
Each @i{class} has a @i{class precedence list}
494
@IGindex{class precedence list}
496
which is a total ordering on the set of the given @i{class} and its @i{superclasses}.
497
The total ordering is expressed as a list ordered from most specific to least specific.
498
The @i{class precedence list} is used in several ways. In general, more
499
specific @i{classes} can @i{shadow}
501
_1 features that would
502
otherwise be inherited from less specific @i{classes}.
503
The @i{method} selection and combination process uses
504
the @i{class precedence list} to order @i{methods}
505
from most specific to least specific.
507
When a @i{class} is defined, the order in which its direct @i{superclasses}
508
are mentioned in the defining form is important. Each @i{class} has a
509
@i{local precedence order}
510
@IGindex{local precedence order}
511
, which is a @i{list} consisting of the
512
@i{class} followed by its @i{direct superclasses} in the order mentioned
513
in the defining @i{form}.
515
A @i{class precedence list} is always consistent with the
516
@i{local precedence order} of each @i{class} in the list.
517
The @i{classes} in each @i{local precedence order} appear
518
within the @i{class precedence list} in the same order.
519
If the @i{local precedence orders} are inconsistent with each other,
520
no @i{class precedence list} can be constructed, and an error is signaled.
521
The @i{class precedence list} and its computation is discussed
522
in @ref{Determining the Class Precedence List}.
524
@i{classes} are organized into a directed acyclic graph.
525
There are two distinguished @i{classes}, named @b{t} and @b{standard-object}.
526
The @i{class} named @b{t} has no @i{superclasses}.
527
It is a @i{superclass} of every @i{class} except itself.
528
The @i{class} named @b{standard-object} is an @i{instance} of
529
the @i{class} @b{standard-class} and is a @i{superclass} of
530
every @i{class} that is an @i{instance} of the @i{class} @b{standard-class} except itself.
532
[Reviewer Note by Barmar: This or something like it needs to be said in the introduction.]
533
There is a mapping from the object system @i{class} space into
534
the @i{type} space. Many of the standard @i{types} specified
535
in this document have a corresponding @i{class} that has the same
536
@i{name} as the @i{type}. Some @i{types} do not have a
537
corresponding @i{class}. The integration of the @i{type} and @i{class}
538
systems is discussed in @ref{Integrating Types and Classes}.
540
@i{Classes} are represented by @i{objects} that are themselves
541
@i{instances} of @i{classes}.
542
The @i{class} of the @i{class} of an @i{object} is termed
545
of that @i{object}. When no misinterpretation is
546
possible, the term @i{metaclass} is used to refer to a @i{class}
547
that has @i{instances} that are themselves @i{classes}. The @i{metaclass}
548
determines the form of inheritance used by the @i{classes} that are its
549
@i{instances} and the representation of the @i{instances} of those @i{classes}.
550
The object system provides a default @i{metaclass}, @b{standard-class}, that is
551
appropriate for most programs.
553
Except where otherwise specified, all @i{classes} mentioned in this
554
standard are @i{instances} of the @i{class} @b{standard-class},
555
all @i{generic functions} are @i{instances}
556
of the @i{class} @b{standard-generic-function},
557
and all @i{methods} are @i{instances} of the @i{class} @b{standard-method}.
560
* Standard Metaclasses::
563
@node Standard Metaclasses, , Introduction to Classes, Introduction to Classes
564
@subsubsection Standard Metaclasses
566
The object system provides a number of predefined @i{metaclasses}.
567
These include the @i{classes} @b{standard-class},
568
@b{built-in-class}, and @b{structure-class}:
573
The @i{class} @b{standard-class} is the default @i{class} of
574
@i{classes} defined by @b{defclass}.
577
The @i{class} @b{built-in-class} is the @i{class} whose
578
@i{instances} are @i{classes} that have special implementations with
579
restricted capabilities. Any @i{class} that corresponds to a standard
580
@i{type} might be an @i{instance} of @b{built-in-class}.
581
The predefined @i{type} specifiers that are required to have
582
corresponding @i{classes} are listed in @i{Figure~4--8}.
583
It is @i{implementation-dependent} whether each of these @i{classes}
584
is implemented as a @i{built-in class}.
587
All @i{classes} defined by means of @b{defstruct} are
588
@i{instances} of the @i{class} @b{structure-class}.
591
@node Defining Classes, Creating Instances of Classes, Introduction to Classes, Classes
592
@subsection Defining Classes
594
The macro @b{defclass} is used to define a new named @i{class}.
596
The definition of a @i{class} includes:
601
The @i{name} of the new @i{class}.
602
For newly-defined @i{classes} this @i{name} is a @i{proper name}.
605
The list of the direct @i{superclasses} of the new @i{class}.
608
A set of @i{slot specifiers}
609
@IGindex{slot specifier}
611
Each @i{slot specifier} includes the @i{name} of the @i{slot}
612
and zero or more @i{slot} options. A @i{slot} option pertains
613
only to a single @i{slot}. If a @i{class} definition contains
614
two @i{slot specifiers} with the same @i{name}, an error is signaled.
617
A set of @i{class} options.
618
Each @i{class} option pertains to the @i{class} as a whole.
622
The @i{slot} options and @i{class} options of
623
the @b{defclass} form provide mechanisms for the following:
628
Supplying a default initial value @i{form}
629
for a given @i{slot}.
632
Requesting that @i{methods} for @i{generic functions}
633
be automatically generated for reading or writing @i{slots}.
636
Controlling whether a given @i{slot} is shared by
638
of the @i{class} or whether each
639
@i{instance} of the @i{class} has its own @i{slot}.
642
Supplying a set of initialization arguments and initialization
643
argument defaults to be used in @i{instance} creation.
646
Indicating that the @i{metaclass} is to be other
647
than the default. The @t{:metaclass} option is reserved for future use;
648
an implementation can be extended to make use of the @t{:metaclass}
652
Indicating the expected @i{type} for the value stored
656
Indicating the @i{documentation string} for the @i{slot}.
660
@node Creating Instances of Classes, Inheritance, Defining Classes, Classes
661
@subsection Creating Instances of Classes
663
The generic function @b{make-instance} creates and returns a new
664
@i{instance} of a @i{class}.
665
The object system provides several mechanisms for
666
specifying how a new @i{instance} is to be initialized. For example, it
667
is possible to specify the initial values for @i{slots} in newly created
669
either by giving arguments to @b{make-instance} or by
670
providing default initial values. Further initialization activities
671
can be performed by @i{methods} written for @i{generic functions}
673
part of the initialization protocol. The complete initialization
674
protocol is described in @ref{Object Creation and Initialization}.
676
@node Inheritance, Determining the Class Precedence List, Creating Instances of Classes, Classes
677
@subsection Inheritance
679
A @i{class} can inherit @i{methods}, @i{slots},
680
and some @b{defclass} options from its @i{superclasses}.
681
Other sections describe the inheritance of @i{methods},
682
the inheritance of @i{slots} and @i{slot} options,
683
and the inheritance of @i{class} options.
686
* Examples of Inheritance::
687
* Inheritance of Class Options::
690
@node Examples of Inheritance, Inheritance of Class Options, Inheritance, Inheritance
691
@subsubsection Examples of Inheritance
695
((S1 :initform 5.4 :type number)
696
(S2 :allocation :class)))
699
((S1 :initform 5 :type integer)
700
(S2 :allocation :instance)
701
(S3 :accessor C2-S3)))
704
@i{Instances} of the class @t{C1} have a @i{local slot} named @t{S1},
705
whose default initial value is 5.4 and
706
whose @i{value} should always be a @i{number}.
707
The class @t{C1} also has a @i{shared slot} named @t{S2}.
709
There is a @i{local slot} named @t{S1} in @i{instances} of @t{C2}.
710
The default initial value of @t{S1} is 5.
711
The value of @t{S1} should always be of type @t{(and integer number)}.
712
There are also @i{local slots} named @t{S2} and @t{S3} in @i{instances} of @t{C2}.
713
The class @t{C2} has a @i{method} for @t{C2-S3} for reading the value of slot @t{S3};
714
there is also a @i{method} for @t{(setf C2-S3)} that writes the value of @t{S3}.
716
@node Inheritance of Class Options, , Examples of Inheritance, Inheritance
717
@subsubsection Inheritance of Class Options
719
The @t{:default-initargs} class option is inherited. The set of
720
defaulted initialization arguments for a @i{class} is the union of the
721
sets of initialization arguments supplied in
722
the @t{:default-initargs} class options of the @i{class} and its @i{superclasses}.
723
When more than one default initial value @i{form} is supplied for a given
724
initialization argument, the default initial value @i{form} that is used
725
is the one supplied by the @i{class} that is most specific according to
726
the @i{class precedence list}.
728
If a given @t{:default-initargs} class option specifies an
729
initialization argument of the same @i{name} more than once, an
730
error of @i{type} @b{program-error} is signaled.
732
@node Determining the Class Precedence List, Redefining Classes, Inheritance, Classes
733
@subsection Determining the Class Precedence List
735
The @b{defclass} form for a @i{class} provides a total ordering
736
on that @i{class} and its direct @i{superclasses}. This ordering is
737
called the @i{local precedence order}
738
@IGindex{local precedence order}
739
. It is an ordered list of the
740
@i{class} and its direct @i{superclasses}. The
741
@i{class precedence list}
742
@IGindex{class precedence list}
743
for a class C is a total ordering on
744
C and its @i{superclasses} that is consistent with the
745
@i{local precedence orders} for each of C and its @i{superclasses}.
747
A @i{class} precedes its direct @i{superclasses},
748
and a direct @i{superclass} precedes all other
749
direct @i{superclasses} specified to its right
750
in the @i{superclasses} list of the @b{defclass} form.
751
For every class C, define
752
@center R_C=@{(C,C_1),(C_1,C_2),...,(C_@{n-1@},C_n)@}
753
where C_1,...,C_n are
754
the direct @i{superclasses} of C in the order in which
755
they are mentioned in the @b{defclass} form. These ordered pairs
756
generate the total ordering on the class C and its direct
759
Let S_C be the set of C and its @i{superclasses}. Let R be
761
@center R=\bigcup_@{c\in S_C @}R_c
764
[Reviewer Note by Barmar: ``Consistent'' needs to be defined, or maybe we should say
765
``logically consistent''?]
767
The set R might or might not generate a partial ordering, depending on
768
whether the R_c, c\in S_C, are
769
consistent; it is assumed
770
that they are consistent and that R generates a partial ordering.
771
When the R_c are not consistent, it is said that R is inconsistent.
773
To compute the @i{class precedence list} for~C,
774
topologically sort the elements of S_C with respect to the
775
partial ordering generated by R. When the topological
776
sort must select a @i{class} from a set of two or more
778
which are preceded by other @i{classes} with respect to~R,
779
the @i{class} selected is chosen deterministically, as described below.
781
If R is inconsistent, an error is signaled.
784
* Topological Sorting::
785
* Examples of Class Precedence List Determination::
788
@node Topological Sorting, Examples of Class Precedence List Determination, Determining the Class Precedence List, Determining the Class Precedence List
789
@subsubsection Topological Sorting
791
Topological sorting proceeds by finding a class C in~S_C such
792
that no other @i{class} precedes that element according to the elements
793
in~R. The class C is placed first in the result.
794
Remove C from S_C, and remove all pairs of the form (C,D),
795
D\in S_C, from R. Repeat the process, adding
796
@i{classes} with no predecessors to the end of the result. Stop when no
797
element can be found that has no predecessor.
799
If S_C is not empty and the process has stopped, the set R is
800
inconsistent. If every @i{class} in the finite set of
801
@i{classes} is preceded
802
by another, then R contains a loop. That is, there is a chain of
803
classes C_1,...,C_n such that C_i precedes
804
C_@{i+1@}, 1<= i<n, and C_n precedes C_1.
806
Sometimes there are several @i{classes} from S_C with no
807
predecessors. In this case select the one that has a direct
808
@i{subclass} rightmost in the @i{class precedence list} computed so far.
809
(If there is no such candidate @i{class}, R does not generate
810
a partial ordering---the R_c, c\in S_C, are inconsistent.)
812
In more precise terms, let @{N_1,...,N_m@}, m>= 2, be
813
the @i{classes} from S_C with no predecessors. Let (C_1... C_n), n>= 1, be the @i{class precedence list}
814
constructed so far. C_1 is the most specific @i{class}, and C_n is the least specific. Let 1<= j<= n be the largest number
815
such that there exists an i where 1<= i<= m and N_i
816
is a direct @i{superclass} of C_j; N_i is placed next.
818
The effect of this rule for selecting from a set of @i{classes} with no
819
predecessors is that the @i{classes} in a simple @i{superclass} chain are
820
adjacent in the @i{class precedence list} and that @i{classes} in each
821
relatively separated subgraph are adjacent in the @i{class precedence list}.
822
For example, let T_1 and T_2 be subgraphs whose only
823
element in common is the class J.
824
Suppose that no superclass of J appears in either T_1 or T_2,
825
and that J is in the superclass chain of every class in both T_1 and T_2.
826
Let C_1 be the bottom of T_1;
827
and let C_2 be the bottom of T_2.
828
Suppose C is a @i{class} whose direct @i{superclasses}
829
are C_1 and C_2 in that order, then the @i{class precedence list}
830
for C starts with C and is followed by
831
all @i{classes} in T_1 except J.
832
All the @i{classes} of T_2 are next.
833
The @i{class} J and its @i{superclasses} appear last.
835
@node Examples of Class Precedence List Determination, , Topological Sorting, Determining the Class Precedence List
836
@subsubsection Examples of Class Precedence List Determination
838
This example determines a @i{class precedence list} for the
839
class @t{pie}. The following @i{classes} are defined:
842
(defclass pie (apple cinnamon) ())
844
(defclass apple (fruit) ())
846
(defclass cinnamon (spice) ())
848
(defclass fruit (food) ())
850
(defclass spice (food) ())
852
(defclass food () ())
855
The set S_@{pie@}~= @{pie, apple, cinnamon, fruit, spice, food,
856
standard-object, t @}. The set R~= @{ (pie, apple),
857
(apple, cinnamon), (apple, fruit), (cinnamon, spice), \break
858
(fruit, food), (spice, food), (food, standard-object), (standard-object,
861
The class @t{pie} is not preceded by anything, so it comes first;
862
the result so far is @t{(pie)}. Remove @t{pie} from S and pairs
863
mentioning @t{pie} from R to get S~= @{apple, cinnamon,
864
fruit, spice, food, standard-object, t @} and R~=~@{(apple, cinnamon), (apple, fruit), (cinnamon, spice),\break (fruit,
865
food), (spice, food), (food, standard-object),
866
(standard-object, t) @}.
868
The class @t{apple} is not preceded by anything, so it is next; the
869
result is @t{(pie apple)}. Removing @t{apple} and the relevant
870
pairs results in S~= @{ cinnamon, fruit, spice, food,
871
standard-object, t @} and R~= @{ (cinnamon, spice),
872
(fruit, food), (spice, food), (food, standard-object),\break
873
(standard-object, t) @}.
875
The classes @t{cinnamon} and @t{fruit} are not preceded by
876
anything, so the one with a direct @i{subclass} rightmost in the
877
@i{class precedence list} computed so far goes next. The class @t{apple} is a
878
direct @i{subclass} of @t{fruit}, and the class @t{pie} is a direct
879
@i{subclass} of @t{cinnamon}. Because @t{apple} appears to the right
880
of @t{pie} in the @i{class precedence list},
881
@t{fruit} goes next, and the
882
result so far is @t{(pie apple fruit)}. S~= @{ cinnamon,
883
spice, food, standard-object, t @}; R~= @{(cinnamon,
884
spice), (spice, food),\break (food, standard-object),
885
(standard-object, t) @}.
887
The class @t{cinnamon} is next, giving the result so far as @t{(pie apple fruit cinnamon)}. At this point S~= @{ spice,
888
food, standard-object, t @}; R~= @{ (spice, food), (food,
889
standard-object), (standard-object, t) @}.
891
The classes @t{spice}, @t{food}, @b{standard-object}, and
892
@b{t} are added in that order, and the @i{class precedence list}
893
is @t{(pie apple fruit cinnamon spice food standard-object t)}.
895
It is possible to write a set of @i{class} definitions that cannot be
896
ordered. For example:
899
(defclass new-class (fruit apple) ())
901
(defclass apple (fruit) ())
904
The class @t{fruit} must precede @t{apple}
905
because the local ordering of @i{superclasses} must be preserved.
906
The class @t{apple} must precede @t{fruit}
907
because a @i{class} always precedes its own @i{superclasses}.
908
When this situation occurs, an error is signaled, as happens here
909
when the system tries to compute the @i{class precedence list}
912
The following might appear to be a conflicting set of definitions:
915
(defclass pie (apple cinnamon) ())
917
(defclass pastry (cinnamon apple) ())
919
(defclass apple () ())
921
(defclass cinnamon () ())
924
The @i{class precedence list} for @t{pie} is
925
@t{(pie apple cinnamon standard-object t)}.
927
The @i{class precedence list} for @t{pastry} is
928
@t{(pastry cinnamon apple standard-object t)}.
930
It is not a problem for @t{apple} to precede @t{cinnamon} in the
931
ordering of the @i{superclasses} of @t{pie} but not in the ordering for
932
@t{pastry}. However, it is not possible to build a new @i{class} that
933
has both @t{pie} and @t{pastry} as @i{superclasses}.
935
@node Redefining Classes, Integrating Types and Classes, Determining the Class Precedence List, Classes
936
@subsection Redefining Classes
938
A @i{class} that is a @i{direct instance} of @b{standard-class} can
939
be redefined if the new @i{class} is also
940
a @i{direct instance} of @b{standard-class}.
941
Redefining a @i{class} modifies the existing
942
@i{class} @i{object} to reflect the new @i{class} definition; it does not
943
create a new @i{class} @i{object} for the @i{class}.
944
Any @i{method} @i{object} created by a @t{:reader}, @t{:writer},
945
or @t{:accessor} option specified by the old @b{defclass} form is
946
removed from the corresponding @i{generic function}.
947
@i{Methods} specified by the new @b{defclass} form are added.
949
When the class C is redefined, changes are propagated to its @i{instances}
950
and to @i{instances} of any of its @i{subclasses}. Updating such an
951
@i{instance} occurs at an @i{implementation-dependent} time, but no later than
952
the next time a @i{slot}
953
of that @i{instance} is read or written. Updating an
955
does not change its identity as defined by the @i{function} @b{eq}.
956
The updating process may change the @i{slots} of that
957
particular @i{instance},
958
but it does not create a new @i{instance}. Whether
959
updating an @i{instance} consumes storage is @i{implementation-dependent}.
961
Note that redefining a @i{class} may cause @i{slots} to be added or
962
deleted. If a @i{class} is redefined in a way that changes the set of
963
@i{local slots} @i{accessible} in @i{instances}, the @i{instances}
964
are updated. It is @i{implementation-dependent} whether @i{instances}
965
are updated if a @i{class} is redefined in a way that does not change
966
the set of @i{local slots} @i{accessible} in @i{instances}.
968
The value of a @i{slot}
969
that is specified as shared both in the old @i{class}
970
and in the new @i{class} is retained.
971
If such a @i{shared slot} was unbound
972
in the old @i{class}, it is unbound in the new @i{class}.
974
were local in the old @i{class} and that are shared in the new
976
initialized. Newly added @i{shared slots} are initialized.
978
Each newly added @i{shared slot} is set to the result of evaluating the
979
@i{captured initialization form} for the @i{slot} that was specified
980
in the @b{defclass} @i{form} for the new @i{class}.
981
If there was no @i{initialization form}, the @i{slot} is unbound.
983
If a @i{class} is redefined in such a way that the set of
984
@i{local slots} @i{accessible} in an @i{instance} of the @i{class}
985
is changed, a two-step process of updating the @i{instances} of the
986
@i{class} takes place. The process may be explicitly started by
987
invoking the generic function @b{make-instances-obsolete}. This
988
two-step process can happen in other circumstances in some implementations.
989
For example, in some implementations this two-step process is
990
triggered if the order of @i{slots} in storage is changed.
992
The first step modifies the structure of the @i{instance} by adding new
993
@i{local slots} and discarding @i{local slots} that are not
994
defined in the new version of the @i{class}. The second step
995
initializes the newly-added @i{local slots} and performs any other
996
user-defined actions. These two steps are further specified
997
in the next two sections.
1000
* Modifying the Structure of Instances::
1001
* Initializing Newly Added Local Slots (Redefining Classes)::
1002
* Customizing Class Redefinition::
1005
@node Modifying the Structure of Instances, Initializing Newly Added Local Slots (Redefining Classes), Redefining Classes, Redefining Classes
1006
@subsubsection Modifying the Structure of Instances
1008
[Reviewer Note by Barmar: What about shared slots that are deleted?]
1010
The first step modifies the structure of @i{instances} of the redefined
1011
@i{class} to conform to its new @i{class} definition.
1012
@i{Local slots} specified
1013
by the new @i{class} definition that are not specified as either local or
1014
shared by the old @i{class} are added, and @i{slots}
1015
not specified as either
1016
local or shared by the new @i{class} definition that are specified as
1017
local by the old @i{class} are discarded.
1018
The @i{names} of these added and discarded
1019
@i{slots} are passed as arguments
1020
to @b{update-instance-for-redefined-class}
1021
as described in the next section.
1023
The values of @i{local slots} specified by both the new and old
1024
@i{classes} are retained. If such a @i{local slot} was unbound,
1027
The value of a @i{slot} that is specified as shared in the old
1028
@i{class} and as local in the new @i{class} is retained. If such
1029
a @i{shared slot} was unbound, the @i{local slot} is unbound.
1031
@node Initializing Newly Added Local Slots (Redefining Classes), Customizing Class Redefinition, Modifying the Structure of Instances, Redefining Classes
1032
@subsubsection Initializing Newly Added Local Slots
1034
The second step initializes the newly added @i{local slots} and performs
1035
any other user-defined actions. This step is implemented by the generic
1036
function @b{update-instance-for-redefined-class}, which is called after
1037
completion of the first step of modifying the structure of the
1040
The generic function @b{update-instance-for-redefined-class} takes
1041
four required arguments: the @i{instance} being updated after it has
1042
undergone the first step, a list of the names of @i{local slots} that were
1043
added, a list of the names of @i{local slots} that were discarded, and a
1044
property list containing the @i{slot} names and values of
1046
discarded and had values. Included among the discarded @i{slots} are
1047
@i{slots} that were local in the old @i{class} and that are shared in the new
1050
The generic function @b{update-instance-for-redefined-class} also
1051
takes any number of initialization arguments. When it is called by
1052
the system to update an @i{instance} whose @i{class}
1053
has been redefined, no
1054
initialization arguments are provided.
1056
There is a system-supplied primary @i{method} for
1057
@b{update-instance-for-redefined-class} whose @i{parameter specializer}
1058
for its @i{instance} argument is the @i{class} @b{standard-object}.
1059
First this @i{method} checks the validity of initialization arguments and signals an
1060
error if an initialization argument is supplied that is not declared
1061
as valid. (For more information, see @ref{Declaring the Validity of Initialization Arguments}.)
1062
Then it calls the generic function
1063
@b{shared-initialize} with the following arguments: the
1065
the list of @i{names} of
1066
the newly added @i{slots}, and the initialization
1067
arguments it received.
1069
@node Customizing Class Redefinition, , Initializing Newly Added Local Slots (Redefining Classes), Redefining Classes
1070
@subsubsection Customizing Class Redefinition
1072
[Reviewer Note by Barmar: This description is hard to follow.]
1074
@i{Methods} for @b{update-instance-for-redefined-class} may be
1075
defined to specify actions to be taken when an @i{instance} is updated.
1076
If only @i{after methods} for @b{update-instance-for-redefined-class} are
1077
defined, they will be run after the system-supplied primary @i{method} for
1078
initialization and therefore will not interfere with the default
1079
behavior of @b{update-instance-for-redefined-class}. Because no
1080
initialization arguments are passed to @b{update-instance-for-redefined-class}
1081
when it is called by the system, the
1082
@i{initialization forms} for @i{slots}
1083
that are filled by @i{before methods} for @b{update-instance-for-redefined-class}
1084
will not be evaluated by @b{shared-initialize}.
1086
@i{Methods} for @b{shared-initialize} may be defined to customize
1087
@i{class} redefinition. For more information, see @ref{Shared-Initialize}.
1089
@node Integrating Types and Classes, , Redefining Classes, Classes
1090
@subsection Integrating Types and Classes
1092
The object system maps the space of @i{classes} into the space of @i{types}.
1093
Every @i{class} that has a proper name has a corresponding @i{type}
1094
with the same @i{name}.
1096
The proper name of every @i{class} is a valid @i{type specifier}. In
1097
addition, every @i{class} @i{object} is a valid @i{type specifier}.
1098
Thus the expression @t{(typep @i{object} @i{class})} evaluates to
1099
@i{true} if the @i{class} of @i{object} is @i{class} itself or
1100
a @i{subclass} of @i{class}. The evaluation of the expression
1101
@t{(subtypep class1 class2)} returns the values
1102
@i{true} and @i{true} if @t{class1} is a subclass of @t{class2} or if they are the
1103
same @i{class}; otherwise it returns the values
1104
@i{false} and @i{true}.
1105
If I is an @i{instance} of some @i{class} C named S
1106
and C is an @i{instance} of @b{standard-class},
1107
the evaluation of the expression @t{(type-of I\/)} returns S
1108
if S is the @i{proper name} of C;
1109
otherwise, it returns C.
1111
Because the names of @i{classes}
1112
and @i{class} @i{objects} are @i{type specifiers}, they may
1113
be used in the special form @b{the} and in type declarations.
1115
Many but not all of the predefined @i{type specifiers} have a
1116
corresponding @i{class} with
1117
the same proper name as the @i{type}. These type
1118
specifiers are listed in @i{Figure~4--8}.
1119
For example, the @i{type} @b{array} has
1120
a corresponding @i{class} named @b{array}.
1121
No @i{type specifier} that is a
1122
list, such as @t{(vector double-float 100)}, has a corresponding @i{class}.
1123
The @i{operator} @b{deftype} does not create any @i{classes}.
1125
Each @i{class} that corresponds to a predefined @i{type specifier} can
1126
be implemented in one of three ways, at the discretion of each implementation.
1127
It can be a @i{standard class},
1128
a @i{structure class},
1130
or a @i{system class}.
1132
A @i{built-in class} is one whose @i{generalized instances} have restricted capabilities
1133
or special representations. Attempting to use @b{defclass} to define
1134
@i{subclasses} of a @b{built-in-class} signals an error.
1135
Calling @b{make-instance} to create a @i{generalized instance} of a
1136
@i{built-in class} signals an error. Calling @b{slot-value} on a
1137
@i{generalized instance} of a @i{built-in class} signals an error.
1138
Redefining a @i{built-in class} or using @b{change-class} to change
1139
the @i{class} of an @i{object} to or from a @i{built-in class} signals an error.
1140
However, @i{built-in classes} can be used as @i{parameter specializers}
1143
It is possible to determine whether a @i{class} is a @i{built-in class}
1144
by checking the @i{metaclass}.
1145
A @i{standard class} is an @i{instance} of the @i{class} @b{standard-class},
1146
a @i{built-in class} is an @i{instance} of the @i{class} @b{built-in-class}, and
1147
a @i{structure class} is an @i{instance} of the @i{class} @b{structure-class}.
1149
Each @i{structure} @i{type} created by @b{defstruct} without
1150
using the @t{:type} option has a corresponding @i{class}.
1151
This @i{class} is a @i{generalized instance} of the @i{class} @b{structure-class}.
1152
The @t{:include} option of @b{defstruct} creates a direct
1153
@i{subclass} of the @i{class}
1154
that corresponds to the included @i{structure}
1157
It is @i{implementation-dependent} whether @i{slots} are involved in the
1158
operation of @i{functions} defined in this specification
1159
on @i{instances} of @i{classes} defined in this specification,
1160
except when @i{slots} are explicitly defined by this specification.
1162
If in a particular @i{implementation} a @i{class} defined in this specification
1163
has @i{slots} that are not defined by this specfication, the names of these @i{slots}
1164
must not be @i{external symbols} of @i{packages} defined in this specification nor
1165
otherwise @i{accessible} in the @t{CL-USER} @i{package}.
1167
The purpose of specifying that many of the standard @i{type specifiers} have a
1168
corresponding @i{class} is to enable users to write @i{methods} that
1169
discriminate on these @i{types}. @i{Method} selection requires that a
1170
@i{class precedence list} can be determined for each @i{class}.
1172
The hierarchical relationships among the @i{type specifiers} are mirrored by
1173
relationships among the @i{classes} corresponding to those @i{types}.
1175
@i{Figure~4--8} lists the set of @i{classes}
1176
that correspond to predefined @i{type specifiers}.
1181
@w{ arithmetic-error generic-function simple-error }
1182
@w{ array hash-table simple-type-error }
1183
@w{ bit-vector integer simple-warning }
1184
@w{ broadcast-stream list standard-class }
1185
@w{ built-in-class logical-pathname standard-generic-function }
1186
@w{ cell-error method standard-method }
1187
@w{ character method-combination standard-object }
1188
@w{ class null storage-condition }
1189
@w{ complex number stream }
1190
@w{ concatenated-stream package stream-error }
1191
@w{ condition package-error string }
1192
@w{ cons parse-error string-stream }
1193
@w{ control-error pathname structure-class }
1194
@w{ division-by-zero print-not-readable structure-object }
1195
@w{ echo-stream program-error style-warning }
1196
@w{ end-of-file random-state symbol }
1197
@w{ error ratio synonym-stream }
1198
@w{ file-error rational t }
1199
@w{ file-stream reader-error two-way-stream }
1200
@w{ float readtable type-error }
1201
@w{ floating-point-inexact real unbound-slot }
1202
@w{ floating-point-invalid-operation restart unbound-variable }
1203
@w{ floating-point-overflow sequence undefined-function }
1204
@w{ floating-point-underflow serious-condition vector }
1205
@w{ function simple-condition warning }
1208
@w{ Figure 4--8: Classes that correspond to pre-defined type specifiers }
1213
The @i{class precedence list} information specified in the entries for
1214
each of these @i{classes} are those that are required by the object system.
1216
Individual implementations may be extended to define other type
1217
specifiers to have a corresponding @i{class}. Individual implementations
1218
may be extended to add other @i{subclass} relationships and to add other
1219
@i{elements} to the @i{class precedence lists} as long as
1220
they do not violate the type relationships and disjointness
1221
requirements specified by this standard.
1222
A standard @i{class} defined with no direct @i{superclasses} is guaranteed to
1223
be disjoint from all of the @i{classes} in the table, except for the
1226
@c end of including concept-classes
1228
@node Types and Classes Dictionary, , Classes, Types and Classes
1229
@section Types and Classes Dictionary
1231
@c including dict-types
1236
* function (System Class)::
1237
* compiled-function::
1238
* generic-function::
1239
* standard-generic-function::
1246
* structure-object::
1248
* method-combination::
1249
* t (System Class)::
1251
* member (Type Specifier)::
1252
* not (Type Specifier)::
1253
* and (Type Specifier)::
1254
* or (Type Specifier)::
1255
* values (Type Specifier)::
1256
* eql (Type Specifier)::
1263
* type-error-datum::
1264
* simple-type-error::
1267
@node nil (Type), boolean, Types and Classes Dictionary, Types and Classes Dictionary
1268
@subsection nil [Type]
1270
@subsubheading Supertypes::
1273
@subsubheading Description::
1275
The @i{type} @b{nil} contains no @i{objects} and so is also
1276
called the @i{empty type}.
1277
The @i{type} @b{nil} is a @i{subtype} of every @i{type}.
1278
No @i{object} is of @i{type} @b{nil}.
1280
@subsubheading Notes::
1282
The @i{type} containing the @i{object} @b{nil} is the @i{type} @b{null},
1283
not the @i{type} @b{nil}.
1285
@node boolean, function (System Class), nil (Type), Types and Classes Dictionary
1286
@subsection boolean [Type]
1288
@subsubheading Supertypes::
1294
@subsubheading Description::
1296
The @i{type} @b{boolean} contains the @i{symbols} @b{t} and @b{nil},
1297
which represent true and false, respectively.
1299
@subsubheading See Also::
1301
@b{t} (@i{constant variable}),
1302
@b{nil} (@i{constant variable}),
1309
@subsubheading Notes::
1311
Conditional operations, such as @b{if},
1312
permit the use of @i{generalized booleans},
1313
not just @i{booleans};
1314
any @i{non-nil} value,
1316
counts as true for a @i{generalized boolean}.
1317
However, as a matter of convention,
1318
the @i{symbol} @b{t} is considered the canonical value to use
1319
even for a @i{generalized boolean} when no better choice presents itself.
1321
@node function (System Class), compiled-function, boolean, Types and Classes Dictionary
1322
@subsection function [System Class]
1324
@subsubheading Class Precedence List::
1328
@subsubheading Description::
1330
A @i{function} is an @i{object} that represents code
1331
to be executed when an appropriate number of arguments is supplied.
1332
A @i{function} is produced by
1333
the @b{function} @i{special form},
1334
the @i{function} @b{coerce},
1337
the @i{function} @b{compile}.
1338
A @i{function} can be directly invoked by using it as the first argument to
1339
@b{funcall}, @b{apply}, or @b{multiple-value-call}.
1341
@subsubheading Compound Type Specifier Kind::
1345
@subsubheading Compound Type Specifier Syntax::
1347
(@code{function}@{@i{@t{[}arg-typespec @r{[}value-typespec@r{]}@t{]}}@})
1349
@w{@i{arg-typespec} ::=@r{(}@{@i{typespec}@}* }
1350
@w{ @t{[}@r{&optional} @{@i{typespec}@}*@t{]} }
1351
@w{ @t{[}@r{&rest} @i{typespec}@t{]} }
1352
@w{ @t{[}@r{&key} @{@r{(}keyword typespec @r{)}@}*@t{]}@r{)}}
1354
@subsubheading Compound Type Specifier Arguments::
1356
@i{typespec}---a @i{type specifier}.
1358
@i{value-typespec}---a @i{type specifier}.
1360
@subsubheading Compound Type Specifier Description::
1362
[Editorial Note by KMP: Isn't there some context info about ftype declarations to be merged here?]
1364
[Editorial Note by KMP: This could still use some cleaning up.]
1366
[Editorial Note by Sandra: Still need clarification about what happens if the
1367
number of arguments doesn't match the FUNCTION type declaration.]
1369
The list form of the @b{function} @i{type-specifier}
1370
can be used only for declaration and not for discrimination.
1371
Every element of this @i{type} is
1372
a @i{function} that accepts arguments of the
1374
specified by the @i{argj-types} and returns values that are
1375
members of the @i{types} specified by @i{value-type}. The
1376
@b{&optional}, @b{&rest}, @b{&key},
1378
and @b{&allow-other-keys}
1380
markers can appear in the list of argument types.
1382
The @i{type specifier} provided
1383
with @b{&rest} is the @i{type}
1384
of each actual argument, not the @i{type} of the
1385
corresponding variable.
1387
The @b{&key} parameters
1388
should be supplied as lists of the form @t{(@i{keyword} @i{type})}.
1389
The @i{keyword} must be a valid keyword-name symbol
1390
as must be supplied in the actual arguments of a
1393
This is usually a @i{symbol} in the @t{KEYWORD} @i{package} but can be any @i{symbol}.
1395
When @b{&key} is given in a
1396
@b{function} @i{type specifier} @i{lambda list},
1397
the @i{keyword parameters} given
1398
are exhaustive unless @b{&allow-other-keys} is also present.
1399
@b{&allow-other-keys} is an indication
1400
that other keyword arguments might actually be
1401
supplied and, if supplied, can be used.
1403
the @i{type} of the @i{function} @b{make-list} could be declared as follows:
1406
(function ((integer 0) &key (:initial-element t)) list)
1409
The @i{value-type} can be a @b{values}
1410
@i{type specifier} in order to indicate the
1411
@i{types} of @i{multiple values}.
1413
Consider a declaration of the following form:
1416
(ftype (function (arg0-type arg1-type ...) val-type) f))
1420
@t{(f arg0 arg1 ...)}
1422
that declaration is equivalent to the following:
1425
(the val-type (f (the arg0-type arg0) (the arg1-type arg1) ...))
1428
That is, the consequences are undefined if any of the arguments are
1429
not of the specified @i{types} or the result is not of the
1430
specified @i{type}. In particular, if any argument is not of the
1431
correct @i{type}, the result is not guaranteed to be of the
1434
Thus, an @b{ftype} declaration for a @i{function}
1435
describes @i{calls} to the @i{function}, not the actual definition
1436
of the @i{function}.
1438
Consider a declaration of the following form:
1441
(type (function (arg0-type arg1-type ...) val-type) fn-valued-variable)
1444
This declaration has the interpretation that, within the scope of the
1445
declaration, the consequences are unspecified if the value of @t{fn-valued-variable} is called with arguments not of the specified
1446
@i{types}; the value resulting from a valid call will be of type
1449
As with variable type declarations, nested declarations
1450
imply intersections of @i{types}, as follows:
1454
Consider the following two
1455
declarations of @b{ftype}:
1458
(ftype (function (arg0-type1 arg1-type1 ...) val-type1) f))
1464
(ftype (function (arg0-type2 arg1-type2 ...) val-type2) f))
1467
If both these declarations are in effect,
1468
then within the shared scope of the declarations, calls to @t{f} can be
1469
treated as if @t{f} were declared as follows:
1472
(ftype (function ((and arg0-type1 arg0-type2) (and arg1-type1 arg1-type2 ...) ...)
1473
(and val-type1 val-type2))
1477
It is permitted to ignore one or all of the @b{ftype} declarations in force.
1480
If two (or more) type declarations are in effect for a variable, and
1481
they are both @t{function} declarations, the declarations combine similarly.
1484
@node compiled-function, generic-function, function (System Class), Types and Classes Dictionary
1485
@subsection compiled-function [Type]
1487
@subsubheading Supertypes::
1489
@b{compiled-function},
1493
@subsubheading Description::
1495
Any @i{function} may be considered by an @i{implementation} to be a
1496
a @i{compiled function} if it contains no references to @i{macros} that
1497
must be expanded at run time, and it contains no unresolved references
1498
to @i{load time values}. See @ref{Compilation Semantics}.
1500
@i{Functions} whose definitions appear lexically within a
1501
@i{file} that has been @i{compiled} with @b{compile-file} and then
1502
@i{loaded} with @b{load} are of @i{type} @b{compiled-function}.
1504
@i{Functions} produced by the @b{compile} function
1505
are of @i{type} @b{compiled-function}.
1507
Other @i{functions} might also be of @i{type} @b{compiled-function}.
1509
@node generic-function, standard-generic-function, compiled-function, Types and Classes Dictionary
1510
@subsection generic-function [System Class]
1512
@subsubheading Class Precedence List::
1514
@b{generic-function},
1518
@subsubheading Description::
1520
A @i{generic function}
1521
@IGindex{generic function}
1522
is a @i{function} whose behavior
1523
depends on the @i{classes} or identities of the @i{arguments}
1524
supplied to it. A generic function object contains a set of
1525
@i{methods}, a @i{lambda list}, a @i{method combination} @i{type},
1526
and other information. The @i{methods}
1527
define the class-specific behavior and operations of the @i{generic function};
1528
a @i{method} is said to @i{specialize} a @i{generic function}.
1529
When invoked, a @i{generic function} executes a subset of its
1530
@i{methods} based on the @i{classes} or identities of its @i{arguments}.
1532
A @i{generic function} can be used in the same ways that an
1533
ordinary @i{function} can be used; specifically, a @i{generic function} can
1534
be used as an argument to @b{funcall} and @b{apply},
1535
and can be given a global or a local name.
1537
@node standard-generic-function, class, generic-function, Types and Classes Dictionary
1538
@subsection standard-generic-function [System Class]
1540
@subsubheading Class Precedence List::
1541
@b{standard-generic-function},
1542
@b{generic-function},
1546
@subsubheading Description::
1548
The @i{class} @b{standard-generic-function} is the default @i{class} of
1549
@i{generic functions} @i{established} by
1551
@b{ensure-generic-function},
1555
@b{defclass} @i{forms}.
1557
@node class, built-in-class, standard-generic-function, Types and Classes Dictionary
1558
@subsection class [System Class]
1560
@subsubheading Class Precedence List::
1563
@b{standard-object},
1567
@subsubheading Description::
1569
The @i{type} @b{class} represents @i{objects} that determine the structure
1570
and behavior of their @i{instances}. Associated with an @i{object}
1571
of @i{type} @b{class} is information describing its place in the
1572
directed acyclic graph of @i{classes}, its @i{slots}, and its options.
1574
@node built-in-class, structure-class, class, Types and Classes Dictionary
1575
@subsection built-in-class [System Class]
1577
@subsubheading Class Precedence List::
1581
@b{standard-object},
1585
@subsubheading Description::
1587
A @i{built-in class} is a @i{class} whose @i{instances} have
1588
restricted capabilities or special representations.
1590
@b{defclass} to define @i{subclasses} of a @i{built-in class}
1591
signals an error of @i{type} @b{error}.
1592
Calling @b{make-instance} to create an @i{instance}
1593
of a @i{built-in class} signals an error of @i{type} @b{error}.
1594
Calling @b{slot-value} on an @i{instance} of a @i{built-in class}
1595
signals an error of @i{type} @b{error}. Redefining a @i{built-in class}
1596
or using @b{change-class} to change the @i{class} of an @i{instance}
1597
to or from a @i{built-in class} signals an error of @i{type} @b{error}.
1598
However, @i{built-in classes} can be used as @i{parameter specializers}
1601
@node structure-class, standard-class, built-in-class, Types and Classes Dictionary
1602
@subsection structure-class [System Class]
1604
@subsubheading Class Precedence List::
1606
@b{structure-class},
1609
@b{standard-object},
1613
@subsubheading Description::
1615
All @i{classes} defined by means of @b{defstruct}
1616
are @i{instances} of the @i{class} @b{structure-class}.
1618
@node standard-class, method, structure-class, Types and Classes Dictionary
1619
@subsection standard-class [System Class]
1621
@subsubheading Class Precedence List::
1625
@b{standard-object},
1629
@subsubheading Description::
1631
The @i{class} @b{standard-class} is the default @i{class} of @i{classes}
1632
defined by @b{defclass}.
1634
@node method, standard-method, standard-class, Types and Classes Dictionary
1635
@subsection method [System Class]
1637
@subsubheading Class Precedence List::
1641
@subsubheading Description::
1643
A @i{method} is an @i{object} that represents a modular part of the behavior
1644
of a @i{generic function}.
1646
A @i{method} contains @i{code} to implement the @i{method}'s
1647
behavior, a sequence of @i{parameter specializers} that specify when the
1648
given @i{method} is applicable, and a sequence of @i{qualifiers}
1649
that is used by the method combination facility to distinguish among
1650
@i{methods}. Each required parameter of each
1651
@i{method} has an associated @i{parameter specializer}, and the
1652
@i{method} will be invoked only on arguments that satisfy its
1653
@i{parameter specializers}.
1655
The method combination facility controls the selection of
1656
@i{methods}, the order in which they are run, and the values that are
1657
returned by the generic function. The object system offers a default method
1658
combination type and provides a facility for declaring new types of
1661
@subsubheading See Also::
1663
@ref{Generic Functions and Methods}
1665
@node standard-method, structure-object, method, Types and Classes Dictionary
1666
@subsection standard-method [System Class]
1668
@subsubheading Class Precedence List::
1669
@b{standard-method},
1672
@b{standard-object},
1676
@subsubheading Description::
1678
The @i{class} @b{standard-method} is the default @i{class} of
1679
@i{methods} defined by the
1681
@b{defgeneric} @i{forms}.
1683
@node structure-object, standard-object, standard-method, Types and Classes Dictionary
1684
@subsection structure-object [Class]
1686
@subsubheading Class Precedence List::
1688
@b{structure-object},
1691
@subsubheading Description::
1693
The @i{class} @b{structure-object} is an @i{instance} of @b{structure-class}
1694
and is a @i{superclass} of every @i{class}
1695
that is an @i{instance} of @b{structure-class}
1696
except itself, and is a @i{superclass} of every @i{class}
1697
that is defined by @b{defstruct}.
1699
@subsubheading See Also::
1704
@ref{Printing Structures}
1706
@node standard-object, method-combination, structure-object, Types and Classes Dictionary
1707
@subsection standard-object [Class]
1709
@subsubheading Class Precedence List::
1710
@b{standard-object},
1713
@subsubheading Description::
1715
The @i{class} @b{standard-object} is an @i{instance} of @b{standard-class}
1716
and is a @i{superclass} of every @i{class} that is an @i{instance} of
1717
@b{standard-class} except itself.
1719
@node method-combination, t (System Class), standard-object, Types and Classes Dictionary
1720
@subsection method-combination [System Class]
1722
@subsubheading Class Precedence List::
1723
@b{method-combination},
1726
@subsubheading Description::
1728
Every @i{method combination} @i{object} is an
1729
@i{indirect instance} of the @i{class} @b{method-combination}.
1730
A @i{method combination} @i{object} represents the information about
1731
the @i{method combination} being used by a @i{generic function}.
1732
A @i{method combination} @i{object} contains information about
1733
both the type of @i{method combination} and the arguments being used
1736
@node t (System Class), satisfies, method-combination, Types and Classes Dictionary
1737
@subsection t [System Class]
1739
@subsubheading Class Precedence List::
1742
@subsubheading Description::
1743
The set of all @i{objects}.
1744
The @i{type} @b{t} is a @i{supertype} of every @i{type},
1745
including itself. Every @i{object} is of @i{type} @b{t}.
1747
@node satisfies, member (Type Specifier), t (System Class), Types and Classes Dictionary
1748
@subsection satisfies [Type Specifier]
1750
@subsubheading Compound Type Specifier Kind::
1754
@subsubheading Compound Type Specifier Syntax::
1756
(@code{satisfies}@{@i{predicate-name}@})
1758
@subsubheading Compound Type Specifier Arguments::
1760
@i{predicate-name}---a @i{symbol}.
1762
@subsubheading Compound Type Specifier Description::
1764
This denotes the set of all @i{objects} that satisfy the
1765
@i{predicate} @i{predicate-name}, which must be a @i{symbol}
1766
whose global @i{function} definition is a one-argument
1767
predicate. A name is required for @i{predicate-name};
1768
@i{lambda expressions} are not allowed.
1769
For example, the @i{type specifier} @t{(and integer (satisfies evenp))}
1770
denotes the set of all even integers.
1771
The form @t{(typep @i{x} '(satisfies @i{p}))} is equivalent to
1772
@t{(if (@i{p} @i{x}) t nil)}.
1774
The argument is required.
1775
The @i{symbol} @b{*} can be the argument, but it
1776
denotes itself (the @i{symbol} @b{*}),
1777
and does not represent an unspecified value.
1779
The symbol @b{satisfies} is not valid as a @i{type specifier}.
1781
@node member (Type Specifier), not (Type Specifier), satisfies, Types and Classes Dictionary
1782
@subsection member [Type Specifier]
1784
@subsubheading Compound Type Specifier Kind::
1788
@subsubheading Compound Type Specifier Syntax::
1790
(@code{member}@{@i{@{@i{object}@}*}@})
1792
@subsubheading Compound Type Specifier Arguments::
1794
@i{object}---an @i{object}.
1796
@subsubheading Compound Type Specifier Description::
1798
This denotes the set containing the named @i{objects}. An
1799
@i{object} is of this @i{type} if and only if it is @b{eql}
1800
to one of the specified @i{objects}.
1802
The @i{type specifiers} @t{(member)} and @b{nil} are equivalent.
1803
@b{*} can be among the @i{objects},
1804
but if so it denotes itself (the symbol @b{*})
1805
and does not represent an unspecified value.
1806
The symbol @b{member} is not valid as a @i{type specifier};
1807
and, specifically, it is not an abbreviation for either @t{(member)} or @t{(member *)}.
1809
@subsubheading See Also::
1811
the @i{type} @b{eql}
1813
@node not (Type Specifier), and (Type Specifier), member (Type Specifier), Types and Classes Dictionary
1814
@subsection not [Type Specifier]
1816
@subsubheading Compound Type Specifier Kind::
1820
@subsubheading Compound Type Specifier Syntax::
1822
(@code{not}@{@i{typespec}@})
1824
@subsubheading Compound Type Specifier Arguments::
1826
@i{typespec}---a @i{type specifier}.
1828
@subsubheading Compound Type Specifier Description::
1830
This denotes the set of all @i{objects} that are not of the @i{type} @i{typespec}.
1832
The argument is required, and cannot be @b{*}.
1834
The symbol @b{not} is not valid as a @i{type specifier}.
1836
@node and (Type Specifier), or (Type Specifier), not (Type Specifier), Types and Classes Dictionary
1837
@subsection and [Type Specifier]
1839
@subsubheading Compound Type Specifier Kind::
1843
@subsubheading Compound Type Specifier Syntax::
1845
(@code{and}@{@i{@{@i{typespec}@}*}@})
1847
@subsubheading Compound Type Specifier Arguments::
1849
@i{typespec}---a @i{type specifier}.
1851
@subsubheading Compound Type Specifier Description::
1853
This denotes the set of all @i{objects} of the @i{type}
1854
determined by the intersection of the @i{typespecs}.
1856
@b{*} is not permitted as an argument.
1858
The @i{type specifiers} @t{(and)} and @b{t} are equivalent.
1859
The symbol @b{and} is not valid as a @i{type specifier},
1860
and, specifically, it is not an abbreviation for @t{(and)}.
1862
@node or (Type Specifier), values (Type Specifier), and (Type Specifier), Types and Classes Dictionary
1863
@subsection or [Type Specifier]
1865
@subsubheading Compound Type Specifier Kind::
1869
@subsubheading Compound Type Specifier Syntax::
1871
(@code{or}@{@i{@{@i{typespec}@}*}@})
1873
@subsubheading Compound Type Specifier Arguments::
1875
@i{typespec}---a @i{type specifier}.
1877
@subsubheading Compound Type Specifier Description::
1879
This denotes the set of all @i{objects} of the
1880
@i{type} determined by the union of the @i{typespecs}.
1881
For example, the @i{type} @b{list} by definition is the same as @t{(or null cons)}.
1882
Also, the value returned by @b{position} is an @i{object} of @i{type} @t{(or null (integer 0 *))};
1883
@i{i.e.}, either @b{nil} or a non-negative @i{integer}.
1885
@b{*} is not permitted as an argument.
1887
The @i{type specifiers} @t{(or)} and @b{nil} are equivalent.
1888
The symbol @b{or} is not valid as a @i{type specifier};
1889
and, specifically, it is not an abbreviation for @t{(or)}.
1891
@node values (Type Specifier), eql (Type Specifier), or (Type Specifier), Types and Classes Dictionary
1892
@subsection values [Type Specifier]
1894
@subsubheading Compound Type Specifier Kind::
1898
@subsubheading Compound Type Specifier Syntax::
1900
(@code{values}@{@i{!@i{value-typespec}}@})
1902
[Reviewer Note by Barmar: Missing @b{&key}]
1904
@w{@i{value-typespec} ::=@{@i{typespec}@}* @t{[}@r{&optional} @r{@{@i{typespec}@}*}@t{]} @t{[}@r{&rest} typespec @t{]} @t{[}@b{&allow-other-keys}@t{]}}
1906
@subsubheading Compound Type Specifier Arguments::
1908
@i{typespec}---a @i{type specifier}.
1910
@subsubheading Compound Type Specifier Description::
1912
This @i{type specifier} can be used only as the @i{value-type} in a
1913
@b{function} @i{type specifier} or a @b{the}
1914
@i{special form}. It is used to specify individual @i{types}
1915
when @i{multiple values} are involved.
1916
The @b{&optional} and @b{&rest} markers can appear in the @i{value-type} list;
1917
they indicate the parameter list of a @i{function} that,
1918
when given to @b{multiple-value-call} along with the values,
1919
would correctly receive those values.
1921
The symbol @b{*} may not be among the @i{value-types}.
1923
The symbol @b{values} is not valid as a @i{type specifier};
1924
and, specifically, it is not an abbreviation for @t{(values)}.
1926
@node eql (Type Specifier), coerce, values (Type Specifier), Types and Classes Dictionary
1927
@subsection eql [Type Specifier]
1929
@subsubheading Compound Type Specifier Kind::
1933
@subsubheading Compound Type Specifier Syntax::
1935
(@code{eql}@{@i{object}@})
1937
@subsubheading Compound Type Specifier Arguments::
1939
@i{object}---an @i{object}.
1941
@subsubheading Compound Type Specifier Description::
1943
Represents the @i{type} whose only @i{element} is @i{object}.
1945
The argument @i{object} is required. The @i{object} can be @b{*},
1946
but if so it denotes itself (the symbol @b{*})
1947
and does not represent an unspecified value.
1948
The @i{symbol} @b{eql} is not valid as an @i{atomic type specifier}.
1950
@node coerce, deftype, eql (Type Specifier), Types and Classes Dictionary
1951
@subsection coerce [Function]
1953
@code{coerce} @i{object result-type} @result{} @i{result}
1955
@subsubheading Arguments and Values::
1957
@i{object}---an @i{object}.
1959
@i{result-type}---a @i{type specifier}.
1961
@i{result}---an @i{object}, of @i{type} @i{result-type}
1962
except in situations described in @ref{Rule of Canonical Representation for Complex Rationals}.
1964
@subsubheading Description::
1966
@i{Coerces} the @i{object} to @i{type} @i{result-type}.
1968
If @i{object} is already of @i{type} @i{result-type},
1969
the @i{object} itself is returned, regardless of whether it
1970
would have been possible in general to coerce an @i{object} of
1971
some other @i{type} to @i{result-type}.
1973
Otherwise, the @i{object} is @i{coerced} to @i{type} @i{result-type}
1974
according to the following rules:
1980
If the @i{result-type} is a @i{recognizable subtype} of @b{list},
1981
and the @i{object} is a @i{sequence},
1982
then the @i{result} is a @i{list}
1983
that has the @i{same} @i{elements} as @i{object}.
1985
If the @i{result-type} is a @i{recognizable subtype} of @b{vector},
1986
and the @i{object} is a @i{sequence},
1987
then the @i{result} is a @i{vector}
1988
that has the @i{same} @i{elements} as @i{object}.
1989
If @i{result-type} is a specialized @i{type},
1990
the @i{result} has an @i{actual array element type} that is the result of
1991
@i{upgrading} the element type part of that @i{specialized} @i{type}.
1992
If no element type is specified, the element type defaults to @b{t}.
1993
If the @i{implementation} cannot determine the element type, an error is signaled.
1996
If the @i{result-type} is @b{character}
1997
and the @i{object} is a @i{character designator},
1998
the @i{result} is the @i{character} it denotes.
2001
If the @i{result-type} is @b{complex}
2002
and the @i{object} is a @i{number},
2003
then the @i{result} is obtained by constructing a @i{complex}
2004
whose real part is the @i{object} and
2005
whose imaginary part is the result of @i{coercing} an @i{integer} zero
2006
to the @i{type} of the @i{object} (using @b{coerce}).
2007
(If the real part is a @i{rational}, however,
2008
then the result must be represented as a @i{rational} rather
2009
than a @i{complex}; see @ref{Rule of Canonical Representation for Complex Rationals}.
2010
So, for example, @t{(coerce 3 'complex)} is permissible,
2011
but will return @t{3}, which is not a @i{complex}.)
2014
If the @i{result-type} is any of @b{float},
2019
and the @i{object} is a
2023
then the @i{result} is a @i{float} of @i{type} @i{result-type}
2024
which is equal in sign and magnitude to the @i{object} to whatever degree of
2025
representational precision is permitted by that @i{float} representation.
2026
(If the @i{result-type} is @b{float}
2027
and @i{object} is not already a @i{float},
2028
then the @i{result} is a @i{single float}.)
2031
If the @i{result-type} is @b{function},
2032
and @i{object} is any
2037
but that is globally defined neither as a @i{macro name} nor as a @i{special operator},
2038
then the @i{result} is the @i{functional value} of @i{object}.
2040
If the @i{result-type} is @b{function},
2041
and @i{object} is a @i{lambda expression},
2042
then the @i{result} is a @i{closure} of @i{object}
2043
in the @i{null lexical environment}.
2046
Any @i{object} can be @i{coerced} to an @i{object} of @i{type} @b{t}.
2047
In this case, the @i{object} is simply returned.
2051
@subsubheading Examples::
2054
(coerce '(a b c) 'vector) @result{} #(A B C)
2055
(coerce 'a 'character) @result{} #\A
2056
(coerce 4.56 'complex) @result{} #C(4.56 0.0)
2057
(coerce 4.5s0 'complex) @result{} #C(4.5s0 0.0s0)
2058
(coerce 7/2 'complex) @result{} 7/2
2059
(coerce 0 'short-float) @result{} 0.0s0
2060
(coerce 3.5L0 'float) @result{} 3.5L0
2061
(coerce 7/2 'float) @result{} 3.5
2062
(coerce (cons 1 2) t) @result{} (1 . 2)
2065
All the following @i{forms} should signal an error:
2068
(coerce '(a b c) '(vector * 4))
2069
(coerce #(a b c) '(vector * 4))
2070
(coerce '(a b c) '(vector * 2))
2071
(coerce #(a b c) '(vector * 2))
2072
(coerce "foo" '(string 2))
2073
(coerce #(#\a #\b #\c) '(string 2))
2074
(coerce '(0 1) '(simple-bit-vector 3))
2077
@subsubheading Exceptional Situations::
2079
If a coercion is not possible, an error of @i{type} @b{type-error} is signaled.
2081
@t{(coerce x 'nil)} always signals an error of @i{type} @b{type-error}.
2084
of @i{type} @b{error} is signaled
2085
if the @i{result-type} is @b{function} but
2086
@i{object} is a @i{symbol} that is not @i{fbound} or
2087
if the @i{symbol} names a @i{macro} or a @i{special operator}.
2089
An error of @i{type} @b{type-error} should be signaled if @i{result-type}
2090
specifies the number of elements and @i{object} is of a different length.
2092
@subsubheading See Also::
2094
@ref{rational (Function)}
2102
@subsubheading Notes::
2104
Coercions from @i{floats} to @i{rationals}
2105
and from @i{ratios} to @i{integers}
2106
are not provided because of rounding problems.
2109
(coerce x 't) @equiv{} (identity x) @equiv{} x
2112
@node deftype, subtypep, coerce, Types and Classes Dictionary
2113
@subsection deftype [Macro]
2115
@code{deftype} @i{name lambda-list @r{[[@{@i{declaration}@}* | @i{documentation}]]} @{@i{form}@}*} @result{} @i{name}
2117
@subsubheading Arguments and Values::
2119
@i{name}---a @i{symbol}.
2121
@i{lambda-list}---a @i{deftype lambda list}.
2123
@i{declaration}---a @b{declare} @i{expression}; not evaluated.
2125
@i{documentation}---a @i{string}; not evaluated.
2127
@i{form}---a @i{form}.
2129
@subsubheading Description::
2131
@b{deftype} defines a @i{derived type specifier} named @i{name}.
2133
The meaning of the new @i{type specifier} is given in terms of
2134
a function which expands the @i{type specifier} into another
2135
@i{type specifier}, which itself will be expanded if it contains
2136
references to another @i{derived type specifier}.
2138
The newly defined @i{type specifier} may be referenced as a list of
2139
the form @t{(@i{name} @i{arg_1} @i{arg_2} ...)\/}.
2140
The number of arguments must be appropriate to the @i{lambda-list}.
2141
If the new @i{type specifier} takes no arguments,
2142
or if all of its arguments are optional,
2143
the @i{type specifier} may be used as an @i{atomic type specifier}.
2145
The @i{argument} @i{expressions} to the @i{type specifier},
2146
@i{arg_1} ... @i{arg_n}, are not @i{evaluated}.
2147
Instead, these @i{literal objects} become the @i{objects} to which
2148
corresponding @i{parameters} become @i{bound}.
2150
The body of the @b{deftype} @i{form}
2152
(but not the @i{lambda-list})
2156
implicitly enclosed in a @i{block} named @i{name},
2158
and is evaluated as an @i{implicit progn},
2159
returning a new @i{type specifier}.
2161
The @i{lexical environment} of the body is the one which was current
2162
at the time the @b{deftype} form was evaluated, augmented by the
2163
@i{variables} in the @i{lambda-list}.
2165
Recursive expansion of the @i{type specifier} returned as the expansion
2166
must terminate, including the expansion of @i{type specifiers} which
2167
are nested within the expansion.
2169
The consequences are undefined if the result of fully expanding a
2170
@i{type specifier} contains any circular structure, except within
2171
the @i{objects} referred to by @b{member} and @b{eql}
2172
@i{type specifiers}.
2174
@i{Documentation} is attached to @i{name} as a @i{documentation string}
2177
If a @b{deftype} @i{form} appears as a @i{top level form},
2178
the @i{compiler} must ensure that the @i{name} is recognized
2179
in subsequent @i{type} declarations.
2180
The @i{programmer} must ensure that the body of a @b{deftype} form
2181
can be @i{evaluated} at compile time if the @i{name} is
2182
referenced in subsequent @i{type} declarations.
2183
If the expansion of a @i{type specifier} is not defined fully at compile time
2184
(perhaps because it expands into an unknown @i{type specifier} or a
2185
@b{satisfies} of a named @i{function} that isn't defined in the
2186
compile-time environment), an @i{implementation} may ignore any references to
2187
this @i{type} in declarations and/or signal a warning.
2189
@subsubheading Examples::
2191
(defun equidimensional (a)
2192
(or (< (array-rank a) 2)
2193
(apply #'= (array-dimensions a)))) @result{} EQUIDIMENSIONAL
2194
(deftype square-matrix (&optional type size)
2195
`(and (array ,type (,size ,size))
2196
(satisfies equidimensional))) @result{} SQUARE-MATRIX
2199
@subsubheading See Also::
2206
@ref{Type Specifiers},
2207
@ref{Syntactic Interaction of Documentation Strings and Declarations}
2209
@node subtypep, type-of, deftype, Types and Classes Dictionary
2210
@subsection subtypep [Function]
2212
@code{subtypep} @i{type-1 type-2 @r{&optional} environment} @result{} @i{subtype-p, valid-p}
2214
@subsubheading Arguments and Values::
2216
@i{type-1}---a @i{type specifier}.
2218
@i{type-2}---a @i{type specifier}.
2220
@i{environment}---an @i{environment} @i{object}.
2221
The default is @b{nil}, denoting the @i{null lexical environment}
2222
and the current @i{global environment}.
2224
@i{subtype-p}---a @i{generalized boolean}.
2226
@i{valid-p}---a @i{generalized boolean}.
2228
@subsubheading Description::
2230
If @i{type-1} is a @i{recognizable subtype} of @i{type-2},
2231
the first @i{value} is @i{true}.
2232
Otherwise, the first @i{value} is @i{false},
2233
indicating that either
2234
@i{type-1} is not a @i{subtype} of @i{type-2}, or else
2235
@i{type-1} is a @i{subtype} of @i{type-2}
2236
but is not a @i{recognizable subtype}.
2238
A second @i{value} is also returned indicating the `certainty' of
2239
the first @i{value}. If this value is @i{true}, then the first
2240
value is an accurate indication of the @i{subtype} relationship.
2241
(The second @i{value} is always @i{true} when the first @i{value}
2244
Figure 4--9 summarizes the possible combinations of @i{values}
2250
@w{ Value 1 Value 2 Meaning }
2251
@w{ @i{true} @i{true} @i{type-1} is definitely a @i{subtype} of @i{type-2}. }
2252
@w{ @i{false} @i{true} @i{type-1} is definitely not a @i{subtype} of @i{type-2}. }
2253
@w{ @i{false} @i{false} @b{subtypep} could not determine the relationship, }
2254
@w{ so @i{type-1} might or might not be a @i{subtype} of @i{type-2}. }
2257
@w{ Figure 4--9: Result possibilities for subtypep }
2262
@b{subtypep} is permitted to return the
2263
@i{values} @i{false} and @i{false} only when at least
2264
one argument involves one of these @i{type specifiers}:
2267
the list form of @b{function},
2274
(A @i{type specifier} `involves' such a @i{symbol} if,
2275
after being @i{type expanded},
2276
it contains that @i{symbol} in a position that would call for
2277
its meaning as a @i{type specifier} to be used.)
2278
One consequence of this is that if neither @i{type-1} nor @i{type-2}
2279
involves any of these @i{type specifiers}, then @b{subtypep} is obliged
2280
to determine the relationship accurately. In particular, @b{subtypep}
2281
returns the @i{values} @i{true} and @i{true}
2282
if the arguments are @b{equal} and do not involve
2283
any of these @i{type specifiers}.
2285
@b{subtypep} never returns a second value of @b{nil} when both
2286
@i{type-1} and @i{type-2} involve only
2287
the names in @i{Figure~4--2}, or
2288
names of @i{types} defined by @b{defstruct},
2289
@b{define-condition},
2291
@i{derived types} that expand into only those names.
2292
While @i{type specifiers} listed in @i{Figure~4--2} and
2293
names of @b{defclass} and @b{defstruct} can in some cases be
2294
implemented as @i{derived types}, @b{subtypep} regards them as primitive.
2296
The relationships between @i{types} reflected by @b{subtypep}
2297
are those specific to the particular implementation. For example, if
2298
an implementation supports only a single type of floating-point numbers,
2299
in that implementation @t{(subtypep 'float 'long-float)}
2300
returns the @i{values} @i{true} and @i{true}
2301
(since the two @i{types} are identical).
2303
For all @i{T1} and @i{T2} other than @t{*},
2304
@t{(array @i{T1})} and @t{(array @i{T2})}
2305
are two different @i{type specifiers} that always refer to the same sets of
2306
things if and only if they refer to @i{arrays}
2307
of exactly the same specialized representation, @i{i.e.}, if @t{(upgraded-array-element-type '@i{T1})} and
2308
@t{(upgraded-array-element-type '@i{T2})}
2309
return two different @i{type specifiers} that always refer to the same sets of
2311
This is another way of saying that
2312
@t{`(array @i{type-specifier})}
2314
@t{`(array ,(upgraded-array-element-type '@i{type-specifier}))}
2316
set of specialized @i{array} representations.
2317
For all @i{T1} and @i{T2} other than @t{*},
2320
and @t{(array @i{T2})} is the empty set
2321
if and only if they refer to @i{arrays} of different,
2322
distinct specialized representations.
2327
(subtypep '(array T1) '(array T2)) @result{} @i{true}
2333
(upgraded-array-element-type 'T1) and
2334
(upgraded-array-element-type 'T2)
2337
return two different @i{type specifiers} that always refer to the same sets of
2340
For all type-specifiers @i{T1} and @i{T2} other than @t{*},
2343
(subtypep '(complex T1) '(complex T2)) @result{} @i{true}, @i{true}
2350
@t{T1} is a @i{subtype} of @t{T2}, or
2352
@t{(upgraded-complex-part-type '@i{T1})} and
2353
@t{(upgraded-complex-part-type '@i{T2})}
2354
return two different @i{type specifiers} that always refer to the
2355
same sets of @i{objects}; in this case,
2356
@t{(complex @i{T1})} and
2357
@t{(complex @i{T2})} both refer to the
2358
same specialized representation.
2361
The @i{values} are @i{false} and @i{true} otherwise.
2366
(subtypep '(complex single-float) '(complex float))
2369
must return @i{true} in all implementations, but
2372
(subtypep '(array single-float) '(array float))
2375
returns @i{true} only in implementations that do not have a specialized @i{array}
2376
representation for @i{single floats} distinct from that for other @i{floats}.
2378
@subsubheading Examples::
2381
(subtypep 'compiled-function 'function) @result{} @i{true}, @i{true}
2382
(subtypep 'null 'list) @result{} @i{true}, @i{true}
2383
(subtypep 'null 'symbol) @result{} @i{true}, @i{true}
2384
(subtypep 'integer 'string) @result{} @i{false}, @i{true}
2385
(subtypep '(satisfies dummy) nil) @result{} @i{false}, @i{implementation-dependent}
2386
(subtypep '(integer 1 3) '(integer 1 4)) @result{} @i{true}, @i{true}
2387
(subtypep '(integer (0) (0)) 'nil) @result{} @i{true}, @i{true}
2388
(subtypep 'nil '(integer (0) (0))) @result{} @i{true}, @i{true}
2389
(subtypep '(integer (0) (0)) '(member)) @result{} @i{true}, @i{true} ;or @i{false}, @i{false}
2390
(subtypep '(member) 'nil) @result{} @i{true}, @i{true} ;or @i{false}, @i{false}
2391
(subtypep 'nil '(member)) @result{} @i{true}, @i{true} ;or @i{false}, @i{false}
2394
Let @t{<aet-x>} and @t{<aet-y>} be two distinct @i{type specifiers} that
2395
do not always refer to the same sets of
2397
in a given implementation, but for which
2398
@b{make-array}, will return an
2399
@i{object} of the same @i{array} @i{type}.
2404
(subtypep (array-element-type (make-array 0 :element-type '<aet-x>))
2405
(array-element-type (make-array 0 :element-type '<aet-y>)))
2406
@result{} @i{true}, @i{true}
2408
(subtypep (array-element-type (make-array 0 :element-type '<aet-y>))
2409
(array-element-type (make-array 0 :element-type '<aet-x>)))
2410
@result{} @i{true}, @i{true}
2413
If @t{(array <aet-x>)}
2414
and @t{(array <aet-y>)} are different names for
2415
exactly the same set of @i{objects},
2416
these names should always refer to the same sets of
2418
That implies that the following set of tests are also true:
2421
(subtypep '(array <aet-x>) '(array <aet-y>)) @result{} @i{true}, @i{true}
2422
(subtypep '(array <aet-y>) '(array <aet-x>)) @result{} @i{true}, @i{true}
2425
@subsubheading See Also::
2429
@subsubheading Notes::
2431
The small differences between the @b{subtypep} specification for
2432
the @b{array} and @b{complex} types are necessary because there
2433
is no creation function for @i{complexes} which allows
2434
the specification of the resultant part type independently of
2435
the actual types of the parts. Thus in the case of the @i{type} @b{complex},
2436
the actual type of the parts is referred to, although a @i{number}
2437
can be a member of more than one @i{type}.
2438
For example, @t{17} is of @i{type} @t{(mod 18)}
2439
as well as @i{type} @t{(mod 256)} and @i{type} @b{integer};
2440
and @t{2.3f5} is of @i{type} @b{single-float}
2441
as well as @i{type} @b{float}.
2443
@node type-of, typep, subtypep, Types and Classes Dictionary
2444
@subsection type-of [Function]
2446
@code{type-of} @i{object} @result{} @i{typespec}
2448
@subsubheading Arguments and Values::
2450
@i{object}---an @i{object}.
2452
@i{typespec}---a @i{type specifier}.
2454
@subsubheading Description::
2456
Returns a @i{type specifier}, @i{typespec}, for a @i{type}
2457
that has the @i{object} as an @i{element}.
2458
The @i{typespec} satisfies the following:
2463
For any @i{object} that is an @i{element} of some @i{built-in type}:
2468
the @i{type} returned is a @i{recognizable subtype} of that @i{built-in type}.
2471
the @i{type} returned does not involve
2482
For all @i{objects}, @t{(typep @i{object} (type-of @i{object}))}
2484
Implicit in this is that @i{type specifiers} which are
2485
not valid for use with @b{typep}, such as the @i{list} form of the
2486
@b{function} @i{type specifier}, are never returned by @b{type-of}.
2489
The @i{type} returned by @b{type-of} is always a @i{recognizable subtype}
2490
of the @i{class} returned by @b{class-of}. That is,
2493
(subtypep (type-of @i{object}) (class-of @i{object})) @result{} @i{true}, @i{true}
2497
For @i{objects} of metaclass @b{structure-class} or @b{standard-class},
2499
and for @i{conditions},
2501
@b{type-of} returns the @i{proper name} of the @i{class} returned
2502
by @b{class-of} if it has a @i{proper name},
2503
and otherwise returns the @i{class} itself.
2504
In particular, for @i{objects} created by the constructor function
2505
of a structure defined with @b{defstruct} without a @t{:type} option,
2506
@b{type-of} returns the structure name; and for @i{objects} created
2507
by @b{make-condition}, the @i{typespec} is the @i{name} of the
2508
@i{condition} @i{type}.
2511
For each of the @i{types}
2516
of which the @i{object} is an @i{element},
2517
the @i{typespec} is a @i{recognizable subtype} of that @i{type}.
2521
@subsubheading Examples::
2527
(type-of 'a) @result{} SYMBOL
2530
@i{OR}@result{} (CONS FIXNUM FIXNUM)
2533
@i{OR}@result{} (COMPLEX INTEGER)
2534
(defstruct temp-struct x y z) @result{} TEMP-STRUCT
2535
(type-of (make-temp-struct)) @result{} TEMP-STRUCT
2538
@i{OR}@result{} (STRING 3)
2539
(subtypep (type-of "abc") 'string) @result{} @i{true}, @i{true}
2540
(type-of (expt 2 40))
2542
@i{OR}@result{} INTEGER
2543
@i{OR}@result{} (INTEGER 1099511627776 1099511627776)
2544
@i{OR}@result{} SYSTEM::TWO-WORD-BIGNUM
2545
@i{OR}@result{} FIXNUM
2546
(subtypep (type-of 112312) 'integer) @result{} @i{true}, @i{true}
2547
(defvar *foo* (make-array 5 :element-type t)) @result{} *FOO*
2548
(class-name (class-of *foo*)) @result{} VECTOR
2551
@i{OR}@result{} (VECTOR T 5)
2554
@subsubheading See Also::
2556
@ref{array-element-type}
2568
@subsubheading Notes::
2570
Implementors are encouraged to arrange for @b{type-of} to return
2574
@node typep, type-error, type-of, Types and Classes Dictionary
2575
@subsection typep [Function]
2577
@code{typep} @i{object type-specifier @r{&optional} environment} @result{} @i{generalized-boolean}
2579
@subsubheading Arguments and Values::
2581
@i{object}---an @i{object}.
2583
@i{type-specifier}---any @i{type specifier} except
2585
@b{values}, or a @i{type specifier} list
2586
whose first element is either @b{function} or @b{values}.
2588
@i{environment}---an @i{environment} @i{object}.
2589
The default is @b{nil}, denoting the @i{null lexical environment}
2590
and the and current @i{global environment}.
2592
@i{generalized-boolean}---a @i{generalized boolean}.
2594
@subsubheading Description::
2596
Returns @i{true} if @i{object} is of the @i{type} specified by @i{type-specifier};
2597
otherwise, returns @i{false}.
2599
A @i{type-specifier} of the form @t{(satisfies fn)}
2600
is handled by applying the function @t{fn} to @i{object}.
2602
@t{(typep @i{object} '(array @i{type-specifier}))},
2603
where @i{type-specifier} is not @t{*},
2604
returns @i{true} if and only if @i{object} is an @i{array}
2605
that could be the result
2606
of supplying @i{type-specifier}
2607
as the @t{:element-type} argument to @b{make-array}.
2608
@t{(array *)} refers to all @i{arrays}
2609
regardless of element type, while @t{(array @i{type-specifier})}
2610
refers only to those @i{arrays}
2611
that can result from giving @i{type-specifier} as the
2612
@t{:element-type} argument to @b{make-array}.
2613
A similar interpretation applies to @t{(simple-array @i{type-specifier})}
2614
and @t{(vector @i{type-specifier})}.
2615
See @ref{Array Upgrading}.
2617
@t{(typep @i{object} '(complex @i{type-specifier}))}
2618
returns @i{true} for all @i{complex} numbers that can result from
2619
giving @i{numbers} of type @i{type-specifier}
2620
to the @i{function} @b{complex}, plus all other @i{complex} numbers
2621
of the same specialized representation.
2622
Both the real and the imaginary parts of any such
2623
@i{complex} number must satisfy:
2626
(typep realpart 'type-specifier)
2627
(typep imagpart 'type-specifier)
2630
See the @i{function} @b{upgraded-complex-part-type}.
2632
@subsubheading Examples::
2635
(typep 12 'integer) @result{} @i{true}
2636
(typep (1+ most-positive-fixnum) 'fixnum) @result{} @i{false}
2637
(typep nil t) @result{} @i{true}
2638
(typep nil nil) @result{} @i{false}
2639
(typep 1 '(mod 2)) @result{} @i{true}
2640
(typep #c(1 1) '(complex (eql 1))) @result{} @i{true}
2641
;; To understand this next example, you might need to refer to
2642
;; @ref{Rule of Canonical Representation for Complex Rationals}.
2643
(typep #c(0 0) '(complex (eql 0))) @result{} @i{false}
2646
Let @t{A_x} and @t{A_y} be two @i{type specifiers} that
2647
denote different @i{types}, but for which
2650
(upgraded-array-element-type 'A_x)
2656
(upgraded-array-element-type 'A_y)
2659
denote the same @i{type}. Notice that
2662
(typep (make-array 0 :element-type 'A_x) '(array A_x)) @result{} @i{true}
2663
(typep (make-array 0 :element-type 'A_y) '(array A_y)) @result{} @i{true}
2664
(typep (make-array 0 :element-type 'A_x) '(array A_y)) @result{} @i{true}
2665
(typep (make-array 0 :element-type 'A_y) '(array A_x)) @result{} @i{true}
2668
@subsubheading Exceptional Situations::
2670
An error of @i{type} @b{error} is signaled if @i{type-specifier} is @t{values},
2671
or a @i{type specifier} list whose first element is either
2672
@b{function} or @b{values}.
2674
The consequences are undefined if
2675
the @i{type-specifier} is not a @i{type specifier}.
2677
@subsubheading See Also::
2681
@ref{upgraded-array-element-type}
2683
@ref{upgraded-complex-part-type}
2685
@ref{Type Specifiers}
2687
@subsubheading Notes::
2689
@i{Implementations} are encouraged to recognize and optimize the case of
2690
@t{(typep @i{x} (the class @i{y}))},
2691
since it does not involve any need for expansion
2692
of @b{deftype} information at runtime.
2698
@node type-error, type-error-datum, typep, Types and Classes Dictionary
2699
@subsection type-error [Condition Type]
2701
@subsubheading Class Precedence List::
2704
@b{serious-condition},
2708
@subsubheading Description::
2710
The @i{type} @b{type-error} represents a situation in which an @i{object} is not
2711
of the expected type. The ``offending datum'' and ``expected type'' are initialized
2712
by the initialization arguments named @t{:datum} and @t{:expected-type} to @b{make-condition},
2713
and are @i{accessed} by the functions
2714
@b{type-error-datum} and @b{type-error-expected-type}.
2716
@subsubheading See Also::
2718
@ref{type-error-datum}
2719
, @b{type-error-expected-type}
2721
@node type-error-datum, simple-type-error, type-error, Types and Classes Dictionary
2722
@subsection type-error-datum, type-error-expected-type [Function]
2724
@code{type-error-datum} @i{condition} @result{} @i{datum}
2726
@code{type-error-expected-type} @i{condition} @result{} @i{expected-type}
2728
@subsubheading Arguments and Values::
2730
@i{condition}---a @i{condition} of @i{type} @b{type-error}.
2732
@i{datum}---an @i{object}.
2734
@i{expected-type}---a @i{type specifier}.
2736
@subsubheading Description::
2738
@b{type-error-datum} returns the offending datum in the @i{situation}
2739
represented by the @i{condition}.
2741
@b{type-error-expected-type} returns the expected type of the
2742
offending datum in the @i{situation} represented by the @i{condition}.
2744
@subsubheading Examples::
2747
(defun fix-digits (condition)
2748
(check-type condition type-error)
2749
(let* ((digits '(zero one two three four
2750
five six seven eight nine))
2751
(val (position (type-error-datum condition) digits)))
2752
(if (and val (subtypep 'fixnum (type-error-expected-type condition)))
2756
(handler-bind ((type-error #'fix-digits))
2757
(check-type x number)
2764
@subsubheading See Also::
2769
@node simple-type-error, , type-error-datum, Types and Classes Dictionary
2770
@subsection simple-type-error [Condition Type]
2772
@subsubheading Class Precedence List::
2774
@b{simple-type-error},
2775
@b{simple-condition},
2778
@b{serious-condition},
2782
@subsubheading Description::
2784
@i{Conditions} of @i{type} @b{simple-type-error}
2785
are like @i{conditions} of @i{type} @b{type-error},
2786
except that they provide an alternate mechanism for specifying
2787
how the @i{condition} is to be @i{reported};
2788
see the @i{type} @b{simple-condition}.
2790
@subsubheading See Also::
2792
@b{simple-condition},
2794
@ref{simple-condition-format-control}
2797
@b{simple-condition-format-arguments},
2798
@ref{type-error-datum}
2800
@b{type-error-expected-type}
2802
@c end of including dict-types
2804
@c %**end of chapter
added
removed
info/chap-4.texi
