4.12 Vectors

Vectors are heterogeneous structures whose elements are indexed by integers. A vector typically occupies less space than a list of the same length, and the average time needed to access a randomly chosen element is typically less for the vector than for the list.

The length of a vector is the number of elements that it contains. This number is a non–negative integer that is fixed when the vector is created. The valid indices of a vector are the exact non–negative integer objects less than the length of the vector. The first element in a vector is indexed by zero, and the last element is indexed by one less than the length of the vector.

Like list constants, vector constants must be quoted:

'#(0 (2 2 2 2) "Anna")     ⇒  #(0 (2 2 2 2) "Anna")

Procedure: vector? obj

Return #t if obj is a vector, #f otherwise.

Procedure: make-vector k

Procedure: make-vector k fill

Return a newly allocated vector of k elements. If a second argument is given, then each element is initialized to fill. Otherwise the initial contents of each element is unspecified.

As Vicare extension: when fill is unused, it defaults to the void object.

Procedure: vector obj …

Return a newly allocated vector whose elements contain the given arguments. Analogous to list.

(vector 'a 'b 'c)               ⇒  #(a b c)

Procedure: vector-length vector

Return the number of elements in vector as an exact integer object.

Procedure: vector-ref vector k

k must be a valid index of vector. The vector-ref procedure returns the contents of element k of vector.

(vector-ref '#(1 1 2 3 5 8 13 21) 5)     ⇒  8

Procedure: vector-set! vector k obj

k must be a valid index of vector. The vector-set! procedure stores obj in element k of vector, and returns unspecified.

Passing an immutable vector to vector-set! should cause an exception with condition type &assertion to be raised.

(let ((vec (vector 0 '(2 2 2 2) "Anna")))
  (vector-set! vec 1 '("Sue" "Sue"))
  vec)
⇒  #(0 ("Sue" "Sue") "Anna")

(vector-set! '#(0 1 2) 1 "doe")
⇒  unspecified
    ;; constant vector
    ;; should raise exception &assertion

Procedure: vector->list vector

Procedure: list->vector list

The vector->list procedure returns a newly allocated list of the objects contained in the elements of vector.

The list->vector procedure returns a newly created vector initialized to the elements of the list list.

(vector->list '#(dah dah didah))        ⇒ (dah dah didah)
(list->vector '(dididit dah))           ⇒ #(dididit dah)

Procedure: vector-fill! vector fill

Store fill in every element of vector and returns unspecified values.

Procedure: vector-map proc vector1 vector2 …

The vectors must all have the same length. proc should accept as many arguments as there are vectors and return a single value.

The vector-map procedure applies proc element–wise to the elements of the vectors and returns a vector of the results, in order. proc is always called in the same dynamic environment as vector-map itself. The order in which proc is applied to the elements of the vectors is unspecified. If multiple returns occur from vector-map, the return values returned by earlier returns are not mutated.

Analogous to map.

Implementation responsibilities: The implementation must check the restrictions on proc to the extent performed by applying it as described. An implementation may check whether proc is an appropriate argument before applying it.

Procedure: vector-for-each proc vector1 vector2 …

The vectors must all have the same length. proc should accept as many arguments as there are vectors. The vector-for-each procedure applies proc element–wise to the elements of the vectors for its side effects, in order from the first elements to the last. proc is always called in the same dynamic environment as vector-for-each itself. The return values of vector-for-each are unspecified.

Analogous to for-each.

Implementation responsibilities: The implementation must check the restrictions on proc to the extent performed by applying it as described. An implementation may check whether proc is an appropriate argument before applying it.