Textual Input Port Operations (MIT/GNU Scheme 10.1.6)

Next: Textual Output Port Operations, Previous: Constructors and Accessors for Textual Ports, Up: Textual Port Primitives [Contents][Index]

#### 14.12.3 Textual Input Port Operations

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

operation on textual input port: read-char port

  Removes the next character available from port and returns it. If port has no more characters and will never have any (e.g. at the end of an input file), this operation returns an end-of-file object. If port has no more characters but will eventually have some more (e.g. a terminal where nothing has been typed recently), and it is in non-blocking mode, `#f` is returned; otherwise the operation hangs until input is available.

operation on textual input port: peek-char port

  Reads the next character available from port and returns it. The character is not removed from port, and a subsequent attempt to read from the port will get that character again. In other respects this operation behaves like `read-char`.

operation on textual input port: char-ready? port k

  `char-ready?` returns `#t` if at least one character is available to be read from port. If no characters are available, the operation waits up to k milliseconds before returning `#f`, returning immediately if any characters become available while it is waiting.

operation on textual input port: read-string port char-set
operation on textual input port: discard-chars port char-set

  These operations are like `read-char`, except that they read or discard multiple characters at once. All characters up to, but excluding, the first character in char-set (or end of file) are read from port. `read-string` returns these characters as a newly allocated string, while `discard-chars` discards them and returns an unspecified value. These operations hang until sufficient input is available, even if port is in non-blocking mode. If end of file is encountered before any input characters, `read-string` returns an end-of-file object.

operation on textual input port: read-substring port string start end

  Reads characters from port into the substring defined by string, start, and end until either the substring has been filled or there are no more characters available. Returns the number of characters written to the substring.

  If port is an interactive port, and at least one character is immediately available, the available characters are written to the substring and this operation returns immediately. If no characters are available, and port is in blocking mode, the operation blocks until at least one character is available. Otherwise, the operation returns `#f` immediately.

  This is an extremely fast way to read characters from a port.

procedure: input-port/read-char textual-input-port
procedure: input-port/peek-char textual-input-port
procedure: input-port/char-ready? textual-input-port k
procedure: input-port/read-string textual-input-port char-set
procedure: input-port/discard-chars textual-input-port char-set
procedure: input-port/read-substring textual-input-port string start end

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

      (input-port/read-char textual-input-port)
      ((textual-port-operation textual-input-port 'read-char)
       textual-input-port)

The following custom operations are implemented for input ports to files, and will also work with some other kinds of input ports:

operation on textual input port: eof? port

  Returns `#t` if port is known to be at end of file, otherwise it returns `#f`.

operation on textual input port: chars-remaining port

  Returns an estimate of the number of characters remaining to be read from port. This is useful only when port is a file port in binary mode; in other cases, it returns `#f`.

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

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

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

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

operation on textual input port: set-input-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.

Next: Textual Output Port Operations, Previous: Constructors and Accessors for Textual Ports, Up: Textual Port Primitives [Contents][Index]