An array contains a set of objects called elements that can be referenced individually according to a rectilinear coordinate system.
An array element is referred to by a (possibly empty) series of indices. The length of the series must equal the rank of the array.
Each index must be a non-negative fixnum
less than the corresponding array dimension. Array indexing is zero-origin.
An axis of an array is called a dimension @IGindex{dimension} .
Each dimension is a non-negative
fixnum;
if any dimension of an array is zero, the array has no elements. It is permissible for a dimension to be zero, in which case the array has no elements, and any attempt to access an element is an error. However, other properties of the array, such as the dimensions themselves, may be used.
An implementation may impose a limit on dimensions of an array, but there is a minimum requirement on that limit. See the variable array-dimension-limit.
An array can have any number of dimensions (including zero). The number of dimensions is called the rank @IGindex{rank} .
If the rank of an array is zero then the array is said to have no dimensions, and the product of the dimensions (see array-total-size) is then 1; a zero-rank array therefore has a single element.
An array of rank one (i.e., a one-dimensional array) is called a vector @IGindex{vector} .
A fill pointer @IGindex{fill pointer} is a non-negative integer no larger than the total number of elements in a vector. Not all vectors have fill pointers. See the functions make-array and adjust-array.
An element of a vector is said to be active @IGindex{active} if it has an index that is greater than or equal to zero, but less than the fill pointer (if any). For an array that has no fill pointer, all elements are considered active.
Only vectors may have fill pointers; multidimensional arrays may not. A multidimensional array that is displaced to a vector that has a fill pointer can be created.
Multidimensional arrays store their components in row-major order; that is, internally a multidimensional array is stored as a one-dimensional array, with the multidimensional index sets ordered lexicographically, last index varying fastest.
An implementation may impose a limit on the rank of an array, but there is a minimum requirement on that limit. See the variable array-rank-limit.
An array can be a general array, meaning each element may be any object, or it may be a specialized array, meaning that each element must be of a restricted type.
The phrasing "an array specialized to type <<type>>" is sometimes used to emphasize the element type of an array. This phrasing is tolerated even when the <<type>> is t, even though an array specialized to type t is a general array, not a specialized array.
Figure 15--1 lists some defined names that are applicable to array creation, access, and information operations.
adjust-array array-in-bounds-p svref adjustable-array-p array-rank upgraded-array-element-type aref array-rank-limit upgraded-complex-part-type array-dimension array-row-major-index vector array-dimension-limit array-total-size vector-pop array-dimensions array-total-size-limit vector-push array-element-type fill-pointer vector-push-extend array-has-fill-pointer-p make-array
Figure 15--1: General Purpose Array-Related Defined Names
The upgraded array element type @IGindex{upgraded array element type} of a type T_1 is a type T_2 that is a supertype of T_1 and that is used instead of T_1 whenever T_1 is used as an array element type for object creation or type discrimination.
During creation of an array, the element type that was requested is called the expressed array element type @IGindex{expressed array element type} . The upgraded array element type of the expressed array element type becomes the actual array element type @IGindex{actual array element type} of the array that is created.
Type upgrading implies a movement upwards in the type hierarchy lattice. A type is always a subtype of its upgraded array element type. Also, if a type T_x is a subtype of another type T_y, then the upgraded array element type of T_x must be a subtype of the upgraded array element type of T_y. Two disjoint types can be upgraded to the same type.
The upgraded array element type T_2 of a type T_1 is a function only of T_1 itself; that is, it is independent of any other property of the array for which T_2 will be used, such as rank, adjustability, fill pointers, or displacement. The function upgraded-array-element-type can be used by conforming programs to predict how the implementation will upgrade a given type.
Vectors whose elements are restricted to type
character or a subtype of character
are called strings @IGindex{string} . Strings are of type string. Figure 15--2 lists some defined names related to strings.
Strings are specialized arrays and might logically have been included in this chapter. However, for purposes of readability most information about strings does not appear in this chapter; see instead section Strings.
char string-equal string-upcase make-string string-greaterp string/= nstring-capitalize string-left-trim string< nstring-downcase string-lessp string<= nstring-upcase string-not-equal string= schar string-not-greaterp string> string string-not-lessp string>= string-capitalize string-right-trim string-downcase string-trim
Figure 15--2: Operators that Manipulate Strings
Vectors whose elements are restricted to type bit are called bit vectors @IGindex{bit vector} . Bit vectors are of type bit-vector. Figure 15--3 lists some defined names for operations on bit arrays.
bit bit-ior bit-orc2 bit-and bit-nand bit-xor bit-andc1 bit-nor sbit bit-andc2 bit-not bit-eqv bit-orc1
Figure 15--3: Operators that Manipulate Bit Arrays
array, t
An array contains objects arranged according to a Cartesian coordinate system. An array provides mappings from a set of
fixnums
\left{i_0,i_1,\dots,i_{r-1}\right} to corresponding elements of the array, where 0 \le i_j < d_j, r is the rank of the array, and d_j is the size of dimension j of the array.
When an array is created, the program requesting its creation may declare that all elements are of a particular type, called the expressed array element type. The implementation is permitted to upgrade this type in order to produce the actual array element type, which is the element type for the array is actually specialized. See the function upgraded-array-element-type.
Specializing.
(array{[{element-type | *} [dimension-spec]]})
dimension-spec ::=rank | * | ({dimension | *}{*)}
dimension---a valid array dimension.
element-type---a type specifier.
rank---a non-negative fixnum.
This denotes the set of arrays whose element type, rank, and dimensions match any given element-type, rank, and dimensions. Specifically:
If element-type is the symbol *, arrays are not excluded on the basis of their element type. Otherwise, only those arrays are included whose actual array element type
is the result of upgrading element-type; see section Array Upgrading.
If the dimension-spec is a rank, the set includes only those arrays having that rank. If the dimension-spec is a list of dimensions, the set includes only those arrays having a rank given by the length of the dimensions, and having the indicated dimensions; in this case, * matches any value for the corresponding dimension. If the dimension-spec is the symbol *, the set is not restricted on the basis of rank or dimension.
*print-array*, section aref [Accessor] , section make-array [Function] , vector, section Sharpsign A, section Printing Other Arrays
Note that the type (array t) is a proper subtype of the type (array *). The reason is that the type (array t) is the set of arrays that can hold any object (the elements are of type t, which includes all objects). On the other hand, the type (array *) is the set of all arrays whatsoever, including for example arrays that can hold only characters. The type (array character) is not a subtype of the type (array t); the two sets are disjoint because the type (array character) is not the set of all arrays that can hold characters, but rather the set of arrays that are specialized to hold precisely characters and no other objects.
simple-array, array, t
The type of an array that is not displaced to another array, has no fill pointer, and is not expressly adjustable is a subtype of type simple-array. The concept of a simple array exists to allow the implementation to use a specialized representation and to allow the user to declare that certain values will always be simple arrays.
The types simple-vector, simple-string, and simple-bit-vector are disjoint subtypes of type simple-array, for they respectively mean (simple-array t (*)), the union of all (simple-array c (*)) for any c being a subtype of type character, and (simple-array bit (*)).
Specializing.
(simple-array{[{element-type | *} [dimension-spec]]})
dimension-spec ::=rank | * | ({dimension | *}{*)}
dimension---a valid array dimension.
element-type---a type specifier.
rank---a non-negative fixnum.
This compound type specifier is treated exactly as the corresponding compound type specifier for type array would be treated, except that the set is further constrained to include only simple arrays.
It is implementation-dependent whether displaced arrays, vectors with fill pointers, or arrays that are actually adjustable are simple arrays.
(simple-array *) refers to all simple arrays regardless of element type, (simple-array type-specifier) refers only to those simple arrays that can result from giving type-specifier as the :element-type argument to make-array.
vector, array, sequence, t
Any one-dimensional array is a vector.
The type vector is a subtype of type array; for all types x, (vector x) is the same as (array x (*)).
The type (vector t), the type string, and the type bit-vector are disjoint subtypes of type vector.
Specializing.
(vector{[{element-type | *} [{size | *}{]]}})
size---a non-negative fixnum.
element-type---a type specifier.
This denotes the set of specialized vectors whose element type and dimension match the specified values. Specifically:
If element-type is the symbol *, vectors are not excluded on the basis of their element type. Otherwise, only those vectors are included whose actual array element type
is the result of upgrading element-type; see section Array Upgrading.
If a size is specified, the set includes only those vectors whose only dimension is size. If the symbol * is specified instead of a size, the set is not restricted on the basis of dimension.
section Required Kinds of Specialized Arrays, section Sharpsign Left-Parenthesis, section Printing Other Vectors, section Sharpsign A
The type (vector e s) is equivalent to the type (array e (s)).
The type (vector bit) has the name bit-vector.
The union of all types (vector C), where C is any subtype of character, has the name string.
(vector *) refers to all vectors regardless of element type, (vector type-specifier) refers only to those vectors that can result from giving type-specifier as the :element-type argument to make-array.
simple-vector, vector, simple-array, array, sequence, t
The type of a vector that is not displaced to another array, has no fill pointer, is not expressly adjustable and is able to hold elements of any type is a subtype of type simple-vector.
The type simple-vector is a subtype of type vector, and is a subtype of type (vector t).
Specializing.
(simple-vector{[size]})
size---a non-negative fixnum, or the symbol *. The default is the symbol *.
This is the same as (simple-array t (size)).
bit-vector, vector, array, sequence, t
A bit vector is a vector the element type of which is bit.
The type bit-vector is a subtype of type vector, for bit-vector means (vector bit).
Abbreviating.
(bit-vector{[size]})
size---a non-negative fixnum, or the symbol *.
This denotes the same type as the type (array bit (size)); that is, the set of bit vectors of size size.
section Sharpsign Asterisk, section Printing Bit Vectors, section Required Kinds of Specialized Arrays
simple-bit-vector, bit-vector, vector, simple-array, array, sequence, t
The type of a bit vector that is not displaced to another array, has no fill pointer, and is not expressly adjustable is a subtype of type simple-bit-vector.
Abbreviating.
(simple-bit-vector{[size]})
size---a non-negative fixnum, or the symbol *. The default is the symbol *.
This denotes the same type as the type (simple-array bit (size)); that is, the set of simple bit vectors of size size.
make-array dimensions {&key element-type
initial-element
initial-contents
adjustable
fill-pointer
displaced-to
displaced-index-offset}
=> new-array
dimensions---a designator for a list of valid array dimensions.
element-type---a type specifier. The default is t.
initial-element---an object.
initial-contents---an object.
adjustable---a generalized boolean. The default is nil.
fill-pointer---a valid fill pointer for the array to be created, or t or nil. The default is nil.
displaced-to---an array or nil. The default is nil. This option must not be supplied if either initial-element or initial-contents is supplied.
displaced-index-offset---a valid array row-major index for displaced-to. The default is 0. This option must not be supplied unless a non-nil displaced-to is supplied.
new-array---an array.
Creates and returns an array constructed of the most specialized type that can accommodate elements of type given by element-type. If dimensions is nil then a zero-dimensional array is created.
Dimensions represents the dimensionality of the new array.
element-type indicates the type of the elements intended to be stored in the new-array. The new-array can actually store any objects of the type which results from upgrading element-type; see section Array Upgrading.
If initial-element is supplied, it is used to initialize each element of new-array. If initial-element is supplied, it must be of the type given by element-type. initial-element cannot be supplied if either the :initial-contents option is supplied or displaced-to is non-nil. If initial-element is not supplied,
the consequences of later reading an uninitialized element of new-array are undefined
unless either initial-contents is supplied or displaced-to is non-nil.
initial-contents is used to initialize the contents of array. For example:
(make-array '(4 2 3) :initial-contents
'(((a b c) (1 2 3))
((d e f) (3 1 2))
((g h i) (2 3 1))
((j k l) (0 0 0))))
initial-contents is composed of a nested structure of sequences. The numbers of levels in the structure must equal the rank of array. Each leaf of the nested structure must be of the type given by element-type. If array is zero-dimensional, then initial-contents specifies the single element. Otherwise, initial-contents must be a sequence whose length is equal to the first dimension; each element must be a nested structure for an array whose dimensions are the remaining dimensions, and so on. Initial-contents cannot be supplied if either initial-element is supplied or displaced-to is non-nil. If initial-contents is not supplied,
the consequences of later reading an uninitialized element of new-array are undefined
unless either initial-element is supplied or displaced-to is non-nil.
If adjustable is non-nil, the array is expressly adjustable (and so actually adjustable); otherwise, the array is not expressly adjustable (and it is implementation-dependent whether the array is actually adjustable).
If fill-pointer is non-nil, the array must be one-dimensional; that is, the array must be a vector. If fill-pointer is t, the length of the vector is used to initialize the fill pointer. If fill-pointer is an integer, it becomes the initial fill pointer for the vector.
If displaced-to is non-nil, make-array will create a displaced array and displaced-to is the target of that displaced array. In that case, the consequences are undefined if the actual array element type of displaced-to is not type equivalent to the actual array element type of the array being created. If displaced-to is nil, the array is not a displaced array.
The displaced-index-offset is made to be the index offset of the array. When an array A is given as the :displaced-to argument to make-array when creating array B, then array B is said to be displaced to array A. The total number of elements in an array, called the total size of the array, is calculated as the product of all the dimensions. It is required that the total size of A be no smaller than the sum of the total size of B plus the offset n supplied by the displaced-index-offset. The effect of displacing is that array B does not have any elements of its own, but instead maps accesses to itself into accesses to array A. The mapping treats both arrays as if they were one-dimensional by taking the elements in row-major order, and then maps an access to element k of array B to an access to element k+n of array A.
If make-array is called with adjustable, fill-pointer, and displaced-to each nil, then the result is a simple array.
If make-array is called with one or more of adjustable, fill-pointer, or displaced-to being true, whether the resulting array is a simple array is implementation-dependent.
When an array A is given as the :displaced-to argument to make-array when creating array B, then array B is said to be displaced to array A. The total number of elements in an array, called the total size of the array, is calculated as the product of all the dimensions. The consequences are unspecified if the total size of A is smaller than the sum of the total size of B plus the offset n supplied by the displaced-index-offset. The effect of displacing is that array B does not have any elements of its own, but instead maps accesses to itself into accesses to array A. The mapping treats both arrays as if they were one-dimensional by taking the elements in row-major order, and then maps an access to element k of array B to an access to element k+n of array A.
(make-array 5) ;; Creates a one-dimensional array of five elements.
(make-array '(3 4) :element-type '(mod 16)) ;; Creates a
;;two-dimensional array, 3 by 4, with four-bit elements.
(make-array 5 :element-type 'single-float) ;; Creates an array of single-floats.
(make-array nil :initial-element nil) => #0ANIL
(make-array 4 :initial-element nil) => #(NIL NIL NIL NIL)
(make-array '(2 4)
:element-type '(unsigned-byte 2)
:initial-contents '((0 1 2 3) (3 2 1 0)))
=> #2A((0 1 2 3) (3 2 1 0))
(make-array 6
:element-type 'character
:initial-element #\a
:fill-pointer 3) => "aaa"
The following is an example of making a displaced array.
(setq a (make-array '(4 3)))
=> #<ARRAY 4x3 simple 32546632>
(dotimes (i 4)
(dotimes (j 3)
(setf (aref a i j) (list i 'x j '= (* i j)))))
=> NIL
(setq b (make-array 8 :displaced-to a
:displaced-index-offset 2))
=> #<ARRAY 8 indirect 32550757>
(dotimes (i 8)
(print (list i (aref b i))))
|> (0 (0 X 2 = 0))
|> (1 (1 X 0 = 0))
|> (2 (1 X 1 = 1))
|> (3 (1 X 2 = 2))
|> (4 (2 X 0 = 0))
|> (5 (2 X 1 = 2))
|> (6 (2 X 2 = 4))
|> (7 (3 X 0 = 0))
=> NIL
The last example depends on the fact that arrays are, in effect, stored in row-major order.
(setq a1 (make-array 50))
=> #<ARRAY 50 simple 32562043>
(setq b1 (make-array 20 :displaced-to a1 :displaced-index-offset 10))
=> #<ARRAY 20 indirect 32563346>
(length b1) => 20
(setq a2 (make-array 50 :fill-pointer 10))
=> #<ARRAY 50 fill-pointer 10 46100216>
(setq b2 (make-array 20 :displaced-to a2 :displaced-index-offset 10))
=> #<ARRAY 20 indirect 46104010>
(length a2) => 10
(length b2) => 20
(setq a3 (make-array 50 :fill-pointer 10))
=> #<ARRAY 50 fill-pointer 10 46105663>
(setq b3 (make-array 20 :displaced-to a3 :displaced-index-offset 10
:fill-pointer 5))
=> #<ARRAY 20 indirect, fill-pointer 5 46107432>
(length a3) => 10
(length b3) => 5
section adjustable-array-p [Function] , section aref [Accessor] , section arrayp [Function] , section array-element-type [Function] , section array-rank-limit [Constant Variable] , section array-dimension-limit [Constant Variable] , section fill-pointer [Accessor] , section upgraded-array-element-type [Function]
There is no specified way to create an array for which adjustable-array-p definitely returns false. There is no specified way to create an array that is not a simple array.
adjust-array array new-dimensions {&key element-type
initial-element
initial-contents
fill-pointer
displaced-to
displaced-index-offset}
=> adjusted-array
array---an array.
new-dimensions---a valid array dimension or a list of valid array dimensions.
element-type---a type specifier.
initial-element---an object. Initial-element must not be supplied if either initial-contents or displaced-to is supplied.
initial-contents---an object. If array has rank greater than zero, then initial-contents is composed of nested sequences, the depth of which must equal the rank of array. Otherwise, array is zero-dimensional and initial-contents supplies the single element. initial-contents must not be supplied if either initial-element or displaced-to is given.
fill-pointer---a valid fill pointer for the array to be created, or t, or nil. The default is nil.
displaced-to---an array or nil. initial-elements and initial-contents must not be supplied if displaced-to is supplied.
displaced-index-offset---an object of type (fixnum 0 n) where n is (array-total-size displaced-to). displaced-index-offset may be supplied only if displaced-to is supplied.
adjusted-array---an array.
adjust-array changes the dimensions or elements of array. The result is an array of the same type and rank as array, that is either the modified array, or a newly created array to which array can be displaced, and that has the given new-dimensions.
New-dimensions specify the size of each dimension of array.
Element-type specifies the type of the elements of the resulting array. If element-type is supplied, the consequences are unspecified if the upgraded array element type of element-type is not the same as the actual array element type of array.
If initial-contents is supplied, it is treated as for make-array. In this case none of the original contents of array appears in the resulting array.
If fill-pointer is an integer, it becomes the fill pointer for the resulting array. If fill-pointer is the symbol t, it indicates that the size of the resulting array should be used as the fill pointer. If fill-pointer is nil, it indicates that the fill pointer should be left as it is.
If displaced-to non-nil, a displaced array is created. The resulting array shares its contents with the array given by displaced-to. The resulting array cannot contain more elements than the array it is displaced to. If displaced-to is not supplied or nil, the resulting array is not a displaced array. If array A is created displaced to array B and subsequently array B is given to adjust-array, array A will still be displaced to array B. Although array might be a displaced array, the resulting array is not a displaced array unless displaced-to is supplied and not nil.
The interaction between adjust-array and displaced arrays is as follows given three arrays, A, B, and~C:
(adjust-array A ...)The dimensions of A are altered, and the contents rearranged as appropriate. Additional elements of A are taken from initial-element. The use of initial-contents causes all old contents to be discarded.
(adjust-array A ... :displaced-to C)None of the original contents of A appears in A afterwards; A now contains the contents of C, without any rearrangement of C.
(adjust-array A ... :displaced-to B) (adjust-array A ... :displaced-to C)B and C might be the same. The contents of B do not appear in A afterward unless such contents also happen to be in C If displaced-index-offset is not supplied in the adjust-array call, it defaults to zero; the old offset into B is not retained.
(adjust-array A ... :displaced-to B) (adjust-array A ... :displaced-to nil)A gets a new "data region," and contents of B are copied into it as appropriate to maintain the existing old contents; additional elements of A are taken from initial-element if supplied. However, the use of initial-contents causes all old contents to be discarded.
If displaced-index-offset is supplied, it specifies the offset of the resulting array from the beginning of the array that it is displaced to. If displaced-index-offset is not supplied, the offset is~0. The size of the resulting array plus the offset value cannot exceed the size of the array that it is displaced to.
If only new-dimensions and an initial-element argument are supplied, those elements of array that are still in bounds appear in the resulting array. The elements of the resulting array that are not in the bounds of array are initialized to initial-element; if initial-element is not provided,
the consequences of later reading any such new element of new-array before it has been initialized are undefined.
If initial-contents or displaced-to is supplied, then none of the original contents of array appears in the new array.
The consequences are unspecified if array is adjusted to a size smaller than its fill pointer without supplying the fill-pointer argument so that its fill-pointer is properly adjusted in the process.
If A is displaced to B, the consequences are unspecified if B is adjusted in such a way that it no longer has enough elements to satisfy A.
If adjust-array is applied to an array that is actually adjustable, the array returned is identical to array. If the array returned by adjust-array is distinct from array, then the argument array is unchanged.
Note that if an array A is displaced to another array B, and B is displaced to another array C, and B is altered by adjust-array, A must now refer to the adjust contents of B. This means that an implementation cannot collapse the chain to make A refer to C directly and forget that the chain of reference passes through B. However, caching techniques are permitted as long as they preserve the semantics specified here.
(adjustable-array-p
(setq ada (adjust-array
(make-array '(2 3)
:adjustable t
:initial-contents '((a b c) (1 2 3)))
'(4 6)))) => T
(array-dimensions ada) => (4 6)
(aref ada 1 1) => 2
(setq beta (make-array '(2 3) :adjustable t))
=> #2A((NIL NIL NIL) (NIL NIL NIL))
(adjust-array beta '(4 6) :displaced-to ada)
=> #2A((A B C NIL NIL NIL)
(1 2 3 NIL NIL NIL)
(NIL NIL NIL NIL NIL NIL)
(NIL NIL NIL NIL NIL NIL))
(array-dimensions beta) => (4 6)
(aref beta 1 1) => 2
Suppose that the 4-by-4 array in m looks like this:
#2A(( alpha beta gamma delta )
( epsilon zeta eta theta )
( iota kappa lambda mu )
( nu xi omicron pi ))
Then the result of
(adjust-array m '(3 5) :initial-element 'baz)
is a 3-by-5 array with contents
#2A(( alpha beta gamma delta baz )
( epsilon zeta eta theta baz )
( iota kappa lambda mu baz ))
An error of type error is signaled if fill-pointer is supplied and non-nil but array has no fill pointer.
section adjustable-array-p [Function] , section make-array [Function] , section array-dimension-limit [Constant Variable] , section array-total-size-limit [Constant Variable] , array
adjustable-array-p array => generalized-boolean
array---an array.
generalized-boolean---a generalized boolean.
Returns true if and only if adjust-array could return a value which is identical to array when given that array as its first argument.
(adjustable-array-p
(make-array 5
:element-type 'character
:adjustable t
:fill-pointer 3)) => true
(adjustable-array-p (make-array 4)) => implementation-dependent
Should signal an error of type type-error if its argument is not an array.
section adjust-array [Function] , section make-array [Function]
aref array {&rest subscripts} => element
(setf ( aref array {&rest subscripts}) new-element)
array---an array.
subscripts---a list of valid array indices for the array.
element, new-element---an object.
Accesses the array element specified by the subscripts. If no subscripts are supplied and array is zero rank, aref accesses the sole element of array.
aref ignores fill pointers. It is permissible to use aref to access any array element, whether active or not.
If the variable foo names a 3-by-5 array, then the first index could be 0, 1, or 2, and then second index could be 0, 1, 2, 3, or 4. The array elements can be referred to by using the function aref; for example, (aref foo 2 1) refers to element (2, 1) of the array.
(aref (setq alpha (make-array 4)) 3) => implementation-dependent
(setf (aref alpha 3) 'sirens) => SIRENS
(aref alpha 3) => SIRENS
(aref (setq beta (make-array '(2 4)
:element-type '(unsigned-byte 2)
:initial-contents '((0 1 2 3) (3 2 1 0))))
1 2) => 1
(setq gamma '(0 2))
(apply #'aref beta gamma) => 2
(setf (apply #'aref beta gamma) 3) => 3
(apply #'aref beta gamma) => 3
(aref beta 0 2) => 3
section bit [Type] , @xref{char; schar} , section elt [Accessor] , section row-major-aref [Accessor] , section svref [Accessor] ,
section Compiler Terminology
array-dimension array axis-number => dimension
array---an array.
axis-number---an integer greater than or equal to zero and less than the rank of the array.
dimension---a non-negative integer.
array-dimension returns the axis-number dimension_1 of array. (Any fill pointer is ignored.)
(array-dimension (make-array 4) 0) => 4 (array-dimension (make-array '(2 3)) 1) => 3
None.
section array-dimensions [Function] , section length [Function]
(array-dimension array n) == (nth n (array-dimensions array))
array-dimensions array => dimensions
array---an array.
dimensions---a list of integers.
Returns a list of the dimensions of array. (If array is a vector with a fill pointer, that fill pointer is ignored.)
(array-dimensions (make-array 4)) => (4) (array-dimensions (make-array '(2 3))) => (2 3) (array-dimensions (make-array 4 :fill-pointer 2)) => (4)
Should signal an error of type type-error if its argument is not an array.
section array-dimension [Function]
array-element-type array => typespec
array---an array.
typespec---a type specifier.
Returns a type specifier which represents the actual array element type of the array, which is the set of objects that such an array can hold. (Because of array upgrading, this type specifier can in some cases denote a supertype of the expressed array element type of the array.)
(array-element-type (make-array 4)) => T (array-element-type (make-array 12 :element-type '(unsigned-byte 8))) => implementation-dependent (array-element-type (make-array 12 :element-type '(unsigned-byte 5))) => implementation-dependent
(array-element-type (make-array 5 :element-type '(mod 5)))
could be (mod 5), (mod 8), fixnum, t, or any other type of which (mod 5) is a subtype.
The implementation.
Should signal an error of type type-error if its argument is not an array.
array, section make-array [Function] , section subtypep [Function] , section upgraded-array-element-type [Function]
array-has-fill-pointer-p array => generalized-boolean
array---an array.
generalized-boolean---a generalized boolean.
Returns true if array has a fill pointer; otherwise returns false.
(array-has-fill-pointer-p (make-array 4)) => implementation-dependent
(array-has-fill-pointer-p (make-array '(2 3))) => false
(array-has-fill-pointer-p
(make-array 8
:fill-pointer 2
:initial-element 'filler)) => true
Should signal an error of type type-error if its argument is not an array.
section make-array [Function] , section fill-pointer [Accessor]
Since arrays of rank other than one cannot have a fill pointer, array-has-fill-pointer-p always returns nil when its argument is such an array.
array-displacement array => displaced-to, displaced-index-offset
array---an array.
displaced-to---an array or nil.
displaced-index-offset---a non-negative fixnum.
If the array is a displaced array, returns the values of the :displaced-to and :displaced-index-offset options for the array (see the functions make-array and adjust-array). If the array is not a displaced array, nil and 0 are returned.
If array-displacement is called on an array for which a non-nil object was provided as the :displaced-to argument to make-array or adjust-array, it must return that object as its first value. It is implementation-dependent whether array-displacement returns a non-nil primary value for any other array.
(setq a1 (make-array 5)) => #<ARRAY 5 simple 46115576>
(setq a2 (make-array 4 :displaced-to a1
:displaced-index-offset 1))
=> #<ARRAY 4 indirect 46117134>
(array-displacement a2)
=> #<ARRAY 5 simple 46115576>, 1
(setq a3 (make-array 2 :displaced-to a2
:displaced-index-offset 2))
=> #<ARRAY 2 indirect 46122527>
(array-displacement a3)
=> #<ARRAY 4 indirect 46117134>, 2
Should signal an error of type type-error if array is not an array.
section make-array [Function]
array-in-bounds-p array {&rest subscripts} => generalized-boolean
array---an array.
subscripts---a list of integers of length equal to the rank of the array.
generalized-boolean---a generalized boolean.
Returns true if the subscripts are all in bounds for array; otherwise returns false. (If array is a vector with a fill pointer, that fill pointer is ignored.)
(setq a (make-array '(7 11) :element-type 'string-char)) (array-in-bounds-p a 0 0) => true (array-in-bounds-p a 6 10) => true (array-in-bounds-p a 0 -1) => false (array-in-bounds-p a 0 11) => false (array-in-bounds-p a 7 0) => false
section array-dimensions [Function]
(array-in-bounds-p array subscripts)
== (and (not (some #'minusp (list subscripts)))
(every #'< (list subscripts) (array-dimensions array)))
array-rank array => rank
array---an array.
rank---a non-negative integer.
Returns the number of dimensions of array.
(array-rank (make-array '())) => 0 (array-rank (make-array 4)) => 1 (array-rank (make-array '(4))) => 1 (array-rank (make-array '(2 3))) => 2
Should signal an error of type type-error if its argument is not an array.
section array-rank-limit [Constant Variable] , section make-array [Function]
array-row-major-index array {&rest subscripts} => index
array---an array.
subscripts---a list of valid array indices for the array.
index---a valid array row-major index for the array.
Computes the position according to the row-major ordering of array for the element that is specified by subscripts, and returns the offset of the element in the computed position from the beginning of array.
For a one-dimensional array, the result of array-row-major-index equals subscript.
array-row-major-index ignores fill pointers.
(setq a (make-array '(4 7) :element-type '(unsigned-byte 8)))
(array-row-major-index a 1 2) => 9
(array-row-major-index
(make-array '(2 3 4)
:element-type '(unsigned-byte 8)
:displaced-to a
:displaced-index-offset 4)
0 2 1) => 9
A possible definition of array-row-major-index, with no error-checking, is
(defun array-row-major-index (a &rest subscripts)
(apply #'+ (maplist #'(lambda (x y)
(* (car x) (apply #'* (cdr y))))
subscripts
(array-dimensions a))))
array-total-size array => size
array---an array.
size---a non-negative integer.
Returns the array total size of the array.
(array-total-size (make-array 4)) => 4 (array-total-size (make-array 4 :fill-pointer 2)) => 4 (array-total-size (make-array 0)) => 0 (array-total-size (make-array '(4 2))) => 8 (array-total-size (make-array '(4 0))) => 0 (array-total-size (make-array '())) => 1
Should signal an error of type type-error if its argument is not an array.
section make-array [Function] , section array-dimensions [Function]
If the array is a vector with a fill pointer, the fill pointer is ignored when calculating the array total size.
Since the product of no arguments is one, the array total size of a zero-dimensional array is one.
(array-total-size x)
== (apply #'* (array-dimensions x))
== (reduce #'* (array-dimensions x))
arrayp object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type array; otherwise, returns false.
(arrayp (make-array '(2 3 4) :adjustable t)) => true (arrayp (make-array 6)) => true (arrayp #*1011) => true (arrayp "hi") => true (arrayp 'hi) => false (arrayp 12) => false
section typep [Function]
(arrayp object) == (typep object 'array)
fill-pointer vector => fill-pointer
(setf ( fill-pointer vector) new-fill-pointer)
vector---a vector with a fill pointer.
fill-pointer, new-fill-pointer---a valid fill pointer for the vector.
Accesses the fill pointer of vector.
(setq a (make-array 8 :fill-pointer 4)) => #(NIL NIL NIL NIL) (fill-pointer a) => 4 (dotimes (i (length a)) (setf (aref a i) (* i i))) => NIL a => #(0 1 4 9) (setf (fill-pointer a) 3) => 3 (fill-pointer a) => 3 a => #(0 1 4) (setf (fill-pointer a) 8) => 8 a => #(0 1 4 9 NIL NIL NIL NIL)
Should signal an error of type type-error if vector is not a vector with a fill pointer.
section make-array [Function] , section length [Function]
There is no operator that will remove a vector's fill pointer.
row-major-aref array index => element
(setf ( row-major-aref array index) new-element)
array---an array.
index---a valid array row-major index for the array.
element, new-element---an object.
Considers array as a vector by viewing its elements in row-major order, and returns the element of that vector which is referred to by the given index.
row-major-aref is valid for use with setf.
section aref [Accessor] , section array-row-major-index [Function]
(row-major-aref array index) ==
(aref (make-array (array-total-size array)
:displaced-to array
:element-type (array-element-type array))
index)
(aref array i1 i2 ...) ==
(row-major-aref array (array-row-major-index array i1 i2))
upgraded-array-element-type typespec {&optional environment} => upgraded-typespec
typespec---a type specifier.
environment---an environment object. The default is nil, denoting the null lexical environment and the current global environment.
upgraded-typespec---a type specifier.
Returns the element type of the most specialized array representation capable of holding items of the type denoted by typespec.
The typespec is a subtype of (and possibly type equivalent to) the upgraded-typespec.
If typespec is bit, the result is type equivalent to bit.
If typespec is base-char, the result is type equivalent to base-char.
If typespec is character, the result is type equivalent to character.
The purpose of upgraded-array-element-type is to reveal how an implementation does its upgrading.
The environment is used to expand any derived type specifiers that are mentioned in the typespec.
section array-element-type [Function] , section make-array [Function]
Except for storage allocation consequences and dealing correctly with the optional environment argument, upgraded-array-element-type could be defined as:
(defun upgraded-array-element-type (type &optional environment) (array-element-type (make-array 0 :element-type type)))
A positive
fixnum,
the exact magnitude of which is implementation-dependent, but which is not less than 1024.
The upper exclusive bound on each individual dimension of an array.
section make-array [Function]
A positive
fixnum,
the exact magnitude of which is implementation-dependent, but which is not less than 8.
The upper exclusive bound on the rank of an array.
section make-array [Function]
A positive
fixnum,
the exact magnitude of which is implementation-dependent, but which is not less than 1024.
The upper exclusive bound on the array total size of an array.
The actual limit on the array total size imposed by the implementation might vary according the element type of the array; in this case, the value of array-total-size-limit will be the smallest of these possible limits.
section make-array [Function] , section array-element-type [Function]
simple-vector-p object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type simple-vector; otherwise, returns false..
(simple-vector-p (make-array 6)) => true (simple-vector-p "aaaaaa") => false (simple-vector-p (make-array 6 :fill-pointer t)) => false
simple-vector
(simple-vector-p object) == (typep object 'simple-vector)
svref simple-vector index => element
(setf ( svref simple-vector index) new-element)
simple-vector---a simple vector.
index---a valid array index for the simple-vector.
element, new-element---an object (whose type is a subtype of the array element type of the simple-vector).
Accesses the element of simple-vector specified by index.
(simple-vector-p (setq v (vector 1 2 'sirens))) => true (svref v 0) => 1 (svref v 2) => SIRENS (setf (svref v 1) 'newcomer) => NEWCOMER v => #(1 NEWCOMER SIRENS)
section aref [Accessor] , sbit, schar, section vector [Function] ,
section Compiler Terminology
svref is identical to aref except that it requires its first argument to be a simple vector.
(svref v i) == (aref (the simple-vector v) i)
vector {&rest objects} => vector
object---an object.
vector---a vector of type (vector t *).
Creates a fresh simple general vector whose size corresponds to the number of objects.
The vector is initialized to contain the objects.
(arrayp (setq v (vector 1 2 'sirens))) => true (vectorp v) => true (simple-vector-p v) => true (length v) => 3
section make-array [Function]
vector is analogous to list.
(vector a{{}_1} a{{}_2} ... a{{}_n})
== (make-array (list n) :element-type t
:initial-contents
(list a{{}_1} a{{}_2} ... a{{}_n}))
vector-pop vector => element
vector---a vector with a fill pointer.
element---an object.
Decreases the fill pointer of vector by one, and retrieves the element of vector that is designated by the new fill pointer.
(vector-push (setq fable (list 'fable))
(setq fa (make-array 8
:fill-pointer 2
:initial-element 'sisyphus))) => 2
(fill-pointer fa) => 3
(eq (vector-pop fa) fable) => true
(vector-pop fa) => SISYPHUS
(fill-pointer fa) => 1
The fill pointer is decreased by one.
The value of the fill pointer.
An error of type type-error is signaled if vector does not have a fill pointer.
If the fill pointer is zero, vector-pop signals an error of type error.
@xref{vector-push; vector-push-extend} , vector-push-extend, section fill-pointer [Accessor]
vector-push new-element vector => new-index-p
vector-push-extend new-element vector {&optional extension} => new-index
new-element---an object.
vector---a vector with a fill pointer.
extension---a positive integer. The default is implementation-dependent.
new-index-p---a valid array index for vector, or nil.
new-index---a valid array index for vector.
vector-push and vector-push-extend store new-element in vector. vector-push attempts to store new-element in the element of vector designated by the fill pointer, and to increase the fill pointer by one. If the (>= (fill-pointer vector) (array-dimension vector 0)), neither vector nor its fill pointer are affected. Otherwise, the store and increment take place and vector-push returns the former value of the fill pointer which is one less than the one it leaves in vector.
vector-push-extend is just like vector-push except that if the fill pointer gets too large, vector is extended using adjust-array so that it can contain more elements. Extension is the minimum number of elements to be added to vector if it must be extended.
vector-push and vector-push-extend return the index of new-element in vector. If (>= (fill-pointer vector) (array-dimension vector 0)), vector-push returns nil.
(vector-push (setq fable (list 'fable))
(setq fa (make-array 8
:fill-pointer 2
:initial-element 'first-one))) => 2
(fill-pointer fa) => 3
(eq (aref fa 2) fable) => true
(vector-push-extend #\X
(setq aa
(make-array 5
:element-type 'character
:adjustable t
:fill-pointer 3))) => 3
(fill-pointer aa) => 4
(vector-push-extend #\Y aa 4) => 4
(array-total-size aa) => at least 5
(vector-push-extend #\Z aa 4) => 5
(array-total-size aa) => 9 ;(or more)
The value of the fill pointer.
How vector was created.
An error of type error is signaled by vector-push-extend if it tries to extend vector and vector is not actually adjustable.
An error of type error is signaled if vector does not have a fill pointer.
section adjustable-array-p [Function] , section fill-pointer [Accessor] , section vector-pop [Function]
vectorp object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type vector; otherwise, returns false.
(vectorp "aaaaaa") => true (vectorp (make-array 6 :fill-pointer t)) => true (vectorp (make-array '(2 3 4))) => false (vectorp #*11) => true (vectorp #b11) => false
(vectorp object) == (typep object 'vector)
bit bit-array {&rest subscripts} => bit
sbit bit-array {&rest subscripts} => bit
(setf (bit bit-array {&rest subscripts}) new-bit)
(setf (sbit bit-array {&rest subscripts}) new-bit)
bit-array---for bit, a bit array; for sbit, a simple bit array.
subscripts---a list of valid array indices for the bit-array.
bit---a bit.
bit and sbit access the bit-array element specified by subscripts.
These functions ignore the fill pointer when accessing elements.
(bit (setq ba (make-array 8
:element-type 'bit
:initial-element 1))
3) => 1
(setf (bit ba 3) 0) => 0
(bit ba 3) => 0
(sbit ba 5) => 1
(setf (sbit ba 5) 1) => 1
(sbit ba 5) => 1
section aref [Accessor] ,
section Compiler Terminology
bit and sbit are like aref except that they require arrays to be a bit array and a simple bit array, respectively.
bit and sbit, unlike char and schar, allow the first argument to be an array of any rank.
[Function]
bit-and bit-array1 bit-array2 {&optional opt-arg} => resulting-bit-array
bit-andc1 bit-array1 bit-array2 {&optional opt-arg} => resulting-bit-array
bit-andc2 bit-array1 bit-array2 {&optional opt-arg} => resulting-bit-array
bit-eqv bit-array1 bit-array2 {&optional opt-arg} => resulting-bit-array
bit-ior bit-array1 bit-array2 {&optional opt-arg} => resulting-bit-array
bit-nand bit-array1 bit-array2 {&optional opt-arg} => resulting-bit-array
bit-nor bit-array1 bit-array2 {&optional opt-arg} => resulting-bit-array
bit-orc1 bit-array1 bit-array2 {&optional opt-arg} => resulting-bit-array
bit-orc2 bit-array1 bit-array2 {&optional opt-arg} => resulting-bit-array
bit-xor bit-array1 bit-array2 {&optional opt-arg} => resulting-bit-array
bit-not bit-array {&optional opt-arg} => resulting-bit-array
bit-array, bit-array1, bit-array2---a bit array.
Opt-arg---a bit array, or t, or nil. The default is nil.
Bit-array, bit-array1, bit-array2, and opt-arg (if an array) must all be of the same rank and dimensions.
resulting-bit-array---a bit array.
These functions perform bit-wise logical operations on bit-array1 and bit-array2 and return an array of matching rank and dimensions, such that any given bit of the result is produced by operating on corresponding bits from each of the arguments.
In the case of bit-not, an array of rank and dimensions matching bit-array is returned that contains a copy of bit-array with all the bits inverted.
If opt-arg is of type (array bit) the contents of the result are destructively placed into opt-arg. If opt-arg is the symbol t, bit-array or bit-array1 is replaced with the result; if opt-arg is nil or omitted, a new array is created to contain the result.
Figure 15--4 indicates the logical operation performed by each of the functions.
2 Function Operation _______________________________________________________________________________________________________ bit-and and bit-eqv equivalence (exclusive nor) bit-not complement bit-ior inclusive or bit-xor exclusive or bit-nand complement of bit-array1 and bit-array2 bit-nor complement of bit-array1 or bit-array2 bit-andc1 and complement of bit-array1 with bit-array2 bit-andc2 and bit-array1 with complement of bit-array2 bit-orc1 or complement of bit-array1 with bit-array2 bit-orc2 or bit-array1 with complement of bit-array2 Figure 15--3: Bit-wise Logical Operations on Bit Arrays
(bit-and (setq ba #*11101010) #*01101011) => #*01101010
(bit-and #*1100 #*1010) => #*1000
(bit-andc1 #*1100 #*1010) => #*0010
(setq rba (bit-andc2 ba #*00110011 t)) => #*11001000
(eq rba ba) => true
(bit-not (setq ba #*11101010)) => #*00010101
(setq rba (bit-not ba
(setq tba (make-array 8
:element-type 'bit))))
=> #*00010101
(equal rba tba) => true
(bit-xor #*1100 #*1010) => #*0110
lognot, @xref{logand; logandc1; logandc2; logeqv; logior; lognand; lognor; lognot; logorc1; logorc2; logxor}
bit-vector-p object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type bit-vector; otherwise, returns false.
(bit-vector-p (make-array 6
:element-type 'bit
:fill-pointer t)) => true
(bit-vector-p #*) => true
(bit-vector-p (make-array 6)) => false
section typep [Function]
(bit-vector-p object) == (typep object 'bit-vector)
simple-bit-vector-p object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type simple-bit-vector; otherwise, returns false.
(simple-bit-vector-p (make-array 6)) => false (simple-bit-vector-p #*) => true
section simple-vector-p [Function]
(simple-bit-vector-p object) == (typep object 'simple-bit-vector)
Go to the first, previous, next, last section, table of contents.