Skip to main content

fill-pointer

fill-pointer Accessor

Syntax:

fill-pointer vector → fill-pointer

(setf (fill-pointer vector) new-fill-pointer**)**

Arguments and Values:

vector—a vector with a fill pointer .

fill-pointer, new-fill-pointer—a valid fill pointer for the vector.

Description:

Accesses the fill pointer of vector.

Examples:

(setq a (make-array 8 :fill-pointer 4)) → #(NIL NIL NIL NIL) 
(fill-pointer a) → 4 
(dotimes (i (length a)) (setf (aref a i) (\* i i))) → NIL 
a → #(0 1 4 9) 
(setf (fill-pointer a) 3) → 3 
(fill-pointer a) → 3 
a → #(0 1 4) 
(setf (fill-pointer a) 8) → 8 
a → #(0 1 4 9 NIL NIL NIL NIL)

Exceptional Situations:

Should signal an error of type type-error if vector is not a vector with a fill pointer .

See Also:

make-array, length

Notes:

There is no operator that will remove a vector ’s fill pointer .

Expanded Reference: fill-pointer​

Reading the Fill Pointer​

fill-pointer returns the current fill pointer of a vector, which represents the "active" length of the vector.

(let ((v (make-array 10 :fill-pointer 4 :initial-element 0)))
  (list (fill-pointer v) (length v)))
=> (4 4)

Setting the Fill Pointer with SETF​

You can change the fill pointer to expose or hide elements. The new value must be between 0 and the array's total size.

(let ((v (make-array 8 :fill-pointer 3 :initial-element 'x)))
  (setf (fill-pointer v) 6)
  (list (fill-pointer v) (length v) v))
=> (6 6 #(X X X X X X))

Shrinking and Growing the Logical Size​

Decreasing the fill pointer hides elements; increasing it reveals elements that were previously stored.

(let ((v (make-array 5 :fill-pointer 5
                     :initial-contents '(a b c d e))))
  ;; Shrink logical size to 2
  (setf (fill-pointer v) 2)
  (let ((shrunk (copy-seq v)))  ; only copies active elements
    ;; Grow back to 5 -- old elements are still there
    (setf (fill-pointer v) 5)
    (list shrunk v)))
=> (#(A B) #(A B C D E))

Fill Pointer Controls Sequence Operations​

Most sequence functions respect the fill pointer. length, map, reduce, and iteration all see only the active portion.

(let ((v (make-array 6 :fill-pointer 3
                     :initial-contents '(10 20 30 40 50 60))))
  (list (length v)
        (reduce #'+ v)        ; only sums active elements
        (aref v 5)))          ; aref ignores fill pointer
=> (3 60 60)

Resetting a Vector for Reuse​

Setting the fill pointer to 0 effectively clears the vector without deallocating storage -- useful for reusing a buffer.

(let ((buf (make-array 100 :fill-pointer 0 :adjustable t)))
  (dotimes (i 5) (vector-push-extend i buf))
  (let ((first-pass (copy-seq buf)))
    (setf (fill-pointer buf) 0)  ; "clear" the buffer
    (dotimes (i 3) (vector-push-extend (* i 10) buf))
    (list first-pass buf)))
=> (#(0 1 2 3 4) #(0 10 20))