Iterator Concepts

An Iterator is a restricted pointer-like object pointing into a
vector or matrix container.

Indexed Bidirectional Iterator

Description

An Indexed Bidirectional Iterator is an iterator of a container
that can be dereferenced, incremented, decremented and carries
index information.

Refinement of

Assignable, Equality Comparable, Default Constructible.

Associated types

Value type

The type of the value obtained by dereferencing a Indexed
Bidirectional Iterator

Container type

The type of the container a Indexed Bidirectional Iterator
points into.

Notation

I

A type that is a model of Indexed Bidirectional Iterator

T

The value type of I

C

The container type of I

it, itt, it1, it2

Objects of type I

t

Object of type T

c

Object of type C

Definitions

A Indexed Bidirectional Iterator may be mutable, meaning
that the values referred to by objects of that type may be
modified, or constant , meaning that they may not. If an
iterator type is mutable, this implies that its value type is a
model of Assignable; the converse, though, is not necessarily
true.

A Indexed Bidirectional Iterator may have a singular
value, meaning that the results of most operations, including
comparison for equality, are undefined. The only operation that is
guaranteed to be supported is assigning a nonsingular iterator to a
singular iterator.

A Indexed Bidirectional Iterator may have a
dereferenceable value, meaning that dereferencing it yields
a well-defined value. Dereferenceable iterators are always
nonsingular, but the converse is not true.

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

Valid expressions

In addition to the expressions defined for Assignable, Equality
Comparable and Default Constructible, the following expressions
must be valid.

Name

Expression

Type requirements

Return type

Default constructor

I it

Dereference

*it

Convertible to T.

Dereference assignment

*it = t

I is mutable.

Member access

it->m

T is a type for which t.m is
defined.

Preincrement

++ it

I &

Postincrement

it ++

I

Predecrement

-- it

I &

Postdecrement

it --

I

Index

it.index ()

C::size_type

Expression Semantics

Semantics of an expression is defined only where it differs
from, or is not defined in, Assignable, Equality Comparable and
Default Constructible.

If it is a Column Iterator,
then it2 = it.begin () is a Row Iterator
with it2.index1 () == it.index1 ().

If it is a Row Iterator,
then it2 = it.begin () is a Column Iterator
with it2.index2 () == it.index2 ().

Row/Column End

it.end ()

it is dereferenceable.

If it is a Column Iterator,
then it2 = it.end () is a Row Iterator
with it2.index1 () == it.index1 ().

If it is a Row Iterator,
then it2 = it.end () is a Column Iterator
with it2.index2 () == it.index2 ().

Reverse Row/Column Begin

it.rbegin ()

it is dereferenceable.

Equivalent to reverse_iterator<I2> (it.end
()).

Reverse Row/Column End

it.rend ()

it is dereferenceable.

Equivalent to reverse_iterator<I2> (it.begin
()).

Complexity guarantees

The complexity of operations on indexed bidirectional column/row
iterators is guaranteed to be logarithmic depending on the size of
the container. The complexity of one iterator (depending on the
storage layout) can be lifted to be amortized constant time. The
complexity of the other iterator (depending on the storage layout
and the container) can be lifted to be amortized constant time for
the first row/first column respectively.

Invariants

Identity

it1 == it2 if and only if &*it1 ==
&*it2.

Symmetry of increment and decrement

If it is dereferenceable, then ++ it;
--it; is a null operation. Similarly, -- it; ++
it; is a null operation.