Textual Output Port Operations (MIT/GNU Scheme 11.2)

Previous: Textual Input Port Operations, Up: Textual Port Primitives [Contents][Index]

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

Previous: Textual Input Port Operations, Up: Textual Port Primitives [Contents][Index]