make-bytevector(3scm)

💖 make-bytevector(3scm) 💖

okay so bestie, this is the Scheme Programmer's Manual page for make-bytevector — the little bytevector-maker that's lowkey carrying a lot of Scheme code. No cap, it's giving "fresh bytes, but make it cute." 🎀

---

✨ NAME ✨

make-bytevector — create a new bytevector

📚 LIBRARY 📚

import it from whichever RnRS situation you're in, bestie:

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

🫶 SYNOPSIS 🫶

(make-bytevector k)
(make-bytevector k fill)

💅 DESCRIPTION 💅

Return a newly allocated bytevector of k bytes. Periodt. ✨

If the fill argument is missing, the initial contents of the returned bytevector are unspecified. Yes, bestie — unspecified means don't go assuming it's zeroed unless your implementation says so down below. 🙈

If the fill argument is present, it must be an exact integer object. Every byte in the returned bytevector will be set to this value. Like, every single one. 💖

• R6RS — The fill argument must be in the range [−128, 255]. If fill is positive, it is interpreted as if passed to bytevector-u8-set!(3scm). If it is negative, it is instead used as if passed to bytevector-s8-set!(3scm).
• R7RS — The fill argument must be in the range [0, 255].

🧚 IMPLEMENTATION NOTES 🧚

Not every Scheme is the same, and this is where the vibes get specific:

• Chez Scheme, Loko Scheme, (others?) — If k is zero then the empty bytevector object is returned.
• GNU Guile, Loko Scheme, (others?) — If fill is missing then the bytevector is initialized to zeros. Slay for predictability. ✨
• Chibi Scheme — Even though Chibi is an R7RS implementation, the fill argument is interpreted as in R6RS. This is a valid extension of R7RS.

👑 RETURN VALUES 👑

Returns a single object which is a bytevector object of the given length. If k is non-zero then the bytevector is fresh. If k is zero then the unique empty bytevector object may be returned.

So yeah — non-zero k means a new one; zero k means you might get the iconic shared empty bytevector. 💅

🌸 EXAMPLES 🌸

(make-bytevector 2 12)
    => #u8(12 12)          ;R7RS notation

🔥 APPLICATION USAGE 🔥

This procedure is used in code that works with mutable bytevectors. For some code an alternative is to use open-bytevector-output-port(3scm) and to build the data sequentially.

Both are valid, bestie — it's giving "choose your fighter." 🦋

🌈 COMPATIBILITY 🌈

Portable code should provide the second argument, and should keep it in the range [0, 255].

That's the safe zone for maximum portability. Don't be out here raw-dogging make-bytevector with no fill and then acting surprised. 😭

💀 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.
• &implementation-restriction (R6RS) — There is not enough free memory to hold the new 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.

"fail catastrophically" is right there in the spec, bestie. Not me adding drama — that's literally the wording. 💀

👀 SEE ALSO 👀

Go check out u8-list->bytevector(3scm) — sibling behavior, different vibe. 💜

⭐ STANDARDS ⭐

R6RS, R7RS

🫶 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 🍓

It is often a mistake to call this procedure without the fill argument. Unusual values of k can stress the Scheme implementation's memory allocator and cause a crash.

So like… maybe don't be chaotic with k, and maybe do provide fill. Your allocator will thank you. 🙏

---

later bestie — this was the Scheme Programmer's Manual, dated 2022-03-21, for make-bytevector(3scm). bye and slay 💅✨🫶