Next: , Previous: Ports, Up: Top

## 18 Vectors

A vector is an object that contains a sequence of arbitrary klisp objects. A vector has a length that is fixed at creation time, and as many objects, indexed from `0` to `length-1`. Compared to lists, klisp vectors use less size and have constant access time for any element.

Vectors may be mutable or immutable. If an attempt is made to mutate an immutable vector, an error is signaled. Two immutable vectors are “eq?” iff they are “equal?”. Two mutable vectors are “eq?” if they were created by the same constructor call. Two mutable vectors are “equal?” iff they have the same length and have “equal?” objects in each position. As is the case for lists, in order to handle possibly cyclic structures, the “equal?” algorithm considers vectors as FSMs where it position is a state change. There is only one empty vector (that is, a vector of length 0) and that vector is immutable. The vector type is encapsulated.

SOURCE NOTE: The report doesn't currently include vectors. They are taken from r7rs scheme.

— Applicative: vector? (vector? . objects)

The primitive type predicate for type vector. `vector?` returns true iff all the objects in `objects` are of type vector.

— Applicative: immutable-vector? (immutable-vector? objects)
— Applicative: mutable-vector? (mutable-vector? objects)

The primitive type predicates for types immutable vector and mutable vector. These return true iff all the objects in `objects` are of type immutable vector or mutable vector respectively.

— Applicative: make-vector (make-vector k [obj])

Applicative `make-vector` constructs and returns a new mutable vector of length `k`. If `obj` is specified, then all objects in the returned vector are `obj`, otherwise the content of the vector is unspecified.

— Applicative: vector-length (vector-length vector)

Applicative `vector-length` returns the length of `vector`.

— Applicative: vector-ref (vector-ref vector k)

Applicative `vector-ref` returns the object of `vector` at position `k`. If `k` is out of bounds (i.e. less than `0` or greater or equal than `(vector-length vector)`) an error is signaled.

— Applicative: vector-set! (vector-set! vector k obj)

Applicative `vector-set!` replaces the object with index `k` in `vector` with object `obj`. If `k` is out of bounds, or `vector` is immutable, an error is signaled. The result returned by `vector-set!` is inert.

— Applicative: vector (vector . objs)

Applicative `vector` contructs and return a new mutable vector composed of the object arguments.

— Applicative: vector->list (vector->list vector)
— Applicative: list->vector (list->vector objs)

These applicatives convert between vectors and lists. The objects returned by these applicatives are always mutable.

— Applicative: vector-copy (vector-copy vector)

Applicative `vector-copy` constructs and returns a new mutable vector with the same length and objects as `vector`.

— Applicative: vector->bytevector (vector->bytevector vector)
— Applicative: bytevector->vector (bytevector->vector bytevector)

These applicatives convert between vectors and bytevectors. If a vector containing objects other than exact integers between 0 and 255 inclusive are passed to `vector->bytevector`, an error is signaled. The objects returned by these applicatives are always mutable.

— Applicative: vector->string (vector->string vector)
— Applicative: string->vector (string->vector string)

These applicatives convert between vectors and strings. If a vector containing objects other than characters is passed to `vector->string`, an error is signaled. The objects returned by these applicatives are always mutable.

— Applicative: vector-copy! (vector-copy! vector1 vector2)

vector2 should have a length greater than or equal to that of vector1.

Copies the values in vector1 to the corresponding positions in vector2. If vector2 is immutable, an error is signaled. The result returned by `vector-copy!` is inert.

— Applicative: vector-copy-partial (vector-copy-partial vector k1 k2)

Both `k1` & `k2` should be valid indexes in `vector`. Also it should be the case that `k1 <= k2`.

Applicative `vector-copy-partial` constructs and returns a new mutable vector with length `k2 - k1`, with the objects from `vector`, starting at index `k1` (inclusive) and ending at index `k2` (exclusive).

— Applicative: vector-copy-partial! (vector-copy-partial! vector1 k1 k2 vector2 k3)

Both `k1` & `k2-1` should be valid indexes in `vector1`. Also it should be the case that `k1 <= k2`. Both `k3` & `k3 + (k2-k1) - 1` should be valid indexes in `vector2`.

Applicative `vector-copy-partial!` copies objects k1 (inclusive) through k2 (exclusive) from `vector1` to the `k2-k1` positions in `vector2` starting at `k3`. If `vector2` is an immutable vector, an error is signaled. The result returned by `vector-copy-partial!` is inert.

— Applicative: vector-fill! (vector-fill! vector obj)

Applicative `vector-fill!` replaces all the objects in `vector` with object `obj`. If `vector` is an immutable vector, an error is signaled. The result returned by `vector-fill!` is inert.

— Applicative: vector->immutable-vector (vector->immutable-vector vector)

Applicative `vector->immutable-vector` constructs and returns a new immutable vector with the same length and objects as `vector`.