Star Sapphire Common LISP Home

Download Star Saphire
Index

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