Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Indirect Iterator

indirect_iterator adapts an iterator by applying an extra dereference inside of operator*(). For example, this iterator adaptor makes it possible to view a container of pointers (e.g. list<foo*>) as if it were a container of the pointed-to type (e.g. list<foo>). indirect_iterator depends on two auxiliary traits, pointee and indirect_reference, to provide support for underlying iterators whose value_type is not an iterator.

Example

This example prints an array of characters, using indirect_iterator to access the array of characters through an array of pointers. Next indirect_iterator is used with the transform algorithm to copy the characters (incremented by one) to another array. A constant indirect iterator is used for the source and a mutable indirect iterator is used for the destination. The last part of the example prints the original array of characters, but this time using the make_indirect_iterator helper function.

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];

// Example of using indirect_iterator

boost::indirect_iterator<char**, char>
  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;


// Example of making mutable and constant indirect iterators

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

boost::indirect_iterator<char* const*> mutable_indirect_first(pointers_to_mutable_chars),
  mutable_indirect_last(pointers_to_mutable_chars + N);
boost::indirect_iterator<char* const*, char const> 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;


// Example of using make_indirect_iterator()

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;

The output is:

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

The source code for this example can be found here.

Reference

Synopsis

template <
    class Iterator
  , class Value = use_default
  , class CategoryOrTraversal = use_default
  , class Reference = use_default
  , class Difference = use_default
>
class indirect_iterator
{
 public:
    typedef /* see below */ value_type;
    typedef /* see below */ reference;
    typedef /* see below */ pointer;
    typedef /* see below */ difference_type;
    typedef /* see below */ iterator_category;

    indirect_iterator();
    indirect_iterator(Iterator x);

    template <
        class Iterator2, class Value2, class Category2
      , class Reference2, class Difference2
    >
    indirect_iterator(
        indirect_iterator<
             Iterator2, Value2, Category2, Reference2, Difference2
        > const& y
      , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
    );

    Iterator const& base() const;
    reference operator*() const;
    indirect_iterator& operator++();
    indirect_iterator& operator--();
private:
   Iterator m_iterator; // exposition
};

The member types of indirect_iterator are defined according to the following pseudo-code, where V is iterator_traits<Iterator>::value_type

  if (Value is use_default) then
      typedef remove_const<pointee<V>::type>::type value_type;
  else
      typedef remove_const<Value>::type value_type;

  if (Reference is use_default) then
      if (Value is use_default) then
          typedef indirect_reference<V>::type reference;
      else
          typedef Value& reference;
  else
      typedef Reference reference;

  if (Value is use_default) then
      typedef pointee<V>::type* pointer;
  else
      typedef Value* pointer;

  if (Difference is use_default)
      typedef iterator_traits<Iterator>::difference_type difference_type;
  else
      typedef Difference difference_type;

  if (CategoryOrTraversal is use_default)
      typedef iterator-category (
          iterator_traversal<Iterator>::type,reference,value_type
      ) iterator_category;
  else
      typedef iterator-category (
          CategoryOrTraversal,reference,value_type
      ) iterator_category;

Requirements

The expression *v, where v is an object of iterator_traits<Iterator>::value_type, shall be valid expression and convertible to reference. Iterator shall model the traversal concept indicated by iterator_category. Value, Reference, and Difference shall be chosen so that value_type, reference, and difference_type meet the requirements indicated by iterator_category.

Note: there are further requirements on the iterator_traits<Iterator>::value_type if the Value parameter is not use_default, as implied by the algorithm for deducing the default for the value_type member.

Concepts

In addition to the concepts indicated by iterator_category and by iterator_traversal<indirect_iterator>::type, a specialization of indirect_iterator models the following concepts, Where v is an object of iterator_traits<Iterator>::value_type:

Readable Iterator if reference(*v) is convertible to value_type.

Writable Iterator if reference(*v) = t is a valid expression (where t is an object of type indirect_iterator::value_type)

Lvalue Iterator if reference is a reference type.

indirect_iterator<X,V1,C1,R1,D1> is interoperable with indirect_iterator<Y,V2,C2,R2,D2> if and only if X is interoperable with Y.

Operations

In addition to the operations required by the concepts described above, specializations of indirect_iterator provide the following operations:

indirect_iterator();

Requires: Iterator must be Default Constructible.
Effects: Constructs an instance of indirect_iterator with a default-constructed m_iterator.

indirect_iterator(Iterator x);

Effects: Constructs an instance of indirect_iterator with m_iterator copy constructed from x.

template <
    class Iterator2, class Value2, unsigned Access, class Traversal
  , class Reference2, class Difference2
>
indirect_iterator(
    indirect_iterator<
         Iterator2, Value2, Access, Traversal, Reference2, Difference2
    > const& y
  , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
);

Requires: Iterator2 is implicitly convertible to Iterator.
Effects: Constructs an instance of indirect_iterator whose m_iterator subobject is constructed from y.base().

Iterator const& base() const;

Returns: m_iterator

reference operator*() const;

Returns: **m_iterator

indirect_iterator& operator++();

Effects: ++m_iterator
Returns: *this

indirect_iterator& operator--();

Effects: --m_iterator
Returns: *this


PrevUpHomeNext