Output Port Operations - MIT/GNU Scheme 7.7.91
Description: MIT/GNU Scheme 7.7.91

Next: Blocking Mode, 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.