3
@node Arrays, Strings, Conses, Top
11
@node Array Concepts, Arrays Dictionary, Arrays, Arrays
12
@section Array Concepts
14
@c including concept-arrays
18
* Specialized Arrays::
21
@node Array Elements, Specialized Arrays, Array Concepts, Array Concepts
22
@subsection Array Elements
24
An @i{array} contains a set of @i{objects} called @i{elements}
25
that can be referenced individually according to a rectilinear coordinate system.
30
* Implementation Limits on Individual Array Dimensions::
34
* Multidimensional Arrays::
35
* Storage Layout for Multidimensional Arrays::
36
* Implementation Limits on Array Rank::
39
@node Array Indices, Array Dimensions, Array Elements, Array Elements
40
@subsubsection Array Indices
42
An @i{array} @i{element} is referred to by a (possibly empty) series of indices.
43
The length of the series must equal the @i{rank} of the @i{array}.
45
Each index must be a non-negative @i{fixnum}
47
less than the corresponding @i{array} @i{dimension}.
48
@i{Array} indexing is zero-origin.
50
@node Array Dimensions, Implementation Limits on Individual Array Dimensions, Array Indices, Array Elements
51
@subsubsection Array Dimensions
53
An axis of an @i{array} is called a @i{dimension}
57
Each @i{dimension} is a non-negative
61
if any dimension of an @i{array} is zero, the @i{array} has no elements.
62
It is permissible for a @i{dimension} to be zero,
63
in which case the @i{array} has no elements,
64
and any attempt to @i{access} an @i{element}
65
is an error. However, other properties of the @i{array},
66
such as the @i{dimensions} themselves, may be used.
68
@node Implementation Limits on Individual Array Dimensions, Array Rank, Array Dimensions, Array Elements
69
@subsubsection Implementation Limits on Individual Array Dimensions
71
An @i{implementation} may impose a limit on @i{dimensions} of an @i{array},
72
but there is a minimum requirement on that limit. See the @i{variable} @b{array-dimension-limit}.
74
@node Array Rank, Vectors, Implementation Limits on Individual Array Dimensions, Array Elements
75
@subsubsection Array Rank
77
An @i{array} can have any number of @i{dimensions} (including zero).
78
The number of @i{dimensions} is called the @i{rank}
82
If the rank of an @i{array} is zero then the @i{array} is said to have
83
no @i{dimensions}, and the product of the dimensions (see @b{array-total-size})
84
is then 1; a zero-rank @i{array} therefore has a single element.
86
@node Vectors, Fill Pointers, Array Rank, Array Elements
87
@subsubsection Vectors
89
An @i{array} of @i{rank} one (@i{i.e.}, a one-dimensional @i{array})
90
is called a @i{vector}
94
@node Fill Pointers, Multidimensional Arrays, Vectors, Array Elements
95
@subsubsection Fill Pointers
98
@IGindex{fill pointer}
99
is a non-negative @i{integer} no
100
larger than the total number of @i{elements} in a @i{vector}.
101
Not all @i{vectors} have @i{fill pointers}.
102
See the @i{functions} @b{make-array} and @b{adjust-array}.
104
An @i{element} of a @i{vector} is said to be @i{active}
107
an index that is greater than or equal to zero,
108
but less than the @i{fill pointer} (if any).
109
For an @i{array} that has no @i{fill pointer},
110
all @i{elements} are considered @i{active}.
112
Only @i{vectors} may have @i{fill pointers};
113
multidimensional @i{arrays} may not.
114
A multidimensional @i{array} that is displaced to a @i{vector}
115
that has a @i{fill pointer} can be created.
117
@node Multidimensional Arrays, Storage Layout for Multidimensional Arrays, Fill Pointers, Array Elements
118
@subsubsection Multidimensional Arrays
120
@node Storage Layout for Multidimensional Arrays, Implementation Limits on Array Rank, Multidimensional Arrays, Array Elements
121
@subsubsection Storage Layout for Multidimensional Arrays
123
Multidimensional @i{arrays} store their components in row-major order;
124
that is, internally a multidimensional @i{array} is stored as a
125
one-dimensional @i{array}, with the multidimensional index sets
126
ordered lexicographically, last index varying fastest.
128
@node Implementation Limits on Array Rank, , Storage Layout for Multidimensional Arrays, Array Elements
129
@subsubsection Implementation Limits on Array Rank
131
An @i{implementation} may impose a limit on the @i{rank} of an @i{array},
132
but there is a minimum requirement on that limit. See the @i{variable} @b{array-rank-limit}.
134
@node Specialized Arrays, , Array Elements, Array Concepts
135
@subsection Specialized Arrays
137
An @i{array} can be a @i{general} @i{array},
138
meaning each @i{element} may be any @i{object},
139
or it may be a @i{specialized} @i{array},
140
meaning that each @i{element} must be of a restricted @i{type}.
142
The phrasing ``an @i{array} @i{specialized} to @i{type} <<@i{type}>>''
143
is sometimes used to emphasize the @i{element type} of an @i{array}.
144
This phrasing is tolerated even when the <<@i{type}>> is @b{t},
145
even though an @i{array} @i{specialized} to @i{type} @i{t}
146
is a @i{general} @i{array}, not a @i{specialized} @i{array}.
148
Figure 15--1 lists some @i{defined names} that are applicable to @i{array}
149
creation, @i{access}, and information operations.
154
@w{ adjust-array array-in-bounds-p svref }
155
@w{ adjustable-array-p array-rank upgraded-array-element-type }
156
@w{ aref array-rank-limit upgraded-complex-part-type }
157
@w{ array-dimension array-row-major-index vector }
158
@w{ array-dimension-limit array-total-size vector-pop }
159
@w{ array-dimensions array-total-size-limit vector-push }
160
@w{ array-element-type fill-pointer vector-push-extend }
161
@w{ array-has-fill-pointer-p make-array }
164
@w{ Figure 15--1: General Purpose Array-Related Defined Names }
171
* Required Kinds of Specialized Arrays::
174
@node Array Upgrading, Required Kinds of Specialized Arrays, Specialized Arrays, Specialized Arrays
175
@subsubsection Array Upgrading
177
The @i{upgraded array element type}
178
@IGindex{upgraded array element type}
180
is a @i{type} T_2 that is a @i{supertype} of T_1
181
and that is used instead of T_1 whenever T_1
182
is used as an @i{array element type}
183
for object creation or type discrimination.
185
During creation of an @i{array},
186
the @i{element type} that was requested
187
is called the @i{expressed array element type}
188
@IGindex{expressed array element type}
190
The @i{upgraded array element type} of the @i{expressed array element type}
191
becomes the @i{actual array element type}
192
@IGindex{actual array element type}
193
of the @i{array} that is created.
195
@i{Type} @i{upgrading} implies a movement upwards in the type hierarchy lattice.
196
A @i{type} is always a @i{subtype} of its @i{upgraded array element type}.
197
Also, if a @i{type} T_x is a @i{subtype} of another @i{type} T_y,
199
the @i{upgraded array element type} of T_x
200
must be a @i{subtype} of
201
the @i{upgraded array element type} of T_y.
202
Two @i{disjoint} @i{types} can be @i{upgraded} to the same @i{type}.
204
The @i{upgraded array element type} T_2 of a @i{type} T_1
205
is a function only of T_1 itself;
206
that is, it is independent of any other property of the @i{array}
207
for which T_2 will be used,
208
such as @i{rank}, @i{adjustability}, @i{fill pointers}, or displacement.
209
The @i{function} @b{upgraded-array-element-type}
210
can be used by @i{conforming programs} to predict how the @i{implementation}
211
will @i{upgrade} a given @i{type}.
213
@node Required Kinds of Specialized Arrays, , Array Upgrading, Specialized Arrays
214
@subsubsection Required Kinds of Specialized Arrays
216
@i{Vectors} whose @i{elements} are restricted to @i{type}
218
@b{character} or a @i{subtype} of @b{character}
220
are called @i{strings}
223
@i{Strings} are of @i{type} @b{string}.
224
Figure 15--2 lists some @i{defined names} related to @i{strings}.
226
@i{Strings} are @i{specialized} @i{arrays}
227
and might logically have been included in this chapter.
228
However, for purposes of readability
229
most information about @i{strings} does not appear in this chapter;
230
see instead @ref{Strings}.
235
@w{ char string-equal string-upcase }
236
@w{ make-string string-greaterp string@t{/=} }
237
@w{ nstring-capitalize string-left-trim string@t{<} }
238
@w{ nstring-downcase string-lessp string@t{<=} }
239
@w{ nstring-upcase string-not-equal string@t{=} }
240
@w{ schar string-not-greaterp string@t{>} }
241
@w{ string string-not-lessp string@t{>=} }
242
@w{ string-capitalize string-right-trim }
243
@w{ string-downcase string-trim }
246
@w{ Figure 15--2: Operators that Manipulate Strings }
251
@i{Vectors} whose @i{elements} are restricted to @i{type}
252
@b{bit} are called @i{bit vectors}
255
@i{Bit vectors} are of @i{type} @b{bit-vector}.
256
Figure 15--3 lists some @i{defined names} for operations on @i{bit arrays}.
261
@w{ bit bit-ior bit-orc2 }
262
@w{ bit-and bit-nand bit-xor }
263
@w{ bit-andc1 bit-nor sbit }
264
@w{ bit-andc2 bit-not }
265
@w{ bit-eqv bit-orc1 }
268
@w{ Figure 15--3: Operators that Manipulate Bit Arrays}
273
@c end of including concept-arrays
275
@node Arrays Dictionary, , Array Concepts, Arrays
276
@section Arrays Dictionary
278
@c including dict-arrays
283
* vector (System Class)::
286
* simple-bit-vector::
289
* adjustable-array-p::
293
* array-element-type::
294
* array-has-fill-pointer-p::
295
* array-displacement::
296
* array-in-bounds-p::
298
* array-row-major-index::
303
* upgraded-array-element-type::
304
* array-dimension-limit::
306
* array-total-size-limit::
316
* simple-bit-vector-p::
319
@node array, simple-array, Arrays Dictionary, Arrays Dictionary
320
@subsection array [System Class]
322
@subsubheading Class Precedence List::
326
@subsubheading Description::
328
An @i{array} contains @i{objects} arranged according to a
329
Cartesian coordinate system.
330
An @i{array} provides mappings from a set of
334
\left@{i_0,i_1,\dots,i_@{r-1@}\right@} to corresponding @i{elements}
336
where 0 \le i_j < d_j,
337
r is the rank of the array, and d_j is the size of @i{dimension} j of
340
When an @i{array} is created, the program requesting its creation may
341
declare that all @i{elements} are of a particular @i{type},
342
called the @i{expressed array element type}.
343
The implementation is permitted to @i{upgrade} this type in order to
344
produce the @i{actual array element type},
345
which is the @i{element type} for the @i{array} is actually @i{specialized}.
346
See the @i{function} @b{upgraded-array-element-type}.
348
@subsubheading Compound Type Specifier Kind::
352
@subsubheading Compound Type Specifier Syntax::
354
(@code{array}@{@i{@t{[}@{element-type | @b{*}@} @r{[}dimension-spec@r{]}@t{]}}@})
356
@w{@i{dimension-spec} ::=rank | @b{*} | @r{(}@{dimension | @b{*}@}*@r{)}}
358
@subsubheading Compound Type Specifier Arguments::
360
@i{dimension}---a @i{valid array dimension}.
362
@i{element-type}---a @i{type specifier}.
364
@i{rank}---a non-negative @i{fixnum}.
366
@subsubheading Compound Type Specifier Description::
368
This denotes the set of @i{arrays} whose
369
@i{element type}, @i{rank}, and @i{dimensions}
371
@i{element-type}, @i{rank}, and @i{dimensions}.
374
If @i{element-type} is the @i{symbol} @b{*},
375
@i{arrays} are not excluded on the basis of their @i{element type}.
376
Otherwise, only those @i{arrays} are included whose @i{actual array element type}
378
is the result of @i{upgrading} @i{element-type};
379
see @ref{Array Upgrading}.
381
If the @i{dimension-spec} is a @i{rank},
382
the set includes only those @i{arrays} having that @i{rank}.
383
If the @i{dimension-spec} is a @i{list} of @i{dimensions},
384
the set includes only those @i{arrays} having a @i{rank}
385
given by the @i{length} of the @i{dimensions},
386
and having the indicated @i{dimensions};
387
in this case, @b{*} matches any value for the corresponding @i{dimension}.
388
If the @i{dimension-spec} is the @i{symbol} @b{*},
389
the set is not restricted on the basis of @i{rank} or @i{dimension}.
391
@subsubheading See Also::
400
@ref{Printing Other Arrays}
402
@subsubheading Notes::
404
Note that the type @t{(array t)}
405
is a proper @i{subtype} of the type @t{(array *)}.
406
The reason is that the type @t{(array t)} is the set of @i{arrays}
408
hold any @i{object} (the @i{elements} are of @i{type} @b{t}, which includes
410
On the other hand, the type @t{(array *)}
411
is the set of all @i{arrays} whatsoever, including for example
412
@i{arrays} that can hold only @i{characters}.
413
The type @t{(array character)}
414
is not a @i{subtype} of the type @t{(array t)};
416
are @i{disjoint} because the type @t{(array character)} is not the
417
set of all @i{arrays} that can hold
418
@i{characters}, but rather the set of
420
that are specialized to hold precisely @i{characters} and no
423
@node simple-array, vector (System Class), array, Arrays Dictionary
424
@subsection simple-array [Type]
426
@subsubheading Supertypes::
432
@subsubheading Description::
434
The @i{type} of an @i{array} that is not displaced
435
to another @i{array}, has no @i{fill pointer}, and is
437
@i{expressly adjustable} is a @i{subtype} of @i{type} @b{simple-array}.
438
The concept of a @i{simple array}
439
exists to allow the implementation to use a specialized representation
440
and to allow the user to declare that certain values will always be
443
The @i{types} @b{simple-vector},
445
and @b{simple-bit-vector}
446
are @i{disjoint} @i{subtypes} of @i{type} @b{simple-array},
447
for they respectively mean @t{(simple-array t (*))},
448
the union of all @t{(simple-array @i{c} (*))}
449
for any @i{c} being a @i{subtype} of @i{type} @b{character},
450
and @t{(simple-array bit (*))}.
452
@subsubheading Compound Type Specifier Kind::
456
@subsubheading Compound Type Specifier Syntax::
458
(@code{simple-array}@{@i{@t{[}@{element-type | @b{*}@} @r{[}dimension-spec@r{]}@t{]}}@})
460
@w{@i{dimension-spec} ::=rank | @b{*} | @r{(}@{dimension | @b{*}@}*@r{)}}
462
@subsubheading Compound Type Specifier Arguments::
464
@i{dimension}---a @i{valid array dimension}.
466
@i{element-type}---a @i{type specifier}.
468
@i{rank}---a non-negative @i{fixnum}.
470
@subsubheading Compound Type Specifier Description::
472
This @i{compound type specifier} is treated exactly as the corresponding
473
@i{compound type specifier} for @i{type} @b{array} would be treated,
474
except that the set is further constrained to include only @i{simple arrays}.
476
@subsubheading Notes::
478
It is @i{implementation-dependent}
479
whether @i{displaced arrays},
480
@i{vectors} with @i{fill pointers},
481
or arrays that are @i{actually adjustable}
482
are @i{simple arrays}.
484
@t{(simple-array *)} refers to all @i{simple arrays}
485
regardless of element type, @t{(simple-array @i{type-specifier})}
486
refers only to those @i{simple arrays}
487
that can result from giving @i{type-specifier} as the
488
@t{:element-type} argument to @b{make-array}.
490
@node vector (System Class), simple-vector, simple-array, Arrays Dictionary
491
@subsection vector [System Class]
493
@subsubheading Class Precedence List::
499
@subsubheading Description::
501
Any one-dimensional @i{array} is a @i{vector}.
503
The @i{type} @b{vector} is a @i{subtype} of @i{type} @b{array};
504
for all @i{types} @t{x}, @t{(vector x)} is the same as @t{(array x (*))}.
506
The @i{type} @t{(vector t)}, the @i{type} @b{string}, and the @i{type} @b{bit-vector}
507
are @i{disjoint} @i{subtypes} of @i{type} @b{vector}.
509
@subsubheading Compound Type Specifier Kind::
513
@subsubheading Compound Type Specifier Syntax::
515
(@code{vector}@{@i{@t{[}@{element-type | @b{*}@} @r{[}@{size | @b{*}@}@r{]}@t{]}}@})
517
@subsubheading Compound Type Specifier Arguments::
519
@i{size}---a non-negative @i{fixnum}.
521
@i{element-type}---a @i{type specifier}.
523
@subsubheading Compound Type Specifier Description::
525
This denotes the set of specialized @i{vectors}
526
whose @i{element type} and @i{dimension} match the specified values.
529
If @i{element-type} is the @i{symbol} @b{*},
530
@i{vectors} are not excluded on the basis of their @i{element type}.
531
Otherwise, only those @i{vectors} are included whose @i{actual array element type}
533
is the result of @i{upgrading} @i{element-type};
534
see @ref{Array Upgrading}.
536
If a @i{size} is specified,
537
the set includes only those @i{vectors} whose only @i{dimension}
539
If the @i{symbol} @b{*} is specified instead of a @i{size},
540
the set is not restricted on the basis of @i{dimension}.
542
@subsubheading See Also::
544
@ref{Required Kinds of Specialized Arrays},
545
@ref{Sharpsign Left-Parenthesis},
546
@ref{Printing Other Vectors},
549
@subsubheading Notes::
551
The @i{type} @t{(vector @i{e} @i{s})}
552
is equivalent to the @i{type} @t{(array @i{e} (@i{s}))}.
554
The type @t{(vector bit)} has the name @b{bit-vector}.
556
The union of all @i{types} @t{(vector C)},
557
where C is any @i{subtype} of @b{character},
558
has the name @b{string}.
560
@t{(vector *)} refers to all @i{vectors}
561
regardless of element type, @t{(vector @i{type-specifier})}
562
refers only to those @i{vectors}
563
that can result from giving @i{type-specifier} as the
564
@t{:element-type} argument to @b{make-array}.
566
@node simple-vector, bit-vector, vector (System Class), Arrays Dictionary
567
@subsection simple-vector [Type]
569
@subsubheading Supertypes::
578
@subsubheading Description::
580
The @i{type} of a @i{vector} that is not displaced to another
581
@i{array}, has no @i{fill pointer}, is not
582
@i{expressly adjustable}
584
elements of any @i{type} is a @i{subtype} of @i{type} @b{simple-vector}.
586
The @i{type} @b{simple-vector} is a @i{subtype} of @i{type} @b{vector},
587
and is a @i{subtype} of @i{type} @t{(vector t)}.
589
@subsubheading Compound Type Specifier Kind::
593
@subsubheading Compound Type Specifier Syntax::
595
(@code{simple-vector}@{@i{@t{[}size@t{]}}@})
597
@subsubheading Compound Type Specifier Arguments::
599
@i{size}---a non-negative @i{fixnum},
600
or the @i{symbol} @b{*}.
601
The default is the @i{symbol} @b{*}.
603
@subsubheading Compound Type Specifier Description::
605
This is the same as @t{(simple-array t (@i{size}))}.
607
@node bit-vector, simple-bit-vector, simple-vector, Arrays Dictionary
608
@subsection bit-vector [System Class]
610
@subsubheading Class Precedence List::
617
@subsubheading Description::
619
A @i{bit vector} is a @i{vector} the @i{element type} of which is @i{bit}.
621
The @i{type} @b{bit-vector} is a @i{subtype} of @i{type} @b{vector},
622
for @b{bit-vector} means @t{(vector bit)}.
624
@subsubheading Compound Type Specifier Kind::
628
@subsubheading Compound Type Specifier Syntax::
630
(@code{bit-vector}@{@i{@t{[}size@t{]}}@})
632
@subsubheading Compound Type Specifier Arguments::
634
@i{size}---a non-negative @i{fixnum},
635
or the @i{symbol} @b{*}.
637
@subsubheading Compound Type Specifier Description::
639
This denotes the same @i{type} as the @i{type} @t{(array bit (@i{size}))};
640
that is, the set of @i{bit vectors} of size @i{size}.
642
@subsubheading See Also::
644
@ref{Sharpsign Asterisk},
645
@ref{Printing Bit Vectors},
646
@ref{Required Kinds of Specialized Arrays}
648
@node simple-bit-vector, make-array, bit-vector, Arrays Dictionary
649
@subsection simple-bit-vector [Type]
651
@subsubheading Supertypes::
653
@b{simple-bit-vector},
661
@subsubheading Description::
663
The @i{type} of a @i{bit vector} that is not displaced
664
to another @i{array}, has no @i{fill pointer}, and is
666
@i{expressly adjustable}
668
@i{subtype} of @i{type} @b{simple-bit-vector}.
670
@subsubheading Compound Type Specifier Kind::
674
@subsubheading Compound Type Specifier Syntax::
676
(@code{simple-bit-vector}@{@i{@t{[}size@t{]}}@})
678
@subsubheading Compound Type Specifier Arguments::
680
@i{size}---a non-negative @i{fixnum},
681
or the @i{symbol} @b{*}.
682
The default is the @i{symbol} @b{*}.
684
@subsubheading Compound Type Specifier Description::
686
This denotes the same type as the @i{type}
687
@t{(simple-array bit (@i{size}))};
688
that is, the set of @i{simple bit vectors} of size @i{size}.
690
@node make-array, adjust-array, simple-bit-vector, Arrays Dictionary
691
@subsection make-array [Function]
693
@code{make-array} @i{dimensions @r{&key} element-type
699
displaced-index-offset}@*
700
@result{} @i{new-array}
702
@subsubheading Arguments and Values::
704
@i{dimensions}---a @i{designator} for a @i{list} of @i{valid array dimensions}.
706
@i{element-type}---a @i{type specifier}.
707
The default is @b{t}.
709
@i{initial-element}---an @i{object}.
711
@i{initial-contents}---an @i{object}.
713
@i{adjustable}---a @i{generalized boolean}.
714
The default is @b{nil}.
716
@i{fill-pointer}---a @i{valid fill pointer} for the @i{array} to be created,
718
The default is @b{nil}.
720
@i{displaced-to}---an @i{array} or @b{nil}.
721
The default is @b{nil}.
722
This option must not be supplied if either @i{initial-element}
723
or @i{initial-contents} is supplied.
725
@i{displaced-index-offset}---a @i{valid array row-major index}
726
for @i{displaced-to}. The default is @t{0}.
727
This option must not be supplied unless a @i{non-nil} @i{displaced-to} is supplied.
729
@i{new-array}---an @i{array}.
731
@subsubheading Description::
733
Creates and returns an @i{array} constructed of the most @i{specialized}
734
@i{type} that can accommodate elements of @i{type} given by @i{element-type}.
735
If @i{dimensions} is @b{nil} then a zero-dimensional @i{array} is created.
737
@i{Dimensions} represents the dimensionality of the new @i{array}.
739
@i{element-type} indicates the @i{type} of the elements intended to be stored
740
in the @i{new-array}. The @i{new-array} can actually store any @i{objects}
741
of the @i{type} which results from @i{upgrading} @i{element-type};
742
see @ref{Array Upgrading}.
744
If @i{initial-element} is supplied,
745
it is used to initialize each @i{element} of @i{new-array}.
746
If @i{initial-element} is supplied,
747
it must be of the @i{type} given by @i{element-type}.
748
@i{initial-element} cannot be supplied if either the @t{:initial-contents} option
749
is supplied or @i{displaced-to} is @i{non-nil}.
750
If @i{initial-element} is not supplied,
752
the consequences of later reading an uninitialized @i{element} of @i{new-array}
755
unless either @i{initial-contents} is supplied
756
or @i{displaced-to} is @i{non-nil}.
758
@i{initial-contents} is used to initialize the contents of @i{array}.
762
(make-array '(4 2 3) :initial-contents
769
@i{initial-contents} is composed of a nested structure of @i{sequences}.
770
The numbers of levels in the structure must equal the rank of @i{array}.
771
Each leaf of the nested structure must be of the @i{type} given by @i{element-type}.
772
If @i{array} is zero-dimensional, then @i{initial-contents} specifies the single
773
@i{element}. Otherwise, @i{initial-contents} must be a @i{sequence}
774
whose length is equal to the first dimension; each element must be a nested
775
structure for an @i{array} whose dimensions are the remaining dimensions,
777
@i{Initial-contents} cannot be supplied if either
778
@i{initial-element} is supplied
779
or @i{displaced-to} is @i{non-nil}.
780
If @i{initial-contents} is not supplied,
782
the consequences of later reading an uninitialized @i{element} of @i{new-array}
785
unless either @i{initial-element} is supplied
786
or @i{displaced-to} is @i{non-nil}.
788
If @i{adjustable} is @i{non-nil},
789
the array is @i{expressly adjustable}
790
(and so @i{actually adjustable});
791
otherwise, the array is not @i{expressly adjustable}
792
(and it is @i{implementation-dependent} whether
793
the array is @i{actually adjustable}).
795
If @i{fill-pointer} is @i{non-nil},
796
the @i{array} must be one-dimensional;
797
that is, the @i{array} must be a @i{vector}.
798
If @i{fill-pointer} is @b{t},
799
the length of the @i{vector} is used to initialize the @i{fill pointer}.
800
If @i{fill-pointer} is an @i{integer},
801
it becomes the initial @i{fill pointer} for the @i{vector}.
803
If @i{displaced-to} is @i{non-nil},
804
@b{make-array} will create a @i{displaced array}
805
and @i{displaced-to} is the @i{target} of that @i{displaced array}.
806
In that case, the consequences are undefined if the @i{actual array element type} of
807
@i{displaced-to} is not @i{type equivalent} to the @i{actual array element type}
808
of the @i{array} being created.
809
If @i{displaced-to} is @b{nil}, the @i{array} is not a @i{displaced array}.
811
The @i{displaced-index-offset} is made to be the index offset of the @i{array}.
812
When an array A is given as
813
the @t{:displaced-to} @i{argument} to @b{make-array}
814
when creating array B,
815
then array B is said to be displaced to array A. The
816
total number of elements in an @i{array},
817
called the total size of the @i{array},
818
is calculated as the product of all the dimensions.
819
It is required that the total size of A be no smaller than the sum
820
of the total size of B plus the offset @t{n} supplied by
821
the @i{displaced-index-offset}.
822
The effect of displacing is that array B does not have any
823
elements of its own, but instead maps @i{accesses} to itself into
824
@i{accesses} to array A. The mapping treats both @i{arrays} as if they
825
were one-dimensional by taking the elements in row-major order,
826
and then maps an @i{access} to element @t{k} of array B to an @i{access} to element
827
@t{k}+@t{n} of array A.
829
If @b{make-array} is called with @i{adjustable}, @i{fill-pointer},
830
and @i{displaced-to} each @b{nil},
831
then the result is a @i{simple array}.
833
If @b{make-array} is called with one or more of @i{adjustable},
834
@i{fill-pointer}, or @i{displaced-to} being @i{true}, whether the
835
resulting @i{array} is a @i{simple array} is @i{implementation-dependent}.
837
When an array A is given as the @t{:displaced-to} @i{argument} to
838
@b{make-array} when creating array B, then array B is said to
839
be displaced to array A. The total number of elements in an @i{array},
840
called the total size of the @i{array}, is calculated as the product
841
of all the dimensions.
842
The consequences are unspecified if
843
the total size of A is smaller than the sum
844
of the total size of B plus the offset @t{n} supplied by
845
the @i{displaced-index-offset}.
846
The effect of displacing is that array B does not have any
847
elements of its own, but instead maps @i{accesses} to itself into
848
@i{accesses} to array A. The mapping treats both @i{arrays} as if they
849
were one-dimensional by taking the elements in row-major order,
850
and then maps an @i{access} to element @t{k} of array B to an @i{access}
851
to @i{element} @t{k}+@t{n} of array A.
853
@subsubheading Examples::
856
(make-array 5) ;; Creates a one-dimensional array of five elements.
857
(make-array '(3 4) :element-type '(mod 16)) ;; Creates a
858
;;two-dimensional array, 3 by 4, with four-bit elements.
859
(make-array 5 :element-type 'single-float) ;; Creates an array of single-floats.
863
(make-array nil :initial-element nil) @result{} #0ANIL
864
(make-array 4 :initial-element nil) @result{} #(NIL NIL NIL NIL)
866
:element-type '(unsigned-byte 2)
867
:initial-contents '((0 1 2 3) (3 2 1 0)))
868
@result{} #2A((0 1 2 3) (3 2 1 0))
870
:element-type 'character
872
:fill-pointer 3) @result{} "aaa"
875
The following is an example of making a @i{displaced array}.
878
(setq a (make-array '(4 3)))
879
@result{} #<ARRAY 4x3 simple 32546632>
882
(setf (aref a i j) (list i 'x j '= (* i j)))))
884
(setq b (make-array 8 :displaced-to a
885
:displaced-index-offset 2))
886
@result{} #<ARRAY 8 indirect 32550757>
888
(print (list i (aref b i))))
889
@t{ |> } (0 (0 X 2 = 0))
890
@t{ |> } (1 (1 X 0 = 0))
891
@t{ |> } (2 (1 X 1 = 1))
892
@t{ |> } (3 (1 X 2 = 2))
893
@t{ |> } (4 (2 X 0 = 0))
894
@t{ |> } (5 (2 X 1 = 2))
895
@t{ |> } (6 (2 X 2 = 4))
896
@t{ |> } (7 (3 X 0 = 0))
900
The last example depends on the fact that @i{arrays} are, in effect,
901
stored in row-major order.
904
(setq a1 (make-array 50))
905
@result{} #<ARRAY 50 simple 32562043>
906
(setq b1 (make-array 20 :displaced-to a1 :displaced-index-offset 10))
907
@result{} #<ARRAY 20 indirect 32563346>
908
(length b1) @result{} 20
910
(setq a2 (make-array 50 :fill-pointer 10))
911
@result{} #<ARRAY 50 fill-pointer 10 46100216>
912
(setq b2 (make-array 20 :displaced-to a2 :displaced-index-offset 10))
913
@result{} #<ARRAY 20 indirect 46104010>
914
(length a2) @result{} 10
915
(length b2) @result{} 20
917
(setq a3 (make-array 50 :fill-pointer 10))
918
@result{} #<ARRAY 50 fill-pointer 10 46105663>
919
(setq b3 (make-array 20 :displaced-to a3 :displaced-index-offset 10
921
@result{} #<ARRAY 20 indirect, fill-pointer 5 46107432>
922
(length a3) @result{} 10
923
(length b3) @result{} 5
926
@subsubheading See Also::
928
@ref{adjustable-array-p}
934
@ref{array-element-type}
936
@ref{array-rank-limit}
938
@ref{array-dimension-limit}
942
@ref{upgraded-array-element-type}
944
@subsubheading Notes::
946
There is no specified way to create an @i{array}
947
for which @b{adjustable-array-p} definitely
949
There is no specified way to create an @i{array}
950
that is not a @i{simple array}.
952
@node adjust-array, adjustable-array-p, make-array, Arrays Dictionary
953
@subsection adjust-array [Function]
955
@code{adjust-array} @i{array new-dimensions @r{&key} element-type
960
displaced-index-offset}@*
961
@result{} @i{adjusted-array}
963
@subsubheading Arguments and Values::
965
@i{array}---an @i{array}.
967
@i{new-dimensions}---a @i{valid array dimension}
968
or a @i{list} of @i{valid array dimensions}.
970
@i{element-type}---a @i{type specifier}.
972
@i{initial-element}---an @i{object}.
973
@i{Initial-element} must not be supplied if either
974
@i{initial-contents} or @i{displaced-to} is supplied.
976
@i{initial-contents}---an @i{object}.
977
If @i{array} has rank greater than zero, then @i{initial-contents}
978
is composed of nested @i{sequences}, the depth of which must equal
979
the rank of @i{array}. Otherwise, @i{array} is zero-dimensional and
980
@i{initial-contents} supplies the single element.
981
@i{initial-contents} must not be supplied if either
982
@i{initial-element} or @i{displaced-to} is given.
984
@i{fill-pointer}---a @i{valid fill pointer} for the
985
@i{array} to be created, or @b{t}, or @b{nil}.
986
The default is @b{nil}.
988
@i{displaced-to}---an @i{array} or @b{nil}.
989
@i{initial-elements} and @i{initial-contents} must not be supplied
990
if @i{displaced-to} is supplied.
992
@i{displaced-index-offset}---an @i{object} of @i{type} @t{(fixnum 0 @i{n})}
993
where @i{n} is @t{(array-total-size @i{displaced-to})}.
994
@i{displaced-index-offset} may be supplied only if @i{displaced-to} is supplied.
996
@i{adjusted-array}---an @i{array}.
998
@subsubheading Description::
1000
@b{adjust-array} changes the dimensions or elements of @i{array}.
1001
The result is an @i{array} of the same @i{type} and rank as @i{array},
1002
that is either the modified @i{array},
1003
or a newly created @i{array} to which
1004
@i{array} can be displaced, and that has
1005
the given @i{new-dimensions}.
1007
@i{New-dimensions} specify the size of each @i{dimension} of @i{array}.
1009
@i{Element-type} specifies the @i{type} of the @i{elements}
1010
of the resulting @i{array}. If @i{element-type} is supplied,
1011
the consequences are unspecified if
1012
the @i{upgraded array element type} of @i{element-type}
1013
is not the same as the @i{actual array element type} of @i{array}.
1015
If @i{initial-contents} is supplied, it is treated as for
1016
@b{make-array}. In this case none of the original contents of
1017
@i{array} appears in the resulting @i{array}.
1019
If @i{fill-pointer} is an @i{integer},
1020
it becomes the @i{fill pointer} for the resulting @i{array}.
1021
If @i{fill-pointer} is the symbol @b{t},
1022
it indicates that the size of the resulting @i{array}
1023
should be used as the @i{fill pointer}.
1024
If @i{fill-pointer} is @b{nil},
1025
it indicates that the @i{fill pointer} should be left as it is.
1028
@i{non-nil}, a @i{displaced array}
1029
is created. The resulting @i{array} shares its contents with the @i{array} given by
1031
The resulting @i{array} cannot contain more elements than the @i{array}
1033
If @i{displaced-to} is not supplied or @b{nil},
1034
the resulting @i{array} is not a @i{displaced array}.
1035
If array A is created displaced to array B and subsequently
1036
array B is given to @b{adjust-array}, array A will still be
1037
displaced to array B.
1038
Although @i{array} might be a @i{displaced array},
1039
the resulting @i{array} is not a @i{displaced array} unless
1040
@i{displaced-to} is supplied and not @b{nil}.
1042
The interaction between @b{adjust-array} and
1043
displaced @i{arrays}
1044
is as follows given three @i{arrays}, @t{A}, @t{B}, and~@t{C}:
1048
@item @t{A} is not displaced before or after the call
1050
(adjust-array A ...)
1053
The dimensions of @t{A} are altered, and the
1054
contents rearranged as appropriate.
1055
Additional elements of @t{A} are taken from
1056
@i{initial-element}.
1057
The use of @i{initial-contents} causes all old contents to be
1060
@item @t{A} is not displaced before, but is displaced to
1061
@t{C} after the call
1063
(adjust-array A ... :displaced-to C)
1066
None of the original contents of @t{A} appears in
1067
@t{A} afterwards; @t{A} now contains
1068
the contents of @t{C}, without any rearrangement of @t{C}.
1070
@item @t{A} is displaced to @t{B}
1071
before the call, and is displaced to @t{C} after
1074
(adjust-array A ... :displaced-to B)
1075
(adjust-array A ... :displaced-to C)
1078
@t{B} and @t{C} might be the same. The contents of @t{B} do not appear in
1079
@t{A} afterward unless such contents also happen to be in @t{C} If
1080
@i{displaced-index-offset}
1081
is not supplied in the @b{adjust-array} call, it defaults
1082
to zero; the old offset into @t{B} is not retained.
1084
@item @t{A} is displaced to @t{B} before the call, but not displaced
1087
(adjust-array A ... :displaced-to B)
1088
(adjust-array A ... :displaced-to nil)
1092
new ``data region,'' and contents of @t{B} are copied into it as appropriate to
1093
maintain the existing old contents; additional elements of @t{A}
1095
@i{initial-element} if supplied. However,
1096
the use of @i{initial-contents} causes all old contents
1100
If @i{displaced-index-offset} is supplied,
1101
it specifies the offset
1102
of the resulting @i{array} from the beginning of
1103
the @i{array} that it is displaced to.
1104
If @i{displaced-index-offset} is not supplied, the offset is~0.
1105
The size of the resulting @i{array} plus the
1106
offset value cannot exceed the size of
1107
the @i{array} that it is displaced to.
1109
If only @i{new-dimensions}
1110
and an @i{initial-element} argument are supplied,
1111
those elements of @i{array} that
1112
are still in bounds appear in the resulting @i{array}. The elements of
1113
the resulting @i{array} that are not in the bounds of
1114
@i{array} are initialized
1115
to @i{initial-element}; if @i{initial-element} is not provided,
1117
the consequences of later reading any such new @i{element} of @i{new-array}
1118
before it has been initialized
1121
If @i{initial-contents} or @i{displaced-to} is supplied,
1122
then none of the original contents of @i{array} appears in the new @i{array}.
1124
The consequences are unspecified if @i{array} is adjusted
1125
to a size smaller than its @i{fill pointer} without supplying
1126
the @i{fill-pointer} argument so that its @i{fill-pointer}
1127
is properly adjusted in the process.
1129
If @t{A} is displaced to @t{B}, the consequences are unspecified
1130
if @t{B} is adjusted in such a way that it no longer has enough elements
1133
If @b{adjust-array} is applied to an @i{array} that is @i{actually adjustable},
1134
the @i{array} returned is @i{identical} to @i{array}.
1135
If the @i{array} returned by @b{adjust-array}
1136
is @i{distinct} from @i{array}, then the argument @i{array} is unchanged.
1138
Note that if an @i{array} A is displaced to another @i{array} B,
1139
and B is displaced to another @i{array} C, and B is altered by
1140
@b{adjust-array}, A must now refer to the adjust contents of B.
1141
This means that an implementation cannot collapse the chain to make A
1142
refer to C directly and forget that the chain of reference passes through
1143
B. However, caching techniques are permitted as long as they preserve the
1144
semantics specified here.
1146
@subsubheading Examples::
1150
(setq ada (adjust-array
1153
:initial-contents '((a b c) (1 2 3)))
1154
'(4 6)))) @result{} T
1155
(array-dimensions ada) @result{} (4 6)
1156
(aref ada 1 1) @result{} 2
1157
(setq beta (make-array '(2 3) :adjustable t))
1158
@result{} #2A((NIL NIL NIL) (NIL NIL NIL))
1159
(adjust-array beta '(4 6) :displaced-to ada)
1160
@result{} #2A((A B C NIL NIL NIL)
1162
(NIL NIL NIL NIL NIL NIL)
1163
(NIL NIL NIL NIL NIL NIL))
1164
(array-dimensions beta) @result{} (4 6)
1165
(aref beta 1 1) @result{} 2
1168
Suppose that the 4-by-4 array in @t{m} looks like this:
1171
#2A(( alpha beta gamma delta )
1172
( epsilon zeta eta theta )
1173
( iota kappa lambda mu )
1174
( nu xi omicron pi ))
1180
(adjust-array m '(3 5) :initial-element 'baz)
1183
is a 3-by-5 array with contents
1186
#2A(( alpha beta gamma delta baz )
1187
( epsilon zeta eta theta baz )
1188
( iota kappa lambda mu baz ))
1191
@subsubheading Exceptional Situations::
1193
An error of @i{type} @b{error} is signaled if @i{fill-pointer} is supplied
1194
and @i{non-nil} but @i{array} has no @i{fill pointer}.
1196
@subsubheading See Also::
1198
@ref{adjustable-array-p}
1202
@ref{array-dimension-limit}
1204
@ref{array-total-size-limit}
1208
@node adjustable-array-p, aref, adjust-array, Arrays Dictionary
1209
@subsection adjustable-array-p [Function]
1211
@code{adjustable-array-p} @i{array} @result{} @i{generalized-boolean}
1213
@subsubheading Arguments and Values::
1215
@i{array}---an @i{array}.
1217
@i{generalized-boolean}---a @i{generalized boolean}.
1219
@subsubheading Description::
1221
Returns true if and only if @b{adjust-array} could return a @i{value}
1222
which is @i{identical} to @i{array} when given that @i{array} as its
1225
@subsubheading Examples::
1230
:element-type 'character
1232
:fill-pointer 3)) @result{} @i{true}
1233
(adjustable-array-p (make-array 4)) @result{} @i{implementation-dependent}
1236
@subsubheading Exceptional Situations::
1238
Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}.
1240
@subsubheading See Also::
1246
@node aref, array-dimension, adjustable-array-p, Arrays Dictionary
1247
@subsection aref [Accessor]
1249
@code{aref} @i{array @r{&rest} subscripts} @result{} @i{element}
1251
(setf (@code{ aref} @i{array @r{&rest} subscripts}) new-element)@*
1253
@subsubheading Arguments and Values::
1255
@i{array}---an @i{array}.
1257
@i{subscripts}---a @i{list} of @i{valid array indices} for the @i{array}.
1259
@i{element}, @i{new-element}---an @i{object}.
1261
@subsubheading Description::
1263
@i{Accesses} the @i{array} @i{element} specified by the @i{subscripts}.
1264
If no @i{subscripts} are supplied and @i{array} is zero rank,
1265
@b{aref} @i{accesses} the sole element of @i{array}.
1267
@b{aref} ignores @i{fill pointers}.
1268
It is permissible to use @b{aref}
1269
to @i{access} any @i{array} @i{element},
1270
whether @i{active} or not.
1272
@subsubheading Examples::
1274
If the variable @t{foo} names a 3-by-5 array,
1275
then the first index could be 0, 1, or 2, and then second index
1276
could be 0, 1, 2, 3, or 4. The array elements can be referred to by using
1277
the @i{function} @b{aref}; for example, @t{(aref foo 2 1)}
1278
refers to element (2, 1) of the array.
1281
(aref (setq alpha (make-array 4)) 3) @result{} @i{implementation-dependent}
1282
(setf (aref alpha 3) 'sirens) @result{} SIRENS
1283
(aref alpha 3) @result{} SIRENS
1284
(aref (setq beta (make-array '(2 4)
1285
:element-type '(unsigned-byte 2)
1286
:initial-contents '((0 1 2 3) (3 2 1 0))))
1289
(apply #'aref beta gamma) @result{} 2
1290
(setf (apply #'aref beta gamma) 3) @result{} 3
1291
(apply #'aref beta gamma) @result{} 3
1292
(aref beta 0 2) @result{} 3
1295
@subsubheading See Also::
1303
@ref{row-major-aref}
1308
@ref{Compiler Terminology}
1310
@node array-dimension, array-dimensions, aref, Arrays Dictionary
1311
@subsection array-dimension [Function]
1313
@code{array-dimension} @i{array axis-number} @result{} @i{dimension}
1315
@subsubheading Arguments and Values::
1317
@i{array}---an @i{array}.
1319
@i{axis-number}---an @i{integer} greater than or equal to zero
1320
and less than the @i{rank} of the @i{array}.
1322
@i{dimension}---a non-negative @i{integer}.
1324
@subsubheading Description::
1326
@b{array-dimension} returns the @i{axis-number}
1327
@i{dimension}_1 of @i{array}.
1328
(Any @i{fill pointer} is ignored.)
1330
@subsubheading Examples::
1333
(array-dimension (make-array 4) 0) @result{} 4
1334
(array-dimension (make-array '(2 3)) 1) @result{} 3
1337
@subsubheading Affected By::
1340
@subsubheading See Also::
1342
@ref{array-dimensions}
1346
@subsubheading Notes::
1348
(array-dimension array n) @equiv{} (nth n (array-dimensions array))
1351
@node array-dimensions, array-element-type, array-dimension, Arrays Dictionary
1352
@subsection array-dimensions [Function]
1354
@code{array-dimensions} @i{array} @result{} @i{dimensions}
1356
@subsubheading Arguments and Values::
1358
@i{array}---an @i{array}.
1360
@i{dimensions}---a @i{list} of @i{integers}.
1362
@subsubheading Description::
1364
Returns a @i{list} of the @i{dimensions} of @i{array}.
1365
(If @i{array} is a @i{vector} with a @i{fill pointer},
1366
that @i{fill pointer} is ignored.)
1368
@subsubheading Examples::
1371
(array-dimensions (make-array 4)) @result{} (4)
1372
(array-dimensions (make-array '(2 3))) @result{} (2 3)
1373
(array-dimensions (make-array 4 :fill-pointer 2)) @result{} (4)
1376
@subsubheading Exceptional Situations::
1378
Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}.
1380
@subsubheading See Also::
1382
@ref{array-dimension}
1384
@node array-element-type, array-has-fill-pointer-p, array-dimensions, Arrays Dictionary
1385
@subsection array-element-type [Function]
1387
@code{array-element-type} @i{array} @result{} @i{typespec}
1389
@subsubheading Arguments and Values::
1391
@i{array}---an @i{array}.
1393
@i{typespec}---a @i{type specifier}.
1395
@subsubheading Description::
1397
Returns a @i{type specifier} which represents the @i{actual array element type}
1398
of the array, which is the set of @i{objects} that such an @i{array} can hold.
1399
(Because of @i{array} @i{upgrading}, this @i{type specifier} can in
1400
some cases denote a @i{supertype} of the @i{expressed array element type}
1403
@subsubheading Examples::
1406
(array-element-type (make-array 4)) @result{} T
1407
(array-element-type (make-array 12 :element-type '(unsigned-byte 8)))
1408
@result{} @i{implementation-dependent}
1409
(array-element-type (make-array 12 :element-type '(unsigned-byte 5)))
1410
@result{} @i{implementation-dependent}
1414
(array-element-type (make-array 5 :element-type '(mod 5)))
1417
could be @t{(mod 5)}, @t{(mod 8)}, @t{fixnum}, @t{t}, or any other
1418
type of which @t{(mod 5)} is a @i{subtype}.
1420
@subsubheading Affected By::
1422
The @i{implementation}.
1424
@subsubheading Exceptional Situations::
1426
Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}.
1428
@subsubheading See Also::
1435
@ref{upgraded-array-element-type}
1437
@node array-has-fill-pointer-p, array-displacement, array-element-type, Arrays Dictionary
1438
@subsection array-has-fill-pointer-p [Function]
1440
@code{array-has-fill-pointer-p} @i{array} @result{} @i{generalized-boolean}
1442
@subsubheading Arguments and Values::
1444
@i{array}---an @i{array}.
1446
@i{generalized-boolean}---a @i{generalized boolean}.
1448
@subsubheading Description::
1450
Returns @i{true} if @i{array} has a @i{fill pointer};
1451
otherwise returns @i{false}.
1453
@subsubheading Examples::
1456
(array-has-fill-pointer-p (make-array 4)) @result{} @i{implementation-dependent}
1457
(array-has-fill-pointer-p (make-array '(2 3))) @result{} @i{false}
1458
(array-has-fill-pointer-p
1461
:initial-element 'filler)) @result{} @i{true}
1464
@subsubheading Exceptional Situations::
1466
Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}.
1468
@subsubheading See Also::
1474
@subsubheading Notes::
1476
Since @i{arrays} of @i{rank} other than one cannot have a @i{fill pointer},
1477
@b{array-has-fill-pointer-p} always returns @b{nil} when its argument
1480
@node array-displacement, array-in-bounds-p, array-has-fill-pointer-p, Arrays Dictionary
1481
@subsection array-displacement [Function]
1483
@code{array-displacement} @i{array} @result{} @i{displaced-to, displaced-index-offset}
1485
@subsubheading Arguments and Values::
1487
@i{array}---an @i{array}.
1489
@i{displaced-to}---an @i{array} or @b{nil}.
1491
@i{displaced-index-offset}---a non-negative @i{fixnum}.
1493
@subsubheading Description::
1495
If the @i{array} is a @i{displaced array},
1496
returns the @i{values} of the @t{:displaced-to} and @t{:displaced-index-offset}
1498
for the @i{array} (see the @i{functions} @b{make-array} and @b{adjust-array}).
1499
If the @i{array} is not a @i{displaced array},
1500
@b{nil} and @t{0} are returned.
1502
If @b{array-displacement} is called on an @i{array}
1503
for which a @i{non-nil} @i{object} was provided as the
1504
@t{:displaced-to} @i{argument} to @b{make-array}
1505
or @b{adjust-array}, it must return that @i{object}
1506
as its first value. It is @i{implementation-dependent}
1507
whether @b{array-displacement} returns a @i{non-nil}
1508
@i{primary value} for any other @i{array}.
1510
@subsubheading Examples::
1513
(setq a1 (make-array 5)) @result{} #<ARRAY 5 simple 46115576>
1514
(setq a2 (make-array 4 :displaced-to a1
1515
:displaced-index-offset 1))
1516
@result{} #<ARRAY 4 indirect 46117134>
1517
(array-displacement a2)
1518
@result{} #<ARRAY 5 simple 46115576>, 1
1519
(setq a3 (make-array 2 :displaced-to a2
1520
:displaced-index-offset 2))
1521
@result{} #<ARRAY 2 indirect 46122527>
1522
(array-displacement a3)
1523
@result{} #<ARRAY 4 indirect 46117134>, 2
1526
@subsubheading Exceptional Situations::
1528
Should signal an error of @i{type} @b{type-error}
1529
if @i{array} is not an @i{array}.
1531
@subsubheading See Also::
1535
@node array-in-bounds-p, array-rank, array-displacement, Arrays Dictionary
1536
@subsection array-in-bounds-p [Function]
1538
@code{array-in-bounds-p} @i{array @r{&rest} subscripts} @result{} @i{generalized-boolean}
1540
@subsubheading Arguments and Values::
1542
@i{array}---an @i{array}.
1544
@i{subscripts}---a list of @i{integers}
1545
of length equal to the @i{rank} of the @i{array}.
1547
@i{generalized-boolean}---a @i{generalized boolean}.
1549
@subsubheading Description::
1551
Returns @i{true} if the @i{subscripts} are all in bounds for @i{array};
1552
otherwise returns @i{false}.
1553
(If @i{array} is a @i{vector} with a @i{fill pointer},
1554
that @i{fill pointer} is ignored.)
1556
@subsubheading Examples::
1558
(setq a (make-array '(7 11) :element-type 'string-char))
1559
(array-in-bounds-p a 0 0) @result{} @i{true}
1560
(array-in-bounds-p a 6 10) @result{} @i{true}
1561
(array-in-bounds-p a 0 -1) @result{} @i{false}
1562
(array-in-bounds-p a 0 11) @result{} @i{false}
1563
(array-in-bounds-p a 7 0) @result{} @i{false}
1566
@subsubheading See Also::
1568
@ref{array-dimensions}
1570
@subsubheading Notes::
1572
(array-in-bounds-p array subscripts)
1573
@equiv{} (and (not (some #'minusp (list subscripts)))
1574
(every #'< (list subscripts) (array-dimensions array)))
1577
@node array-rank, array-row-major-index, array-in-bounds-p, Arrays Dictionary
1578
@subsection array-rank [Function]
1580
@code{array-rank} @i{array} @result{} @i{rank}
1582
@subsubheading Arguments and Values::
1584
@i{array}---an @i{array}.
1586
@i{rank}---a non-negative @i{integer}.
1588
@subsubheading Description::
1590
Returns the number of @i{dimensions} of @i{array}.
1592
@subsubheading Examples::
1595
(array-rank (make-array '())) @result{} 0
1596
(array-rank (make-array 4)) @result{} 1
1597
(array-rank (make-array '(4))) @result{} 1
1598
(array-rank (make-array '(2 3))) @result{} 2
1601
@subsubheading Exceptional Situations::
1603
Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}.
1605
@subsubheading See Also::
1607
@ref{array-rank-limit}
1611
@node array-row-major-index, array-total-size, array-rank, Arrays Dictionary
1612
@subsection array-row-major-index [Function]
1614
@code{array-row-major-index} @i{array @r{&rest} subscripts} @result{} @i{index}
1616
@subsubheading Arguments and Values::
1618
@i{array}---an @i{array}.
1620
@i{subscripts}---a @i{list} of @i{valid array indices} for the @i{array}.
1622
@i{index}---a @i{valid array row-major index} for the @i{array}.
1624
@subsubheading Description::
1626
Computes the position according to the row-major ordering of @i{array}
1627
for the element that is specified by @i{subscripts}, and returns the
1628
offset of the element in the computed position from the beginning of @i{array}.
1630
For a one-dimensional @i{array},
1631
the result of @b{array-row-major-index}
1632
equals @i{subscript}.
1634
@b{array-row-major-index} ignores @i{fill pointers}.
1636
@subsubheading Examples::
1639
(setq a (make-array '(4 7) :element-type '(unsigned-byte 8)))
1640
(array-row-major-index a 1 2) @result{} 9
1641
(array-row-major-index
1642
(make-array '(2 3 4)
1643
:element-type '(unsigned-byte 8)
1645
:displaced-index-offset 4)
1649
@subsubheading Notes::
1651
A possible definition of @b{array-row-major-index},
1652
with no error-checking, is
1655
(defun array-row-major-index (a &rest subscripts)
1656
(apply #'+ (maplist #'(lambda (x y)
1657
(* (car x) (apply #'* (cdr y))))
1659
(array-dimensions a))))
1662
@node array-total-size, arrayp, array-row-major-index, Arrays Dictionary
1663
@subsection array-total-size [Function]
1665
@code{array-total-size} @i{array} @result{} @i{size}
1667
@subsubheading Arguments and Values::
1669
@i{array}---an @i{array}.
1671
@i{size}---a non-negative @i{integer}.
1673
@subsubheading Description::
1675
Returns the @i{array total size} of the @i{array}.
1677
@subsubheading Examples::
1680
(array-total-size (make-array 4)) @result{} 4
1681
(array-total-size (make-array 4 :fill-pointer 2)) @result{} 4
1682
(array-total-size (make-array 0)) @result{} 0
1683
(array-total-size (make-array '(4 2))) @result{} 8
1684
(array-total-size (make-array '(4 0))) @result{} 0
1685
(array-total-size (make-array '())) @result{} 1
1688
@subsubheading Exceptional Situations::
1690
Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}.
1692
@subsubheading See Also::
1696
@ref{array-dimensions}
1698
@subsubheading Notes::
1700
If the @i{array} is a @i{vector} with a @i{fill pointer},
1701
the @i{fill pointer} is ignored when calculating the @i{array total size}.
1703
Since the product of no arguments is one, the @i{array total size} of a
1704
zero-dimensional @i{array} is one.
1707
(array-total-size x)
1708
@equiv{} (apply #'* (array-dimensions x))
1709
@equiv{} (reduce #'* (array-dimensions x))
1712
@node arrayp, fill-pointer, array-total-size, Arrays Dictionary
1713
@subsection arrayp [Function]
1715
@code{arrayp} @i{object} @result{} @i{generalized-boolean}
1717
@subsubheading Arguments and Values::
1719
@i{object}---an @i{object}.
1721
@i{generalized-boolean}---a @i{generalized boolean}.
1723
@subsubheading Description::
1725
Returns @i{true} if @i{object} is of @i{type} @b{array};
1726
otherwise, returns @i{false}.
1728
@subsubheading Examples::
1731
(arrayp (make-array '(2 3 4) :adjustable t)) @result{} @i{true}
1732
(arrayp (make-array 6)) @result{} @i{true}
1733
(arrayp #*1011) @result{} @i{true}
1734
(arrayp "hi") @result{} @i{true}
1735
(arrayp 'hi) @result{} @i{false}
1736
(arrayp 12) @result{} @i{false}
1739
@subsubheading See Also::
1743
@subsubheading Notes::
1746
(arrayp @i{object}) @equiv{} (typep @i{object} 'array)
1749
@node fill-pointer, row-major-aref, arrayp, Arrays Dictionary
1750
@subsection fill-pointer [Accessor]
1752
@code{fill-pointer} @i{vector} @result{} @i{fill-pointer}
1754
(setf (@code{ fill-pointer} @i{vector}) new-fill-pointer)@*
1756
@subsubheading Arguments and Values::
1758
@i{vector}---a @i{vector} with a @i{fill pointer}.
1760
@i{fill-pointer}, @i{new-fill-pointer}---a @i{valid fill pointer}
1763
@subsubheading Description::
1765
@i{Accesses} the @i{fill pointer} of @i{vector}.
1767
@subsubheading Examples::
1770
(setq a (make-array 8 :fill-pointer 4)) @result{} #(NIL NIL NIL NIL)
1771
(fill-pointer a) @result{} 4
1772
(dotimes (i (length a)) (setf (aref a i) (* i i))) @result{} NIL
1773
a @result{} #(0 1 4 9)
1774
(setf (fill-pointer a) 3) @result{} 3
1775
(fill-pointer a) @result{} 3
1776
a @result{} #(0 1 4)
1777
(setf (fill-pointer a) 8) @result{} 8
1778
a @result{} #(0 1 4 9 NIL NIL NIL NIL)
1781
@subsubheading Exceptional Situations::
1783
Should signal an error of @i{type} @b{type-error}
1784
if @i{vector} is not a @i{vector} with a @i{fill pointer}.
1786
@subsubheading See Also::
1792
@subsubheading Notes::
1794
There is no @i{operator} that will remove a @i{vector}'s @i{fill pointer}.
1796
@node row-major-aref, upgraded-array-element-type, fill-pointer, Arrays Dictionary
1797
@subsection row-major-aref [Accessor]
1799
@code{row-major-aref} @i{array index} @result{} @i{element}
1801
(setf (@code{ row-major-aref} @i{array index}) new-element)@*
1803
@subsubheading Arguments and Values::
1805
@i{array}---an @i{array}.
1807
@i{index}---a @i{valid array row-major index} for the @i{array}.
1809
@i{element}, @i{new-element}---an @i{object}.
1811
@subsubheading Description::
1813
Considers @i{array} as a @i{vector} by viewing its @i{elements}
1814
in row-major order, and returns the @i{element} of that @i{vector}
1815
which is referred to by the given @i{index}.
1817
@b{row-major-aref} is valid for use with @b{setf}.
1819
@subsubheading See Also::
1823
@ref{array-row-major-index}
1825
@subsubheading Notes::
1828
(row-major-aref array index) @equiv{}
1829
(aref (make-array (array-total-size array)
1831
:element-type (array-element-type array))
1834
(aref array i1 i2 ...) @equiv{}
1835
(row-major-aref array (array-row-major-index array i1 i2))
1838
@node upgraded-array-element-type, array-dimension-limit, row-major-aref, Arrays Dictionary
1839
@subsection upgraded-array-element-type [Function]
1841
@code{upgraded-array-element-type} @i{typespec @r{&optional} environment} @result{} @i{upgraded-typespec}
1843
@subsubheading Arguments and Values::
1845
@i{typespec}---a @i{type specifier}.
1847
@i{environment}---an @i{environment} @i{object}.
1848
The default is @b{nil}, denoting the @i{null lexical environment}
1849
and the current @i{global environment}.
1851
@i{upgraded-typespec}---a @i{type specifier}.
1853
@subsubheading Description::
1855
Returns the @i{element type} of
1856
the most @i{specialized} @i{array} representation capable of
1857
holding items of the @i{type} denoted by @i{typespec}.
1859
The @i{typespec} is a @i{subtype} of
1860
(and possibly @i{type equivalent} to)
1861
the @i{upgraded-typespec}.
1863
If @i{typespec} is @b{bit},
1864
the result is @i{type equivalent} to @t{bit}.
1866
If @i{typespec} is @b{base-char},
1867
the result is @i{type equivalent} to @t{base-char}.
1869
If @i{typespec} is @b{character},
1870
the result is @i{type equivalent} to @t{character}.
1872
The purpose of @b{upgraded-array-element-type} is to reveal how
1873
an implementation does its @i{upgrading}.
1875
The @i{environment} is used to expand any @i{derived type specifiers}
1876
that are mentioned in the @i{typespec}.
1878
@subsubheading See Also::
1880
@ref{array-element-type}
1884
@subsubheading Notes::
1886
Except for storage allocation consequences and dealing correctly with the
1887
optional @i{environment} @i{argument},
1888
@b{upgraded-array-element-type} could be defined as:
1891
(defun upgraded-array-element-type (type &optional environment)
1892
(array-element-type (make-array 0 :element-type type)))
1895
@node array-dimension-limit, array-rank-limit, upgraded-array-element-type, Arrays Dictionary
1896
@subsection array-dimension-limit [Constant Variable]
1898
@subsubheading Constant Value::
1904
the exact magnitude of which is @i{implementation-dependent},
1905
but which is not less than @t{1024}.
1907
@subsubheading Description::
1909
The upper exclusive bound on each individual @i{dimension} of an @i{array}.
1911
@subsubheading See Also::
1915
@node array-rank-limit, array-total-size-limit, array-dimension-limit, Arrays Dictionary
1916
@subsection array-rank-limit [Constant Variable]
1918
@subsubheading Constant Value::
1924
the exact magnitude of which is @i{implementation-dependent},
1925
but which is not less than @t{8}.
1927
@subsubheading Description::
1929
The upper exclusive bound on the @i{rank} of an @i{array}.
1931
@subsubheading See Also::
1935
@node array-total-size-limit, simple-vector-p, array-rank-limit, Arrays Dictionary
1936
@subsection array-total-size-limit [Constant Variable]
1938
@subsubheading Constant Value::
1944
the exact magnitude of which is @i{implementation-dependent},
1945
but which is not less than @t{1024}.
1947
@subsubheading Description::
1949
The upper exclusive bound on the @i{array total size} of an @i{array}.
1951
The actual limit on the @i{array total size}
1952
imposed by the @i{implementation}
1953
might vary according the @i{element type} of the @i{array};
1954
in this case, the value of @b{array-total-size-limit}
1955
will be the smallest of these possible limits.
1957
@subsubheading See Also::
1961
@ref{array-element-type}
1963
@node simple-vector-p, svref, array-total-size-limit, Arrays Dictionary
1964
@subsection simple-vector-p [Function]
1966
@code{simple-vector-p} @i{object} @result{} @i{generalized-boolean}
1968
@subsubheading Arguments and Values::
1970
@i{object}---an @i{object}.
1972
@i{generalized-boolean}---a @i{generalized boolean}.
1974
@subsubheading Description::
1976
Returns @i{true} if @i{object} is of @i{type} @b{simple-vector};
1977
otherwise, returns @i{false}..
1979
@subsubheading Examples::
1982
(simple-vector-p (make-array 6)) @result{} @i{true}
1983
(simple-vector-p "aaaaaa") @result{} @i{false}
1984
(simple-vector-p (make-array 6 :fill-pointer t)) @result{} @i{false}
1987
@subsubheading See Also::
1991
@subsubheading Notes::
1994
(simple-vector-p @i{object}) @equiv{} (typep @i{object} 'simple-vector)
1997
@node svref, vector, simple-vector-p, Arrays Dictionary
1998
@subsection svref [Accessor]
2000
@code{svref} @i{simple-vector index} @result{} @i{element}
2002
(setf (@code{ svref} @i{simple-vector index}) new-element)@*
2004
@subsubheading Arguments and Values::
2006
@i{simple-vector}---a @i{simple vector}.
2008
@i{index}---a @i{valid array index} for the @i{simple-vector}.
2010
@i{element}, @i{new-element}---an @i{object}
2011
(whose @i{type} is a @i{subtype}
2012
of the @i{array element type} of the @i{simple-vector}).
2014
@subsubheading Description::
2016
@i{Accesses} the @i{element} of @i{simple-vector} specified by @i{index}.
2018
@subsubheading Examples::
2021
(simple-vector-p (setq v (vector 1 2 'sirens))) @result{} @i{true}
2022
(svref v 0) @result{} 1
2023
(svref v 2) @result{} SIRENS
2024
(setf (svref v 1) 'newcomer) @result{} NEWCOMER
2025
v @result{} #(1 NEWCOMER SIRENS)
2028
@subsubheading See Also::
2037
@ref{Compiler Terminology}
2039
@subsubheading Notes::
2041
@b{svref} is identical to @b{aref}
2042
except that it requires its first argument to be a @i{simple vector}.
2045
(svref @i{v} @i{i}) @equiv{} (aref (the simple-vector @i{v}) @i{i})
2048
@node vector, vector-pop, svref, Arrays Dictionary
2049
@subsection vector [Function]
2051
@code{vector} @i{@r{&rest} objects} @result{} @i{vector}
2053
@subsubheading Arguments and Values::
2055
@i{object}---an @i{object}.
2057
@i{vector}---a @i{vector} of @i{type} @t{(vector t @t{*})}.
2059
@subsubheading Description::
2061
Creates a @i{fresh} @i{simple general vector} whose size
2062
corresponds to the number of @i{objects}.
2064
The @i{vector} is initialized to contain the @i{objects}.
2066
@subsubheading Examples::
2069
(arrayp (setq v (vector 1 2 'sirens))) @result{} @i{true}
2070
(vectorp v) @result{} @i{true}
2071
(simple-vector-p v) @result{} @i{true}
2072
(length v) @result{} 3
2075
@subsubheading See Also::
2079
@subsubheading Notes::
2081
@b{vector} is analogous to @b{list}.
2084
(vector a_1 a_2 ... a_n)
2085
@equiv{} (make-array (list @i{n}) :element-type t
2087
(list a_1 a_2 ... a_n))
2090
@node vector-pop, vector-push, vector, Arrays Dictionary
2091
@subsection vector-pop [Function]
2093
@code{vector-pop} @i{vector} @result{} @i{element}
2095
@subsubheading Arguments and Values::
2097
@i{vector}---a @i{vector} with a @i{fill pointer}.
2099
@i{element}---an @i{object}.
2101
@subsubheading Description::
2103
Decreases the @i{fill pointer} of @i{vector} by one,
2104
and retrieves the @i{element} of @i{vector} that is
2105
designated by the new @i{fill pointer}.
2107
@subsubheading Examples::
2110
(vector-push (setq fable (list 'fable))
2111
(setq fa (make-array 8
2113
:initial-element 'sisyphus))) @result{} 2
2114
(fill-pointer fa) @result{} 3
2115
(eq (vector-pop fa) fable) @result{} @i{true}
2116
(vector-pop fa) @result{} SISYPHUS
2117
(fill-pointer fa) @result{} 1
2120
@subsubheading Side Effects::
2122
The @i{fill pointer} is decreased by one.
2124
@subsubheading Affected By::
2126
The value of the @i{fill pointer}.
2128
@subsubheading Exceptional Situations::
2130
An error of @i{type} @b{type-error} is signaled if @i{vector} does not have a @i{fill pointer}.
2132
If the @i{fill pointer} is zero, @b{vector-pop} signals an error of @i{type} @b{error}.
2134
@subsubheading See Also::
2137
, @b{vector-push-extend},
2140
@node vector-push, vectorp, vector-pop, Arrays Dictionary
2141
@subsection vector-push, vector-push-extend [Function]
2143
@code{vector-push} @i{new-element vector} @result{} @i{new-index-p}
2145
@code{vector-push-extend} @i{new-element vector @r{&optional} extension} @result{} @i{new-index}
2147
@subsubheading Arguments and Values::
2149
@i{new-element}---an @i{object}.
2151
@i{vector}---a @i{vector} with a @i{fill pointer}.
2153
@i{extension}---a positive @i{integer}.
2154
The default is @i{implementation-dependent}.
2156
@i{new-index-p}---a @i{valid array index} for @i{vector}, or @b{nil}.
2158
@i{new-index}---a @i{valid array index} for @i{vector}.
2160
@subsubheading Description::
2162
@b{vector-push} and @b{vector-push-extend} store
2163
@i{new-element} in @i{vector}.
2164
@b{vector-push} attempts to store
2166
in the element of @i{vector} designated by the @i{fill pointer},
2167
and to increase the @i{fill pointer} by one. If the
2168
@t{(>= (fill-pointer @i{vector}) (array-dimension @i{vector} 0))},
2169
neither @i{vector} nor its @i{fill pointer} are affected.
2170
Otherwise, the store and increment take
2171
place and @b{vector-push}
2172
returns the former value of the @i{fill pointer}
2173
which is one less than the one it leaves in @i{vector}.
2175
@b{vector-push-extend} is just like @b{vector-push} except
2176
that if the @i{fill pointer} gets too large, @i{vector} is extended using
2177
@b{adjust-array} so that it can contain more elements.
2179
is the minimum number of elements to be added to @i{vector} if it
2183
@b{vector-push-extend} return the index of @i{new-element} in @i{vector}.
2184
If @t{(>= (fill-pointer @i{vector}) (array-dimension @i{vector} 0))},
2185
@b{vector-push} returns @b{nil}.
2187
@subsubheading Examples::
2190
(vector-push (setq fable (list 'fable))
2191
(setq fa (make-array 8
2193
:initial-element 'first-one))) @result{} 2
2194
(fill-pointer fa) @result{} 3
2195
(eq (aref fa 2) fable) @result{} @i{true}
2196
(vector-push-extend #\X
2199
:element-type 'character
2201
:fill-pointer 3))) @result{} 3
2202
(fill-pointer aa) @result{} 4
2203
(vector-push-extend #\Y aa 4) @result{} 4
2204
(array-total-size aa) @result{} at least 5
2205
(vector-push-extend #\Z aa 4) @result{} 5
2206
(array-total-size aa) @result{} 9 ;(or more)
2209
@subsubheading Affected By::
2210
The value of the @i{fill pointer}.
2212
How @i{vector} was created.
2214
@subsubheading Exceptional Situations::
2216
An error of @i{type} @b{error} is signaled by @b{vector-push-extend}
2217
if it tries to extend @i{vector} and @i{vector} is not @i{actually adjustable}.
2219
An error of @i{type} @b{error} is signaled if @i{vector} does not
2220
have a @i{fill pointer}.
2222
@subsubheading See Also::
2224
@ref{adjustable-array-p}
2230
@node vectorp, bit (Array), vector-push, Arrays Dictionary
2231
@subsection vectorp [Function]
2233
@code{vectorp} @i{object} @result{} @i{generalized-boolean}
2235
@subsubheading Arguments and Values::
2237
@i{object}---an @i{object}.
2239
@i{generalized-boolean}---a @i{generalized boolean}.
2241
@subsubheading Description::
2243
Returns @i{true} if @i{object} is of @i{type} @b{vector};
2244
otherwise, returns @i{false}.
2246
@subsubheading Examples::
2249
(vectorp "aaaaaa") @result{} @i{true}
2250
(vectorp (make-array 6 :fill-pointer t)) @result{} @i{true}
2251
(vectorp (make-array '(2 3 4))) @result{} @i{false}
2252
(vectorp #*11) @result{} @i{true}
2253
(vectorp #b11) @result{} @i{false}
2256
@subsubheading Notes::
2258
(vectorp @i{object}) @equiv{} (typep @i{object} 'vector)
2261
@node bit (Array), bit-and, vectorp, Arrays Dictionary
2262
@subsection bit, sbit [Accessor]
2264
@code{bit} @i{bit-array @r{&rest} subscripts} @result{} @i{bit}
2266
@code{sbit} @i{bit-array @r{&rest} subscripts} @result{} @i{bit}
2268
(setf (@code{bit} @i{bit-array @r{&rest} subscripts}) new-bit)@*(setf (@code{sbit} @i{bit-array @r{&rest} subscripts}) new-bit)@*
2270
@subsubheading Arguments and Values::
2272
@i{bit-array}---for @b{bit}, a @i{bit array};
2273
for @b{sbit}, a @i{simple bit array}.
2275
@i{subscripts}---a @i{list} of @i{valid array indices}
2276
for the @i{bit-array}.
2278
@i{bit}---a @i{bit}.
2280
@subsubheading Description::
2282
@b{bit} and @b{sbit} @i{access} the @i{bit-array}
2283
@i{element} specified by @i{subscripts}.
2285
These @i{functions} ignore the @i{fill pointer} when @i{accessing} @i{elements}.
2287
@subsubheading Examples::
2290
(bit (setq ba (make-array 8
2292
:initial-element 1))
2294
(setf (bit ba 3) 0) @result{} 0
2295
(bit ba 3) @result{} 0
2296
(sbit ba 5) @result{} 1
2297
(setf (sbit ba 5) 1) @result{} 1
2298
(sbit ba 5) @result{} 1
2301
@subsubheading See Also::
2306
@ref{Compiler Terminology}
2308
@subsubheading Notes::
2310
@b{bit} and @b{sbit} are like @b{aref}
2311
except that they require @i{arrays} to be
2312
a @i{bit array} and a @i{simple bit array}, respectively.
2314
@b{bit} and @b{sbit}, unlike @b{char} and @b{schar},
2315
allow the first argument to be an @i{array} of any @i{rank}.
2317
@node bit-and, bit-vector-p, bit (Array), Arrays Dictionary
2318
@subsection bit-and, bit-andc1, bit-andc2, bit-eqv,
2319
@subheading bit-ior, bit-nand, bit-nor, bit-not, bit-orc1, bit-orc2, bit-xor
2324
@code{bit-and} @i{bit-array1 bit-array2 @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2326
@code{bit-andc1} @i{bit-array1 bit-array2 @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2328
@code{bit-andc2} @i{bit-array1 bit-array2 @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2330
@code{bit-eqv} @i{bit-array1 bit-array2 @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2332
@code{bit-ior} @i{bit-array1 bit-array2 @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2334
@code{bit-nand} @i{bit-array1 bit-array2 @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2336
@code{bit-nor} @i{bit-array1 bit-array2 @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2338
@code{bit-orc1} @i{bit-array1 bit-array2 @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2340
@code{bit-orc2} @i{bit-array1 bit-array2 @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2342
@code{bit-xor} @i{bit-array1 bit-array2 @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2344
@code{bit-not} @i{bit-array @r{&optional} opt-arg} @result{} @i{resulting-bit-array}
2346
@subsubheading Arguments and Values::
2348
@i{bit-array}, @i{bit-array1}, @i{bit-array2}---a @i{bit array}.
2350
@i{Opt-arg}---a @i{bit array}, or @b{t}, or @b{nil}.
2351
The default is @b{nil}.
2353
@i{Bit-array}, @i{bit-array1}, @i{bit-array2}, and @i{opt-arg}
2354
(if an @i{array}) must all be of the same @i{rank} and @i{dimensions}.
2356
@i{resulting-bit-array}---a @i{bit array}.
2358
@subsubheading Description::
2360
These functions perform
2361
bit-wise logical operations on @i{bit-array1} and @i{bit-array2}
2362
and return an @i{array}
2363
of matching @i{rank} and @i{dimensions},
2364
such that any given bit of the result
2365
is produced by operating on corresponding bits from each of the arguments.
2367
In the case of @b{bit-not}, an @i{array}
2368
of @i{rank} and @i{dimensions} matching @i{bit-array}
2369
is returned that contains a copy of @i{bit-array}
2370
with all the bits inverted.
2372
If @i{opt-arg} is of type @t{(array bit)} the contents of the
2373
result are destructively placed into @i{opt-arg}.
2374
If @i{opt-arg} is the symbol @b{t},
2375
@i{bit-array} or @i{bit-array1} is replaced with the result;
2376
if @i{opt-arg} is @b{nil} or omitted, a new @i{array} is created
2377
to contain the result.
2379
Figure 15--4 indicates the logical operation
2380
performed by each of the @i{functions}.
2386
@w{@b{Function} @b{Operation} }
2387
@w{_______________________________________________________________________________________________________}
2389
@w{@b{bit-and} and }
2390
@w{@b{bit-eqv} equivalence (exclusive nor) }
2391
@w{@b{bit-not} complement }
2392
@w{@b{bit-ior} inclusive or }
2393
@w{@b{bit-xor} exclusive or }
2394
@w{@b{bit-nand} complement of @i{bit-array1} and @i{bit-array2} }
2395
@w{@b{bit-nor} complement of @i{bit-array1} or @i{bit-array2} }
2396
@w{@b{bit-andc1} and complement of @i{bit-array1} with @i{bit-array2}}
2397
@w{@b{bit-andc2} and @i{bit-array1} with complement of @i{bit-array2}}
2398
@w{@b{bit-orc1} or complement of @i{bit-array1} with @i{bit-array2} }
2399
@w{@b{bit-orc2} or @i{bit-array1} with complement of @i{bit-array2} }
2400
@w{@w{ Figure 15--3: Bit-wise Logical Operations on Bit Arrays}
2405
@subsubheading Examples::
2407
(bit-and (setq ba #*11101010) #*01101011) @result{} #*01101010
2408
(bit-and #*1100 #*1010) @result{} #*1000
2409
(bit-andc1 #*1100 #*1010) @result{} #*0010
2410
(setq rba (bit-andc2 ba #*00110011 t)) @result{} #*11001000
2411
(eq rba ba) @result{} @i{true}
2412
(bit-not (setq ba #*11101010)) @result{} #*00010101
2413
(setq rba (bit-not ba
2414
(setq tba (make-array 8
2415
:element-type 'bit))))
2416
@result{} #*00010101
2417
(equal rba tba) @result{} @i{true}
2418
(bit-xor #*1100 #*1010) @result{} #*0110
2421
@subsubheading See Also::
2426
@node bit-vector-p, simple-bit-vector-p, bit-and, Arrays Dictionary
2427
@subsection bit-vector-p [Function]
2429
@code{bit-vector-p} @i{object} @result{} @i{generalized-boolean}
2431
@subsubheading Arguments and Values::
2433
@i{object}---an @i{object}.
2435
@i{generalized-boolean}---a @i{generalized boolean}.
2437
@subsubheading Description::
2439
Returns @i{true} if @i{object} is of @i{type} @b{bit-vector};
2440
otherwise, returns @i{false}.
2442
@subsubheading Examples::
2445
(bit-vector-p (make-array 6
2447
:fill-pointer t)) @result{} @i{true}
2448
(bit-vector-p #*) @result{} @i{true}
2449
(bit-vector-p (make-array 6)) @result{} @i{false}
2452
@subsubheading See Also::
2456
@subsubheading Notes::
2459
(bit-vector-p @i{object}) @equiv{} (typep @i{object} 'bit-vector)
2462
@node simple-bit-vector-p, , bit-vector-p, Arrays Dictionary
2463
@subsection simple-bit-vector-p [Function]
2465
@code{simple-bit-vector-p} @i{object} @result{} @i{generalized-boolean}
2467
@subsubheading Arguments and Values::
2469
@i{object}---an @i{object}.
2471
@i{generalized-boolean}---a @i{generalized boolean}.
2473
@subsubheading Description::
2475
Returns @i{true} if @i{object} is of @i{type} @b{simple-bit-vector};
2476
otherwise, returns @i{false}.
2478
@subsubheading Examples::
2480
(simple-bit-vector-p (make-array 6)) @result{} @i{false}
2481
(simple-bit-vector-p #*) @result{} @i{true}
2484
@subsubheading See Also::
2486
@ref{simple-vector-p}
2488
@subsubheading Notes::
2490
(simple-bit-vector-p @i{object}) @equiv{} (typep @i{object} 'simple-bit-vector)
2493
@c end of including dict-arrays
2495
@c %**end of chapter
added
removed
info/chap-15.texi
