[ Character I/O | Reference Manual | Alphabetic Index ]

# unget(+Stream)

Back up one character on Stream

Stream
  Stream handle or alias (atom)

## Description

Go back one character on the given Stream. This can be used to implement lookaheads.

The number of characters that can be reliably ungotten is 4, and the result is only defined if these characters have been read previously.

The result of the operation is undefined if

- trying to unget more than 4 characters
- trying to unget more characters than had been read previously
- trying to unget after a seek operation

In these cases, unget/1 will succeed, but subsequent read operations will return undefined results.

### Modes and Determinism

- unget(+) is det

### Exceptions

(4) instantiation fault
  Stream is not instantiated.
(5) type error
  Stream is neither a stream handle nor an atom.
(192) illegal stream mode
  Stream not in read mode.

## Examples

    % look ahead one character in Stream:

        peek(Stream, X) :-
            get(Stream, X),
            unget(Stream).

## See Also

get / 2, get_char / 2