27.2.3 Views over bytevectors

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

• The full bytevector.
• The start index: the index of the first byte included in the selected subvector.
• The past index: the index of the byte past the last byte included in the selected subvector.

To select the subvector #vu8(6 7 8 9) from the bytevector #vu8(0 1 2 3 4 5 6 7 8 9) we have to determine the half–open range of bytes, which is [6, 10), then apply a function to the arguments:

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

while to select the whole bytevector we can do:

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

or:

(let ((bv '#vu8(0 1 2 3 4 5 6 7 8 9)))
  (%the-function bv 0 (bytevector-length bv)))

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

(the-function '#vu8(0 1 2 3 4 5 6 7 8 9))
        ; select the whole bytevector

(the-function (view '#vu8(0 1 2 3 4 5 6 7 8 9)))
        ; select the whole bytevector

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

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

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

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

?bytevector

(view ?bytevector)

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

(view ?bytevector (start ?start-index))

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

(view ?bytevector (past ?past-index))

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

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

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

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

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.