# Input Iterator

Category: iterators | Component type: concept

### Description

An Input Iterator is an iterator that may be dereferenced to refer to some object, and that may be incremented to obtain the next iterator in a sequence. Input Iterators are not required to be mutable.

### Refinement of

Trivial iterator.

### Associated types

Value type | The type of the value obtained by dereferencing an Input Iterator
Distance type | A signed integral type used to represent the distance from one iterator to another, or the number of elements in a range.

### Notation

`X` | A type that is a model of Input Iterator
`T` | The value type of `X`
`i`, `j` | Object of type `X`
`t` | Object of type `T`

### Definitions

An iterator is past-the-end if it points beyond the last element of a container. Past-the-end values are nonsingular and nondereferenceable.

An iterator is valid if it is dereferenceable or past-the-end.

An iterator `i` is incrementable if there is a "next" iterator, that is, if `++i` is well-defined. Past-the-end iterators are not incrementable.

An Input Iterator `j` is reachable from an Input Iterator `i` if, after applying `operator++` to `i` a finite number of times, `i == j`. [1]

The notation `[i,j)` refers to a range of iterators beginning with `i` and up to but not including `j`.

The range `[i,j)` is a valid range if both `i` and `j` are valid iterators, and `j` is reachable from `i` [2].

### Valid expressions

In addition to the expressions defined in Trivial Iterator, the following expressions must be valid.

Name | Expression | Type requirements | Return type
--- | --- | --- | ---
Preincrement | `++i` |  | `X&`
Postincrement | `(void)i++` |  |
Postincrement and dereference | `*i++` |  | `T`

### Expression semantics

Name | Expression | Precondition | Semantics | Postcondition
--- | --- | --- | --- | ---
Dereference | `*t` | `i` is incrementable |  |
Preincrement | `++i` | `i` is dereferenceable |  | `i` is dereferenceable or past-the-end [3] [4]
Postincrement | `(void)i++` | `i` is dereferenceable | Equivalent to `(void)++i` | `i` is dereferenceable or past-the-end [3] [4]
Postincrement and dereference | `*i++` | `i` is dereferenceable | Equivalent to `{T t = *i; ++i; return t;}` | `i` is dereferenceable or past-the-end [3] [4]

### Complexity guarantees

All operations are amortized constant time.

### Invariants

### Models

- istream_iterator

### Notes

[1] `i == j` does not imply `++i == ++j`.

[2] Every iterator in a valid range `[i, j)` is dereferenceable, and `j` is either dereferenceable or past-the-end. The fact that every iterator in the range is dereferenceable follows from the fact that incrementable iterators must be deferenceable.

[3] After executing `++i`, it is not required that copies of the old value of `i` be dereferenceable or that they be in the domain of `operator==`.

[4] It is not guaranteed that it is possible to pass through the same input iterator twice.

### See also

Output Iterator, Iterator overview

Copyright © 1999 Silicon Graphics, Inc. All Rights Reserved. TrademarkInformation