get-string-n!(3scm)

💖 get-string-n! — read characters into a string 💖

okay so real talk, this page is from the Scheme Programmer's Manual (yes, the 3scm section, we love a niche corner of the manual), and it's about one very specific little procedure. she's niche. she's specific. she's get-string-n!. let's get into it 🎀

---

✨ LIBRARY ✨

bestie you gotta import her first, and she lives in two spots depending on your vibe:

(import (rnrs))                     ;R6RS
(import (rnrs io ports))            ;R6RS

✨ SYNOPSIS ✨

the whole entire shape of her, no cap:

(get-string-n! textual-port string start count)

🌸 DESCRIPTION 🌸

so what she does is read from textual-input-port the exact same way get-string-n does — same energy, same manners, she's just the ! version (iykyk, the bang means she's mutating your string, she's writing into it, main character behavior 💅).

here's the breakdown, and it's literally three whole scenarios:

• if count characters are available before an end of file, they get written into string starting at index start, and count is returned. slay, full read, ate.
• if fewer characters are available before an end of file, but one or more can still be read, those characters get written into string starting at index start, and the number of characters actually read is returned as an exact integer object. flexible queen 🦋
• if no characters can be read before an end of file, you get the end-of-file object back, and the end-of-file condition is consumed. that's it, that's the whole thing 🙈

⭐ RETURN VALUES ⭐

she returns a single value, periodt. either an exact positive integer object, or the end of file object. no surprises, no extras, one value, we respect a monogamous return.

🔥 EXAMPLES 🔥

here's her in her natural habitat, reading /etc/hostname like the icon she is:

(define s (make-string 10 #\space))
(call-with-port (open-input-file "/etc/hostname")
  (lambda (p)
    (get-string-n! p s 0 10)))
   => 9
s => "darkstar"

see how she returned 9? that's the actual count read, and s came out as "darkstar". the way that just works 😭💖

🧚 APPLICATION USAGE 🧚

real talk: "Application usage is rare in practice." that's the whole section. she's a little niche girly. not every procedure gets invited to the party and that's okay 🎀

💜 COMPATIBILITY 💜

"This procedure is unique to R6RS." so like… if you're on some other Scheme, don't come for her, she's an R6RS exclusive 💅✨

💀 ERRORS 💀

she can raise exceptions, and here's the full list of condition types, no gatekeeping:

• &assertion (R6RS) — the wrong number of arguments was passed, or an argument was outside its domain. specifically, lowkey important: start and count must be exact, non-negative integer objects, and string must be a string with at least start+count characters. get that math wrong and she WILL yell at you 😤
• &i/o-read (R6RS) — a read error occurred during an I/O operation. sad girl hours 😭
• &i/o-decoding (R6RS) — the textual-input-port is associated with a transcoder in the raise error handling mode and an invalid byte sequence was encountered. that's a <red>whole situation</red>, okay, be careful 💀

👑 SEE ALSO 👑

go read her cousins too, they're all icons:

• get-string-n(3scm)
• get-bytevector-n(3scm)

🌈 STANDARDS 🌈

R6RS. that's it. that's the standard. 🫶

⭐ HISTORY ⭐

"This procedure first appeared in R6RS as part of the reworked I/O system." so she's a glow-up baby, born in the big I/O redesign. we stan a rebrand that actually slaps ✨

🎀 AUTHORS 🎀

this page is part of the scheme-manpages project — it includes materials from the RnRS documents, and you can find more info at https://github.com/schemedoc/manpages/. give them a follow, they're doing the lord's work 💖

---

and that's the whole page bestie!! 🦋 this version is from the 2023-07-23 release of the scheme-manpages project (source: the RnRS documents, obvi) — go forth and read some characters into a string, and remember: start and count must be exact non-negative integers. start+count math or it's a vibe check fail 💅🌸💜