# (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
**(gvector? *****obj*****)** 
Returns `#t` if *obj* is a growable vector; otherwise returns `#f`.
**(gvector-empty? *****obj*****)**
Returns `#t` if *obj* is a growable vector of length zero; otherwise returns `#f`.
## Constructors
**(make-gvector)** \
\&#xNAN;**(make-gvector *****c*****)**
Returns a newly allocated growable vector of capacity *c*. The capacity is used to pre-allocate space for up to *c* elements.
**(gvector *****obj ...*****)**
Returns a newly allocated growable vector whose elements contain the given arguments.
```scheme
(gvector ’a ’b ’c) ⇒ #g(a b c)
```
**(list->gvector *****list*****)**
The `list->gvector` procedure returns a newly created growable vector initialized to the elements of the list *list* in the order of the list.
```scheme
(list->gvector ’(a b c)) ⇒ #g(a b c)
```
**(vector->gvector *****vector*****)**
Returns a newly allocated growable vector initialized to the elements of the vector *vector* in the order of *vector*.
**(gvector-copy *****vector*****)** \
\&#xNAN;**(gvector-copy *****vector start*****)**\
\&#xNAN;**(gvector-copy *****vector start end*****)**
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.
**(gvector-append *****vector ...*****)**
Returns a newly allocated growable vector whose elements are the concatenation of the elements of the given vectors.
```scheme
(gvector-append #(a b c) #g(d e f)) ⇒ #g(a b c d e f)
```
**(gvector-concatenate *****vector xs*****)**
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.
```scheme
(gvector-concatenate '(#g(a b c) #(d) #g(e f))) ⇒ #g(a b c d e f)
```
**(gvector-map *****f vector1 vector2 ...*****)**
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.
```scheme
(gvector-map + #(1 2 3 4 5) #g(10 20 30 40)) ⇒ #g(11 22 33 44)
```
**(gvector-map/index *****f vector1 vector2 ...*****)**
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.
```scheme
(gvector-map/index (lambda (i x y) (cons i (+ x y))) #g(1 2 3) #(10 20 30)) ⇒ #g((0 . 11) (1 . 22) (2 . 33))
```
## Iterating over vector elements
**(gvector-for-each *****f vector1 vector2 ...*****)**
`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.
```scheme
(gvector-for-each (lambda (x) (display x) (newline))
#g("foo" "bar" "baz" "quux" "zot"))
⇒
foo
bar
baz
quux
zot
```
**(gvector-for-each/index *****f vector1 vector2 ...*****)**
`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 ...*.
```scheme
(gvector-for-each/index
(lambda (i x) (display i)(display ": ")(display x)(newline))
#g("foo" "bar" "baz" "quux" "zot"))
⇒
0: foo
1: bar
2: baz
3: quux
4: zot
```
## Managing vector state
**(gvector-length *****vector*****)**
Returns the number of elements in growable vector *vector* as an exact integer.
**(gvector-ref *****vector k*****)**
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.
```scheme
(gvector-ref ’#g(1 1 2 3 5 8 13 21) 5) ⇒ 8
(gvector-ref ’#g(1 1 2 3 5 8 13 21) (exact (round (* 2 (acos -1))))) ⇒ 13
```
**(gvector-set! *****vector k obj*****)**
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.
```scheme
(let ((vec (gvector 0 '(2 2 2 2) "Anna")))
(gvector-set! vec 1 '("Sue" "Sue"))
vec)
⇒ #g(0 ("Sue" "Sue") "Anna")
```
**(gvector-add! *****vector obj ...*****)**
Appends the values *obj*, ... to growable vector *vector*. This increases the length of the growable vector by the number of *obj* arguments.
```scheme
(let ((vec (gvector 0 '(2 2 2 2) "Anna")))
(gvector-add! vec "Micha")
vec)
⇒ #g(0 (2 2 2 2) "Anna" "Micha")
```
**(gvector-insert! *****vector k obj*****)**
Inserts the value *obj* into growable vector *vector* at index *k*. This increases the length of the growable vector by one.
```scheme
(let ((vec (gvector 0 '(2 2 2 2) "Anna")))
(gvector-insert! vec 1 "Micha")
vec)
⇒ #g(0 "Micha" (2 2 2 2) "Anna")
```
**(gvector-remove! *****vector k*****)**
Removes the element at index *k* from growable vector *vector*. This decreases the length of the growable vector by one.
```scheme
(let ((vec (gvector 0 '(2 2 2 2) "Anna")))
(gvector-remove! vec 1)
vec)
⇒ #g(0 "Anna")
```
**(gvector-remove-last! *****vector*****)**
Removes the last element of the growable vector *vector*. This decreases the length of the growable vector by one.
```scheme
(let ((vec (gvector 0 '(2 2 2 2) "Anna")))
(gvector-remove-last! vec)
vec)
⇒ #g(0 (2 2 2 2))
```
## 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.
**(gvector-copy! *****to at from*****)** \
\&#xNAN;**(gvector-copy! *****to at from start*****)**\
\&#xNAN;**(gvector-copy! *****to at from start end*****)**
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)`.
```scheme
(define a (vector 1 2 3 4 5))
(define b (gvector 10 20 30 40 50))
(gvector-copy! b 1 a 0 2)
b ⇒ #g(10 1 2 40 50)
```
**(gvector-append! *****vector v1 ...*****)**
Appends the elements of the vectors *v1 ...* to the growable vector *vector* in the given order.
**(gvector-reverse! *****vector*****)** \
\&#xNAN;**(gvector-reverse! *****vector start*****)**\
\&#xNAN;**(gvector-reverse! *****vector start end*****)**
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*.
```scheme
(define a (gvector 1 2 3 4 5))
(vector-reverse! a)
a ⇒ #g(5 4 3 2 1)
```
**(gvector-sort! *****pred vector*****)**
Procedure `gvector-sort!` destructively sorts the elements of growable vector *vector* using the "less than" predicate *pred*.
```scheme
(define a (gvector 7 4 9 1 2 8 5))
(gvector-sort! < a)
a ⇒ #g(1 2 4 5 7 8 9)
```
**(gvector-map! *****f vector1 vector2 ...*****)**
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.
```scheme
(define a (gvector 1 2 3 4))
(gvector-map! + a #(10 20 30))
a ⇒ #g(11 22 33 4)
```
**(gvector-map/index! *****f vector1 vector2 ...*****)**
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.
```scheme
(define a #g(1 2 3 4))
(gvector-map/index! (lambda (i x y) (cons i (+ x y))) a #(10 20 30))
a ⇒ #g((0 . 11) (1 . 22) (2 . 33) 4)
```
## Converting growable vectors
**(gvector->list *****vector*****)** \
\&#xNAN;**(gvector->list *****vector start*****)**\
\&#xNAN;**(gvector->list *****vector start end*****)**
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*.
```scheme
(gvector->list ’#g(dah dah didah)) ⇒ (dah dah didah)
(gvector->list ’#g(dah dah didah) 1 2) ⇒ (dah)
```
**(gvector->vector *****vector*****)** \
\&#xNAN;**(gvector->vector *****vector start*****)**\
\&#xNAN;**(gvector->vector *****vector start end*****)**
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*.
```scheme
(gvector->list ’#(dah dah didah)) ⇒ error since the argument is not a gvector
(gvector->list ’#g(dah dah didah) 1 2) ⇒ (dah)
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://www.lisppad.app/libraries/lispkit/lispkit-gvector.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.