mirror of
https://github.com/saitohirga/WSJT-X.git
synced 2024-11-19 18:42:06 -05:00
333 lines
11 KiB
Plaintext
333 lines
11 KiB
Plaintext
|
|
[section:adaptor Iterator Adaptor]
|
|
|
|
The `iterator_adaptor` class template adapts some `Base` [#base]_
|
|
type to create a new iterator. Instantiations of `iterator_adaptor`
|
|
are derived from a corresponding instantiation of `iterator_facade`
|
|
and implement the core behaviors in terms of the `Base` type. In
|
|
essence, `iterator_adaptor` merely forwards all operations to an
|
|
instance of the `Base` type, which it stores as a member.
|
|
|
|
.. [#base] The term "Base" here does not refer to a base class and is
|
|
not meant to imply the use of derivation. We have followed the lead
|
|
of the standard library, which provides a base() function to access
|
|
the underlying iterator object of a `reverse_iterator` adaptor.
|
|
|
|
The user of `iterator_adaptor` creates a class derived from an
|
|
instantiation of `iterator_adaptor` and then selectively
|
|
redefines some of the core member functions described in the
|
|
`iterator_facade` core requirements table. The `Base` type need
|
|
not meet the full requirements for an iterator; it need only
|
|
support the operations used by the core interface functions of
|
|
`iterator_adaptor` that have not been redefined in the user's
|
|
derived class.
|
|
|
|
Several of the template parameters of `iterator_adaptor` default
|
|
to `use_default`. This allows the
|
|
user to make use of a default parameter even when she wants to
|
|
specify a parameter later in the parameter list. Also, the
|
|
defaults for the corresponding associated types are somewhat
|
|
complicated, so metaprogramming is required to compute them, and
|
|
`use_default` can help to simplify the implementation. Finally,
|
|
the identity of the `use_default` type is not left unspecified
|
|
because specification helps to highlight that the `Reference`
|
|
template parameter may not always be identical to the iterator's
|
|
`reference` type, and will keep users from making mistakes based on
|
|
that assumption.
|
|
|
|
[section:adaptor_reference Reference]
|
|
|
|
[h2 Synopsis]
|
|
|
|
template <
|
|
class Derived
|
|
, class Base
|
|
, class Value = use_default
|
|
, class CategoryOrTraversal = use_default
|
|
, class Reference = use_default
|
|
, class Difference = use_default
|
|
>
|
|
class iterator_adaptor
|
|
: public iterator_facade<Derived, *V'*, *C'*, *R'*, *D'*> // see details
|
|
{
|
|
friend class iterator_core_access;
|
|
public:
|
|
iterator_adaptor();
|
|
explicit iterator_adaptor(Base const& iter);
|
|
typedef Base base_type;
|
|
Base const& base() const;
|
|
protected:
|
|
typedef iterator_adaptor iterator_adaptor\_;
|
|
Base const& base_reference() const;
|
|
Base& base_reference();
|
|
private: // Core iterator interface for iterator_facade.
|
|
typename iterator_adaptor::reference dereference() const;
|
|
|
|
template <
|
|
class OtherDerived, class OtherIterator, class V, class C, class R, class D
|
|
>
|
|
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
|
|
|
|
void advance(typename iterator_adaptor::difference_type n);
|
|
void increment();
|
|
void decrement();
|
|
|
|
template <
|
|
class OtherDerived, class OtherIterator, class V, class C, class R, class D
|
|
>
|
|
typename iterator_adaptor::difference_type distance_to(
|
|
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
|
|
|
|
private:
|
|
Base m_iterator; // exposition only
|
|
};
|
|
|
|
__ base_parameters_
|
|
|
|
.. _requirements:
|
|
|
|
[h2 Requirements]
|
|
|
|
`static_cast<Derived*>(iterator_adaptor*)` shall be well-formed.
|
|
The `Base` argument shall be Assignable and Copy Constructible.
|
|
|
|
|
|
.. _base_parameters:
|
|
|
|
[h2 Base Class Parameters]
|
|
|
|
The *V'*, *C'*, *R'*, and *D'* parameters of the `iterator_facade`
|
|
used as a base class in the summary of `iterator_adaptor`
|
|
above are defined as follows:
|
|
|
|
[pre
|
|
*V'* = if (Value is use_default)
|
|
return iterator_traits<Base>::value_type
|
|
else
|
|
return Value
|
|
|
|
*C'* = if (CategoryOrTraversal is use_default)
|
|
return iterator_traversal<Base>::type
|
|
else
|
|
return CategoryOrTraversal
|
|
|
|
*R'* = if (Reference is use_default)
|
|
if (Value is use_default)
|
|
return iterator_traits<Base>::reference
|
|
else
|
|
return Value&
|
|
else
|
|
return Reference
|
|
|
|
*D'* = if (Difference is use_default)
|
|
return iterator_traits<Base>::difference_type
|
|
else
|
|
return Difference
|
|
]
|
|
|
|
[h2 Operations]
|
|
|
|
[h3 Public]
|
|
|
|
|
|
iterator_adaptor();
|
|
|
|
[*Requires:] The `Base` type must be Default Constructible.[br]
|
|
[*Returns:] An instance of `iterator_adaptor` with
|
|
`m_iterator` default constructed.
|
|
|
|
|
|
explicit iterator_adaptor(Base const& iter);
|
|
|
|
[*Returns:] An instance of `iterator_adaptor` with
|
|
`m_iterator` copy constructed from `iter`.
|
|
|
|
Base const& base() const;
|
|
|
|
[*Returns:] `m_iterator`
|
|
|
|
|
|
[h3 Protected]
|
|
|
|
Base const& base_reference() const;
|
|
|
|
[*Returns:] A const reference to `m_iterator`.
|
|
|
|
|
|
Base& base_reference();
|
|
|
|
[*Returns:] A non-const reference to `m_iterator`.
|
|
|
|
[h3 Private]
|
|
|
|
typename iterator_adaptor::reference dereference() const;
|
|
|
|
[*Returns:] `*m_iterator`
|
|
|
|
|
|
template <
|
|
class OtherDerived, class OtherIterator, class V, class C, class R, class D
|
|
>
|
|
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
|
|
|
|
[*Returns:] `m_iterator == x.base()`
|
|
|
|
|
|
void advance(typename iterator_adaptor::difference_type n);
|
|
|
|
[*Effects:] `m_iterator += n;`
|
|
|
|
void increment();
|
|
|
|
[*Effects:] `++m_iterator;`
|
|
|
|
void decrement();
|
|
|
|
[*Effects:] `--m_iterator;`
|
|
|
|
|
|
template <
|
|
class OtherDerived, class OtherIterator, class V, class C, class R, class D
|
|
>
|
|
typename iterator_adaptor::difference_type distance_to(
|
|
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
|
|
|
|
[*Returns:] `y.base() - m_iterator`
|
|
|
|
[endsect]
|
|
|
|
[section:adaptor_tutorial Tutorial]
|
|
|
|
In this section we'll further refine the `node_iter` class
|
|
template we developed in the |fac_tut|_. If you haven't already
|
|
read that material, you should go back now and check it out because
|
|
we're going to pick up right where it left off.
|
|
|
|
.. |fac_tut| replace:: `iterator_facade` tutorial
|
|
.. _fac_tut: iterator_facade.html#tutorial-example
|
|
|
|
[blurb [*`node_base*` really *is* an iterator][br][br]
|
|
It's not really a very interesting iterator, since `node_base`
|
|
is an abstract class: a pointer to a `node_base` just points
|
|
at some base subobject of an instance of some other class, and
|
|
incrementing a `node_base*` moves it past this base subobject
|
|
to who-knows-where? The most we can do with that incremented
|
|
position is to compare another `node_base*` to it. In other
|
|
words, the original iterator traverses a one-element array.
|
|
]
|
|
|
|
You probably didn't think of it this way, but the `node_base*`
|
|
object that underlies `node_iterator` is itself an iterator,
|
|
just like all other pointers. If we examine that pointer closely
|
|
from an iterator perspective, we can see that it has much in common
|
|
with the `node_iterator` we're building. First, they share most
|
|
of the same associated types (`value_type`, `reference`,
|
|
`pointer`, and `difference_type`). Second, even some of the
|
|
core functionality is the same: `operator*` and `operator==` on
|
|
the `node_iterator` return the result of invoking the same
|
|
operations on the underlying pointer, via the `node_iterator`\ 's
|
|
|dereference_and_equal|_). The only real behavioral difference
|
|
between `node_base*` and `node_iterator` can be observed when
|
|
they are incremented: `node_iterator` follows the
|
|
`m_next` pointer, while `node_base*` just applies an address offset.
|
|
|
|
.. |dereference_and_equal| replace:: `dereference` and `equal` member functions
|
|
.. _dereference_and_equal: iterator_facade.html#implementing-the-core-operations
|
|
|
|
It turns out that the pattern of building an iterator on another
|
|
iterator-like type (the `Base` [#base]_ type) while modifying
|
|
just a few aspects of the underlying type's behavior is an
|
|
extremely common one, and it's the pattern addressed by
|
|
`iterator_adaptor`. Using `iterator_adaptor` is very much like
|
|
using `iterator_facade`, but because iterator_adaptor tries to
|
|
mimic as much of the `Base` type's behavior as possible, we
|
|
neither have to supply a `Value` argument, nor implement any core
|
|
behaviors other than `increment`. The implementation of
|
|
`node_iter` is thus reduced to:
|
|
|
|
template <class Value>
|
|
class node_iter
|
|
: public boost::iterator_adaptor<
|
|
node_iter<Value> // Derived
|
|
, Value* // Base
|
|
, boost::use_default // Value
|
|
, boost::forward_traversal_tag // CategoryOrTraversal
|
|
>
|
|
{
|
|
private:
|
|
struct enabler {}; // a private type avoids misuse
|
|
|
|
public:
|
|
node_iter()
|
|
: node_iter::iterator_adaptor_(0) {}
|
|
|
|
explicit node_iter(Value* p)
|
|
: node_iter::iterator_adaptor_(p) {}
|
|
|
|
template <class OtherValue>
|
|
node_iter(
|
|
node_iter<OtherValue> const& other
|
|
, typename boost::enable_if<
|
|
boost::is_convertible<OtherValue*,Value*>
|
|
, enabler
|
|
>::type = enabler()
|
|
)
|
|
: node_iter::iterator_adaptor_(other.base()) {}
|
|
|
|
private:
|
|
friend class boost::iterator_core_access;
|
|
void increment() { this->base_reference() = this->base()->next(); }
|
|
};
|
|
|
|
Note the use of `node_iter::iterator_adaptor_` here: because
|
|
`iterator_adaptor` defines a nested `iterator_adaptor_` type
|
|
that refers to itself, that gives us a convenient way to refer to
|
|
the complicated base class type of `node_iter<Value>`. [Note:
|
|
this technique is known not to work with Borland C++ 5.6.4 and
|
|
Metrowerks CodeWarrior versions prior to 9.0]
|
|
|
|
You can see an example program that exercises this version of the
|
|
node iterators
|
|
[@../example/node_iterator3.cpp `here`].
|
|
|
|
|
|
In the case of `node_iter`, it's not very compelling to pass
|
|
`boost::use_default` as `iterator_adaptor` 's `Value`
|
|
argument; we could have just passed `node_iter` 's `Value`
|
|
along to `iterator_adaptor`, and that'd even be shorter! Most
|
|
iterator class templates built with `iterator_adaptor` are
|
|
parameterized on another iterator type, rather than on its
|
|
`value_type`. For example, `boost::reverse_iterator` takes an
|
|
iterator type argument and reverses its direction of traversal,
|
|
since the original iterator and the reversed one have all the same
|
|
associated types, `iterator_adaptor` 's delegation of default
|
|
types to its `Base` saves the implementor of
|
|
`boost::reverse_iterator` from writing:
|
|
|
|
std::iterator_traits<Iterator>::*some-associated-type*
|
|
|
|
at least four times.
|
|
|
|
We urge you to review the documentation and implementations of
|
|
|reverse_iterator|_ and the other Boost `specialized iterator
|
|
adaptors`__ to get an idea of the sorts of things you can do with
|
|
`iterator_adaptor`. In particular, have a look at
|
|
|transform_iterator|_, which is perhaps the most straightforward
|
|
adaptor, and also |counting_iterator|_, which demonstrates that
|
|
`iterator_adaptor`\ 's `Base` type needn't be an iterator.
|
|
|
|
.. |reverse_iterator| replace:: `reverse_iterator`
|
|
.. _reverse_iterator: reverse_iterator.html
|
|
|
|
.. |counting_iterator| replace:: `counting_iterator`
|
|
.. _counting_iterator: counting_iterator.html
|
|
|
|
.. |transform_iterator| replace:: `transform_iterator`
|
|
.. _transform_iterator: transform_iterator.html
|
|
|
|
__ index.html#specialized-adaptors
|
|
|
|
|
|
[endsect]
|
|
|
|
[endsect] |