String Ports - MIT/GNU Scheme 7.7.91
Description: MIT/GNU Scheme 7.7.91

Next: Input Procedures, Previous: File Ports, Up: Input/Output

### 14.3 String Ports

This section describes the simplest kinds of ports: input ports that read their input from given strings, and output ports that accumulate their output and return it as a string. It also describes “truncating” output ports, which can limit the length of the resulting string to a given value.

— procedure: open-input-string string [start [end]]

> Returns a new string port that delivers characters from string. The optional arguments start and end may be used to specify that the string port delivers characters from a substring of string; if not given, start defaults to `0` and end defaults to `(string-length` string`)`.

— procedure: with-input-from-string string thunk

> Thunk must be a procedure of no arguments. `with-input-from-string` creates a new input port that reads from string, makes that port the current input port, and calls thunk. When thunk returns, `with-input-from-string` restores the previous current input port and returns the result yielded by thunk.

>               (with-input-from-string "(a b c) (d e f)" read)  =>  (a b c)

> Note: this procedure is equivalent to:

>               (with-input-from-port (open-input-string string) thunk)

— procedure: open-output-string
— procedure: get-output-string

> `open-output-string` returns a new output port that accumulates in a buffer everything that is written to it. The accumulated output can subsequently be obtained by calling `get-output-string` on the port.

— procedure: call-with-output-string procedure

> Procedure is called with one argument, an output port. The value yielded by procedure is ignored. When procedure returns, `call-with-output-string` returns the port's accumulated output as a newly allocated string. This is equivalent to:

>               (define (call-with-output-string procedure)
>                 (let ((port (open-output-string)))
>                   (procedure port)
>                   (get-output-string port)))

— procedure: with-output-to-string thunk

> Thunk must be a procedure of no arguments. `with-output-to-string` creates a new output port that accumulates output, makes that port the default value returned by `current-output-port`, and calls thunk with no arguments. When thunk returns, `with-output-to-string` restores the previous default and returns the accumulated output as a newly allocated string.

>               (with-output-to-string
>                 (lambda ()
>                   (write 'abc)))                    =>  "abc"

> Note: this procedure is equivalent to:

>               (call-with-output-string
>                (lambda (port)
>                  (with-output-to-port port thunk)))

— procedure: with-output-to-truncated-string k thunk

> Similar to `with-output-to-string`, except that the output is limited to k characters. If thunk attempts to write more than k characters, it will be aborted by invoking an escape procedure that returns from `with-output-to-truncated-string`.

> The value of this procedure is a pair; the car of the pair is `#t` if thunk attempted to write more than k characters, and `#f` otherwise. The cdr of the pair is a newly allocated string containing the accumulated output.

> This procedure is helpful for displaying circular lists, as shown in this example:

>               (define inf (list 'inf))
>               (with-output-to-truncated-string 40
>                 (lambda ()
>                   (write inf)))                       =>  (#f . "(inf)")
>               (set-cdr! inf inf)
>               (with-output-to-truncated-string 40
>                 (lambda ()
>                   (write inf)))
>                       =>  (#t . "(inf inf inf inf inf inf inf inf inf inf")

— procedure: write-to-string object [k]

> Writes object to a string output port, and returns the resulting newly allocated string. If k is supplied and not `#f`, this procedure is equivalent to

>               (with-output-to-truncated-string k
>                 (lambda ()
>                   (write object)))

> otherwise it is equivalent to

>               (with-output-to-string
>                (lambda ()
>                  (write object)))