# (lispkit gvector)

This library defines an API for *growable vectors*. Just like regular vectors, *growable vectors* are heterogeneous sequences of elements which are indexed by a range of integers. Unlike for regular vectors, the length of a *growable vector* is not fixed. Growable vectors may expand or shrink in length. Nevertheless, growable vectors are fully compatible to regular vectors and all operations from library `(lispkit vector)`

may also be used in combination with growable vectors. The main significance of library `(lispkit gvector)`

is in providing functions to construct growable vectors. Growable vectors are always *mutable* by design.

Just like for vectors with a fixed length, the valid indexes of a growable 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 growable vector.

Two growable vectors are `equal?`

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

. A growable vector is never `equal?`

a regular vector of fixed length.

Growable vectors are written using the notation `#g(obj ...)`

. For example, a growable vector of initial length 3 containing the number one as element 0, the list (8 16 32) as element 1, and the string "Scheme" as element 2 can be written as follows: `#g(1 (8 16 32) "Scheme")`

.

Growable vector constants are self-evaluating, so they do not need to be quoted in programs.

## Predicates

Returns `#t`

if *obj* is a growable vector; otherwise returns `#f`

.

Returns `#t`

if *obj* is a growable vector of length zero; otherwise returns `#f`

.

## Constructors

Returns a newly allocated growable vector of capacity *c*. The capacity is used to pre-allocate space for up to *c* elements.

Returns a newly allocated growable vector whose elements contain the given arguments.

The `list->gvector`

procedure returns a newly created growable vector initialized to the elements of the list *list* in the order of the list.

Returns a newly allocated growable vector initialized to the elements of the vector *vector* in the order of *vector*.

Returns a newly allocated copy of the elements of the given growable vector between *start* and *end*, but excluding the element at index *end*. The elements of the new vector are the same (in the sense of `eqv?`

) as the elements of the old.

Returns a newly allocated growable vector whose elements are the concatenation of the elements of the given vectors.

Returns a newly allocated growable vector whose elements are the concatenation of the elements of the vectors in *xs*. *xs* is a proper list of vectors.

Constructs a new growable vector of the shortest size of the vector arguments *vector1*, *vector2*, etc. Each element at index *i* of the new vector is mapped from the old vectors by `(f (vector-ref vector1 i) (vector-ref vector2 i) ...)`

. The dynamic order of the application of f is unspecified.

Constructs a new growable vector of the shortest size of the vector arguments *vector1*, *vector2*, etc. Each element at index *i* of the new vector is mapped from the old vectors by `(f i (vector-ref vector1 i) (vector-ref vector2 i) ...)`

. The dynamic order of the application of f is unspecified.

## Iterating over vector elements

`gvector-for-each`

implements a simple vector iterator: it applies *f* to the corresponding list of parallel elements from vectors *vector1 vector2 ...* in the range *[0, length)*, where *length* is the length of the smallest vector argument passed. In contrast with `gvector-map`

, *f* is reliably applied to each subsequent element, starting at index 0, in the vectors.

`gvector-for-each/index`

implements a simple vector iterator: it applies *f* to the index *i* and the corresponding list of parallel elements from *vector1 vector2 ...* in the range *[0, length)*, where *length* is the length of the smallest vector argument passed. The only difference to `gvector-for-each`

is that `gvector-for-each/index`

always passes the current index as the first argument of *f* in addition to the elements from the vectors *vector1 vector2 ...*.

## Managing vector state

Returns the number of elements in growable vector *vector* as an exact integer.

The `gvector-ref`

procedure returns the contents of element *k* of *vector*. It is an error if *k* is not a valid index of *vector* or if *vector* is not a growable vector.

The `vector-set!`

procedure stores *obj* in element *k* of growable vector *vector*. It is an error if *k* is not a valid index of *vector* or if *vector* is not a growable vector.

Appends the values *obj*, ... to growable vector *vector*. This increases the length of the growable vector by the number of *obj* arguments.

Inserts the value *obj* into growable vector *vector* at index *k*. This increases the length of the growable vector by one.

Removes the element at index *k* from growable vector *vector*. This decreases the length of the growable vector by one.

Removes the last element of the growable vector *vector*. This decreases the length of the growable vector by one.

## Destructive growable vector operations

Procedures which operate only on a part of a growable vector specify the applicable range in terms of an index interval [*start*; *end*[; i.e. the *end* index is always exclusive.

Copies the elements of vector *from* between *start* and *end* to growable vector *to*, starting at *at*. The order in which elements are copied is unspecified, except that if the source and destination overlap, copying takes place as if the source is first copied into a temporary vector and then into the destination. *start* defaults to 0 and *end* defaults to the length of *vector*.

It is an error if *at* is less than zero or greater than the length of *to*. It is also an error if `(- (gvector-length to) at)`

is less than `(- end start)`

.

Appends the elements of the vectors *v1 ...* to the growable vector *vector* in the given order.

Procedure `gvector-reverse!`

destructively reverses the contents of growable *vector* between *start* and *end*. *start* defaults to 0 and *end* defaults to the length of *vector*.

Procedure `gvector-sort!`

destructively sorts the elements of growable vector *vector* using the "less than" predicate *pred*.

Similar to `gvector-map`

which maps the various elements into a new vector via function *f*, procedure `gvector-map!`

destructively inserts the mapped elements into growable vector *vector1*. The dynamic order in which *f* gets applied to the elements is unspecified.

Similar to `gvector-map/index`

which maps the various elements together with their index into a new vector via function *f*, procedure `gvector-map/index!`

destructively inserts the mapped elements into growable vector *vector1*. The dynamic order in which *f* gets applied to the elements is unspecified.

## Converting growable vectors

The `gvector->list`

procedure returns a newly allocated list of the objects contained in the elements of growable *vector* between *start* and *end* in the same order as in *vector*.

The `gvector->list`

procedure returns a newly allocated list of the objects contained in the elements of growable vector *vector* between *start* and *end* in the same order as in *vector*.

Last updated