Go to the previous, next section.

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+: string->input-port 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 (string->input-port string) thunk)

procedure+: with-string-output-port procedure

Procedure is called with one argument, an output port. The value yielded by procedure is ignored. When procedure returns, with-string-output-port returns the accumulated output to the port as a newly allocated string.

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:

(with-string-output-port
 (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)))

Go to the previous, next section.