# Peekable

## Description

A Peekable Device allows a character read from the input sequence to be putback.

The name of the concept is based on the observation that a PeekableDevice allow the user to peek at the first character in the sequence it controls by calling `get` or `read` followed by `putback`. The names Putbackable and InputRevertable were considered but rejected.

## Refinement of

Source.

## Associated Types

Same as Source.

## Notation

`P` | - | A type which is a model of Peekable
`p` | - | Object of type `P`
`c` | - | Object of type equal to the character type of `P`
`io` | - | Alias for namespace `boost::iostreams`

## Valid Expressions / Semantics

Expression | Expression Type | Precondition | Semantics | Postcondition
--- | --- | --- | --- | ---
    io::putback(p, c)
| `bool` | One or more characters has been read from `p` using `io::get` or `io::read`, with no intervening i/o operations having been performed | Attempts to put back `c` to `p`, returning `true` for success | If putback returns `true`, the next character read from `p` using `io::get` or `io::read` will be equal to `c`

## Exceptions

Errors which occur during the execution of `putback` are be indicated by throwing exceptions.

## Models

- Standard input streams and stream buffers.

Revised 20 May, 2004

© Copyright Jonathan Turkanis, 2004

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)