vector-push, vector-push-extend

vector-push, vector-push-extend Function

Syntax:

vector-push new-element vector → new-index-p

vector-push-extend new-element vector &optional extension → new-index

Arguments and Values:

new-element—an object.

vector—a vector with a fill pointer .

extension—a positive integer . The default is implementation-dependent.

new-index-p—a valid array index for vector, or nil.

new-index—a valid array index for vector.

Description:

vector-push and vector-push-extend store new-element in vector. vector-push attempts to store new-element in the element of vector designated by the fill pointer , and to increase the fill pointer by one. If the (>= (fill-pointer vector) (array-dimension vector 0)), neither vector nor its fill pointer are affected. Otherwise, the store and increment take place and vector-push returns the former value of the fill pointer which is one less than the one it leaves in vector.

vector-push-extend is just like vector-push except that if the fill pointer gets too large, vector is extended using adjust-array so that it can contain more elements. Extension is the minimum number of elements to be added to vector if it must be extended.

vector-push and vector-push-extend return the index of new-element in vector. If (>= (fill-pointer vector) (array-dimension vector 0)), vector-push returns nil.

Examples:

(vector-push (setq fable (list ’fable)) 
	     (setq fa (make-array 8 
				  :fill-pointer 2 
				  
				  
				  :initial-element ’first-one))) → 2 
(fill-pointer fa) → 3 
(eq (aref fa 2) fable) → true 
(vector-push-extend #\X 
		    (setq aa 
			  (make-array 5 
				      :element-type ’character 
				      :adjustable t 
				      :fill-pointer 3))) → 3 
(fill-pointer aa) → 4 
(vector-push-extend #\Y aa 4) → 4 
(array-total-size aa) → at least 5 
(vector-push-extend #\Z aa 4) → 5 
(array-total-size aa) → 9 ;(or more) 

Affected By:

The value of the fill pointer .

How vector was created.

Exceptional Situations:

An error of type error is signaled by vector-push-extend if it tries to extend vector and vector is not actually adjustable.

An error of type error is signaled if vector does not have a fill pointer .

See Also:

adjustable-array-p, fill-pointer, vector-pop

Expanded Reference: vector-push, vector-push-extend

Basic vector-push

vector-push stores an element at the current fill pointer position and increments the fill pointer by one. It returns the index where the element was stored, or nil if the vector is full.

(let ((v (make-array 5 :fill-pointer 0)))
  (list (vector-push 'a v)   ; stored at index 0
        (vector-push 'b v)   ; stored at index 1
        (vector-push 'c v)   ; stored at index 2
        (fill-pointer v)
        v))
=> (0 1 2 3 #(A B C))

vector-push Returns NIL When Full

When the fill pointer equals the array dimension, vector-push does nothing and returns nil.

(let ((v (make-array 3 :fill-pointer 0)))
  (vector-push 'a v)
  (vector-push 'b v)
  (vector-push 'c v)
  (list (vector-push 'd v)   ; vector is full
        (fill-pointer v)
        v))
=> (NIL 3 #(A B C))

vector-push-extend Grows the Vector

vector-push-extend is like vector-push but automatically extends the vector (using adjust-array) when it is full. The vector must be adjustable.

(let ((v (make-array 3 :fill-pointer 0 :adjustable t)))
  (vector-push-extend 'a v)
  (vector-push-extend 'b v)
  (vector-push-extend 'c v)
  (vector-push-extend 'd v)  ; triggers extension
  (vector-push-extend 'e v)
  (list (fill-pointer v) v))
=> (5 #(A B C D E))

Building a Collection Dynamically

A common pattern is using an adjustable vector with fill pointer as a growable collection.

(let ((result (make-array 0 :fill-pointer 0 :adjustable t)))
  (dotimes (i 6)
    (vector-push-extend (* i i) result))
  result)
=> #(0 1 4 9 16 25)

Specifying the Extension Amount

The optional third argument to vector-push-extend specifies the minimum number of elements to add when extending.

(let ((v (make-array 2 :fill-pointer 0 :adjustable t)))
  (vector-push-extend 'a v)
  (vector-push-extend 'b v)
  ;; Extend by at least 100 elements
  (vector-push-extend 'c v 100)
  (list (fill-pointer v)
        (>= (array-total-size v) 102)))
=> (3 T)