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. For example, a string with a fill pointer has most of the characteristics of a PL/I varying string.

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. (Note, however, that one can create a multidimensional array that is displaced to a vector that has a fill pointer.)

[Function] array-has-fill-pointer-p array

The argument must be an array. array-has-fill-pointer-p returns t if the array has a fill pointer, and otherwise returns nil. Note that array-has-fill-pointer-p always returns nil if the array is not one-dimensional.

[Function] fill-pointer vector

The fill pointer of vector is returned. It is an error if the vector does not have a fill pointer.

setf may be used with fill-pointer to change the fill pointer of a vector. The fill pointer of a vector must always be an integer between zero and the size of the vector (inclusive).

[Function] vector-push new-element vector

vector must be a one-dimensional array that has a fill pointer, and new-element may be any object. vector-push attempts to store new-element in the element of the vector designated by the fill pointer, and to increase the fill pointer by 1. If the fill pointer does not designate an element of the vector (specifically, when it gets too big), it is unaffected and vector-push returns nil. Otherwise, the store and increment take place and vector-push returns the former value of the fill pointer (1 less than the one it leaves in the vector); thus the value of vector-push is the index of the new element pushed.

It is instructive to compare vector-push, which is a function, with push, which is a macro that requires a place suitable for setf. A vector with a fill pointer effectively contains the place to be modified in its fill-pointer slot.

[Function] vector-push-extend new-element vector &optional extension

vector-push-extend is just like vector-push except that if the fill pointer gets too large, the vector is extended (using adjust-array) so that it can contain more elements. If, however, the vector is not adjustable, then vector-push-extend signals an error.

X3J13 voted in June 1989 to clarify that vector-push-extend regards an array as not adjustable if and only if adjustable-array-p is false of that array.

The optional argument extension, which must be a positive integer, is the minimum number of elements to be added to the vector if it must be extended; it defaults to a “reasonable” implementation-dependent value.

[Function] vector-pop vector

vector must be a one-dimensional array that has a fill pointer. If the fill pointer is zero, vector-pop signals an error. Otherwise the fill pointer is decreased by 1, and the vector element designated by the new value of the fill pointer is returned.