Iterator Concepts

The standard iterator concepts (the iterator requirements defined in the C++ Standard) have a flaw. They glom together two separate issues into a single set of concepts. The two issues are iterator traversal and dereference return type semantics. These two issues are inherently orthogonal and therefore ought to be represented by two separate sets of concepts. The concepts described here do just that.

One set of concepts handles the return type semantics:

Readable Iterator
Writable Iterator
Mutable Lvalue Iterator
Constant Lvalue Iterator

The other set of concepts handles iterator traversal:

Single-Pass Iterator
Forward Iterator
Bidirectional Iterator
Random Access Iterator

**Figure 1:** The iterator concepts and refinement relationships.

Relationship with the standard iterator concepts

std::Input Iterator refines boost::Single-Pass Iterator and boost::ReadableIterator.

std::Output Iterator refines boost::Single-Pass Iterator and boost::Writable Iterator.

std::Forward Iterator refines boost::Forward Iterator and boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator.

std::Bidirectional Iterator refines boost::Bidirectional Iterator and boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator.

std::Random Access Iterator refines boost::Random Access Iterator and boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator.

Notation

`X`	The iterator type.
`T`	The value type of `X`.
`x`, `y`	An object of type `X`.
`t`	An object of type `T`.

Readable Iterator

A Readable Iterator is an iterator that dereferences to produce an rvalue that is convertible to the value_type of the iterator. For example, derefencing may return a temporary object and therefore it would be a mistake to bind the result to a reference. Also, an attempt to assign a value to the result will most likely cause an error.

  template <class Readable Iterator>
  void foo(Readable Iterator x)
  {
    typedef std::iterator_traits<Readable Iterator>::value_type T;
    T t = *x;  // Read a value. This is OK.
    T& s = *x; // Bind to a reference. This is a bad idea.
    *x = t;    // Try to assign. This is a really bad idea.
  }

Associated Types

Value type	`boost::iterator_traits<X>::value_type`	The type of the value obtained by dereferencing a LvalueIterator
Return Category	`boost::iterator_traits<X>::return_category`	A type convertible to `boost::readable_iterator_tag`

Refinement of

Assignable, Equality Comparable, Default Constructible

Valid expressions

Name	Expression	Type requirements	Return type
Dereference	`*x`		Convertible to `T`.
Member access	`x->m`	`T` is a type with a member named `m`.

Writable Iterator

A Writable Iterator is an iterator that can be used to store a value using the dereference-assignment expression.

Definitions

If x is an Writable Iterator of type X, then the expression *x = a; stores the value a into x. Note that operator=, like other C++ functions, may be overloaded; it may, in fact, even be a template function. In general, then, a may be any of several different types. A type A belongs to the set of value types of X if, for an object a of type A, *x = a; is well-defined and does not require performing any non-trivial conversions on a.

Associated Types

Return Category boost::iterator_traits<X>::return_category A type convertible to boost::writable_iterator_tag

Refinement of

Assignable, Equality Comparable, Default Constructible

Valid expressions

Name	Expression	Return type
Dereference assignment	`*x = a`	unspecified

Constant Lvalue Iterator

A Constant Lvalue Iterator is an iterator that dereferences to produce a const reference to the pointed-to object, i.e., the associated reference type is const T&. Changing the value of or destroying an iterator that models Constant Lvalue Iterator does not invalidate pointers and references previously obtained from that iterator.

Refinement of

Readable Iterator

Associated Types

Value type	`boost::iterator_traits<X>::value_type`	The type of the value obtained by dereferencing a Constant Lvalue Iterator.
Reference type	`boost::iterator_traits<X>::reference`	The return type of `operator*()`, which must be `const T&`.
POinter type	`boost::iterator_traits<X>::pointer`	The pointer to the value type, which must be `const T*`.
Return Category	`boost::iterator_traits<X>::return_category`	A type convertible to `boost::constant_lvalue_iterator_tag`

Valid expressions

Name	Expression	Type requirements	Return type
Dereference	`*x`		`const T&`
Member access	`x->m`	`T` is a type with a member named `m`.

Mutable Lvalue Iterator

A Mutable Lvalue Iterator is an iterator that dereferences to produce a reference to the pointed-to object. The associated reference type is T&. Changing the value of or destroying an iterator that models Mutable Lvalue Iterator does not invalidate pointers and references previously obtained from that iterator.

Refinement of

Readable Iterator and Writable Iterator.

Associated Types

Value type	`boost::iterator_traits<X>::value_type`	The type of the value obtained by dereferencing a Mutable Lvalue Iterator.
Reference type	`boost::iterator_traits<X>::reference`	The return type of `operator*()`, which is `T&`.
Pointer type	`boost::iterator_traits<X>::pointer`	The pointer to the value type, which is `T*`.
Return Category	`boost::iterator_traits<X>::return_category`	A type convertible to `boost::mutable_lvalue_iterator_tag`

Valid expressions

Name	Expression	Type requirements	Return type
Dereference	`*x`		`T&`
Member access	`x->m`	`T` is a type with a member named `m`.

Single-Pass Iterator

A Single-Pass Iterator is an iterator that can be incremented to traverse through a sequence of objects, but the sequence can only be traversed a single time.

Associated types

Difference type	`boost::iterator_traits<X>::difference_type`	A signed integral type used to represent the distance from one iterator to another, or the number of elements in a range.
Traversal Category	`boost::iterator_traits<X>::traversal_category`	A type convertible to `boost::single_pass_iterator_tag`

Valid expressions

Name	Expression	Type requirements	Return type
Preincrement	`++i`		`X&`
Postincrement	`(void)i++`

Forward Iterator

The Forward Iterator is an iterator that can be incremented. Also, it is permissible to make multiple passes through the sequence.

Refinement of

Single-Pass Iterator

Associated types

Traversal Category boost::iterator_traits<X>::traversal_category A type convertible to boost::forward_iterator_tag

Bidirectional Iterator

An iterator that can be incremented and decremented.

Refinement of

Forward Iterator

Associated types

Traversal Category boost::iterator_traits<X>::traversal_category A type convertible to boost::bidirectional_iterator_tag

Valid expressions

Name	Expression	Type requirements	Return type
Predecrement	`--i`		`X&`
Postdecrement	`i--`		`X`

Random Access Iterator

An iterator that provides constant-time methods for moving forward and backward in arbitrary-sized steps

Refinement of

Bidirectional Iterator

Associated types

Traversal Category boost::iterator_traits<X>::traversal_category A type convertible to boost::random_access_iterator_tag

Valid expressions

Name	Expression	Type requirements	Return type
Iterator addition	`i += n`		`X&`
Iterator addition	`i + n` or `n + i`		`X`
Iterator subtraction	`i -= n`		`X&`
Iterator subtraction	`i - n`		`X`
Difference	`i - j`		`boost::iterator_traits<X>::difference_type`
Element operator	`i[n]`	`X` must be a model of Readable Iterator.	The same return type as `*i`.
Element assignment	`i[n] = t`	`X` must be a model of Writable Iterator.	unspecified

Jeremy Siek, Univ.of Notre Dame (jsiek@lsc.nd.edu)