Go to the first, previous, next, last section, table of contents.

Vectors

Vectors are heterogenous structures whose elements are indexed by exact non-negative integers. A vector typically occupies less space than a list of the same length, and the average time required 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 an exact non-negative integer that is fixed when the vector is created. The valid indexes of a vector are the exact non-negative integers 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.

Vectors are written using the notation #(object ...). For example, a vector of length 3 containing the number zero in element 0, the list (2 2 2 2) in element 1, and the string "Anna" in element 2 can be written as

#(0 (2 2 2 2) "Anna")

Note that this is the external representation of a vector, not an expression evaluating to a vector. Like list constants, vector constants must be quoted:

'#(0 (2 2 2 2) "Anna")          =>  #(0 (2 2 2 2) "Anna")

A number of the vector procedures operate on subvectors. A subvector is a segment of a vector that is specified by two exact non-negative integers, start and end. Start is the index of the first element that is included in the subvector, and end is one greater than the index of the last element that is included in the subvector. Thus if start and end are the same, they refer to a null subvector, and if start is zero and end is the length of the vector, they refer to the entire vector. The valid indexes of a subvector are the exact integers between start inclusive and end exclusive.

Construction of Vectors

procedure: make-vector k [object]: Returns a newly allocated vector of k elements. If object is specified, make-vector initializes each element of the vector to object. Otherwise the initial elements of the result are unspecified.

procedure: vector object ...

Returns a newly allocated vector whose elements are the given arguments. vector is analogous to list.

(vector 'a 'b 'c)                       =>  #(a b c)

procedure+: vector-copy vector: Returns a newly allocated vector that is a copy of vector.

procedure: list->vector list

Returns a newly allocated vector initialized to the elements of list. The inverse of list->vector is vector->list.

(list->vector '(dididit dah))           =>  #(dididit dah)

procedure+: make-initialized-vector k initialization

Similar to make-vector, except that the elements of the result are determined by calling the procedure initialization on the indices. For example:

(make-initialized-vector 5 (lambda (x) (* x x)))
     =>  #(0 1 4 9 16)

procedure+: vector-grow vector k: K must be greater than or equal to the length of vector. Returns a newly allocated vector of length k. The first (vector-length vector) elements of the result are initialized from the corresponding elements of vector. The remaining elements of the result are unspecified.

procedure+: vector-map vector procedure

Procedure must be a procedure of one argument. vector-map applies procedure element-wise to the elements of vector and returns a newly allocated vector of the results, in order from left to right. The dynamic order in which procedure is applied to the elements of vector is unspecified.

(vector-map '#((a b) (d e) (g h)) cadr)           =>  #(b e h)
(vector-map '#(1 2 3 4) (lambda (n) (expt n n)))  =>  #(1 4 27 256)
(vector-map '#(5 7 9) +)                          =>  #(5 7 9)

Selecting Vector Components

procedure: vector? object: Returns #t if object is a vector; otherwise returns #f.

procedure: vector-length vector: Returns the number of elements in vector.

procedure: vector-ref vector k

Returns the contents of element k of vector. K must be a valid index of vector.

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

procedure: vector-set! vector k object

Stores object in element k of vector and returns an unspecified value. K must be a valid index of vector.

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

procedure+: vector-first vector
procedure+: vector-second vector
procedure+: vector-third vector
procedure+: vector-fourth vector
procedure+: vector-fifth vector
procedure+: vector-sixth vector
procedure+: vector-seventh vector
procedure+: vector-eighth vector: These procedures access the first several elements of vector in the obvious way. It is an error if the implicit index of one of these procedurs is not a valid index of vector.

procedure+: vector-binary-search vector key<? unwrap-key key

Searches vector for an element with a key matching key, returning the element if one is found or #f if none. The search operation takes time proportional to the logarithm of the length of vector. Unwrap-key must be a procedure that maps each element of vector to a key. Key<? must be a procedure that implements a total ordering on the keys of the elements.

(define (translate number)
  (vector-binary-search '#((1 . i) (2 . ii) (3 . iii) (6 . vi))
                        <  car  number))
(translate 2)  =>  (2 . ii)
(translate 4)  =>  #F

Cutting Vectors

procedure+: subvector vector start end: Returns a newly allocated vector that contains the elements of vector between index start (inclusive) and end (exclusive).

procedure+: vector-head vector end

Equivalent to

(subvector vector 0 end)

procedure+: vector-tail vector start

Equivalent to

(subvector vector start (vector-length vector))

Modifying Vectors

procedure: vector-fill! vector object
procedure+: subvector-fill! vector start end object: Stores object in every element of the vector (subvector) and returns an unspecified value.

procedure+: subvector-move-left! vector1 start1 end1 vector2 start2

procedure+: subvector-move-right! vector1 start1 end1 vector2 start2

Destructively copies the elements of vector1, starting with index start1 (inclusive) and ending with end1 (exclusive), into vector2 starting at index start2 (inclusive). Vector1, start1, and end1 must specify a valid subvector, and start2 must be a valid index for vector2. The length of the source subvector must not exceed the length of vector2 minus the index start2.

The elements are copied as follows (note that this is only important when vector1 and vector2 are eqv?):

subvector-move-left!: The copy starts at the left end and moves toward the right (from smaller indices to larger). Thus if vector1 and vector2 are the same, this procedure moves the elements toward the left inside the vector.
subvector-move-right!: The copy starts at the right end and moves toward the left (from larger indices to smaller). Thus if vector1 and vector2 are the same, this procedure moves the elements toward the right inside the vector.

procedure+: sort! vector procedure

Procedure must be a procedure of two arguments that defines a total ordering on the elements of vector. The elements of vector are rearranged so that they are sorted in the order defined by procedure. The elements are rearranged in place, that is, vector is destructively modified so that its elements are in the new order.

sort! returns vector as its value.