<metaname="author"content="David Abrahams, Jeremy Siek, Thomas Witt"/>
<metaname="organization"content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction"/>
<td><aclass="first reference"href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <aclass="reference"href="http://www.osl.iu.edu">Open Systems
Lab</a>, University of Hanover <aclass="last reference"href="http://www.ive.uni-hannover.de">Institute for Transport
<trclass="field"><thclass="docinfo-name">Number:</th><tdclass="field-body"><strong>This document is a revised version of the official</strong> N1476=03-0059</td>
<li><aclass="reference"href="#iterator-adaptor-public-operations"id="id38"name="id38"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> public operations</a></li>
<li><aclass="reference"href="#iterator-adaptor-protected-member-functions"id="id39"name="id39"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> protected member functions</a></li>
<li><aclass="reference"href="#iterator-adaptor-private-member-functions"id="id40"name="id40"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> private member functions</a></li>
<li><aclass="reference"href="#transform-iterator-public-operations"id="id52"name="id52"><ttclass="literal"><spanclass="pre">transform_iterator</span></tt> public operations</a></li>
<p>This proposal is formulated in terms of the new <ttclass="literal"><spanclass="pre">iterator</span><spanclass="pre">concepts</span></tt>
as proposed in <aclass="reference"href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html">n1477</a>, since user-defined and especially adapted
iterators suffer from the well known categorization problems that are
inherent to the current iterator categories.</p>
<p>This proposal does not strictly depend on proposal <aclass="reference"href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html">n1477</a>, as there
is a direct mapping between new and old categories. This proposal
could be reformulated using this mapping if <aclass="reference"href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html">n1477</a> was not accepted.</p>
<p>The question of iterator interoperability is poorly addressed in the
current standard. There are currently two defect reports that are
concerned with interoperability issues.</p>
<p>Issue <aclass="reference"href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-defects.html#179">179</a> concerns the fact that mutable container iterator types
are only required to be convertible to the corresponding constant
iterator types, but objects of these types are not required to
interoperate in comparison or subtraction expressions. This situation
is tedious in practice and out of line with the way built in types
work. This proposal implements the proposed resolution to issue
<aclass="reference"href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-defects.html#179">179</a>, as most standard library implementations do nowadays. In other
words, if an iterator type A has an implicit or user defined
conversion to an iterator type B, the iterator types are interoperable
and the usual set of operators are available.</p>
<p>Issue <aclass="reference"href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#280">280</a> concerns the current lack of interoperability between
reverse iterator types. The proposed new reverse_iterator template
fixes the issues raised in 280. It provides the desired
interoperability without introducing unwanted overloads.</p>
<p>While the iterator interface is rich, there is a core subset of the
interface that is necessary for all the functionality. We have
identified the following core behaviors for iterators:</p>
<ulclass="simple">
<li>dereferencing</li>
<li>incrementing</li>
<li>decrementing</li>
<li>equality comparison</li>
<li>random-access motion</li>
<li>distance measurement</li>
</ul>
<p>In addition to the behaviors listed above, the core interface elements
include the associated types exposed through iterator traits:
<ttclass="literal"><spanclass="pre">value_type</span></tt>, <ttclass="literal"><spanclass="pre">reference</span></tt>, <ttclass="literal"><spanclass="pre">difference_type</span></tt>, and
<p>The user of <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> derives his iterator class from an
instantiation of <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> which takes the derived iterator
class as the first template parameter. The order of the other
template parameters to <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> have been carefully chosen
to take advantage of useful defaults. For example, when defining a
constant lvalue iterator, the user can pass a const-qualified version
of the iterator's <ttclass="literal"><spanclass="pre">value_type</span></tt> as <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>'s <ttclass="literal"><spanclass="pre">Value</span></tt>
parameter and omit the <ttclass="literal"><spanclass="pre">Reference</span></tt> parameter which follows.</p>
<p>The derived iterator class must define member functions implementing
the iterator's core behaviors. The following table describes
expressions which are required to be valid depending on the category
of the derived iterator type. These member functions are described
<td>Measure the distance to <ttclass="literal"><spanclass="pre">j</span></tt></td>
</tr>
</tbody>
</table>
</blockquote>
<!-- Should we add a comment that a zero overhead implementation of iterator_facade
is possible with proper inlining? -->
<p>In addition to implementing the core interface functions, an iterator
derived from <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> typically defines several
constructors. To model any of the standard iterator concepts, the
iterator must at least have a copy constructor. Also, if the iterator
type <ttclass="literal"><spanclass="pre">X</span></tt> is meant to be automatically interoperate with another
iterator type <ttclass="literal"><spanclass="pre">Y</span></tt> (as with constant and mutable iterators) then
there must be an implicit conversion from <ttclass="literal"><spanclass="pre">X</span></tt> to <ttclass="literal"><spanclass="pre">Y</span></tt> or from <ttclass="literal"><spanclass="pre">Y</span></tt>
to <ttclass="literal"><spanclass="pre">X</span></tt> (but not both), typically implemented as a conversion
constructor. Finally, if the iterator is to model Forward Traversal
Iterator or a more-refined iterator concept, a default constructor is
member (e.g. <aclass="reference"href="counting_iterator.html">counting_iterator</a>), because <ttclass="literal"><spanclass="pre">*(p+n)</span></tt> is a reference
<p>Writable iterators built with <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> implement the
semantics required by the preferred resolution to <aclass="reference"href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299">issue 299</a> and
adopted by proposal <aclass="reference"href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html">n1477</a>: the result of <ttclass="literal"><spanclass="pre">p[n]</span></tt> is a proxy object
containing a copy of <ttclass="literal"><spanclass="pre">p+n</span></tt>, and <ttclass="literal"><spanclass="pre">p[n]</span><spanclass="pre">=</span><spanclass="pre">x</span></tt> is equivalent to <ttclass="literal"><spanclass="pre">*(p</span>
<spanclass="pre">+</span><spanclass="pre">n)</span><spanclass="pre">=</span><spanclass="pre">x</span></tt>. This approach will work properly for any random-access
iterator regardless of the other details of its implementation. A
user who knows more about the implementation of her iterator is free
to implement an <ttclass="literal"><spanclass="pre">operator[]</span></tt> which returns an lvalue in the derived
iterator class; it will hide the one supplied by <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>
<p>The <ttclass="literal"><spanclass="pre">reference</span></tt> type of a readable iterator (and today's input
iterator) need not in fact be a reference, so long as it is
convertible to the iterator's <ttclass="literal"><spanclass="pre">value_type</span></tt>. When the <ttclass="literal"><spanclass="pre">value_type</span></tt>
is a class, however, it must still be possible to access members
through <ttclass="literal"><spanclass="pre">operator-></span></tt>. Therefore, an iterator whose <ttclass="literal"><spanclass="pre">reference</span></tt>
type is not in fact a reference must return a proxy containing a copy
of the referenced value from its <ttclass="literal"><spanclass="pre">operator-></span></tt>.</p>
<p>The return type for <ttclass="literal"><spanclass="pre">operator-></span></tt> and <ttclass="literal"><spanclass="pre">operator[]</span></tt> is not
explicitly specified. Instead it requires each <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>
instantiation to meet the requirements of its <ttclass="literal"><spanclass="pre">iterator_category</span></tt>.</p>
<p>The <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> class template adapts some <ttclass="literal"><spanclass="pre">Base</span></tt><aclass="footnote-reference"href="#base"id="id8"name="id8"><sup>3</sup></a>
<p>This proposal also contains several examples of specialized adaptors
which were easily implemented using <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt>:</p>
<ulclass="simple">
<li><ttclass="literal"><spanclass="pre">indirect_iterator</span></tt>, which iterates over iterators, pointers,
or smart pointers and applies an extra level of dereferencing.</li>
<li>A new <ttclass="literal"><spanclass="pre">reverse_iterator</span></tt>, which inverts the direction of a Base
iterator's motion, while allowing adapted constant and mutable
iterators to interact in the expected ways (unlike those in most
implementations of C++98).</li>
<li><ttclass="literal"><spanclass="pre">transform_iterator</span></tt>, which applies a user-defined function object
to the underlying values when dereferenced.</li>
<li><ttclass="literal"><spanclass="pre">projection_iterator</span></tt>, which is similar to <ttclass="literal"><spanclass="pre">transform_iterator</span></tt>
except that when dereferenced it returns a reference instead of
a value.</li>
<li><ttclass="literal"><spanclass="pre">filter_iterator</span></tt>, which provides a view of an iterator range in
which some elements of the underlying range are skipped.</li>
<p>[<em>Note:</em> The <ttclass="literal"><spanclass="pre">enable_if_interoperable</span></tt> template used above is for exposition
purposes. The member operators should be only be in an overload set
provided the derived types <ttclass="literal"><spanclass="pre">Dr1</span></tt> and <ttclass="literal"><spanclass="pre">Dr2</span></tt> are interoperable, by
which we mean they are convertible to each other. The
<ttclass="literal"><spanclass="pre">enable_if_interoperable</span></tt> approach uses SFINAE to take the operators
out of the overload set when the types are not interoperable.]</p>
<!-- we need a new label here because the presence of markup in the
title prevents an automatic link from being generated -->
<p>The default for the <ttclass="literal"><spanclass="pre">Reference</span></tt> parameter is <ttclass="literal"><spanclass="pre">Value&</span></tt> if the
access category for <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> is implicitly convertible to
<ttclass="literal"><spanclass="pre">writable_iterator_tag</span></tt>, and <ttclass="literal"><spanclass="pre">const</span><spanclass="pre">Value&</span></tt> otherwise.</p>
<p>The following table describes the other requirements on the
<ttclass="literal"><spanclass="pre">Derived</span></tt> parameter. Depending on the resulting iterator's
<ttclass="literal"><spanclass="pre">iterator_category</span></tt>, a subset of the expressions listed in the table
are required to be valid. The operations in the first column must be
accessible to member functions of class <ttclass="literal"><spanclass="pre">iterator_core_access</span></tt>.</p>
<p>In the table below, <ttclass="literal"><spanclass="pre">X</span></tt> is the derived iterator type, <ttclass="literal"><spanclass="pre">a</span></tt> is an
object of type <ttclass="literal"><spanclass="pre">X</span></tt>, <ttclass="literal"><spanclass="pre">b</span></tt> and <ttclass="literal"><spanclass="pre">c</span></tt> are objects of type <ttclass="literal"><spanclass="pre">const</span><spanclass="pre">X</span></tt>,
<ttclass="literal"><spanclass="pre">n</span></tt> is an object of <ttclass="literal"><spanclass="pre">X::difference_type</span></tt>, <ttclass="literal"><spanclass="pre">y</span></tt> is a constant
object of a single pass iterator type interoperable with X, and <ttclass="literal"><spanclass="pre">z</span></tt>
is a constant object of a random access traversal iterator type
interoperable with <ttclass="literal"><spanclass="pre">X</span></tt>.</p>
<spanclass="pre"><=</span><spanclass="pre">z</span></tt>, <ttclass="literal"><spanclass="pre">c</span><spanclass="pre">></span><spanclass="pre">z</span></tt>, and <ttclass="literal"><spanclass="pre">c</span><spanclass="pre">>=</span><spanclass="pre">c</span></tt>.</td>
<p><ttclass="literal"><spanclass="pre">operator->()</span><spanclass="pre">const;</span></tt> (see <aclass="reference"href="#operator-arrow">below</a>)</p>
<tableclass="field-list"frame="void"rules="none">
<colclass="field-name"/>
<colclass="field-body"/>
<tbodyvalign="top">
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first">If <ttclass="literal"><spanclass="pre">X::reference</span></tt> is a reference type, returns an object
of type <ttclass="literal"><spanclass="pre">X::pointer</span></tt> equal to:</p>
<p>Otherwise returns an object of unspecified type such that, given an
object <ttclass="literal"><spanclass="pre">a</span></tt> of type <ttclass="literal"><spanclass="pre">X</span></tt>, <ttclass="literal"><spanclass="pre">a->m</span></tt> is equivalent to <ttclass="literal"><spanclass="pre">(w</span><spanclass="pre">=</span><spanclass="pre">*a,</span>
<spanclass="pre">w.m)</span></tt> for some temporary object <ttclass="literal"><spanclass="pre">w</span></tt> of type <ttclass="literal"><spanclass="pre">X::value_type</span></tt>.</p>
<pclass="last">The type <ttclass="literal"><spanclass="pre">X::pointer</span></tt> is <ttclass="literal"><spanclass="pre">Value*</span></tt> if the access category for
<ttclass="literal"><spanclass="pre">X</span></tt> is implicitly convertible to <ttclass="literal"><spanclass="pre">writable_iterator_tag</span></tt>, and
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">an object convertible to <ttclass="literal"><spanclass="pre">X::reference</span></tt> and holding a copy
<em>p</em> of <ttclass="literal"><spanclass="pre">a+n</span></tt> such that, for a constant object <ttclass="literal"><spanclass="pre">v</span></tt> of type
<ttclass="literal"><spanclass="pre">X::value_type</span></tt>, <ttclass="literal"><spanclass="pre">X::reference(a[n]</span><spanclass="pre">=</span><spanclass="pre">v)</span></tt> is equivalent
to <ttclass="literal"><spanclass="pre">p</span><spanclass="pre">=</span><spanclass="pre">v</span></tt>.</td>
<p>The <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> is a base class template derived from an
instantiation of <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>. The core interface functions
expected by <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> are implemented in terms of the
<ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt>'s <ttclass="literal"><spanclass="pre">Base</span></tt> template parameter. A class derived
from <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> typically redefines some of the core
interface functions to adapt the behavior of the <ttclass="literal"><spanclass="pre">Base</span></tt> type.
Whether the derived class models any of the standard iterator concepts
depends on the operations supported by the <ttclass="literal"><spanclass="pre">Base</span></tt> type and which
core interface functions of <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> are redefined in the
<h3><aclass="toc-backref"href="#id38"name="iterator-adaptor-public-operations"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> public operations</a></h3>
<trclass="field"><thclass="field-name">Requires:</th><tdclass="field-body">The <ttclass="literal"><spanclass="pre">Base</span></tt> type must be Default Constructible.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> with
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> with
<ttclass="literal"><spanclass="pre">m_iterator</span></tt> copy constructed from <ttclass="literal"><spanclass="pre">iter</span></tt>.</td>
<h3><aclass="toc-backref"href="#id39"name="iterator-adaptor-protected-member-functions"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> protected member functions</a></h3>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">A const reference to <ttclass="literal"><spanclass="pre">m_iterator</span></tt>.</td>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">A non-const reference to <ttclass="literal"><spanclass="pre">m_iterator</span></tt>.</td>
<h3><aclass="toc-backref"href="#id40"name="iterator-adaptor-private-member-functions"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> private member functions</a></h3>
<!-- The requirements for all of these need to be written *much* more
formally -DWA -->
<p>[<em>Note:</em> The <ttclass="literal"><spanclass="pre">enable_if_convertible<X,Y>::type</span></tt> expression used in
this section is for exposition purposes. The converting constructors
for specialized adaptors should be only be in an overload set provided
that an object of type <ttclass="literal"><spanclass="pre">X</span></tt> is implicitly convertible to an object of
type <ttclass="literal"><spanclass="pre">Y</span></tt>. The <ttclass="literal"><spanclass="pre">enable_if_convertible</span></tt> approach uses SFINAE to
take the constructor out of the overload set when the types are not
<p>The <ttclass="literal"><spanclass="pre">value_type</span></tt> of the <ttclass="literal"><spanclass="pre">Iterator</span></tt> template parameter should
itself be dereferenceable. The return type of the <ttclass="literal"><spanclass="pre">operator*</span></tt> for
the <ttclass="literal"><spanclass="pre">value_type</span></tt> must be the same type as the <ttclass="literal"><spanclass="pre">Reference</span></tt> template
parameter. The <ttclass="literal"><spanclass="pre">Value</span></tt> template parameter will be the <ttclass="literal"><spanclass="pre">value_type</span></tt>
for the <ttclass="literal"><spanclass="pre">indirect_iterator</span></tt>, unless <ttclass="literal"><spanclass="pre">Value</span></tt> is const. If <ttclass="literal"><spanclass="pre">Value</span></tt>
is <ttclass="literal"><spanclass="pre">const</span><spanclass="pre">X</span></tt>, then <ttclass="literal"><spanclass="pre">value_type</span></tt> will be <em>non-</em><ttclass="literal"><spanclass="pre">const</span><spanclass="pre">X</span></tt>. The
default for <ttclass="literal"><spanclass="pre">Value</span></tt> is</p>
<p>If the default is used for <ttclass="literal"><spanclass="pre">Value</span></tt>, then there must be a valid
specialization of <ttclass="literal"><spanclass="pre">iterator_traits</span></tt> for the value type of the base
iterator.</p>
<p>The <ttclass="literal"><spanclass="pre">Reference</span></tt> parameter will be the <ttclass="literal"><spanclass="pre">reference</span></tt> type of the
<ttclass="literal"><spanclass="pre">indirect_iterator</span></tt>. The default is <ttclass="literal"><spanclass="pre">Value&</span></tt>.</p>
<p>The <ttclass="literal"><spanclass="pre">Category</span></tt> parameter is the <ttclass="literal"><spanclass="pre">iterator_category</span></tt> type for the
<ttclass="literal"><spanclass="pre">indirect_iterator</span></tt>. The default is
<trclass="field"><thclass="field-name">Requires:</th><tdclass="field-body"><ttclass="literal"><spanclass="pre">Iterator</span></tt> must be Default Constructible.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">indirect_iterator</span></tt> with
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">indirect_iterator</span></tt> with
the <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> subobject copy constructed from <ttclass="literal"><spanclass="pre">x</span></tt>.</td>
<trclass="field"><thclass="field-name">Requires:</th><tdclass="field-body"><ttclass="literal"><spanclass="pre">Iterator2</span></tt> is implicitly convertible to <ttclass="literal"><spanclass="pre">Iterator</span></tt>.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">indirect_iterator</span></tt> that is a copy of <ttclass="literal"><spanclass="pre">y</span></tt>.</td>
<trclass="field"><thclass="field-name">Requires:</th><tdclass="field-body"><ttclass="literal"><spanclass="pre">Iterator</span></tt> must be Default Constructible.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">reverse_iterator</span></tt> with a
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">reverse_iterator</span></tt> with a
base object copy constructed from <ttclass="literal"><spanclass="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
<preclass="literal-block">
template<class OtherIterator>
reverse_iterator(
reverse_iterator<OtherIterator> const& r
<trclass="field"><thclass="field-name">Requires:</th><tdclass="field-body"><ttclass="literal"><spanclass="pre">OtherIterator</span></tt> is implicitly convertible to <ttclass="literal"><spanclass="pre">Iterator</span></tt>.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">reverse_iterator</span></tt> that is a copy of <ttclass="literal"><spanclass="pre">r</span></tt>.</td>
<p>The type <ttclass="literal"><spanclass="pre">UnaryFunction</span></tt> must be Assignable, Copy Constructible, and
the expression <ttclass="literal"><spanclass="pre">f(*i)</span></tt> must be valid where <ttclass="literal"><spanclass="pre">f</span></tt> is an object of
type <ttclass="literal"><spanclass="pre">UnaryFunction</span></tt>, <ttclass="literal"><spanclass="pre">i</span></tt> is an object of type <ttclass="literal"><spanclass="pre">Iterator</span></tt>, and
where the type of <ttclass="literal"><spanclass="pre">f(*i)</span></tt> must be
<li>Writable Lvalue Iterator if <ttclass="literal"><spanclass="pre">result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type</span></tt> is a non-const reference.</li>
<li>Readable Lvalue Iterator if <ttclass="literal"><spanclass="pre">result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type</span></tt> is a const
The <ttclass="literal"><spanclass="pre">value_type</span></tt> is <ttclass="literal"><spanclass="pre">remove_cv<remove_reference<reference></span><spanclass="pre">>::type</span></tt>.</p>
<h4><aclass="toc-backref"href="#id52"name="transform-iterator-public-operations"><ttclass="literal"><spanclass="pre">transform_iterator</span></tt> public operations</a></h4>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">transform_iterator</span></tt> with <ttclass="literal"><spanclass="pre">m_f</span></tt>
and <ttclass="literal"><spanclass="pre">m_iterator</span></tt> default constructed.</td>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">transform_iterator</span></tt> with <ttclass="literal"><spanclass="pre">m_f</span></tt>
initialized to <ttclass="literal"><spanclass="pre">f</span></tt> and <ttclass="literal"><spanclass="pre">m_iterator</span></tt> initialized to <ttclass="literal"><spanclass="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
<preclass="literal-block">
template<class OtherIterator, class R2, class V2>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">transform_iterator</span></tt> that is a copy of <ttclass="literal"><spanclass="pre">t</span></tt>.</td>
</tr>
<trclass="field"><thclass="field-name">Requires:</th><tdclass="field-body"><ttclass="literal"><spanclass="pre">OtherIterator</span></tt> is implicitly convertible to <ttclass="literal"><spanclass="pre">Iterator</span></tt>.</td>
<p>The base <ttclass="literal"><spanclass="pre">Iterator</span></tt> parameter must be a model of Readable Iterator
and Single Pass Iterator. The resulting <ttclass="literal"><spanclass="pre">filter_iterator</span></tt> will be a
model of Forward Traversal Iterator if <ttclass="literal"><spanclass="pre">Iterator</span></tt> is, otherwise the
<ttclass="literal"><spanclass="pre">filter_iterator</span></tt> will be a model of Single Pass Iterator. The
access category of the <ttclass="literal"><spanclass="pre">filter_iterator</span></tt> will be the most refined
standard access category that is modeled by <ttclass="literal"><spanclass="pre">Iterator</span></tt>.</p>
<!-- Thomas is going to try implementing filter_iterator so that
it will be bidirectional if the underlying iterator is. -JGS -->
<p>The <ttclass="literal"><spanclass="pre">Predicate</span></tt> must be Assignable, Copy Constructible, and the
expression <ttclass="literal"><spanclass="pre">p(x)</span></tt> must be valid where <ttclass="literal"><spanclass="pre">p</span></tt> is an object of type
<ttclass="literal"><spanclass="pre">Predicate</span></tt>, <ttclass="literal"><spanclass="pre">x</span></tt> is an object of type
<ttclass="literal"><spanclass="pre">iterator_traits<Iterator>::value_type</span></tt>, and where the type of
<ttclass="literal"><spanclass="pre">p(x)</span></tt> must be convertible to <ttclass="literal"><spanclass="pre">bool</span></tt>.</p>
<trclass="field"><thclass="field-name">Requires:</th><tdclass="field-body"><ttclass="literal"><spanclass="pre">Predicate</span></tt> and <ttclass="literal"><spanclass="pre">Iterator</span></tt> must be Default Constructible.</td>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">A <ttclass="literal"><spanclass="pre">filter_iterator</span></tt> at position <ttclass="literal"><spanclass="pre">x</span></tt> that filters according
to predicate <ttclass="literal"><spanclass="pre">f</span></tt> and that will not increment past <ttclass="literal"><spanclass="pre">end</span></tt>.</td>
<trclass="field"><thclass="field-name">Requires:</th><tdclass="field-body"><ttclass="literal"><spanclass="pre">Predicate</span></tt> must be Default Constructible.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">A <ttclass="literal"><spanclass="pre">filter_iterator</span></tt> at position <ttclass="literal"><spanclass="pre">x</span></tt> that filters
according to a default constructed <ttclass="literal"><spanclass="pre">Predicate</span></tt>
and that will not increment past <ttclass="literal"><spanclass="pre">end</span></tt>.</td>
</tr>
</tbody>
</table>
<preclass="literal-block">
template <class OtherIterator>
filter_iterator(
filter_iterator<Predicate, OtherIterator> const& t
<trclass="field"><thclass="field-name">Requires:</th><tdclass="field-body"><ttclass="literal"><spanclass="pre">OtherIterator</span></tt> is implicitly convertible to <ttclass="literal"><spanclass="pre">Iterator</span></tt>.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">A copy of iterator <ttclass="literal"><spanclass="pre">t</span></tt>.</td>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">A copy of the predicate object used to construct <ttclass="literal"><spanclass="pre">*this</span></tt>.</td>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">The object <ttclass="literal"><spanclass="pre">end</span></tt> used to construct <ttclass="literal"><spanclass="pre">*this</span></tt>.</td>
<dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt>
<dd><ttclass="literal"><spanclass="pre">distance_to</span></tt> and a <ttclass="literal"><spanclass="pre">difference_type</span></tt> that avoids overflows in
the cases when the <ttclass="literal"><spanclass="pre">Incrementable</span></tt> type is a numeric type.]</dd>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">counting_iterator</span></tt> that is a copy of <ttclass="literal"><spanclass="pre">rhs</span></tt>.</td>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">counting_iterator</span></tt> with its base
object copy constructed from <ttclass="literal"><spanclass="pre">x</span></tt>.</td>
<p>The <ttclass="literal"><spanclass="pre">UnaryFunction</span></tt> must be Assignable, Copy Constructible, and the
expression <ttclass="literal"><spanclass="pre">f(x)</span></tt> must be valid, where <ttclass="literal"><spanclass="pre">f</span></tt> is an object of type
<ttclass="literal"><spanclass="pre">UnaryFunction</span></tt> and <ttclass="literal"><spanclass="pre">x</span></tt> is an object of a type accepted by <ttclass="literal"><spanclass="pre">f</span></tt>.
The resulting <ttclass="literal"><spanclass="pre">function_output_iterator</span></tt> is a model of the Writable
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">function_output_iterator</span></tt> with
<ttclass="literal"><spanclass="pre">f</span></tt> stored as a data member.</td>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">output_proxy</span></tt> constructed with
a copy of the unary function <ttclass="literal"><spanclass="pre">f</span></tt>.</td>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">output_proxy</span></tt> with <ttclass="literal"><spanclass="pre">f</span></tt> stored as
Generated by <aclass="reference"href="http://docutils.sourceforge.net/">Docutils</a> from <aclass="reference"href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
