Bytevectors
~~~~~~~~~~~

A _bytevector_ is a data structure that stores bytes -- exact
8-bit unsigned integers. Bytevectors are useful in constructing
system interfaces and other low-level programming. In Larceny,
many bytevector-like structures -- bignums, for example --
are implemented in terms of a
lower-level _bytevector-like_ data type. The operations on
generic bytevector-like structures are particularly fast but
useful largely in code that manipulates Larceny's data
representations.

The <<BytevectorsLibrary, `(rnrs bytevectors)` library>> now
provides a large set of procedures that, in Larceny, are
defined using the procedures described below.

proc:make-bytevector[kind="Integrable procedure",args="length",result="bytevector"]
proctempl:make-bytevector[kind="Integrable procedure",args="length fill",result="bytevector"]

Returns a bytevector of the desired length.
If no second argument is given, then the bytevector has not
been initialized and most likely contains garbage.

_Operations on bytevector structures_

proctempl:bytevector?[args="obj",result="boolean"]

proctempl:bytevector-length[args="bytevector",result="integer"]

proctempl:bytevector-ref[args="bytevector offset",result="byte"]

proctempl:bytevector-set![args="bytevector offset byte",result="unspecified"]

proctempl:bytevector-equal?[args="bytevector1 bytevector2",result="boolean"]

proctempl:bytevector-fill![args="bytevector byte",result="unspecified"]

proctempl:bytevector-copy[args="bytevector",result="bytevector"]

These procedures do what you expect.
All are integrable, except `bytevector-equal?` and `bytevector-copy`.
The `bytevector-equal?` name is deprecated, since the
R6RS calls it `bytevector=?`.

_Operations on bytevector-like structures_

proctempl:bytevector-like?[args="obj",result="boolean"]

proctempl:bytevector-like-length[args="bytevector",result="integer"]

proctempl:bytevector-like-ref[args="bytevector offset",result="byte"]

proctempl:bytevector-like-set![args="bytevector offset byte",result="unspecified"]

proctempl:bytevector-like-equal?[args="bytevector1 bytevector2",result="boolean"]

proctempl:bytevector-like-copy[args="bytevector",result="bytevector"]
    

A bytevector-like structure is a low-level representation
for indexed arrays of uninterpreted bytes.  Bytevector-like
structures are used to represent types such as bignums and
flonums.

There is no way to construct a "generic" bytevector-like
structure; use the constructors for specific bytevector-like
types.

The bytevector-like operations operate on all bytevector-like
structures.  All are integrable, except `bytevector-like-equal?`
and `bytevector-like-copy`.  All are deprecated because they
violate abstraction barriers and make your code
representation-independent; they are useful mainly to
Larceny developers, who might otherwise be tempted to
write some low-level operations in C or assembly language.

