# (lispkit bytevector)

*Bytevectors* represent blocks of binary data. They are fixed-length sequences of bytes, where a *byte* is a fixnum in the range from 0 to 255 inclusive. A bytevector is typically more space-efficient than a vector containing the same values.

The *length* of a bytevector is the number of elements that it contains. The length is a non-negative integer that is fixed when the bytevector is created. The *valid indexes* of a bytevector are the exact non-negative integers less than the length of the bytevector, starting at index zero as with vectors.

Bytevectors are written using the notation `#u8(byte ...)`

. For example, a bytevector of length 3 containing the byte 0 in element 0, the byte 10 in element 1, and the byte 5 in element 2 can be written as follows: `#u8(0 10 5)`

. Bytevector constants are self-evaluating, so they do not need to be quoted.

## Basic

Returns `#t`

if *obj* is a bytevector; otherwise, `#f`

is returned.

Returns a newly allocated bytevector containing its arguments as bytes in the given order.

The `make-bytevector`

procedure returns a newly allocated bytevector of length *k*. If *byte* is given, then all elements of the bytevector are initialized to *byte*, otherwise the contents of each element are unspecified.

Returns the length of bytevector in bytes as an exact integer.

Returns the *k*-th byte of *bytevector*. It is an error if *k* is not a valid index of bytevector.

Stores *byte* as the *k*-th byte of bytevector. It is an error if *k* is not a valid index of bytevector.

Returns a newly allocated bytevector containing the bytes in *bytevector* between *start* and *end*. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

Copies the bytes of bytevector *from* between *start* and *end* to bytevector *to*, starting at *at*. The order in which bytes 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 bytevector and then into the destination. This can be achieved without allocating storage by making sure to copy in the correct direction in such circumstances.

It is an error if *at* is less than zero or greater than the length of *to*. It is also an error if `(- (bytevector-length to) at)`

is less than `(- end start)`

.

Returns a newly allocated bytevector whose elements are the concatenation of the elements in the given bytevectors.

## Input/Output

Reads the file at *path* and stores its content in a new bytevector which gets returned by `read-binary-file`

.

Writes the bytes of *bytevector* between *start* and *end* into a new binary file at *path*. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

## Compression

`bytevector-deflate`

encodes *bytevector* between *start* and *end* using the *Deflate* data compression alogrithm returning a new compressed bytevector. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

`bytevector-inflate`

assumes *bytevector* is encoded using the *Deflate* data compression alogrithm between *start* and *end*. The procedure returns a corresponding new decoded bytevector.

If is an error if *bytevector*, between *start* and *end*, is not encoded using *Deflate*. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

`bytevector-zip`

encodes *bytevector* between *start* and *end* using the *Deflate* data compression alogrithm returning a new compressed bytevector which is using a *zlib* wrapper. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

`bytevector-unzip`

assumes *bytevector* is using a *zlib* wrapper for data encoded using the *Deflate* data compression alogrithm between *start* and *end*. The procedure returns a corresponding new decoded bytevector.

If is an error if *bytevector*, between *start* and *end*, is not encoded using *Deflate* or is not using the *zlib* wrapper format. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

`bytevector-gzip`

encodes *bytevector* between *start* and *end* using the *Deflate* data compression alogrithm returning a new compressed bytevector which is using a *gzip* wrapper. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

`bytevector-gunzip`

assumes *bytevector* is using a *gzip* wrapper for data encoded using the *Deflate* data compression alogrithm between *start* and *end*. The procedure returns a corresponding new decoded bytevector.

If is an error if *bytevector*, between *start* and *end*, is not encoded using *Deflate* or is not using the *gzip* wrapper format. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

## Advanced

These procedures translate between strings and bytevectors that encode those strings using the UTF-8 encoding. The `utf8->string`

procedure decodes the bytes of a *bytevector* between *start* and *end* and returns the corresponding string. The `string->utf8`

procedure encodes the characters of a *string* between *start* and *end* and returns the corresponding bytevector.

It is an error for *bytevector* to contain invalid UTF-8 byte sequences.

`bytevector->base64`

encodes *bytevector* between *start* and *end* as a string consisting of ASCII characters using the *Base64* encoding scheme. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

`base64->bytevector`

assumes string *str* is encoded using *Base64* between *start* and *end* and returns a corresponding new decoded bytevector.

If is an error if *str* between *start* and *end* is not a valid *Base64*-encoded string. If *end* is not provided, it is assumed to be the length of *str*. If *start* is not provided, it is assumed to be 0.

`bytevector-adler32`

computes the Adler32 checksum for *bytevector* between *start* and *end*. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

`bytevector-crc32`

computes the CRC32 checksum for *bytevector* between *start* and *end*. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

Last updated