17. ARRAYS
This chapter contains the following sections:
17.0 Introduction to Arrays
17.1 Array Creation
17.2 Array Access
17.3 Array Information
17.4 Functions on Arrays of Bits
17.5 Fill Pointers
17.0 Introduction to arrays
An array is an object with components arranged according to a rectilinear coordinate system. In principle, an array in Common LISP may have any number of dimensions, including zero. (A zero-dimensional array has exactly one element.) An array may have as many dimensions as can be represented by a 16 bit unsigned integer, i.e. 65,536.
The upper exclusive bound on each individual dimension is the largest 32 bit unsigned integer, somewhat more than four billion. Each dimension is a non-negative integer; if any dimension of an array is zero, the array has no elements.
An array may be a general array, meaning each element may be any LISP object, or it may be a specialized array, meaning that each element must be of a given restricted type.
One-dimensional arrays are called vectors. General vectors may contain any LISP object. Vectors whose elements are restricted to type string-char are called strings. Vectors whose elements are restricted to type bit are called bit-vectors.
17.1 Array Creation
The following Common LISP functions create arrays:
make-array
vector
The following constants define implementation limits on the size of arrays:
array-rank-limit
array-total-size-limit
array-dimension-limit
17.2 Array Access
The following functions allow access to array elements:
aref
svref
17.3 Array Information
The following functions extract from an array information other than the elements:
array-element-type
array-rank
array-dimension
array-dimensions
array-total-size
array-in-bounds-p
array-row-major-index
adjustable-array-p
17.4 Functions on Arrays of Bits
The functions described in this section operate only on arrays of bits, that is, specialized arrays whose elements are all 0 or 1.
bit
sbit
bit-and
bit-ior
bit-xor
bit-eqv
bit-nand
bit-nor
bit-andc1
bit-andc2
bit-orc1
bit-orc2
bit-not
17.5 Fill Pointers
Several functions for manipulating a fill pointer are provided in Common LISP to make it easy to incrementally fill in the contents of a vector and, more generally, to allow efficient varying of the length of a vector. The fill pointer is a non-negative integer no larger than the total number of elements in the vector (as returned by array-dimension); it is the number of active or filled-in elements in the vector. The fill pointer constitutes the active length of the vector; all vector elements whose index is less than the fill pointer are active, and the others are inactive. Nearly all functions that operate on the contents of a vector will operate only on the active elements. An important exception is aref, which can be used to access any vector element whether in the active region of the vector or not. It is important to note that vector elements not in the active region are still considered part of the vector.
Implementation note: An implication of this rule is that vector elements outside the active region may not be garbage-collected.
Only vectors (one-dimensional arrays) may have fill pointers; multidimensional arrays may not.
The following functions relate to fill pointers:
array-has-fill-pointer-p
fill-pointer
vector-push
vector-pop