24.3 Views over vectors

Vector views are syntactic sugar to allow subvector specification with minimum overhead; views make use of auxiliary syntaxes exported by the library (vicare containers auxiliary-syntaxes) and reexported by (vicare containers vectors). Many low level vector functions act on subvectors specified with triplets of arguments:

• The full vector.
• The start index: The index of the first item in the selected subvector.
• The past index: The index of the item past the last item in the selected subvector.

To select the subvector #(2 3 4) from the vector #(0 1 2 3 4 5 6) we have to determine the half–open range of items, which is [2, 5), then apply a function to the arguments:

(%the-function '#(0 1 2 3 4 5 6) 2 5)

while to select the whole vector we can do:

(%the-function '#(0 1 2 3 4 5 6) 0 7)

or:

(let ((vec '#(0 1 2 3 4 5 6)))
  (%the-function vec 0 (vector-length vec)))

With the vector views implemented by (vicare containers vectors), the low level function is wrapped by a high level syntax which can be invoked as:

(the-function '#(0 1 2 3 4 5 6 7))
        ; select the whole vector

(the-function (view '#(0 1 2 3 4 5 6 7)))
        ; select the whole vector

(the-function (view '#(0 1 2 3 4 5 6 7)
                (start 3)))
        ; select the subvector [3, 8)

(the-function (view '#(0 1 2 3 4 5 6 7)
                (start 3)
                (past 6)))
        ; select the subvector [3, 6)

(the-function (view '#(0 1 2 3 4 5 6 7)
                (past 5)))
        ; select the subvector [0, 5)

instead of a triplet of arguments, the vector view is a single argument that can be:

?vector

(view ?vector)

The vector itself or an unquoted list holding the vector itself, prefixed by the view auxiliary syntax: it selects the whole vector.

(view ?vector (start ?start-index))

An unquoted list holding the vector and the start index, with auxiliary syntaxes view and start: it selects the subvector from the start index to the end.

(view ?vector (past ?past-index))

An unquoted list holding the vector and the past index, with auxiliary syntaxes view and past: it selects the subvector from zero to the selected past index.

(view ?vector (start ?start-index) (past ?past-index))

An unquoted list holding the vector, the start index and the past index, with auxiliary syntaxes view, start and past: it selects the subvector between the start and past indexes.

?vector, ?start-index and ?past-index can be arbitrary Scheme expressions. High level macros accepting two or more subvectors as arguments, support vector views for all of them. When we are concerned with the overhead of vector views, we can use the low level functions directly.

When the start and past index are negative, the view syntax normalises them as:

(if (negative? idx)
    (+ idx (vector-length string))
   idx)

so that negative indices are counted from the end of the vector: -1 selects the ultimate character, -2 selected the penultimate character and so on.

In the following documentation: low level functions and high level macros are documented together; only the meaning of arguments to the low level function are described, the meaning of high level arguments is obvious.