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