Next: , Previous: Input Port Operations, Up: Port Primitives


14.9.4 Output Port Operations

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

— operation on output port: write-char output-port char

Writes char to output-port and returns an unspecified value.

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

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

— operation on output port: fresh-line output-port

Most output ports are able to tell whether or not they are at the beginning of a line of output. If output-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 output-port is not such a port, an end-of-line is unconditionally written to the port. Returns an unspecified value.

— operation on output port: flush-output output-port

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

— operation on output port: discretionary-flush-output 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 output-port char
— procedure: output-port/write-substring output-port string start end
— procedure: output-port/fresh-line output-port
— procedure: output-port/flush-output output-port
— procedure: output-port/discretionary-flush-output output-port

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

          (output-port/write-char output-port char)
          ((port/operation output-port 'write-char)
           output-port char)
     
— procedure: output-port/write-string output-port string

Writes string to output-port. Equivalent to

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

The following custom operations are generally useful.

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

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

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

Returns the maximum number of characters that output-port's buffer can hold.

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

Resizes output-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 output port: x-size output-port

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

— operation on output port: y-size output-port

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

— procedure: output-port/x-size 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 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.