6.9 Bytevectors

Bytevectors represent blocks of binary data. They are fixed-length sequences of bytes, where a byte is an exact integer 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. This number 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 in programs.

procedure: bytevector? obj ¶

Returns #t if obj is a bytevector. Otherwise, #f is returned.

procedure: make-bytevector k ¶

procedure: make-bytevector k byte ¶

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.

(make-bytevector 2 12) ⇒ #u8(12 12)

procedure: bytevector byte… ¶

Returns a newly allocated bytevector containing its arguments.

(bytevector 1 3 5 1 3 5) ⇒ #u8(1 3 5 1 3 5)
(bytevector)             ⇒ #u8()

procedure: bytevector-length bytevector ¶

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

procedure: bytevector-u8-ref bytevector k ¶

It is an error if k is not a valid index of bytevector.

Returns the kth byte of bytevector.

(bytevector-u8-ref '#u8(1 1 2 3 5 8 13 21)
            5)
    ⇒  8

procedure: bytevector-u8-set! bytevector k byte ¶

It is an error if k is not a valid index of bytevector.

Stores byte as the kth byte of bytevector.

(let ((bv (bytevector 1 2 3 4)))
  (bytevector-u8-set! bv 1 3)
  bv)
    ⇒ #u8(1 3 3 4)

procedure: bytevector-copy bytevector ¶

procedure: bytevector-copy bytevector start ¶

procedure: bytevector-copy bytevector start end ¶

Returns a newly allocated bytevector containing the bytes in bytevector between start and end.

(define a #u8(1 2 3 4 5))
(bytevector-copy a 2 4)) ⇒ #u8(3 4)

procedure: bytevector-copy! to at from ¶

procedure: bytevector-copy! to at from start ¶

procedure: bytevector-copy! to at from start end ¶

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).

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.

(define a (bytevector 1 2 3 4 5))
(define b (bytevector 10 20 30 40 50))
(bytevector-copy! b 1 a 0 2)
b ⇒ #u8(10 1 2 40 50)

Note: This procedure appears in R⁶RS, but places the source before the destination, contrary to other such procedures in Scheme.

procedure: bytevector-append bytevector… ¶

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

(bytevector-append #u8(0 1 2) #u8(3 4 5))
    ⇒ #u8(0 1 2 3 4 5)

procedure: utf8->string bytevector ¶

procedure: utf8->string bytevector start ¶

procedure: utf8->string bytevector start end ¶

procedure: string->utf8 string ¶

procedure: string->utf8 string start ¶

procedure: string->utf8 string start end ¶

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

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.

(utf8->string #u8(#x41))        ⇒ "A"
(string->utf8 "λ") ⇒ #u8(#xCE #xBB)