3.11 Vectors
Vectors in The Racket Guide 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 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.
A literal or printed vector starts with #(, optionally with a number between the # and (. See Reading Vectors for information on reading vectors and Printing Vectors for information on printing vectors.
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.
Returns a newly allocated 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 a newly allocated 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: | |||||
|
(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).
Example: | ||
|
3.11.1 Additional Vector Functions
The bindings documented in this section are provided by the racket/vector and racket libraries, but not racket/base.
(vector-set*! vec pos v ... ...) → void? vec : (and/c vector? (not/c immutable?)) pos : exact-nonnegative-integer? v : any/c
Updates each slot pos of vec to contain each v.
The update takes place from the left so later updates overwrite earlier updates.
(vector-map proc vec ...+) → vector? proc : procedure? vec : vector?
Applies proc to the elements of the vecs from the
first elements to the last. The proc argument must accept
the same number of arguments as the number of supplied vecs,
and all vecs must have the same number of elements. The
result is a fresh vector containing each result of proc in
order.
Example: | ||
|
(vector-map! proc vec ...+) → vector? proc : procedure? vec : vector?
Applies proc to the elements of the vecs from the
first elements to the last. The proc argument must accept
the same number of arguments as the number of supplied vecs,
and all vecs must have the same number of elements. The
each result of proc is inserted into the first vec
at the index that the arguments to proc was taken from. The
result is the first vec.
Examples: | |||||
|
(vector-append vec ...) → vector? vec : vector?
Creates a fresh vector that contains all
of the elements of the given vectors in order.
Example: | ||
|
(vector-take vec pos) → vector? vec : vector? pos : exact-nonnegative-integer?
Returns a fresh vector whose elements are the first pos elements of
vec. If vec has fewer than
pos elements, then the exn:fail:contract exception is raised.
Example: | ||
|
(vector-take-right vec pos) → vector? vec : vector? pos : exact-nonnegative-integer?
Returns a fresh vector whose elements are the last pos elements of
vec. If vec has fewer than
pos elements, then the exn:fail:contract exception is raised.
Example: | ||
|
(vector-drop vec pos) → vector? vec : vector? pos : exact-nonnegative-integer?
Returns a fresh vector whose elements are the elements of vec
after the first pos elements. If vec has fewer
than pos elements, then the exn:fail:contract exception is raised.
Example: | ||
|
(vector-drop-right vec pos) → vector? vec : vector? pos : exact-nonnegative-integer?
Returns a fresh vector whose elements are the elements of vec
before the first pos elements. If vec has fewer
than pos elements, then the exn:fail:contract exception is raised.
Example: | ||
|
(vector-split-at vec pos) →
vector? vector? vec : vector? pos : exact-nonnegative-integer?
Returns the same result as
(values (vector-take vec pos) (vector-drop vec pos))
except that it can be faster.
Example: | |||
|
(vector-split-at-right vec pos) →
vector? vector? vec : vector? pos : exact-nonnegative-integer?
Returns the same result as
(values (vector-take-right vec pos) (vector-drop-right vec pos))
except that it can be faster.
Example: | |||
|
(vector-copy vec [start end]) → vector? vec : vector? start : exact-nonnegative-integer? = 0 end : exact-nonnegative-integer? = (vector-length v)
Creates a fresh vector of size (- end start), with all of the
elements of vec from start (inclusive) to
end (exclusive).
Examples: | ||||||
|
(vector-filter pred vec) → vector? pred : procedure? vec : vector?
Returns a fresh vector with the elements of vec for which
pred produces a true value. The pred procedure is
applied to each element from first to last.
Example: | ||
|
(vector-filter-not pred vec) → vector? pred : procedure? vec : vector?
Like vector-filter, but the meaning of the pred predicate
is reversed: the result is a vector of all items for which pred
returns #f.
Example: | ||
|
(vector-count proc vec ...+) → exact-nonnegative-integer? proc : procedure? vec : vector?
Returns the number of elements of the vec ... (taken in
parallel) on which proc does not evaluate to #f.
Examples: | ||||
|
This returns the first element in the non-empty vector vec that minimizes
the result of proc.
Examples: | ||||
|
This returns the first element in the non-empty vector vec that maximizes
the result of proc.
Examples: | ||||
|
(vector-member v lst) → (or/c natural-number/c #f) v : any/c lst : vector?
Locates the first element of vec that is equal? to
v. If such an element exists, the index of that element in
vec is returned. Otherwise, the result is #f.
Examples: | ||||
|
(vector-memv v vec) → (or/c natural-number/c #f) v : any/c vec : vector?
Like vector-member, but finds an element using eqv?.
Examples: | ||||
|
(vector-memq v vec) → (or/c natural-number/c #f) v : any/c vec : vector?
Like vector-member, but finds an element using eq?.
Examples: | ||||
|