74.3.2   Forward Circulator

A class Circulator that satisfies the requirements of a forward circulator with the value type T, supports the following operations. See the reference pages for the full set of requirements. Note that the stated return values are not required, only a return value that is convertible to the stated type is required. As for C++, we recommend the use of 0 instead of NULL.

Types

Circulator::value_type
the value type T.

Circulator::reference
either reference or const reference to T.

Circulator::pointer
either pointer or const pointer to T.

Circulator::size_type
unsigned integral type that can hold the size of the sequence.

Circulator::difference_type
signed integral type that can hold the distance between two circulators.

Circulator::iterator_category
circulator category Forward_circulator_tag.

Creation

Circulator c;
a circulator equal to NULL denoting an empty sequence.

Circulator c ( d);
a circulator equal to d.

Operations

Circulator& c = d Assignment.
bool c == NULL const Test for emptiness.
bool c != NULL const Test for non-emptiness, i.e.  !(c == NULL).
bool c == d const c is equal to d if they refer to the same item.
bool c != d const Test for inequality, i.e. !(c == d).

reference * c Returns the value of the circulator. If Circulator is mutable *c = t is valid.
Precondition: c is dereferenceable.

pointer c -> Returns a pointer to the value of the circulator.
Precondition: c is dereferenceable.

Circulator& ++ c Prefix increment operation.
Precondition: c is dereferenceable.
Postcondition: c is dereferenceable.

Circulator c ++ Postfix increment operation. The result is the same as that of: Circulator tmp = c; ++c; return tmp; .

74.3.3   Bidirectional Circulator

A class Circulator that satisfies the requirements of a bidirectional circulator with the value type T, supports the following operations in addition to the operations supported by a forward circulator.

Types

Circulator::iterator_category
circulator category Bidirectional_circulator_tag.

Operations

Circulator& -- c Prefix decrement operation.
Precondition: c is dereferenceable.
Postcondition: c is dereferenceable.

Circulator c -- Postfix decrement operation. The result is the same as that of Circulator tmp = c; --c; return tmp; .

74.3.4   Random Access Circulator

A class Circulator that satisfies the requirements of a random access Circulator for the value type T, supports the following operations in addition to the operations supported by a bidirectional Circulator. In contrast to random access iterators, no comparison operators are available for random access circulators.

Types

Circulator::iterator_category
circulator category Random_access_circulator_tag.

Operations

Circulator& c += difference_type n The result is the same as if the prefix increment operation was applied n times, but it is computed in constant time.

Circulator c + difference_type n Same as above, but returns a new circulator.

Circulator difference_type n + c Same as above.

Circulator& c -= difference_type n The result is the same as if the prefix decrement operation was applied n times, but it is computed in constant time.

Circulator c - difference_type n Same as above, but returns a new circulator.

reference c [ difference_type n ] Returns *(c + n).

difference_type c - Circulator d const returns the difference between the two circulators. The value will be in the interval [ 1-s , s-1 ] if s is the size of the total sequence. The difference for a fixed circulator c (or d) with all other circulators d (or c) is a consistent ordering of the elements in the data structure. There has to be a minimal circulator dmin for which the difference c- dmin to all other circulators c is non-negative.

Circulator c.min_circulator () const Returns the minimal circulator cmin in constant time.