3
@node Structures, Conditions, Objects, Top
7
* Structures Dictionary::
10
@node Structures Dictionary, , Structures, Structures
11
@section Structures Dictionary
13
@c including dict-structures
20
@node defstruct, copy-structure, Structures Dictionary, Structures Dictionary
21
@subsection defstruct [Macro]
23
@code{defstruct} @i{name-and-options @r{[}documentation@r{]} @{!@i{slot-description}@}*}@*
24
@result{} @i{structure-name}
26
@w{@i{name-and-options} ::=structure-name | @r{(}structure-name [[!@i{options}]]@r{)}}
28
@w{@i{options} ::=!@i{conc-name-option} |}
29
@w{ @{!@i{constructor-option}@}* |}
30
@w{ !@i{copier-option} |}
31
@w{ !@i{include-option} |}
32
@w{ !@i{initial-offset-option} |}
33
@w{ !@i{named-option} |}
34
@w{ !@i{predicate-option} |}
35
@w{ !@i{printer-option} |}
38
@w{@i{conc-name-option} ::=@t{:conc-name} | @r{(}@t{:conc-name}@r{)} | @r{(}@t{:conc-name} @i{conc-name}@r{)}}
40
@w{@i{constructor-option} ::=@t{:constructor} |}
41
@w{ @r{(}@t{:constructor}@r{)} |}
42
@w{ @r{(}@t{:constructor} @i{constructor-name}@r{)} |}
43
@w{ @r{(}@t{:constructor} @i{constructor-name} @i{constructor-arglist}@r{)}}
45
@w{@i{copier-option} ::=@t{:copier} | @r{(}@t{:copier}@r{)} | @r{(}@t{:copier} @i{copier-name}@r{)}}
47
@w{@i{predicate-option} ::=@t{:predicate} | @r{(}@t{:predicate}@r{)} | @r{(}@t{:predicate} @i{predicate-name}@r{)}}
49
@w{@i{include-option} ::=@r{(}@t{:include} @i{included-structure-name} @{!@i{slot-description}@}*@r{)}}
51
@w{@i{printer-option} ::=!@i{print-object-option} | !@i{print-function-option}}
53
@w{@i{print-object-option} ::=@r{(}@t{:print-object} @i{printer-name}@r{)} | @r{(}@t{:print-object}@r{)}}
55
@w{@i{print-function-option} ::=@r{(}@t{:print-function} @i{printer-name}@r{)} | @r{(}@t{:print-function}@r{)}}
57
@w{@i{type-option} ::=@r{(}@t{:type} @i{type}@r{)}}
59
@w{@i{named-option} ::=@t{:named}}
61
@w{@i{initial-offset-option} ::=@r{(}@t{:initial-offset} @i{initial-offset}@r{)}}
63
@w{@i{slot-description} ::=@i{slot-name} | }
64
@w{ @r{(}@i{slot-name} @r{[}@i{slot-initform} [[!@i{slot-option}]]@r{]}@r{)}}
66
@w{@i{slot-option} ::=@t{:type} @i{slot-type} | }
67
@w{ @t{:read-only} @i{slot-read-only-p}}
69
@subsubheading Arguments and Values::
71
@i{conc-name}---a @i{string designator}.
73
@i{constructor-arglist}---a @i{boa lambda list}.
75
@i{constructor-name}---a @i{symbol}.
77
@i{copier-name}---a @i{symbol}.
79
@i{included-structure-name}---an already-defined @i{structure name}.
81
Note that a @i{derived type} is not permissible,
82
even if it would expand into a @i{structure name}.
84
@i{initial-offset}---a non-negative @i{integer}.
86
@i{predicate-name}---a @i{symbol}.
88
@i{printer-name}---a @i{function name} or a @i{lambda expression}.
90
@i{slot-name}---a @i{symbol}.
92
@i{slot-initform}---a @i{form}.
94
@i{slot-read-only-p}---a @i{generalized boolean}.
96
@i{structure-name}---a @i{symbol}.
98
@i{type}---one of the @i{type specifiers}
101
or @t{(vector @i{size})},
102
or some other @i{type specifier} defined
103
by the @i{implementation} to be appropriate.
105
@i{documentation}---a @i{string}; not evaluated.
107
@subsubheading Description::
109
@b{defstruct} defines a structured @i{type}, named @i{structure-type},
110
with named slots as specified by the @i{slot-options}.
112
@b{defstruct} defines @i{readers} for the slots and
113
arranges for @b{setf} to work properly on such
114
@i{reader} functions.
115
Also, unless overridden, it
116
defines a predicate named @t{@i{name}-p},
117
defines a constructor function named @t{make-@i{constructor-name}},
118
and defines a copier function named @t{copy-@i{constructor-name}}.
119
All names of automatically created functions might automatically
120
be declared @b{inline} (at the discretion of the @i{implementation}).
122
If @i{documentation} is supplied, it is attached to @i{structure-name}
123
as a @i{documentation string} of kind @b{structure},
125
and unless @t{:type} is used, the @i{documentation} is also attached
126
to @i{structure-name} as a @i{documentation string} of kind
127
@b{type} and as a @i{documentation string} to the @i{class} @i{object}
128
for the @i{class} named @i{structure-name}.
130
@b{defstruct} defines a constructor function that is used to
131
create instances of the structure created by @b{defstruct}.
132
The default name is @t{make-@i{structure-name}}.
133
A different name can be supplied
134
by giving the name as the argument to the @i{constructor} option.
135
@b{nil} indicates that no constructor function will be created.
137
After a new structure type has been defined, instances of that type
138
normally can be created by using the constructor function for the
140
A call to a constructor function is of the following form:
142
@w{ (@t{constructor-function-name}}@*
143
@w{ @t{slot-keyword-1 form-1}}@*
144
@w{ @t{slot-keyword-2 form-2}}@*
147
The arguments to the constructor function are all keyword arguments. Each
148
slot keyword argument must be
149
a keyword whose name corresponds to the name of a structure slot.
150
All the @i{keywords} and @i{forms}
152
If a slot is not initialized in this way,
153
it is initialized by evaluating @i{slot-initform} in the slot description
155
at the time the constructor function is called.
157
If no @i{slot-initform} is supplied,
158
the consequences are undefined if an attempt is later made to read the slot's value
159
before a value is explicitly assigned.
161
Each @i{slot-initform} supplied for a @b{defstruct} component,
162
when used by the constructor function for an otherwise unsupplied
163
component, is re-evaluated on every call to the
164
constructor function.
166
The @i{slot-initform} is not evaluated
167
unless it is needed in the creation of a particular structure
168
instance. If it is never needed, there can be no type-mismatch
169
error, even if the @i{type}
170
of the slot is specified; no warning
171
should be issued in this case.
173
For example, in the following sequence, only the last call is an error.
176
(defstruct person (name 007 :type string))
177
(make-person :name "James")
181
It is as if the @i{slot-initforms} were
182
used as @i{initialization forms} for the @i{keyword parameters}
183
of the constructor function.
185
The @i{symbols} which name the slots must not be used by the
186
@i{implementation} as the @i{names} for the @i{lambda variables}
187
in the constructor function, since one or more of those @i{symbols}
188
might have been proclaimed @b{special} or might be defined as
189
the name of a @i{constant variable}.
190
The slot default init forms are evaluated
191
in the @i{lexical environment} in which the @b{defstruct} form itself appears and
192
in the @i{dynamic environment} in which the call to the constructor function appears.
194
For example, if the form @t{(gensym)} were used as an initialization form,
195
either in the constructor-function call or as the default initialization form
196
in @b{defstruct}, then every call to the constructor function would call
197
@b{gensym} once to generate a new @i{symbol}.
199
Each @i{slot-description} in @b{defstruct} can specify zero or more
202
A @i{slot-option} consists of a pair of a keyword and a value
203
(which is not a form to be evaluated, but the value itself). For example:
207
(x-position 0.0 :type short-float)
208
(y-position 0.0 :type short-float)
209
(x-velocity 0.0 :type short-float)
210
(y-velocity 0.0 :type short-float)
211
(mass *default-ship-mass* :type short-float :read-only t))
214
This specifies that each slot always contains a @i{short float},
215
and that the last slot cannot be altered once a ship is constructed.
217
The available slot-options are:
220
@item @t{:type} @i{type}
221
This specifies that the contents of the
222
slot is always of type @i{type}. This is entirely
223
analogous to the declaration of a variable or function; it
224
effectively declares the result type of the @i{reader} function.
225
It is @i{implementation-dependent} whether the @i{type} is checked
226
when initializing a slot
227
or when assigning to it.
228
@i{Type} is not evaluated; it must be a valid @i{type specifier}.
230
@item @t{:read-only} @i{x}
231
When @i{x} is @i{true},
232
this specifies that this slot cannot be
233
altered; it will always contain the value supplied at construction time.
234
@b{setf} will not accept the @i{reader} function for this slot.
235
If @i{x} is @i{false}, this slot-option has no effect.
236
@i{X} is not evaluated.
238
When this option is @i{false} or unsupplied,
239
it is @i{implementation-dependent} whether the ability to @i{write}
240
the slot is implemented by a @i{setf function} or a @i{setf expander}.
244
The following keyword options are available for use with @b{defstruct}.
245
A @b{defstruct} option can be either a keyword or a @i{list}
246
of a keyword and arguments for that keyword;
247
specifying the keyword by itself is equivalent to specifying a list consisting of
248
the keyword and no arguments.
249
The syntax for @b{defstruct} options differs from the pair syntax
250
used for slot-options. No part of any of these options is evaluated.
254
This provides for automatic prefixing of names of @i{reader} (or @i{access}) functions.
255
The default behavior is to begin the names of all the @i{reader} functions of
256
a structure with the name of the structure followed by a hyphen.
258
@t{:conc-name} supplies an alternate
259
prefix to be used. If a hyphen is to be used as a separator,
260
it must be supplied as part of the prefix.
261
If @t{:conc-name} is @b{nil} or no argument is supplied,
262
then no prefix is used;
263
then the names of the @i{reader} functions
264
are the same as the slot names.
265
If a @i{non-nil} prefix is given,
266
the name of the @i{reader} @i{function} for each slot is constructed by
267
concatenating that prefix and the name of the slot, and interning the resulting
268
@i{symbol} in the @i{package} that is current at the time the
269
@b{defstruct} form is expanded.
271
Note that no matter what is supplied for @t{:conc-name},
272
slot keywords that match the slot names with no prefix attached are used
273
with a constructor function.
274
The @i{reader} function name is used
275
in conjunction with @b{setf}. Here is an example:
278
(defstruct (door (:conc-name dr-)) knob-color width material) @result{} DOOR
279
(setq my-door (make-door :knob-color 'red :width 5.0))
280
@result{} #S(DOOR :KNOB-COLOR RED :WIDTH 5.0 :MATERIAL NIL)
281
(dr-width my-door) @result{} 5.0
282
(setf (dr-width my-door) 43.7) @result{} 43.7
283
(dr-width my-door) @result{} 43.7
286
Whether or not the @t{:conc-name} option is explicitly supplied,
287
the following rule governs name conflicts of generated @i{reader}
288
(or @i{accessor}) names:
289
For any @i{structure} @i{type} S_1
290
having a @i{reader} function named R for a slot named X_1
291
that is inherited by another @i{structure} @i{type} S_2
292
that would have a @i{reader} function with the same name R for a slot named X_2,
293
no definition for R is generated by the definition of S_2;
294
instead, the definition of R is inherited from the definition of S_1.
295
(In such a case, if X_1 and X_2 are different slots,
296
the @i{implementation} might signal a style warning.)
298
@item @t{:constructor}
299
This option takes zero, one, or two arguments.
300
If at least one argument is supplied and the first argument is not @b{nil}, then
301
that argument is a @i{symbol} which specifies the name of the
302
constructor function. If the argument is not supplied (or if the option itself is not
303
supplied), the name of the constructor is produced by concatenating the
304
string @t{"MAKE-"} and the name of the structure, interning the name
305
in whatever @i{package} is current at the time @b{defstruct}
306
is expanded. If the argument is provided and is @b{nil},
307
no constructor function is defined.
309
If @t{:constructor} is given as
310
@t{(:constructor @i{name} @i{arglist})},
311
then instead of making a keyword
312
driven constructor function, @b{defstruct}
313
defines a ``positional'' constructor function,
314
taking arguments whose meaning is determined by the argument's position
315
and possibly by keywords.
316
@i{Arglist} is used to describe what the arguments to the
317
constructor will be. In the simplest case something like
318
@t{(:constructor make-foo (a b c))} defines @t{make-foo} to be
320
constructor function whose arguments are used to initialize the
321
slots named @t{a}, @t{b}, and @t{c}.
323
Because a constructor of this type operates ``By Order of Arguments,''
324
it is sometimes known as a ``boa constructor.''
326
For information on how the @i{arglist} for a ``boa constructor'' is
327
processed, see @ref{Boa Lambda Lists}.
329
It is permissible to use the
330
@t{:constructor} option more than once, so that you can define several
331
different constructor functions, each taking different parameters.
333
[Reviewer Note by Barmar: What about (:constructor) and (:constructor nil).
334
Should we worry about it?]
336
@b{defstruct} creates the default-named keyword constructor function
337
only if no explicit @t{:constructor} options are specified, or if the
338
@t{:constructor} option is specified without a @i{name} argument.
340
@t{(:constructor nil)} is meaningful only when there are no other
341
@t{:constructor} options specified. It prevents @b{defstruct}
342
from generating any constructors at all.
344
Otherwise, @b{defstruct} creates a constructor function corresponding
345
to each supplied @t{:constructor} option. It is permissible to specify
346
multiple keyword constructor functions as well as multiple
347
``boa constructors''.
350
This option takes one argument, a @i{symbol},
351
which specifies the name of the copier
352
function. If the argument is not provided or if the option itself is not
353
provided, the name of the copier is produced by concatenating the
354
string @t{"COPY-"} and the name of the structure, interning the name
355
in whatever @i{package} is current at the time @b{defstruct}
357
If the argument is provided and is @b{nil}, no copier function is defined.
359
The automatically defined copier function is a function of
362
which must be of the structure type being defined.
364
The copier function creates a @i{fresh}
365
structure that has the same @i{type} as its @i{argument},
366
and that has the @i{same} component values as the original
367
structure; that is, the component values are not copied recursively.
369
If the @b{defstruct} @t{:type} option was not used,
370
the following equivalence applies:
373
(@i{copier-name} x) = (copy-structure (the @i{structure-name} x))
377
This option is used for building a new structure definition as
378
an extension of another structure definition. For example:
381
(defstruct person name age sex)
384
To make a new structure to represent an astronaut
386
attributes of name, age, and sex, and @i{functions}
387
that operate on @t{person} structures, @t{astronaut} is defined
388
with @t{:include} as follows:
391
(defstruct (astronaut (:include person)
394
(favorite-beverage 'tang))
397
@t{:include} causes the structure being defined
398
to have the same slots as the included structure.
399
This is done in such a way
400
that the @i{reader} functions for the included
401
structure also work on the structure being defined.
403
@t{astronaut} therefore has five slots: the three defined in
404
@t{person} and the two defined in @t{astronaut}
405
itself. The @i{reader} functions defined by the @t{person} structure
406
can be applied to instances of the @t{astronaut} structure, and they
408
Moreover, @t{astronaut} has its own @i{reader} functions for
409
components defined by the @t{person} structure.
410
The following examples illustrate the
411
use of @t{astronaut} structures:
414
(setq x (make-astronaut :name 'buzz
418
(person-name x) @result{} BUZZ
419
(astro-name x) @result{} BUZZ
420
(astro-favorite-beverage x) @result{} TANG
424
(reduce #'+ astros :key #'person-age) ; obtains the total of the ages
425
; of the possibly empty
429
The difference between the @i{reader} functions @t{person-name} and @t{astro-name}
430
is that @t{person-name} can be correctly applied to any @t{person},
431
including an @t{astronaut}, while @t{astro-name} can be correctly
432
applied only to an @t{astronaut}. An implementation might
433
check for incorrect use of @i{reader} functions.
435
At most one @t{:include} can be supplied in a single @b{defstruct}.
436
The argument to @t{:include} is required and must be the
437
name of some previously defined structure. If the structure being
438
defined has no @t{:type} option, then the included structure must
439
also have had no @t{:type} option supplied for it.
440
If the structure being defined has a @t{:type} option,
441
then the included structure must have been declared with a @t{:type}
442
option specifying the same representation @i{type}.
444
If no @t{:type} option is involved, then
445
the structure name of the including structure definition
446
becomes the name of a @i{data type}, and therefore
447
a valid @i{type specifier} recognizable by @b{typep}; it becomes
448
a @i{subtype} of the included structure.
449
In the above example,
450
@t{astronaut} is a @i{subtype} of @t{person}; hence
453
(typep (make-astronaut) 'person) @result{} @i{true}
456
indicating that all operations on persons also
459
The structure using @t{:include} can specify default values or
460
slot-options for the included slots different from those the included
461
structure specifies, by giving the @t{:include} option as:
464
(:include @i{included-structure-name} @{@i{slot-description}@}*)
467
Each @i{slot-description} must have a @i{slot-name}
469
as that of some slot in the included structure.
470
If a @i{slot-description} has no @i{slot-initform},
471
then in the new structure the slot has no initial value.
472
Otherwise its initial value form is replaced by
473
the @i{slot-initform} in the @i{slot-description}.
474
A normally writable slot can be made read-only.
475
If a slot is read-only in the included structure, then it
476
must also be so in the including structure.
477
If a @i{type} is supplied for a slot, it must be
480
@i{type} specified in the included structure.
483
default age for an astronaut is @t{45}, then
486
(defstruct (astronaut (:include person (age 45)))
488
(favorite-beverage 'tang))
491
If @t{:include} is used with the @t{:type}
492
option, then the effect is first to skip over as many representation
493
elements as needed to represent the included structure, then to
494
skip over any additional elements supplied by the @t{:initial-offset}
495
option, and then to begin allocation of elements from that point.
499
(defstruct (binop (:type list) :named (:initial-offset 2))
500
(operator '? :type symbol)
502
operand-2) @result{} BINOP
503
(defstruct (annotated-binop (:type list)
506
commutative associative identity) @result{} ANNOTATED-BINOP
507
(make-annotated-binop :operator '*
513
@result{} (NIL NIL BINOP * X 5 NIL NIL NIL T T 1)
516
The first two @b{nil} elements stem from the @t{:initial-offset} of @t{2}
517
in the definition of @t{binop}. The next four elements contain the
518
structure name and three slots for @t{binop}. The next three @b{nil} elements
519
stem from the @t{:initial-offset} of @t{3} in the definition of
520
@t{annotated-binop}. The last three list elements contain the additional
521
slots for an @t{annotated-binop}.
523
@item @t{:initial-offset}
524
@t{:initial-offset} instructs @b{defstruct} to skip over a certain
525
number of slots before it starts allocating the slots described in the
526
body. This option's argument is the number of slots @b{defstruct}
527
should skip. @t{:initial-offset} can be used only if @t{:type} is also supplied.
529
[Reviewer Note by Barmar: What are initial values of the skipped slots?]
531
@t{:initial-offset} allows
532
slots to be allocated beginning at a representational
533
element other than the first. For example, the form
536
(defstruct (binop (:type list) (:initial-offset 2))
537
(operator '? :type symbol)
539
operand-2) @result{} BINOP
542
would result in the following behavior for @t{make-binop}:
545
(make-binop :operator '+ :operand-1 'x :operand-2 5)
546
@result{} (NIL NIL + X 5)
547
(make-binop :operand-2 4 :operator '*)
548
@result{} (NIL NIL * NIL 4)
551
The selector functions
552
@t{binop-operator}, @t{binop-operand-1},
553
and @t{binop-operand-2} would be essentially equivalent to @b{third},
554
@b{fourth}, and @b{fifth}, respectively.
558
(defstruct (binop (:type list) :named (:initial-offset 2))
559
(operator '? :type symbol)
561
operand-2) @result{} BINOP
564
would result in the following behavior for @t{make-binop}:
567
(make-binop :operator '+ :operand-1 'x :operand-2 5) @result{} (NIL NIL BINOP + X 5)
568
(make-binop :operand-2 4 :operator '*) @result{} (NIL NIL BINOP * NIL 4)
571
The first two @b{nil} elements stem from the @t{:initial-offset} of @t{2}
572
in the definition of @t{binop}. The next four elements contain the
573
structure name and three slots for @t{binop}.
576
@t{:named} specifies that the structure is named.
577
If no @t{:type} is supplied,
578
then the structure is always named.
583
(defstruct (binop (:type list))
584
(operator '? :type symbol)
586
operand-2) @result{} BINOP
589
This defines a constructor function @t{make-binop} and three
590
selector functions, namely @t{binop-operator}, @t{binop-operand-1},
591
and @t{binop-operand-2}. (It does not, however, define a predicate
592
@t{binop-p}, for reasons explained below.)
594
The effect of @t{make-binop} is simply to construct a list of length three:
597
(make-binop :operator '+ :operand-1 'x :operand-2 5) @result{} (+ X 5)
598
(make-binop :operand-2 4 :operator '*) @result{} (* NIL 4)
601
It is just like the function @t{list} except that it takes
602
keyword arguments and performs slot defaulting appropriate to the @t{binop}
603
conceptual data type. Similarly, the selector functions
604
@t{binop-operator}, @t{binop-operand-1},
605
and @t{binop-operand-2} are essentially equivalent to @b{car},
606
@b{cadr}, and @b{caddr}, respectively. They might not be
607
completely equivalent because,
608
for example, an implementation would be justified in adding error-checking
609
code to ensure that the argument to each selector function is a length-3
612
@t{binop} is a conceptual data type in that it is not made a part of
613
the @r{Common Lisp} type system. @b{typep} does not recognize @t{binop} as
614
a @i{type specifier}, and @b{type-of} returns @t{list} when
615
given a @t{binop} structure. There is no way to distinguish a data
616
structure constructed by @t{make-binop} from any other @i{list} that
617
happens to have the correct structure.
619
There is not any way to recover the structure name @t{binop} from
620
a structure created by @t{make-binop}. This can only be done
621
if the structure is named.
622
A named structure has the property that, given an instance of the
623
structure, the structure name (that names the type) can be reliably
624
recovered. For structures defined
625
with no @t{:type} option, the structure name actually becomes part
626
of the @r{Common Lisp} data-type system. @b{type-of},
627
when applied to such a structure, returns the structure name
628
as the @i{type} of the @i{object};
630
the structure name as a valid @i{type specifier}.
632
For structures defined with a @t{:type} option, @b{type-of}
633
returns a @i{type specifier} such as @t{list} or @t{(vector t)},
634
depending on the type supplied to the @t{:type} option.
635
The structure name does not become a valid @i{type specifier}.
637
if the @t{:named} option is also supplied, then the first component
638
of the structure (as created by a @b{defstruct} constructor function)
639
always contains the structure name. This allows the structure name
640
to be recovered from an instance of the structure and allows a reasonable
641
predicate for the conceptual type to be defined:
642
the automatically defined
643
@i{name-p} predicate for the structure operates by first
644
checking that its argument is of the proper type (@b{list},
646
or whatever) and then checking whether the first component contains
647
the appropriate type name.
649
Consider the @t{binop} example shown above, modified only to
650
include the @t{:named} option:
653
(defstruct (binop (:type list) :named)
654
(operator '? :type symbol)
656
operand-2) @result{} BINOP
659
As before, this defines a constructor function @t{make-binop} and three
660
selector functions @t{binop-operator}, @t{binop-operand-1},
661
and @t{binop-operand-2}. It also defines a predicate @t{binop-p}.
662
The effect of @t{make-binop} is now to construct a list of length four:
665
(make-binop :operator '+ :operand-1 'x :operand-2 5) @result{} (BINOP + X 5)
666
(make-binop :operand-2 4 :operator '*) @result{} (BINOP * NIL 4)
669
The structure has the same layout as before except that the structure name
670
@t{binop} is included as the first list element.
671
The selector functions
672
@t{binop-operator}, @t{binop-operand-1},
673
and @t{binop-operand-2} are essentially equivalent to @b{cadr},
674
@b{caddr}, and @b{cadddr}, respectively.
675
The predicate @t{binop-p} is more or less equivalent to this
680
(and (consp x) (eq (car x) 'binop))) @result{} BINOP-P
683
The name @t{binop} is still not a valid @i{type specifier} recognizable
684
to @b{typep}, but at least there is a way of distinguishing @t{binop}
685
structures from other similarly defined structures.
688
This option takes one argument, which specifies the name of the type predicate.
689
If the argument is not supplied or if the option itself is not
690
supplied, the name of the predicate is made by concatenating the
691
name of the structure to the string @t{"-P"}, interning the name
692
in whatever @i{package} is current at the time @b{defstruct}
694
If the argument is provided and is @b{nil}, no predicate is defined.
695
A predicate can be defined only if the structure is named;
696
if @t{:type} is supplied and @t{:named} is not supplied,
697
then @t{:predicate} must either be unsupplied or have the value @b{nil}.
699
@item @t{:print-function}, @t{:print-object}
700
The @t{:print-function} and @t{:print-object}
702
specify that a @b{print-object}
703
@i{method} for @i{structures} of type @i{structure-name} should be generated.
704
These options are not synonyms, but do perform a similar service;
705
the choice of which option (@t{:print-function} or @t{:print-object}) is used
706
affects how the function named @i{printer-name} is called.
707
Only one of these options may be used, and
708
these options may be used only if @t{:type} is not supplied.
710
If the @t{:print-function} option is used,
711
then when a structure of type @i{structure-name} is to be printed,
712
the designated printer function is called on three @i{arguments}:
717
the structure to be printed
718
(a @i{generalized instance} of @i{structure-name}).
721
a @i{stream} to print to.
724
an @i{integer} indicating the current depth.
725
The magnitude of this integer may vary between @i{implementations};
726
however, it can reliably be compared against @b{*print-level*}
727
to determine whether depth abbreviation is appropriate.
731
Specifying @t{(:print-function @i{printer-name})}
732
is approximately equivalent to specifying:
735
(defmethod print-object ((object @i{structure-name}) stream)
736
(funcall (function @i{printer-name}) object stream <<@i{current-print-depth}>>))
739
where the <<@i{current-print-depth}>> represents the printer's belief of
740
how deep it is currently printing. It is @i{implementation-dependent}
741
whether <<@i{current-print-depth}>> is always 0 and @i{*print-level*},
742
if @i{non-nil}, is re-bound to successively smaller values as printing
743
descends recursively, or whether @i{current-print-depth} varies in
744
value as printing descends recursively and @i{*print-level*} remains
745
constant during the same traversal.
747
If the @t{:print-object} option is used, then
748
when a structure of type @i{structure-name} is to be printed,
749
the designated printer function is called on two arguments:
754
the structure to be printed.
757
the stream to print to.
761
Specifying @t{(:print-object @i{printer-name})} is equivalent to specifying:
764
(defmethod print-object ((object @i{structure-name}) stream)
765
(funcall (function @i{printer-name}) object stream))
768
If no @t{:type} option is supplied,
769
and if either a @t{:print-function} or a @t{:print-object} option is supplied,
770
and if no @i{printer-name} is supplied,
771
then a @b{print-object} @i{method} @i{specialized} for @i{structure-name}
772
is generated that calls a function that implements the default printing behavior for
773
structures using @t{#S} notation; see @ref{Printing Structures}.
775
If neither a @t{:print-function}
776
nor a @t{:print-object} option
778
then @b{defstruct} does not generate a @b{print-object} @i{method}
779
@i{specialized} for @i{structure-name} and some default behavior is inherited
780
either from a structure named in an @t{:include} option
781
or from the default behavior for printing structures;
782
see the @i{function} @b{print-object} and @ref{Printing Structures}.
784
When @b{*print-circle*} is @i{true},
785
a user-defined print function can print @i{objects}
786
to the supplied @i{stream} using
791
and expect circularities to be detected and printed using the @t{#@i{n}#} syntax.
792
This applies to @i{methods} on @b{print-object} in addition to
793
@t{:print-function} options.
794
If a user-defined print function prints to a @i{stream} other than the one
795
that was supplied, then circularity detection starts over for that @i{stream}.
796
See the @i{variable} @b{*print-circle*}.
799
@t{:type} explicitly specifies the representation to be used for
800
the structure. Its argument must be one of these @i{types}:
805
This produces the same result as specifying @t{(vector t)}.
806
The structure is represented
807
as a general @i{vector}, storing components as vector elements.
808
The first component is vector
809
element 1 if the structure is @t{:named}, and element 0 otherwise.
811
[Reviewer Note by Barmar: Do any implementations create non-simple vectors?]
813
@item @t{(vector @i{element-type})}
814
The structure is represented as a (possibly specialized) @i{vector}, storing
815
components as vector elements. Every component must be of a @i{type}
816
that can be stored in a @i{vector} of the @i{type} specified.
817
The first component is vector
818
element 1 if the structure is @t{:named}, and element 0 otherwise.
819
The structure can be @t{:named} only if the @i{type} @b{symbol}
820
is a @i{subtype} of the supplied @i{element-type}.
823
The structure is represented as a @i{list}.
824
The first component is the @i{cadr} if the structure is @t{:named},
825
and the @i{car} if it is not @t{:named}.
828
Specifying this option has the effect of forcing
829
a specific representation and of forcing the components to be
830
stored in the order specified in @b{defstruct}
831
in corresponding successive elements of the specified representation.
832
It also prevents the structure name from becoming a valid
833
@i{type specifier} recognizable by @b{typep}.
838
(defstruct (quux (:type list) :named) x y)
841
should make a constructor that builds a @i{list} exactly like the one
842
that @b{list} produces,
843
with @t{quux} as its @i{car}.
845
If this type is defined:
848
(deftype quux () '(satisfies quux-p))
854
(typep (make-quux) 'quux)
857
should return precisely what this one does
860
(typep (list 'quux nil nil) 'quux)
863
If @t{:type} is not supplied,
864
the structure is represented as an @i{object} of @i{type} @b{structure-object}.
866
@b{defstruct} without a @t{:type} option defines a @i{class} with
867
the structure name as its name. The @i{metaclass} of structure
868
@i{instances} is @b{structure-class}.
872
The consequences of redefining a @b{defstruct} structure are undefined.
874
In the case where no @b{defstruct} options have been supplied,
875
the following functions are automatically defined to operate
876
on instances of the new structure:
881
A predicate with the name @t{@i{structure-name}-p} is defined to
882
test membership in the structure type. The predicate
883
@t{(@i{structure-name}-p @i{object})} is @i{true} if an @i{object}
884
is of this @i{type}; otherwise it is @i{false}. @b{typep} can also
885
be used with the name of the new @i{type} to test whether an
887
belongs to the @i{type}.
888
Such a function call has the form
889
@t{(typep @i{object} '@i{structure-name})}.
891
@item Component reader functions
892
@i{Reader} functions are defined to @i{read} the components of the
893
structure. For each slot name, there is a corresponding
894
@i{reader} function with the name @t{@i{structure-name}-@i{slot-name}}.
895
This function @i{reads} the contents of that slot.
896
Each @i{reader} function takes one argument, which is
897
an instance of the structure type.
898
@b{setf} can be used with any of these @i{reader} functions
899
to alter the slot contents.
901
@item Constructor function
902
A constructor function with the name @t{make-@i{structure-name}}
903
is defined. This function creates and returns new
904
instances of the structure type.
906
@item Copier function
907
A copier function with the name @t{copy-@i{structure-name}} is defined.
908
The copier function takes an object of the structure type and creates a
909
new object of the same type that is a copy of the first. The copier
910
function creates a new structure with the same component entries
911
as the original. Corresponding components of the two structure instances
915
If a @b{defstruct} @i{form} appears as a @i{top level form},
916
the @i{compiler} must make the @i{structure} @i{type} name recognized
917
as a valid @i{type} name in subsequent declarations (as for @b{deftype})
918
and make the structure slot readers known to @b{setf}. In addition, the
919
@i{compiler} must save enough information about the @i{structure} @i{type}
920
so that further @b{defstruct} definitions can use @t{:include} in a subsequent
921
@b{deftype} in the same @i{file} to refer to the @i{structure} @i{type} name.
922
The functions which @b{defstruct} generates are not defined
923
in the compile time environment, although the @i{compiler} may save enough
924
information about the functions to code subsequent calls inline.
925
The @t{#S} @i{reader macro} might or might not recognize the newly defined
926
@i{structure} @i{type} name at compile time.
928
@subsubheading Examples::
929
An example of a structure definition follows:
940
This declares that every @t{ship} is an @i{object}
941
with five named components.
942
The evaluation of this form does the following:
947
It defines @t{ship-x-position} to be a function
948
of one argument, a ship, that returns the @t{x-position}
949
of the ship; @t{ship-y-position}
950
and the other components are given similar function definitions.
951
These functions are called the @i{access} functions, as they
952
are used to @i{access} elements of the structure.
955
@t{ship} becomes the name of a @i{type} of which instances
956
of ships are elements. @t{ship} becomes acceptable to @b{typep},
957
for example; @t{(typep x 'ship)} is @i{true} if @t{x} is a ship
958
and false if @t{x} is any @i{object} other than a ship.
961
A function named @t{ship-p} of
962
one argument is defined; it is a predicate
963
that is @i{true} if its argument is a ship and is @i{false} otherwise.
966
A function called @t{make-ship} is defined that, when invoked,
967
creates a data structure with five components, suitable for use with
968
the @i{access} functions. Thus executing
971
(setq ship2 (make-ship))
974
sets @t{ship2} to a newly created @t{ship} @i{object}.
975
One can supply the initial values of any desired component in the call
976
to @t{make-ship} by using keyword arguments in this way:
979
(setq ship2 (make-ship :mass *default-ship-mass*
984
This constructs a new ship and initializes three of its components.
985
This function is called the ``constructor function''
986
because it constructs a new structure.
989
A function called @t{copy-ship} of one argument
990
is defined that, when given a @t{ship} @i{object},
991
creates a new @t{ship} @i{object} that is a copy of the given one.
992
This function is called the ``copier function.''
995
@b{setf} can be used to alter the components of a @t{ship}:
998
(setf (ship-x-position ship2) 100)
1001
This alters the @t{x-position} of @t{ship2} to be @t{100}.
1002
This works because @b{defstruct} behaves as if
1003
it generates an appropriate @b{defsetf}
1004
for each @i{access} function.
1009
;;; define town structure type
1010
;;; area, watertowers, firetrucks, population, elevation are its components
1015
(firetrucks 1 :type fixnum) ;an initialized slot
1017
(elevation 5128 :read-only t)) ;a slot that can't be changed
1019
;create a town instance
1020
(setq town1 (make-town :area 0 :watertowers 0)) @result{} #S(TOWN...)
1021
;town's predicate recognizes the new instance
1022
(town-p town1) @result{} @i{true}
1023
;new town's area is as specified by make-town
1024
(town-area town1) @result{} 0
1025
;new town's elevation has initial value
1026
(town-elevation town1) @result{} 5128
1027
;setf recognizes reader function
1028
(setf (town-population town1) 99) @result{} 99
1029
(town-population town1) @result{} 99
1030
;copier function makes a copy of town1
1031
(setq town2 (copy-town town1)) @result{} #S(TOWN...)
1032
(= (town-population town1) (town-population town2)) @result{} @i{true}
1033
;since elevation is a read-only slot, its value can be set only
1034
;when the structure is created
1035
(setq town3 (make-town :area 0 :watertowers 3 :elevation 1200))
1036
@result{} #S(TOWN...)
1039
;;; define clown structure type
1040
;;; this structure uses a nonstandard prefix
1042
(defstruct (clown (:conc-name bozo-))
1044
frizzy-hair-p polkadots) @result{} CLOWN
1045
(setq funny-clown (make-clown)) @result{} #S(CLOWN)
1046
;use non-default reader name
1047
(bozo-nose-color funny-clown) @result{} RED
1048
(defstruct (klown (:constructor make-up-klown) ;similar def using other
1049
(:copier clone-klown) ;customizing keywords
1050
(:predicate is-a-bozo-p))
1051
nose-color frizzy-hair-p polkadots) @result{} klown
1052
;custom constructor now exists
1053
(fboundp 'make-up-klown) @result{} @i{true}
1056
;;; define a vehicle structure type
1057
;;; then define a truck structure type that includes
1058
;;; the vehicle structure
1060
(defstruct vehicle name year (diesel t :read-only t)) @result{} VEHICLE
1061
(defstruct (truck (:include vehicle (year 79)))
1063
(axles 6)) @result{} TRUCK
1064
(setq x (make-truck :name 'mac :diesel t :load-limit 17))
1065
@result{} #S(TRUCK...)
1066
;vehicle readers work on trucks
1069
;default taken from :include clause
1072
(defstruct (pickup (:include truck)) ;pickup type includes truck
1073
camper long-bed four-wheel-drive) @result{} PICKUP
1074
(setq x (make-pickup :name 'king :long-bed t)) @result{} #S(PICKUP...)
1075
;:include default inherited
1076
(pickup-year x) @result{} 79
1079
;;; use of BOA constructors
1081
(defstruct (dfs-boa ;BOA constructors
1082
(:constructor make-dfs-boa (a b c))
1083
(:constructor create-dfs-boa
1084
(a &optional b (c 'cc) &rest d &aux e (f 'ff))))
1085
a b c d e f) @result{} DFS-BOA
1086
;a, b, and c set by position, and the rest are uninitialized
1087
(setq x (make-dfs-boa 1 2 3)) @result{} #(DFS-BOA...)
1088
(dfs-boa-a x) @result{} 1
1089
;a and b set, c and f defaulted
1090
(setq x (create-dfs-boa 1 2)) @result{} #(DFS-BOA...)
1091
(dfs-boa-b x) @result{} 2
1092
(eq (dfs-boa-c x) 'cc) @result{} @i{true}
1093
;a, b, and c set, and the rest are collected into d
1094
(setq x (create-dfs-boa 1 2 3 4 5 6)) @result{} #(DFS-BOA...)
1095
(dfs-boa-d x) @result{} (4 5 6)
1098
@subsubheading Exceptional Situations::
1100
If any two slot names (whether present directly or inherited by the @t{:include} option)
1101
are the @i{same} under @b{string=},
1102
@b{defstruct} should signal an error of @i{type} @b{program-error}.
1104
The consequences are undefined if the @i{included-structure-name}
1105
does not name a @i{structure type}.
1107
@subsubheading See Also::
1123
@subsubheading Notes::
1125
The @i{printer-name} should observe the values of
1126
such printer-control variables as @b{*print-escape*}.
1128
The restriction against issuing a warning for type mismatches between
1129
a @i{slot-initform} and the corresponding slot's @t{:type} option is
1130
necessary because a @i{slot-initform} must be specified in order to
1131
specify slot options; in some cases, no suitable default may exist.
1133
The mechanism by which @b{defstruct} arranges for slot accessors to
1134
be usable with @b{setf} is @i{implementation-dependent};
1135
for example, it may use @i{setf functions}, @i{setf expanders}, or
1136
some other @i{implementation-dependent} mechanism known to that
1137
@i{implementation}'s @i{code} for @b{setf}.
1139
@node copy-structure, , defstruct, Structures Dictionary
1140
@subsection copy-structure [Function]
1142
@code{copy-structure} @i{structure} @result{} @i{copy}
1144
@subsubheading Arguments and Values::
1146
@i{structure}---a @i{structure}.
1148
@i{copy}---a copy of the @i{structure}.
1150
@subsubheading Description::
1152
Returns a @i{copy}_6 of the @i{structure}.
1154
Only the @i{structure} itself is copied; not the values of the slots.
1156
@subsubheading See Also::
1158
the @t{:copier} option to
1161
@subsubheading Notes::
1163
The @i{copy} is the @i{same} as the given @i{structure}
1164
under @b{equalp}, but not under @b{equal}.
1166
@c end of including dict-structures
1168
@c %**end of chapter
added
removed
info/chap-8.texi
