get-string-n(3scm)

get-string-n(3scm) 🦋✨

okay bestie, this page is from the Scheme Programmer's Manual, and it's all about get-string-n and read-string. It's giving "read characters from a port, get a string back" energy, and honestly? iconic. let's go 💅

✨ NAME ✨

get-string-n, read-string — read characters from a port, returning a string 🎀

📚 LIBRARY 📚

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

🫶 SYNOPSIS 🫶

;; R6RS
(get-string-n textual-port count)

;; R7RS
(read-string count)
(read-string count textual-input-port)

💖 DESCRIPTION 💖

okay so here's the tea: this reads from textual-input-port, blocking as necessary, until count characters are available, or until an end of file is reached. no cap.

If count characters are available before end of file, you get a string consisting of those count characters. slay.

If fewer characters are available before an end of file, but one or more characters can be read, you get a string containing those characters. still useful, still valid.

If no characters can be read before an end of file, the end-of-file object is returned. that's the vibe check result.

The input port is updated to point just past the characters read, if any. If the end-of-file object is returned, then the end of file condition is consumed. periodt.

🎀 RETURN VALUES 🎀

Returns a single value; a newly allocated string or an end of file object. 💫

• R6RS — There may be a single empty string object, so it does not need to be newly allocated. There is also a single end of file object.
• R7RS — There may be multiple end of file objects, in the sense of eq?(3scm).

🌸 EXAMPLES 🌸

here's the example, bestie — copy it exactly, no cap:

(call-with-port (open-input-file "/etc/os-release")
  (lambda (p)
    (get-string-n p 20)))
   => "PRETTY_NAME=

🦋 COMPATIBILITY 🦋

The R7RS version of this procedure does not specify how multiple end of file conditions are handled; only the ASCII characters (except NUL) need to be supported and attempting to read an unsupported character is an error; and the error handling when passing wrong arguments is unspecified; and there is no way to catch a read or transcoding error. that's a lot, but we keep it real 💀

🔥 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, non-negative integer object and textual-input-port must be an open textual input port.
• &i/o-read (R6RS) — A read error occurred during an I/O operation.
• &i/o-decoding (R6RS) — The textual-input-port is associated with a transcoder in the raise error handling mode and a invalid byte sequence was encountered.

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 👑

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

🌈 STANDARDS 🌈

R6RS, R7RS ⭐

💜 HISTORY 💜

This procedure first appeared in R6RS as part of the reworked I/O system. The similar read-string procedure later appeared in R7RS. These procedures are not part of earlier RnRS revisions.

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

---

🎀 that's the whole page, bestie! footer check: source/version get-string-n(3scm), date 2023-07-23 — mwah! 💖✨