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-elementvector

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-elementvector &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.