# 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

Copyright © 2000 | Jeremy Siek, Univ.of Notre Dame (jsiek@lsc.nd.edu)