6.14.9.2 String Ports

The following allow string ports to be opened by analogy to R4RS file port facilities:

With string ports, the port-encoding is treated differently than other types of ports. When string ports are created, they do not inherit a character encoding from the current locale. They are given a default locale that allows them to handle all valid string characters. Typically one should not modify a string port’s character encoding away from its default.

Scheme Procedure: call-with-output-string proc

C Function: scm_call_with_output_string (proc)

Calls the one-argument procedure proc with a newly created output port. When the function returns, the string composed of the characters written into the port is returned. proc should not close the port.

Note that which characters can be written to a string port depend on the port’s encoding. The default encoding of string ports is specified by the %default-port-encoding fluid (see section %default-port-encoding). For instance, it is an error to write Greek letter alpha to an ISO-8859-1-encoded string port since this character cannot be represented with ISO-8859-1:

(define alpha (integer->char #x03b1)) ; GREEK SMALL LETTER ALPHA

(with-fluids ((%default-port-encoding "ISO-8859-1"))
  (call-with-output-string
    (lambda (p)
      (display alpha p))))

⇒
Throw to key `encoding-error'

Changing the string port’s encoding to a Unicode-capable encoding such as UTF-8 solves the problem.

Scheme Procedure: call-with-input-string string proc

C Function: scm_call_with_input_string (string, proc)

Calls the one-argument procedure proc with a newly created input port from which string’s contents may be read. The value yielded by the proc is returned.

Scheme Procedure: with-output-to-string thunk

Calls the zero-argument procedure thunk with the current output port set temporarily to a new string port. It returns a string composed of the characters written to the current output.

See call-with-output-string above for character encoding considerations.

Scheme Procedure: with-input-from-string string thunk

Calls the zero-argument procedure thunk with the current input port set temporarily to a string port opened on the specified string. The value yielded by thunk is returned.

Scheme Procedure: open-input-string str

C Function: scm_open_input_string (str)

Take a string and return an input port that delivers characters from the string. The port can be closed by close-input-port, though its storage will be reclaimed by the garbage collector if it becomes inaccessible.

Scheme Procedure: open-output-string

C Function: scm_open_output_string ()

Return an output port that will accumulate characters for retrieval by get-output-string. The port can be closed by the procedure close-output-port, though its storage will be reclaimed by the garbage collector if it becomes inaccessible.

Scheme Procedure: get-output-string port

C Function: scm_get_output_string (port)

Given an output port created by open-output-string, return a string consisting of the characters that have been output to the port so far.

get-output-string must be used before closing port, once closed the string cannot be obtained.

A string port can be used in many procedures which accept a port but which are not dependent on implementation details of fports. E.g., seeking and truncating will work on a string port, but trying to extract the file descriptor number will fail.

This document was generated on April 20, 2013 using texi2html 5.0.