Whole document tree

www.fifi.org
    Documentation
        Manpages
        GNU Info
        Debian document tree
        Whole document tree
    Trigance web page
    Public services
    User info
    Mailing lists
    Secure server
    Multilingual usage

Whole document tree

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.