This SRFI proposes a comprehensive and
complete library of vector operations accompanied by a freely
available and complete reference implementation. The reference
implementation is unencumbered by copyright, and useable with no
modifications on any Scheme system that is
R5RS-compliant. It also provides several
hooks for implementation-specific optimization as well.

Because this SRFI is more of a library or module specification
than a request for additions to readers or any other internal
implementation detail, in an implementation that supports a
module or structure or package or library or unit (et cetera)
systems, these procedures should be contained in a module /
structure / package / library / unit called vector-lib.

Many Scheme implementations provide several vector operations
beyond the minuscule set that R5RS defines (the typical
vector-append,
vector-map, et cetera), but
often these procedures have different names, take arguments in
different orders, don't take the same number of arguments, or
have some other flaw that makes them unportable. For this
reason, this SRFI is proposed.

It should be noted that no vector sorting procedures are provided
by this SRFI, because there already is a SRFI for such a purpose
(SRFI 32 (sort-lib)), which
includes routines for sorting not only vectors but also lists.

Here is an index of the procedures provided by this package.
Those marked by bold are provided in
R5RS and those marked by bold
italic are defined by R5RS but are
modified from their original definitions.

In this section containing specifications of procedures, the
following notation is used to specify parameters and return
values:

(f arg1 arg2 ···)
-> something

Indicates a function f takes the parameters
arg1 arg2
··· and returns a value of the
type something. If something
is unspecified, then what f returns is
implementation-dependant; this SRFI does not specify what it
returns, and in order to write portable code, the return value
should be ignored.

vec

The argument in this place must be a vector, i.e. it must
satisfy the predicate
vector?.

i, j, start, size

The argument in this place must be a nonnegative integer, i.e.
it must satisfy the predicates integer? and either
zero? or positive?. The third case of it
indicates the index at which traversal begins; the fourth case
of it indicates the size of a vector.

end

The argument in this place must be a positive integer, i.e. it
must satisfy the predicates integer? and
positive?. This indicates the index directly before
which traversal will stop — processing will occur until
the index of the vector is end. It is the
closed right side of a range.

f

The argument in this place must be a function of one or more
arguments, returning exactly one value.

pred?

The argument in this place must be a function of one or more
arguments that returns one value, which is treated as a
boolean.

x, y, z, seed, knil, fill, key, value

The argument in this place may be any Scheme value.

[something]

Indicates that something is an optional
argument; it needn't necessarily be applied.
Something needn't necessarily be one thing; for
example, this usage of it is perfectly valid:

[start [end]]

and is indeed used quite often.

something ···

Indicates that zero or more somethings are
allowed to be arguments.

something1 something2
···

Indicates that at least one something must be
arguments.

something1 something2
···
somethingn

Exactly equivalent to the previous argument notation, but this
also indicates that n will be used later in the
procedure description.

It should be noted that all of the procedures that iterate across
multiple vectors in parallel stop iterating and produce the final
result when the end of the shortest vector is reached. The sole
exception is vector=, which
automatically returns #f if the vectors' lengths vary.

The fundamental vector constructor. Creates a vector whose
length is length and iterates across each index
k between 0 and
length, applying f at each
iteration to the current index and current seeds, in that
order, to receive n + 1 values: first, the
element to put in the kth slot of the new
vector and n new seeds for the next iteration.
It is an error for the number of seeds to vary between
iterations.

Allocates a new vector whose length is end -
start and fills it with elements from
vec, taking elements from vec
starting at index start and stopping at index
end. start defaults to
0 and end defaults to the value of
(vector-lengthvec). If end extends beyond the
length of vec, the slots in the new vector that
obviously cannot be filled by elements from vec
are filled with fill, whose default value is
unspecified.

Vector structure comparator, generalized across user-specified
element comparators. Vectors a and
b are considered equal by vector= iff
their lengths are the same, and for each respective elements
Ea and
Eb, (elt=? EaEb) returns a true value.
Elt=? is always applied to two arguments.
Element comparison must be consistent with eq; that
is, if (eq? EaEb)
results in a true value, then (elt=? EaEb) must also result in a true value.
This may be exploited to avoid unnecessary element comparisons.
(The reference implementation does, but it does not consider
the situation where elt=? is in fact itself
eq? to avoid yet more unnecessary comparisons.)

If there are only zero or one vector arguments, #t is
automatically returned. The dynamic order in which comparisons
of elements and of vectors are performed is left completely
unspecified; do not rely on a particular order.

Examples:

(vector= eq? '#(a b c d) '#(a b c d))
#t

(vector= eq? '#(a b c d) '#(a b d c))
#f

(vector= = '#(1 2 3 4 5) '#(1 2 3 4))
#f

(vector= = '#(1 2 3 4) '#(1 2 3 4))
#t

The two trivial cases.

(vector= eq?)
#t

(vector= eq? '#(a))
#t

Note the fact that we don't use vector literals in the next two
— it is unspecified whether or not literal vectors with
the same external representation are eq?.

[R5RS] Returns the length of vec, the number of
locations reachable from vec. (The careful
word 'reachable' is used to allow for 'vector slices,' whereby
vec refers to a larger vector that contains
more locations that are unreachable from vec.
This SRFI does not define vector slices, but later SRFIs may.)

The fundamental vector iterator. Kons is
iterated over each index in all of the vectors, stopping at the
end of the shortest; kons is applied as
(konsistate
(vector-refvec1i)
(vector-refvec2i)
···)
where state is the current state value —
the current state value begins with knil, and
becomes whatever kons returned at the
respective iteration —, and i is the
current index.

Constructs a new vector of the shortest size of the vector
arguments. Each element at index i of the new
vector is mapped from the old vectors by
(fi
(vector-refvec1i)
(vector-refvec2i)
···).
The dynamic order of application of f is
unspecified.

Similar to vector-map, but
rather than mapping the new elements into a new vector, the new
mapped elements are destructively inserted into
vec1. Again, the dynamic order of
application of f unspecified, so it is
dangerous for f to apply either
vector-ref or
vector-set! to
vec1 in f.

Simple vector iterator: applies f to each index
in the range [0, length), where
length is the length of the smallest vector
argument passed, and the respective list of parallel elements
from vec1 vec2
··· at that index. In contrast with
vector-map, f
is reliably applied to each subsequent elements, starting at
index 0, in the vectors.

Counts the number of parallel elements in the vectors that
satisfy pred?, which is applied, for each index
i in the range [0, length)
— where length is the length of the
smallest vector argument —, to i and each
parallel element in the vectors at that index, in order.

Finds & returns the index of the first elements in
vec1 vec2
··· that do not satisfy
pred?. If all the values in the vectors
satisfy pred? until the end of the shortest
vector, this returns #f. This is equivalent to:

Similar to vector-index
and
vector-index-right,
but instead of searching left to right or right to left, this
performs a binary search. cmp should be a
procedure of two arguments and return a negative integer, which
indicates that its first argument is less than its second,
zero, which indicates that they are equal, or a positive
integer, which indicates that the first argument is greater
than the second argument. An example cmp might
be:

Finds the first set of elements in parallel from
vec1 vec2
··· for which
pred? returns a true value. If such a parallel
set of elements exists, vector-any returns the value
that pred? returned for that set of elements.
The iteration is strictly left-to-right.

If, for every index i between 0 and the length
of the shortest vector argument, the set of elements
(vector-refvec1i)
(vector-refvec2i)
···
satisfies pred?, vector-every returns
the value that pred? returned for the last
set of elements, at the last index of the shortest vector. The
iteration is strictly left-to-right.

Copies a block of elements from source to
target, both of which must be vectors, starting
in target at tstart and
starting in source at sstart,
ending when send - sstart elements have
been copied. It is an error for target to have
a length less than tstart + (send -
sstart). Sstart defaults to
0 and send defaults to the length of
source.

Like vector-copy!, but
this copies the elements in the reverse order. It is an error
if target and source are
identical vectors and the target & source ranges overlap;
however, if tstart = sstart,
vector-reverse-copy! behaves as
(vector-reverse!targettstartsend)
would.

Thanks to Olin Shivers for his wonderfully complete
list and string
packages; to all the members of the
#scheme IRC
channel on Freenode
who nitpicked a great deal, but also helped quite a lot in
general, and helped test the reference implementation in various
Scheme systems; to Michael Burschik for his numerous comments; to
Sergei Egorov for helping to narrow down the procedures; to Mike
Sperber for putting up with an extremely overdue draft; to
Felix Winkelmann for continually bugging me about finishing up the
SRFI so that it would be only overdue and not withdrawn; and to
everyone else who gave questions, comments, thoughts, or merely
attention to the SRFI.

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.