3.11 Vectors

Vectors in Guide: PLT Scheme introduces vectors.

A vector is a fixed-length array with constant-time access and update of the vector slots, which are numbered from 0 to one less than the number of slots in the vector.

Two vectors are equal? if they have the same length, and if the values in corresponding slots of the the vectors are equal?.

A vector can be mutable or immutable. When an immutable vector is provided to a procedure like vector-set!, the exn:fail:contract exception is raised. Vectors generated by the default reader (see Reading Strings) are immutable.

A vector can be used as a single-valued sequence (see Sequences). The elements of the vector serve as elements of the sequence. See also in-vector.

(vector? v) → boolean?

v : any/c

Returns #t if v is a vector, #f otherwise.

(make-vector size [v]) → vector?

size : exact-nonnegative-integer?

v : any/c = 0

Returns a mutable vector with size slots, where all slots are initialized to contain v.

(vector v ...) → vector?

v : any/c

Returns a mutable vector with as many slots as provided vs, where the slots are initialized to contain the given vs in order.

(vector-immutable v ...)   →   (and/c vector?        immutable?)

v : any/c

Returns an immutable vector with as many slots as provided vs, where the slots are contain the given vs in order.

(vector-length vec) → exact-nonnegative-integer?

vec : vector?

Returns the length of vec (i.e., the number of slots in the vector).

(vector-ref vec pos) → any/c

vec : vector?

pos : exact-nonnegative-integer?

Returns the element in slot pos of vec. The first slot is position 0, and the last slot is one less than (vector-length vec).

(vector-set! vec pos v) → void?

vec : (and/c vector? (not/c immutable?))

pos : exact-nonnegative-integer?

v : any/c

Updates the slot pos of vec to contain v.

(vector->list vec) → list?

vec : vector?

Returns a list with the same length and elements as vec.

(list->vector lst) → vector?

lst : list?

Returns a mutable vector with the same length and elements as lst.

(vector->immutable-vector vec) → (and/c vector? immutable?)

vec : vector?

Returns an immutable vector with the same length and elements as vec. If vec is itself immutable, then it is returned as the result.

(vector-fill! vec v) → void?

vec : (and/c vector? (not/c immutable?))

v : any/c

Changes all slots of vec to contain v.

(vector-copy!   dest             dest-start             src            [ src-start             src-end])   →   void?

dest : (and/c vector? (not/c immutable?))

dest-start : exact-nonnegative-integer?

src : vector?

src-start : exact-nonnegative-integer? = 0

src-end : exact-nonnegative-integer? = (vector-length src)

Changes the elements of dest starting at position dest-start to match the elements in src from src-start (inclusive) to src-end (exclusive). The vectors dest and src can be the same vector, and in that case the destination region can overlap with the source region; the destination elements after the copy match the source elements from before the copy. If any of dest-start, src-start, or src-end are out of range (taking into account the sizes of the vectors and the source and destination regions), the exn:fail:contract exception is raised.

Examples:

> (define v (vector 'A 'p 'p 'l 'e))

> (vector-copy! v 4 #(y))

> (vector-copy! v 0 v 3 4)

> v

#(l p p l y)

(vector->values vec [start-pos end-pos]) → any

vec : vector?

start-pos : exact-nonnegative-integer? = 0

end-pos : exact-nonnegative-integer? = (vector-length vec)

Returns end-pos - start-pos values, which are the elements of vec from start-pos (inclusive) to end-pos (exclusive). If start-pos or end-pos are greater than (vector-length vec), or if end-pos is less than start-pos, the exn:fail:contract exception is raised.

(build-vector n proc) → vector?

n : exact-nonnegative-integer?

proc : (exact-nonnegative-integer? . -> . any/c)

Creates a vector of n elements by applying proc to the integers from 0 to (sub1 n) in order. If vec is the resulting vector, then (vector-ref vec i) is the value produced by (proc i).

Examples:

> (build-vector 5 add1)

#(1 2 3 4 5)