14.12.4 Textual Output Port Operations

This section describes the standard operations on output ports. Following that, some useful custom operations are described.

operation on textual output port: write-char port char

Writes char to port and returns an unspecified value.

operation on textual output port: write-substring port string start end

Writes the substring specified by string, start, and end to port and returns an unspecified value. Equivalent to writing the characters of the substring, one by one, to port, but is implemented very efficiently.

operation on textual output port: fresh-line port

Most output ports are able to tell whether or not they are at the beginning of a line of output. If port is such a port, end-of-line is written to the port only if the port is not already at the beginning of a line. If port is not such a port, an end-of-line is unconditionally written to the port. Returns an unspecified value.

operation on textual output port: flush-output port

If port is buffered, this causes its buffer to be written out. Otherwise it has no effect. Returns an unspecified value.

operation on textual output port: discretionary-flush-output port

Normally, this operation does nothing. However, ports that support discretionary output flushing implement this operation identically to flush-output.

procedure: output-port/write-char textual-output-port char

procedure: output-port/write-substring textual-output-port string start end

procedure: output-port/fresh-line textual-output-port

procedure: output-port/flush-output textual-output-port

procedure: output-port/discretionary-flush-output textual-output-port

Each of these procedures invokes the respective operation on textual-output-port. For example, the following are equivalent:

(output-port/write-char textual-output-port char)
((textual-port-operation textual-output-port 'write-char)
 textual-output-port char)

procedure: output-port/write-string textual-output-port string

Writes string to textual-output-port. Equivalent to

(output-port/write-substring textual-output-port
                             string
                             0
                             (string-length string))

The following custom operations are generally useful.

operation on textual output port: buffered-output-chars port

Returns the number of unwritten characters that are stored in port’s buffer. This will always be less than or equal to the buffer’s size.

operation on textual output port: output-buffer-size port

Returns the maximum number of characters that port’s buffer can hold.

operation on textual output port: set-output-buffer-size port size

Resizes port’s buffer so that it can hold at most size characters. Characters in the buffer are discarded. Size must be an exact non-negative integer.

operation on textual output port: x-size port

Returns an exact positive integer that is the width of port in characters. If port has no natural width, e.g. if it is a file port, #f is returned.

operation on textual output port: y-size port

Returns an exact positive integer that is the height of port in characters. If port has no natural height, e.g. if it is a file port, #f is returned.

procedure: output-port/x-size textual-output-port

This procedure invokes the custom operation whose name is the symbol x-size, if it exists. If the x-size operation is both defined and returns a value other than #f, that value is returned as the result of this procedure. Otherwise, output-port/x-size returns a default value (currently 80).

output-port/x-size is useful for programs that tailor their output to the width of the display (a fairly common practice). If the output device is not a display, such programs normally want some reasonable default width to work with, and this procedure provides exactly that.

procedure: output-port/y-size textual-output-port

This procedure invokes the custom operation whose name is the symbol y-size, if it exists. If the y-size operation is defined, the value it returns is returned as the result of this procedure; otherwise, #f is returned.