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

LIBRARY

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

SYNOPSIS

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

DESCRIPTION

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.

IMPLEMENTATION NOTES

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

RETURN VALUES

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.

EXAMPLES

(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

APPLICATION USAGE

These procedure 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 bytevector(7scm) for more information.

RATIONALE

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

COMPATIBILITY

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

ERRORS

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.

SEE ALSO

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

STANDARDS

R6RS, R7RS

HISTORY

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.

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/.

Markup created by unroff 1.0sc,    March 04, 2023.