bytevector-u8-ref(3scm)

🎀 NAME 🎀

okay so bestie, this page is for bytevector-u8-ref and bytevector-s8-ref from the Scheme Programmer’s Manual (3scm) — the whole vibe is literally “read a byte from a bytevector.” 💖

📚 LIBRARY 📚

these are the imports, no cap:

(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”). slay.

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

💅 IMPLEMENTATION NOTES 💅

tbh there are no notable variations between implementations of these procedures, apart from different levels of performance. so like, the vibes are consistent — performance may differ, and that’s it.

🌈 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. math queen behavior.

🍓 EXAMPLES 🍓

ready? here are the 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 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 bytevector(7scm) for more information. iykyk.

👑 RATIONALE 👑

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

💀 COMPATIBILITY 💀

Bytevectors are absent from R5RS and earlier reports. not invited to the party.

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. catastrophically?? yes bestie, they said it.

🔥 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). glow-up era.

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

🫶 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/. credits to the icons who made this.

---

mwah 💋 okay bestie, that’s the wrap: source/version is bytevector-u8-ref(3scm), dated 2020-05-17. bye, love you, read your bytes responsibly 🫶✨