Common Lisp the Language, 2nd Edition

Next: Changing the Dimensions Up: Arrays Previous: Functions on Arrays

# 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 (ADJUST-ARRAY-NOT-ADJUSTABLE) 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.

Next: Changing the Dimensions Up: Arrays Previous: Functions on Arrays