Indirect Iterator Adaptor

Defined in header boost/iterator_adaptors.hpp

The indirect iterator adaptor augments an iterator by applying an extra dereference inside of operator*(). For example, this iterator makes it possible to view a container of pointers or smart-pointers (e.g. std::list<boost::shared_ptr<foo> >) as if it were a container of the pointed-to type. The following pseudo-code shows the basic idea of the indirect iterator:

// inside a hypothetical indirect_iterator class...
typedef std::iterator_traits<BaseIterator>::value_type Pointer;
typedef std::iterator_traits<Pointer>::reference reference;

reference indirect_iterator::operator*() const {
  return **this->base_iterator;
}

Synopsis

namespace boost {
  template <class BaseIterator,
            class Value, class Reference, class Category, class Pointer>
  struct indirect_iterator_generator;
  
  template <class BaseIterator,
            class Value, class Reference, class ConstReference, 
            class Category, class Pointer, class ConstPointer>
  struct indirect_iterator_pair_generator;

  template <class BaseIterator>
  typename indirect_iterator_generator<BaseIterator>::type
  make_indirect_iterator(BaseIterator base)  
}

The Indirect Iterator Type Generator

The indirect_iterator_generator template is a generator of indirect iterator types. The main template parameter for this class is the BaseIterator type that is being wrapped. In most cases the type of the elements being pointed to can be deduced using std::iterator_traits, but in some situations the user may want to override this type, so there are also template parameters that allow a user to control the value_type, pointer, and reference types of the resulting iterators.

template <class BaseIterator,
          class Value, class Reference, class Pointer>
class indirect_iterator_generator
{
public:
  typedef iterator_adaptor<...> type; // the resulting indirect iterator type 
};

Example

This example uses the indirect_iterator_generator to create indirect iterators which dereference the pointers stored in the pointers_to_chars array to access the chars in the characters array.

#include <boost/config.hpp>
#include <vector>
#include <iostream>
#include <iterator>
#include <boost/iterator_adaptors.hpp>

int main(int, char*[])
{
  char characters[] = "abcdefg";
  const int N = sizeof(characters)/sizeof(char) - 1; // -1 since characters has a null char
  char* pointers_to_chars[N];                        // at the end.
  for (int i = 0; i < N; ++i)
    pointers_to_chars[i] = &characters[i];
  
  boost::indirect_iterator_generator<char**, char>::type 
    indirect_first(pointers_to_chars), indirect_last(pointers_to_chars + N);

  std::copy(indirect_first, indirect_last, std::ostream_iterator<char>(std::cout, ","));
  std::cout << std::endl;
  
  // to be continued...

Template Parameters

Parameter	Description
`BaseIterator`	The iterator type being wrapped. The `value_type` of the base iterator should itself be dereferenceable. The return type of the `operator*` for the `value_type` should match the `Reference` type.
`Value`	The `value_type` of the resulting iterator, unless const. If Value is `const X`, a conforming compiler makes the `value_type` `non-const X`[1]. Note that if the default is used for `Value`, then there must be a valid specialization of `iterator_traits` for the value type of the base iterator. Default: `std::iterator_traits< std::iterator_traits<BaseIterator>::value_type >::value_type`[2]
`Reference`	The `reference` type of the resulting iterator, and in particular, the result type of `operator()`. Default:* `Value&`
`Pointer`	The `pointer` type of the resulting iterator, and in particular, the result type of `operator->()`. Default: `Value*`
`Category`	The `iterator_category` type for the resulting iterator. Default: `std::iterator_traits<BaseIterator>::iterator_category`

Concept Model

The indirect iterator will model whichever standard iterator concept category is modeled by the base iterator. Thus, if the base iterator is a model of Random Access Iterator then so is the resulting indirect iterator. If the base iterator models a more restrictive concept, the resulting indirect iterator will model the same concept [3].

Members

The indirect iterator type implements the member functions and operators required of the Random Access Iterator concept. In addition it has the following constructor:

explicit indirect_iterator_generator::type(const BaseIterator& it)

The Indirect Iterator Pair Generator

Sometimes a pair of const/non-const pair of iterators is needed, such as when implementing a container. The indirect_iterator_pair_generator class makes it more convenient to create this pair of iterator types.

template <class BaseIterator,
          class Value, class Pointer, class Reference,
          class ConstPointer, class ConstReference>
class indirect_iterator_pair_generator
{
public:
  typedef iterator_adaptor<...> iterator;       // the mutable indirect iterator type 
  typedef iterator_adaptor<...> const_iterator; // the immutable indirect iterator type 
};

Example

  // continuing from the last example...

  typedef boost::indirect_iterator_pair_generator<char**,
    char, char*, char&, const char*, const char&> PairGen;

  char mutable_characters[N];
  char* pointers_to_mutable_chars[N];
  for (int i = 0; i < N; ++i)
    pointers_to_mutable_chars[i] = &mutable_characters[i];

  PairGen::iterator mutable_indirect_first(pointers_to_mutable_chars),
    mutable_indirect_last(pointers_to_mutable_chars + N);
  PairGen::const_iterator const_indirect_first(pointers_to_chars),
    const_indirect_last(pointers_to_chars + N);

  std::transform(const_indirect_first, const_indirect_last,
     mutable_indirect_first, std::bind1st(std::plus<char>(), 1));

  std::copy(mutable_indirect_first, mutable_indirect_last,
      std::ostream_iterator<char>(std::cout, ","));
  std::cout << std::endl;
  // to be continued...

The output is:

b,c,d,e,f,g,h,

Template Parameters

Parameter	Description
`BaseIterator`	The iterator type being wrapped. The `value_type` of the base iterator should itself be dereferenceable. The return type of the `operator*` for the `value_type` should match the `Reference` type.
`Value`	The `value_type` of the resulting iterators. If Value is `const X`, a conforming compiler makes the `value_type` `non-const X`[1]. Note that if the default is used for `Value`, then there must be a valid specialization of `iterator_traits` for the value type of the base iterator. Default: `std::iterator_traits< std::iterator_traits<BaseIterator>::value_type >::value_type`[2]
`Reference`	The `reference` type of the resulting `iterator`, and in particular, the result type of its `operator()`. Default:* `Value&`
`Pointer`	The `pointer` type of the resulting `iterator`, and in particular, the result type of its `operator->()`. Default: `Value*`
`ConstReference`	The `reference` type of the resulting `const_iterator`, and in particular, the result type of its `operator()`. Default:* `const Value&`
`ConstPointer`	The `pointer` type of the resulting `const_iterator`, and in particular, the result type of its `operator->()`. Default: `const Value*`
`Category`	The `iterator_category` type for the resulting iterator. Default: `std::iterator_traits<BaseIterator>::iterator_category`

Concept Model

The indirect iterators will model whichever standard iterator concept category is modeled by the base iterator. Thus, if the base iterator is a model of Random Access Iterator then so are the resulting indirect iterators. If the base iterator models a more restrictive concept, the resulting indirect iterators will model the same concept [3].

Members

The resulting iterator and const_iterator types implement the member functions and operators required of the Random Access Iterator concept. In addition they support the following constructors:

explicit indirect_iterator_pair_generator::iterator(const BaseIterator& it)
explicit indirect_iterator_pair_generator::const_iterator(const BaseIterator& it)

The Indirect Iterator Object Generator

The make_indirect_iterator() function provides a more convenient way to create indirect iterator objects. The function saves the user the trouble of explicitly writing out the iterator types.

template <class BaseIterator>
typename indirect_iterator_generator<BaseIterator>::type
make_indirect_iterator(BaseIterator base)

Example

Here we again print the chars from the array characters by accessing them through the array of pointers pointer_to_chars, but this time we use the make_indirect_iterator() function which saves us some typing.

  // continuing from the last example...

  std::copy(boost::make_indirect_iterator(pointers_to_chars), 
      boost::make_indirect_iterator(pointers_to_chars + N),
      std::ostream_iterator<char>(std::cout, ","));
  std::cout << std::endl;

  return 0;
}

The output is:

a,b,c,d,e,f,g,

Notes

[2] If your compiler does not support partial specialization and the base iterator or its value_type is a builtin pointer type, you will not be able to use the default for Value and will need to specify this type explicitly.

[3]There is a caveat to which concept the indirect iterator can model. If the return type of the operator* for the base iterator's value type is not a true reference, then strickly speaking, the indirect iterator can not be a model of Forward Iterator or any of the concepts that refine it. In this case the Category for the indirect iterator should be specified as std::input_iterator_tag. However, even in this case, if the base iterator is a random access iterator, the resulting indirect iterator will still satisfy most of the requirements for Random Access Iterator.

Revised 17 Aug 2001

© Copyright Jeremy Siek and David Abrahams 2001. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.