14.3 String Ports

This section describes textual input ports that read their input from given strings, and textual output ports that accumulate their output and return it as a string.

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

Takes a string and returns a textual input port that delivers characters from the string. If the string is modified, the effect is unspecified.

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

standard procedure: open-output-string

Returns a textual output port that will accumulate characters for retrieval by get-output-string.

standard procedure: get-output-string port

It is an error if port was not created with open-output-string.

Returns a string consisting of the characters that have been output to the port so far in the order they were output. If the result string is modified, the effect is unspecified.

(parameterize ((current-output-port (open-output-string)))
  (display "piece")
  (display " by piece ")
  (display "by piece.")
  (newline)
  (get-output-string (current-output-port)))

    ⇒ "piece by piece by piece.\n"

procedure: call-with-output-string procedure

The procedure is called with one argument, a textual output port. The values yielded by procedure are ignored. When procedure returns, call-with-output-string returns the port’s accumulated output as a string. If the result string is modified, the effect is unspecified.

This procedure could have been defined as follows:

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

procedure: call-with-truncated-output-string limit procedure

Similar to call-with-output-string, except that the output is limited to at most limit characters. The returned value is a pair; the car of the pair is #t if procedure attempted to write more than limit characters, and #f otherwise. The cdr of the pair is a newly allocated string containing the accumulated output.

This procedure could have been defined as follows:

(define (call-with-truncated-output-string limit procedure)
  (let ((port (open-output-string)))
    (let ((truncated?
           (call-with-truncated-output-port limit port
                                            procedure)))
      (cons truncated? (get-output-string port)))))

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

(define inf (list 'inf))
(call-with-truncated-output-string 40
  (lambda (port)
    (write inf port)))                  ⇒  (#f . "(inf)")
(set-cdr! inf inf)
(call-with-truncated-output-string 40
  (lambda (port)
    (write inf port)))
        ⇒  (#t . "(inf inf inf inf inf inf inf inf inf inf")

procedure: write-to-string object [limit]

Writes object to a string output port, and returns the resulting string.

If limit is supplied and not #f, then this procedure is equivalent to the following and returns a pair instead of just a string:

(call-with-truncated-output-string limit
  (lambda (port)
    (write object port)))

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

obsolete procedure: with-output-to-string thunk

obsolete procedure: with-output-to-truncated-string limit thunk

These procedures are deprecated; instead use open-input-string, call-with-output-string, or call-with-truncated-output-string along with parameterize.