bytevector-u8-ref(3scm) Scheme Programmer's Manual bytevector-u8-ref(3scm)

bytevector-u8-ref, bytevector-s8-ref - read a byte from a bytevector 

(import (rnrs))                     ;R6RS
(import (rnrs bytevectors))         ;R6RS
(import (scheme base))              ;R7RS


(bytevector-u8-ref bytevector k)
(bytevector-s8-ref bytevector k)

The bytevector-u8-ref procedure returns the byte at index k of bytevector as an unsigned byte ("octet").

The bytevector-s8-ref procedure returns the byte at index k of bytevector as a signed byte.

There are no notable variations between implementations of these procedures, apart from different levels of performance.

Returns an integer in the range of 0—255 (unsigned) or in the range -128—127 (signed). In R6RS this number is guaranteed to be a fixnum. 

(let ((b1 (make-bytevector 16 -127))
      (b2 (make-bytevector 16 255)))
  (list
    (bytevector-s8-ref b1 0)
    (bytevector-u8-ref b1 0)
    (bytevector-s8-ref b2 0)
    (bytevector-u8-ref b2 0)))
          => (-127 129 -1 255)
;; R7RS syntax. For R6RS, use #vu8(...) instead.
(bytevector-u8-ref '#u8(1 1 2 3 5 8 13 21)
                   5)
          => 8

These procedures are commonly used when a program is dealing directly with data from disk, the network or some other hardware. For more advanced non-uniform structures, a helper is usually used instead. See bytevectors(7scm) for more information.

The bytevector-u8-ref procedure is the fundamental procedure for reading from bytevectors from which all other bytevector read procedures can be built.

Bytevectors are absent from R5RS and earlier reports.

R7RS lacks bytevector-s8-ref, but it can be trivially implemented in terms of bytevector-u8-ref:

(define (bytevector-s8-ref bv k)
  (let ((v (bytevector-u8-ref bv k)))
    (if (< v 128) v (- v 256))))

This procedure can raise exceptions with the following condition types:
&assertion (R6RS)
The wrong number of arguments was passed or an argument was outside its domain. In particular, the index k must be a valid index of bytevector.
R7RS
The assertions described above are errors. Implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically.

bytevectors(7scm), fixnums(7scm), bytevector-u16-ref(3scm)

R6RS, R7RS

These procedures first appeared in R6RS, but they previously existed in a slightly different form as u8vector-ref and s8vector-ref in SRFI-4. The difference was that they required a vector of the matching type (u8vector or s8vector).

Bytes themselves have a much longer history than Scheme but the number of bits depended on the machine. Today, 8-bit bytes are the industry standard.

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://weinholt.se/scheme/manpages/.
2020-05-17