Apache C++ Standard Library User's Guide

## 16.4 Tips and Techniques for Building Algorithms

This section describes some techniques that use features of iterators to increase the flexibility and efficiency of your algorithms.

### 16.4.1 The iterator_traits Template

Sometimes an algorithm that can be implemented most efficiently with a random access iterator can also work with less powerful iterators. The C++ Standard Library includes primitives that allow a single algorithm to provide several different implementations, depending upon the power of the iterator passed into it. The following example demonstrates the usual technique for setting up multiple versions of the same algorithm:

    // Note, this requires that the iterators be derived from
    // Standard base types, unless the iterators are simple pointers.

    namespace my_namespace {

    template <class Iterator>
    Iterator union(Iterator first1, Iterator last1,
                   Iterator first2, Iterator last2,
                   Iterator Result)
    {
      return union_aux(first1,last1,first2,last2,Result,
                       iterator_traits<first1>());
    }

    template <class Iterator>
    Iterator union_aux(Iterator first1, Iterator last1,
                       Iterator first2, Iterator last2,
                       Iterator Result, forward_iterator_tag)
    {
      // General but less efficient implementation
    }

    template <class Iterator>
    Iterator union_aux(Iterator first1, Iterator last1,
                       Iterator first2, Iterator last2,
                       Iterator Result,
                       random_access_iterator_tag)
    {
      // More efficient implementation
    }

    } // End of my_namespace

The `iterator_traits` template provides typedefs for value, difference, pointer, reference, and category types that are based on the type used to instantiate the template. In the example above, we use `iterator_traits::iterator_category` to determine the capabilities of the iterator, and then use specializations to get the best available implementation of the algorithm. In order for `iterator_traits` to work, the iterator provided to the algorithm must be a simple pointer type or be derived from the iterator template, or it must itself define the types for `value_type`, `difference_type`, `pointer`, `reference`, and `iterator_category`. The `iterator_category` type must be one of the following: `input_iterator_tag`, `output_iterator_tag`, `forward_iterator_tag`, `bidirectional_iterator_tag`, or `random_access_iterator_tag`.

Note that when you use the `iterator_traits` template, the default implementation of an algorithm should expect at most a forward iterator. This default version is used if the algorithm encounters an iterator that is not a simple pointer or derived from a basic standard iterator. Note that input and output iterators are less capable than forward iterators, but that the requirements of algorithms generally mandate read/write capabilities.

Not also that `iterator_traits` only works with compilers that support partial specialization, since the specialization of `iterator_traits` for pointer types uses this feature. If your compiler doesn't support partial specialization, you can use the primitive `__iterator_category()`. Calling this function with an iterator argument returns the same tag you would get by using `iterator_traits`. For example, we could substitute the following line for the use of `iterator_traits` in the previous example:

    return std::union_aux(first1,last1,first2,last2,Result,
                      __iterator_category(first1));

Use `iterator_traits::value_type` and `iterator_traits::difference_type` to discover the type of value pointed to by an iterator, or the type that represents a distance between iterators. As with the category type, you must use the alternate functions `__value_type()` or `__distance_type()` when partial specialization is not available. Both of these functions take an iterator as an argument in just the same way as `__iterator_category()`.

### 16.4.2 The distance and advance Primitives

The `value_type` primitive lets you determine the type of value pointed to by an iterator. Similarly, you can use the `distance_type` primitive to get a type that represents distances between iterators.

In order to efficiently find the distance between two iterators, regardless of their capabilities, you can use the `distance` primitive. The `distance` primitive uses the technique in Section 16.4.1 to send a calling program to one of four different implementations. This offers a considerable gain in efficiency, since an implementation for a forward iterator must step through the range defined by the two iterators:

    Distance d = 0;
    while (start++ != end)
      d++;

whereas an implementation for a random access iterator can simply subtract the start iterator from the end iterator:

    Distance d = end - start;

Similar gains are available with the `advance` primitive, which allows you to step forward or backward an arbitrary number of steps as efficiently as possible for a particular iterator.