get-bytevector-n(3scm)

🌸 bestie's guide to get-bytevector-n(3scm) 🌸

okay so welcome to the get-bytevector-n(3scm) page from the Scheme Programmer's Manual 💖. This is the group-chat rundown for get-bytevector-n and read-bytevector — the “gimme bytes from a binary port” icons. Let's get into it, no cap ✨💅

📚 NAME 📚

• get-bytevector-n, read-bytevector — read data from a binary port

🎀 LIBRARY 🎀

import these bad boys depending on your flavor:

       (import (rnrs))                     ;R6RS
       (import (rnrs io ports))            ;R6RS
       (import (scheme base))              ;R7RS

✨ SYNOPSIS ✨

       ;; R6RS
       (get-bytevector-n binary-input-port k)

       ;; R7RS
       (read-bytevector k)
       (read-bytevector k binary-input-port)

🦋 DESCRIPTION 🦋

Okay so what it does: it reads from binary-input-port, blocking as necessary, until count bytes are available from binary-input-port or until an end of file is reached. If an end of file is reached before any bytes are available then the end-of-file object is returned. The input port is updated to point just past the bytes read. Literally the byte-reading main character energy 🫶✨

R7RS — The default value for binary-input-port is the object returned by current-input-port(3scm). 💖

💀 Multiple end-of-file conditions 💀

This is the chaotic part, bestie: the port may return an end-of-file object and then still keep producing data if another read is attempted. Files do not normally work this way, but it is possible for other types of ports to do so, such as terminals. R6RS explicitly mentions this situation while R7RS does not. iykyk 👀

💖 RETURN VALUES 💖

Returns a single value; a bytevector or an end-of-file object. An empty bytevector is returned if k is zero. 🎀

• R6RS — There is a single, unique end-of-file object.

🌈 EXAMPLES 🌈

       (call-with-port (open-file-input-port "/dev/zero")
         (lambda (p)
           (get-bytevector-n p 4)))
               => #vu8(0 0 0 0)

Not the /dev/zero serving infinite zeros and the procedure just grabbing exactly 4 bytes 😭💅

🚨 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, count must be an exact, nonnegative integer object, and binary-input-port must be an open binary input port.
• &i/o-read (R6RS) — There was an I/O error during the read operation.
• &i/o-port (R6RS) — This condition specifies the port object related to an &i/o-read condition.
• 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. fail catastrophically is sending me 💀

👀 SEE ALSO 👀

eof-object?(3scm), get-bytevector-some(3scm), get-bytevector-all(3scm), get-bytevector-n!(3scm)

👑 STANDARDS 👑

R6RS, R7RS

🕰️ HISTORY 🕰️

Reports prior to R6RS did not support binary I/O. a little lore for you 🎀

🫶 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/.

🙈 BUGS 🙈

The default port used by read-bytevector is the current input port, which is normally a textual port that is not expected to support binary I/O. so maybe don't expect your text port to suddenly do binary, bestie 😭

---

💖 That's a wrap on the get-bytevector-n(3scm) page — dated 2023-01-30, from the scheme-manpages source. Go read those bytes and slay, icon behavior only ✨💅🦋