4.12 Vectors

4.12 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. Use immutable? to check whether a vector is 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.

procedure
(vector? v) → boolean?
v : any/c

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

See also immutable-vector? and mutable-vector?.

procedure
(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. Note that v is shared for all elements, so for mutable data, mutating an element will affect other elements.

Examples:

> (make-vector 3 2)
'#(2 2 2)
> (define v (make-vector 5 (box 3)))
> v
'#(#&3 #&3 #&3 #&3 #&3)
> (set-box! (vector-ref v 0) 7)
> v
'#(#&7 #&7 #&7 #&7 #&7)

This function takes time proportional to size.

procedure
(vector v ...) → vector?
v : any/c

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.

procedure
(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 contain the given vs in order.

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

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

This function takes constant time.

procedure
(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).

This function takes constant time.

procedure
(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.

This function takes constant time.

procedure
(vector*-length vec) → exact-nonnegative-integer?
  vec : (and/c vector? (not/c impersonator?))
procedure
(vector*-ref vec pos) → any/c
  vec : (and/c vector? (not/c impersonator?))
  pos : exact-nonnegative-integer?
procedure
(vector*-set! vec pos v) → void?
  vec : (and/c vector? (not/c immutable?)  (not/c impersonator?))
  pos : exact-nonnegative-integer?
  v : any/c

Like vector-length, vector-ref, and vector-set!, but constrained to work on vectors that are not impersonators.

Added in version 6.90.0.15 of package base.

procedure
(vector-cas! vec pos old-v new-v) → boolean?
  vec : (and/c vector? (not/c immutable?) (not/c impersonator?))
  pos : exact-nonnegative-integer?
  old-v : any/c
  new-v : any/c

Compare and set operation for vectors. See box-cas!.

Added in version 6.11.0.2 of package base.

procedure
(vector->list vec) → list?
vec : vector?

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

This function takes time proportional to the size of vec.

procedure
(list->vector lst) → vector?
lst : list?

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

This function takes time proportional to the length of lst.

procedure
(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.

This function takes time proportional to the size of vec when vec is mutable.

procedure
(vector-fill! vec v) → void?
vec : (and/c vector? (not/c immutable?))
v : any/c

Changes all slots of vec to contain v.

This function takes time proportional to the size of vec.

procedure
(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.

This function takes time proportional to (- src-end src-start).

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)

procedure
(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.

This function takes time proportional to the size of vec.

procedure
(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:

> (build-vector 5 add1)
'#(1 2 3 4 5)

4.12.1 Additional Vector Functions🔗ℹ

(require racket/vector)

package: base

The bindings documented in this section are provided by the racket/vector and racket libraries, but not racket/base.

procedure
(vector-empty? v) → boolean?
v : vector?

Returns #t if v is empty (i.e. its length is 0), #f otherwise.

Added in version 7.4.0.4 of package base.

procedure
(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.

procedure
(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 + #(1 2) #(3 4))
'#(4 6)

procedure
(vector-map! proc vec ...+) → vector?
proc : procedure?
vec : (and/c vector? (not/c immutable?))

Like vector-map, but result of proc is inserted into the first vec at the index that the arguments to proc were taken from. The result is the first vec.

Examples:

> (define v (vector 1 2 3 4))
> (vector-map! add1 v)
'#(2 3 4 5)
> v
'#(2 3 4 5)

procedure
(vector-append vec ...) → vector?
vec : vector?

Creates a fresh vector that contains all of the elements of the given vectors in order.

Example:

> (vector-append #(1 2) #(3 4))
'#(1 2 3 4)

procedure
(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 #(1 2 3 4) 2)
'#(1 2)

procedure
(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-take-right #(1 2 3 4) 2)
'#(3 4)

procedure
(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 #(1 2 3 4) 2)
'#(3 4)

procedure
(vector-drop-right vec pos) → vector?
vec : vector?
pos : exact-nonnegative-integer?

Returns a fresh vector whose elements are the prefix of vec, dropping its pos-length tail. If vec has fewer than pos elements, then the exn:fail:contract exception is raised.

Examples:

> (vector-drop-right #(1 2 3 4) 1)
'#(1 2 3)
> (vector-drop-right #(1 2 3 4) 3)
'#(1)

procedure
(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 #(1 2 3 4 5) 2)
'#(1 2)
'#(3 4 5)

procedure
(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-split-at-right #(1 2 3 4 5) 2)
'#(1 2 3)
'#(4 5)

procedure
(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-copy #(1 2 3 4))
'#(1 2 3 4)
> (vector-copy #(1 2 3 4) 3)
'#(4)
> (vector-copy #(1 2 3 4) 2 3)
'#(3)

procedure
(vector-set/copy vec pos val) → vector?
  vec : vector?
  pos : exact-nonnegative-integer?
  val : any/c

Creates a fresh vector with the same content as vec, except that val is the element at index pos.

Examples:

> (vector-set/copy #(1 2 3) 0 'x)
'#(x 2 3)
> (vector-set/copy #(1 2 3) 2 'x)
'#(1 2 x)

Added in version 8.11.1.10 of package base.

procedure
(vector-extend vec new-size [val]) → vector?
  vec : vector?
  new-size : (and/c exact-nonnegative-integer? (>=/c (vector-length vec)))
  val : any/c = 0

Creates a fresh vector of length new-size where the prefix is filled with the elements of vec and the remainder with val.

Examples:

> (vector-extend #(1 2 3) 10)
'#(1 2 3 0 0 0 0 0 0 0)
> (vector-extend #(1 2 3) 10 #f)
'#(1 2 3 #f #f #f #f #f #f #f)
> (vector-extend #(1 2 3) 3 #f)
'#(1 2 3)

Added in version 8.12.0.10 of package base.

procedure
(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 even? #(1 2 3 4 5 6))
'#(2 4 6)

procedure
(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-filter-not even? #(1 2 3 4 5 6))
'#(1 3 5)

procedure
(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:

> (vector-count even? #(1 2 3 4 5))
2
> (vector-count = #(1 2 3 4 5) #(5 4 3 2 1))
1

procedure
(vector-argmin proc vec) → any/c
proc : (-> any/c real?)
vec : vector?

This returns the first element in the non-empty vector vec that minimizes the result of proc.

Examples:

> (vector-argmin car #((3 pears) (1 banana) (2 apples)))
'(1 banana)
> (vector-argmin car #((1 banana) (1 orange)))
'(1 banana)

procedure
(vector-argmax proc vec) → any/c
proc : (-> any/c real?)
vec : vector?

This returns the first element in the non-empty vector vec that maximizes the result of proc.

Examples:

> (vector-argmax car #((3 pears) (1 banana) (2 apples)))
'(3 pears)
> (vector-argmax car #((3 pears) (3 oranges)))
'(3 pears)

procedure
(vector-member v vec [is-equal?]) → (or/c natural-number/c #f)
  v : any/c
  vec : vector?
  is-equal? : (-> any/c any/c any/c) = equal?

Locates the first element of vec that is equal to v according to is-equal?. If such an element exists, the index of that element in vec is returned. Otherwise, the result is #f.

Examples:

> (vector-member 2 (vector 1 2 3 4))
1
> (vector-member 9 (vector 1 2 3 4))
#f
> (vector-member 1.0 (vector 1 2 3 4) =)
0

Changed in version 8.15.0.1 of package base: Added the is-equal? argument.

procedure
(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-memv 2 (vector 1 2 3 4))
1
> (vector-memv 9 (vector 1 2 3 4))
#f

procedure
(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:

> (vector-memq 2 (vector 1 2 3 4))
1
> (vector-memq 9 (vector 1 2 3 4))
#f

procedure
(vector-sort vec
less-than?
[ start
end
#:key key
#:cache-keys? cache-keys?]) → vector?
  vec : vector?
  less-than? : (any/c any/c . -> . any/c)
  start : exact-nonnegative-integer? = 0
  end : exact-nonnegative-integer? = (vector-length vec)
  key : (or/c #f (any/c . -> . any/c)) = #f
  cache-keys? : boolean? = #f

Like sort, but operates on vectors; a fresh vector of length (- end start) is returned containing the elements from indices start (inclusive) through end (exclusive) of vec, but in sorted order (i.e., vec is not modified). This sort is stable (i.e., the order of “equal” elements is preserved).

Examples:

> (define v1 (vector 4 3 2 1))
> (vector-sort v1 <)
'#(1 2 3 4)
> v1
'#(4 3 2 1)
> (define v2 (vector '(4) '(3) '(2) '(1)))
> (vector-sort v2 < 1 3 #:key car)
'#((2) (3))
> v2
'#((4) (3) (2) (1))

Added in version 6.6.0.5 of package base.

procedure
(vector-sort! vec
less-than?
[ start
end
#:key key
#:cache-keys? cache-keys?]) → void?
  vec : (and/c vector? (not/c immutable?))
  less-than? : (any/c any/c . -> . any/c)
  start : exact-nonnegative-integer? = 0
  end : exact-nonnegative-integer? = (vector-length vec)
  key : (any/c . -> . any/c) = (λ (x) x)
  cache-keys? : boolean? = #f

Like vector-sort, but updates indices start (inclusive) through end (exclusive) of vec by sorting them according to the less-than? procedure.

Examples:

> (define v1 (vector 4 3 2 1))
> (vector-sort! v1 <)
> v1
'#(1 2 3 4)
> (define v2 (vector '(4) '(3) '(2) '(1)))
> (vector-sort! v2 < 1 3 #:key car)
> v2
'#((4) (2) (3) (1))

Added in version 6.6.0.5 of package base.

procedure
(vector*-copy vec [start end]) → vector?
  vec : (and/c vector? (not/c impersonator?))
  start : exact-nonnegative-integer? = 0
  end : exact-nonnegative-integer? = (vector-length v)
procedure
(vector*-append vec ...) → vector?
  vec : (and/c vector? (not/c impersonator?))
procedure
(vector*-set/copy vec pos val) → vector?
  vec : (and/c vector? (not/c impersonator?))
  pos : exact-nonnegative-integer?
  val : any/c
procedure
(vector*-extend vec pos [val]) → vector?
  vec : (and/c vector? (not/c impersonator?))
  pos : exact-nonnegative-integer?
  val : any/c = 0

Like vector-copy, vector-append, vector-set/copy, and vector-extend but constrained to work on vectors that are not impersonators.

Added in version 8.11.1.10 of package base.
Changed in version 8.12.0.10: Added vector*-extend.

1	Language Model
2	Notation for Documentation
3	Syntactic Forms
4	Datatypes
5	Structures
6	Classes and Objects
7	Units
8	Contracts
9	Pattern Matching
10	Control Flow
11	Concurrency and Parallelism
12	Macros
13	Input and Output
14	Reflection and Security
15	Operating System
16	Memory Management
17	Unsafe Operations
18	Running Racket
	Bibliography
	Index

4.1	Equality
4.2	Booleans
4.3	Numbers
4.4	Strings
4.5	Byte Strings
4.6	Characters
4.7	Symbols
4.8	Regular Expressions
4.9	Keywords
4.10	Pairs and Lists
4.11	Mutable Pairs and Lists
4.12	Vectors
4.13	Stencil Vectors
4.14	Boxes
4.15	Hash Tables
4.16	Treelists
4.17	Sequences and Streams
4.18	Dictionaries
4.19	Sets
4.20	Procedures
4.21	Void
4.22	Undefined