get-string-n(3scm) Scheme Programmer's Manual get-string-n(3scm)

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

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


;; R6RS
(get-string-n textual-port count)
;; R7RS
(read-string count)
(read-string count textual-input-port)

Reads from textual-input-port, blocking as necessary, until count characters are available, or until an end of file is reached.

If count characters are available before end of file, returns a string consisting of those count characters.

If fewer characters are available before an end of file, but one or more characters can be read, returns a string containing those characters.

If no characters can be read before an end of file, the end-of-file object is returned.

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.

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

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

The R7RS version of this procedure does not specify how multiple end of file conditions are handled; the error handling when passing wrong arguments is unspecified; and there is no way to catch a read or transcoding error. For R7RS, also see the note on supported characters in the errors section.

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.
Unsupported characters (R7RS)
It is an error for read-string to read a character which the implementation does not support. 7-bit ASCII (except #\null) must be supported. Any other character is optional and potentially an error (as described above). You can use the full-unicode feature identifier in cond-expand(3scm) to check if all of Unicode 6.0 is supported.

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

R6RS, R7RS

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.

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://weinholt.se/scheme/manpages/.

2023-07-23