The Iterator Adaptor library allows you transform an arbitrary ``base'' type into a standard-conforming iterator with the behaviors you choose. Doing so is especially easy if the ``base'' type is itself an iterator. The library also supplies several example adaptors which apply specific useful behaviors to arbitrary base iterators.
The library's interface has changed since it was first released, breaking backward compatibility:
``Policy Adaptors and the Boost Iterator Adaptor Library'' is a technical paper describing this library and the powerful design pattern on which it is based. It was presented at the C++ Template Workshop at OOPSLA 2001; the slides from the talk are available here. Please note that while the slides incorporate the minor interface changes described in the previous section, the paper does not.
Dave
Abrahams started the library, applying policy class technique and
handling const/non-const iterator interactions. He also contributed the
indirect_ and reverse_ iterator generators, and expanded
counting_iterator_generator to
cover all incrementable types. He edited most of the documentation,
sometimes heavily.
Jeremy
Siek contributed the transform
iterator adaptor, the integer-only version of counting_iterator_generator,
the function output iterator
adaptor, and most of the documentation.
John
Potter contributed the projection_ and filter_ iterator generators and made some
simplifications to the main iterator_adaptor template.
Jens Maurer
contributed the generator iterator
adaptor.
Toon Knapen contributed the permutation
iterator adaptor.
Ronald Garcia
contributed the shared container iterator
adaptor.
iterator_adaptor is declared like this:
template <class Base, class Policies,
class ValueOrNamedParam = typename std::iterator_traits<Base>::value_type,
class ReferenceOrNamedParam = ...(see below),
class PointerOrNamedParam = ...(see below),
class CategoryOrNamedParam = typename std::iterator_traits<Base>::iterator_category,
class DistanceOrNamedParam = typename std::iterator_traits<Base>::difference_type>
struct iterator_adaptor;
Although iterator_adaptor takes seven template parameters, defaults have been carefully chosen to minimize the number of parameters you must supply in most cases, especially if Base is an iterator.
| Parameter | Description | Requirements |
|---|---|---|
| Base | The data type on which the resulting iterator is based. Do not be misled by the name "Base": this is not a base class. | Assignable, Default Constructible |
| Policies | A policy class that supplies core functionality to the resulting iterator. | See table below. |
| Value | The value_type of the resulting iterator, unless const. If
Value is const X the
value_type will be (non-const) X[1]. If the value_type you wish to use is an abstract
base class see note [5]. Default: std::iterator_traits<Base>::value_type [2] | |
| Reference | The reference type of the resulting iterator, and in
particular, the result type of operator*(). Default: If Value is supplied, Value& is used. Otherwise std::iterator_traits<Base>::reference is used. [7] | ForwardIterators, BidirectionalIterators, and RandomAccessIterators require that Reference is a true reference type (e.g. not a proxy). |
| Pointer | The pointer type of the resulting iterator, and in
particular, the result type of operator->(). Default: If Value was not supplied, std::iterator_traits<Base>::pointer. [7] Otherwise, if iterator_category is
input_iterator, then a class yielding
Value* when operator->() is applied.
Otherwise, Value*.
| value_type* or a
class which yields value_type* when
operator->() is applied.
|
| Category | The iterator_category type for the resulting iterator. Default: std::iterator_traits<Base>::iterator_category | One of
std::input_iterator_tag,
std::output_iterator_tag,
std::forward_iterator_tag,
std::bidirectional_iterator_tag, or
std::random_access_iterator_tag.
|
| Distance | The difference_type for the resulting iterator. Default: std::iterator_traits<Base>::difference_type | A signed integral type |
| NamedParam | A named template parameter (see below). |
For example, the following adapts foo_iterator to create an InputIterator with reference type foo, and whose other traits are determined according to the defaults described above.template <class Value> struct value_type_is; template <class Reference> struct reference_is; template <class Pointer> struct pointer_is; template <class Distance> struct difference_type_is; template <class Category> struct iterator_category_is;
typedef iterator_adaptor<foo_iterator, foo_policies, reference_is<foo>, iterator_category_is<std::input_iterator_tag> > MyIterator;
The main task in using iterator_adaptor is creating an
appropriate Policies class. The Policies class will become
the functional heart of the resulting iterator, supplying the core
operations that determine its behavior. The iterator_adaptor
template defines all of the operators required of a Random Access
Iterator by dispatching to a Policies object. Your
Policies class must implement a subset of the core iterator
operations below corresponding to the iterator categories you want it to
support.
| Expression | Effects | Implements Operations | Required for Iterator Categories |
|---|---|---|---|
| p.initialize(b) | optionally modify base iterator during iterator construction | constructors | Input/ Output/ Forward/ Bidirectional/ Random Access |
| p.dereference(x) | returns an element of the iterator's reference type | *x, x[d] | |
| p.equal(x, y) | tests the iterator for equality | i1 == i2, i1 != i2 | |
| p.increment(x) | increments the iterator | ++x, x++ | |
| p.decrement(x) | decrements the iterator | --x, x-- | Bidirectional/ Random Access |
| p.distance(x, y) | measures the distance between iterators | y - x, x < y | Random Access |
| p.advance(x, n) | adds an integer offset to iterators |
x + d,
d + x,
x += d, x - d, x -= d |
The library also supplies a "trivial" policy class,
default_iterator_policies, which implements all seven of the core
operations in the usual way. If you wish to create an iterator adaptor that
only changes a few of the base type's behaviors, then you can derive your
new policy class from default_iterator_policies to avoid retyping
the usual behaviors. You should also look at
default_iterator_policies as the ``boilerplate'' for your own
policy classes, defining functions with the same interface. This is the
definition of default_iterator_policies:
struct default_iterator_policies
{
// Some of these members were defined static, but Borland got confused
// and thought they were non-const. Also, Sun C++ does not like static
// function templates.
template <class Base>
void initialize(Base&)
{ }
template <class IteratorAdaptor>
typename IteratorAdaptor::reference dereference(const IteratorAdaptor& x) const
{ return *x.base(); }
template <class IteratorAdaptor>
void increment(IteratorAdaptor& x)
{ ++x.base(); }
template <class IteratorAdaptor>
void decrement(IteratorAdaptor& x)
{ --x.base(); }
template <class IteratorAdaptor, class DifferenceType>
void advance(IteratorAdaptor& x, DifferenceType n)
{ x.base() += n; }
template <class IteratorAdaptor1, class IteratorAdaptor2>
typename IteratorAdaptor1::difference_type
distance(const IteratorAdaptor1& x, const IteratorAdaptor2& y) const
{ return y.base() - x.base(); }
template <class IteratorAdaptor1, class IteratorAdaptor2>
bool equal(const IteratorAdaptor1& x, const IteratorAdaptor2& y) const
{ return x.base() == y.base(); }
};
Template member functions are used throughout default_iterator_policies so that it can be employed with a wide range of iterators. If we had used concrete types above, we'd have tied the usefulness of default_iterator_policies to a particular range of adapted iterators. If you follow the same pattern with your Policies classes, you can use them to generate more specialized adaptors along the lines of those supplied by this library.
| explicit iterator_adaptor(const Base&, const Policies& =
Policies())
Construct an adapted iterator from a base object and a policies object. As this constructor is explicit, it does not provide for implicit conversions from the Base type to the iterator adaptor. |
| template <class B, class V, class R, class P> iterator_adaptor(const iterator_adaptor<B,Policies,V,R,P,Category,Distance>&) This constructor allows for conversion from mutable to constant adapted iterators. See below for more details. Requires: B is convertible to Base. |
| const base_type& base() const;
Return a const reference to the base object. |
| base_type& base();
Return a reference to the base object. This is to give the policies object access to the base object. See above for policies iterator_adaptor interaction.[8] |
| const Policies& policies() const;
Return a const reference to the policies object. |
| Policies& policies();
Return a reference to the policies object. |
It is often useful to automatically apply some function to the value returned by dereferencing an iterator. The transform iterator makes it easy to create an iterator adaptor which does just that. Here we will show how easy it is to implement the transform iterator using the iterator_adaptor template.
We want to be able to adapt a range of iterators and functions, so the policies class will have a template parameter for the function type and it will have a data member of that type. We know that the function takes one argument and that we'll need to be able to deduce the result_type of the function so we can use it for the adapted iterator's value_type. AdaptableUnaryFunction is the Concept that fulfills those requirements.
To implement a transform iterator we will only change one of the base
iterator's behaviors, so the transform_iterator_policies class can
inherit the rest from default_iterator_policies. We will define the
dereference() member function, which is used to implement
operator*() of the adapted iterator. The implementation will
dereference the base iterator and apply the function object. The complete
code for transform_iterator_policies is:
template <class AdaptableUnaryFunction>
struct transform_iterator_policies : public default_iterator_policies
{
transform_iterator_policies() { }
transform_iterator_policies(const AdaptableUnaryFunction& f)
: m_f(f) { }
template <class IteratorAdaptor>
typename IteratorAdaptor::reference
dereference(const IteratorAdaptor& iter) const
{ return m_f(*iter.base()); }
AdaptableUnaryFunction m_f;
};
The next step is to use the iterator_adaptor template to
construct the transform iterator type. The nicest way to package the
construction of the transform iterator is to create a type generator.
The first template parameter to the generator will be the type of the
function object and the second will be the base iterator type. We use
iterator_adaptor to define the transform iterator type as a nested
typedef inside the transform_iterator_generator class.
Because the function may return by-value, we must limit the
iterator_category to Input Iterator, and
the iterator's reference type cannot be a true reference (the
standard allows this for input iterators), so in this case we can use few
of iterator_adaptor's default template arguments.
template <class AdaptableUnaryFunction, class Iterator>
struct transform_iterator_generator
{
typedef typename AdaptableUnaryFunction::result_type value_type;
public:
typedef iterator_adaptor<Iterator,
transform_iterator_policies<AdaptableUnaryFunction>,
value_type, value_type, value_type*, std::input_iterator_tag>
type;
};
As a finishing touch, we will create an object generator
for the transform iterator. Our object generator makes it more
convenient to create a transform iterator.
template <class AdaptableUnaryFunction, class Iterator>
typename transform_iterator_generator<AdaptableUnaryFunction,Iterator>::type
make_transform_iterator(Iterator base,
const AdaptableUnaryFunction& f = AdaptableUnaryFunction())
{
typedef typename transform_iterator_generator<AdaptableUnaryFunction,
Iterator>::type result_t;
return result_t(base, f);
}
Here is an example that shows how to use a transform iterator to iterate
through a range of numbers, multiplying each of them by 2 and printing the
result to standard output.
#include <functional> #include <algorithm> #include <iostream> #include <boost/iterator_adaptors.hpp> int main(int, char*[]) { int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 }; const int N = sizeof(x)/sizeof(int); std::cout << "multiplying the array by 2:" << std::endl; std::copy(boost::make_transform_iterator(x, std::bind1st(std::multiplies<int>(), 2)), boost::make_transform_iterator(x + N, std::bind1st(std::multiplies<int>(), 2)), std::ostream_iterator<int>(std::cout, " ")); std::cout << std::endl; return 0; }This output is:2 4 6 8 10 12 14 16
C++ allows const and non-const pointers to interact in the following intuitive ways:
The Projection Iterator adaptor is similar to the transform iterator adaptor in that its operator*() applies some function to the result of dereferencing the base iterator and then returns the result. The difference is that the function must return a reference to some existing object (for example, a data member within the value_type of the base iterator).
The projection_iterator_pair_generator template is a special two-type generator for mutable and constant versions of a projection iterator. It is defined as follows:
template <class AdaptableUnaryFunction, class Iterator, class ConstIterator>
struct projection_iterator_pair_generator {
typedef typename AdaptableUnaryFunction::result_type value_type;
typedef projection_iterator_policies<AdaptableUnaryFunction> policies;
public:
typedef iterator_adaptor<Iterator,policies,value_type> iterator;
typedef iterator_adaptor<ConstIterator,policies,value_type,
const value_type&,const value_type*> const_iterator;
};
It is assumed that the Iterator and ConstIterator arguments are corresponding mutable and constant iterators.
There is an unlimited number of ways the iterator_adaptors class can be used to create iterators. One interesting exercise would be to re-implement the iterators of std::list and slist using iterator_adaptors, where the adapted Iterator types would be node pointers.
template <class Base, class Policies,
class Value = typename std::iterator_traits<Base>::value_type,
class Reference = ...(see below),
class Pointer = ...(see below),
class Category = typename std::iterator_traits<Base>::iterator_category,
class Distance = typename std::iterator_traits<Base>::difference_type
>
struct iterator_adaptor
{
typedef Distance difference_type;
typedef typename boost::remove_const<Value>::type value_type;
typedef Pointer pointer;
typedef Reference reference;
typedef Category iterator_category;
typedef Base base_type;
typedef Policies policies_type;
iterator_adaptor();
explicit iterator_adaptor(const Base&, const Policies& = Policies());
base_type& base();
const base_type& base() const;
template <class B, class V, class R, class P>
iterator_adaptor(
const iterator_adaptor<B,Policies,V,R,P,Category,Distance>&);
reference operator*() const; [6]
operator_arrow_result_type operator->() const; [3]
value_type operator[](difference_type n) const; [4], [6]
iterator_adaptor& operator++();
iterator_adaptor& operator++(int);
iterator_adaptor& operator--();
iterator_adaptor& operator--(int);
iterator_adaptor& operator+=(difference_type n);
iterator_adaptor& operator-=(difference_type n);
iterator_adaptor& operator-(Distance x) const;
};
template <class B, class P, class V, class R, class Ptr,
class C, class D1, class D2>
iterator_adaptor<B,P,V,R,Ptr,C,D1>
operator+(iterator_adaptor<B,P,V,R,Ptr,C,D1>, D2);
template <class B, class P, class V, class R, class Ptr,
class C, class D1, class D2>
iterator_adaptor<B,P,V,R,P,C,D1>
operator+(D2, iterator_adaptor<B,P,V,R,Ptr,C,D1> p);
template <class B1, class B2, class P, class V1, class V2,
class R1, class R2, class P1, class P2, class C, class D>
Distance operator-(const iterator_adaptor<B1,P,V1,R1,P1,C,D>&,
const iterator_adaptor<B2,P,V2,R2,P2,C,D>&);
template <class B1, class B2, class P, class V1, class V2,
class R1, class R2, class P1, class P2, class C, class D>
bool operator==(const iterator_adaptor<B1,P,V1,R1,P1,C,D>&,
const iterator_adaptor<B2,P,V2,R2,P2,C,D>&);
// and similarly for operators !=, <, <=, >=, >
Generally, the iterator adaptors library can be compiled with all compilers supporting iterator traits and type traits.
Microsoft VC++ is not able to handle iterator adaptors based on a
vector without specifying all template paramters explicitly.
In case not all template parameters are specified explicitly, the iterator adaptors
library will deduce these types using iterator_traits. But since in VC++ a
vector is a T*, VC++ can't handle using
iterator_traits due to the lack of partial template specialization.
[1] The standard specifies that the value_type of const iterators to T (e.g. const T*) is non-const T, while the pointer and reference types for all Forward Iterators are const T* and const T&, respectively. Stripping the const-ness of Value allows you to easily make a constant iterator by supplying a const type for Value, and allowing the defaults for the Pointer and Reference parameters to take effect. Although compilers that don't support partial specialization won't strip const for you, having a const value_type is often harmless in practice.
[2] If your compiler does not support partial specialization and the base iterator is a builtin pointer type, you will not be able to use the default for Value and will have to specify this type explicitly.
[3] The result type for the operator->() depends on the category and value type of the iterator and is somewhat complicated to describe. But be assured, it works in a stardard conforming fashion, providing access to members of the objects pointed to by the iterator.
[4] The result type of operator[]() is value_type instead of reference as might be expected. There are two reasons for this choice. First, the C++ standard only requires that the return type of an arbitrary Random Access Iterator's operator[]be ``convertible to T'' (Table 76), so when adapting an arbitrary base iterator we may not have a reference to return. Second, and more importantly, for certain kinds of iterators, returning a reference could cause serious memory problems due to the reference being bound to a temporary object whose lifetime ends inside of the operator[].
[5] The value_type of an iterator may not be an abstract base class, however many common uses of iterators never need the value_type, only the reference type. If you wish to create such an iterator adaptor, use a dummy type such as char for the Value parameter, and use a reference to your abstract base class for the Reference parameter. Note that such an iterator does not fulfill the C++ standards requirements for a Forward Iterator, so you will need to use a less restrictive iterator category such as std::input_iterator_tag.
[6] There is a common misconception that an iterator should have two versions of operator* and of operator[], one version that is a const member function and one version that is non-const. Perhaps the source of this misconception is that containers typically have const and non-const versions of many of their member functions. Iterators, however, are different. A particular iterator type can be either mutable or constant (but not both). One can assign to and change the object pointed to by a mutable iterator whereas a constant iterator returns constant objects when dereferenced. Whether the iterator object itself is const has nothing to do with whether the iterator is mutable or constant. This is analogous to the way built-in pointer types behave. For example, one can modify objects pointed to by a const pointer
int* const x = new int;
int i = 3;
*x = i;
but one cannot modify objects pointed to by a pointer
to const
int const* x = new int;
int i = 3;
*x = i;
[7] If you are using a compiler that does not have a version of std::iterator_traits that works for pointers (i.e., if your compiler does not support partial specialization) then if the Base type is a const pointer, then the correct defaults for the reference and pointer types can not be deduced. You must specify these types explicitly.
[8] Exposing the base object might be considered as being dangerous. A possible fix would require compiler support for template friends. As this is not widely available today, the base object remains exposed for now.
Revised 30 Nov 2001
© Copyright Dave Abrahams and Jeremy Siek 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.