<?xml version="1.0" encoding="utf-8" ?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<meta name="generator" content="Docutils 0.3.1: http://docutils.sourceforge.net/" />

<title>Iterator Facade and Adaptor</title>

<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />

<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />

<meta name="date" content="2003-09-22" />

<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />

<style type="text/css"><!--



/*

:Author: David Goodger

:Contact: goodger@users.sourceforge.net

:date: $Date: 2003/07/07 14:19:05 $

:version: $Revision: 1.1 $

:copyright: This stylesheet has been placed in the public domain.



Default cascading style sheet for the HTML output of Docutils.

*/



.first {

  margin-top: 0 }



.last {

  margin-bottom: 0 }



a.toc-backref {

  text-decoration: none ;

  color: black }



dd {

  margin-bottom: 0.5em }



div.abstract {

  margin: 2em 5em }



div.abstract p.topic-title {

  font-weight: bold ;

  text-align: center }



div.attention, div.caution, div.danger, div.error, div.hint,

div.important, div.note, div.tip, div.warning {

  margin: 2em ;

  border: medium outset ;

  padding: 1em }



div.attention p.admonition-title, div.caution p.admonition-title,

div.danger p.admonition-title, div.error p.admonition-title,

div.warning p.admonition-title {

  color: red ;

  font-weight: bold ;

  font-family: sans-serif }



div.hint p.admonition-title, div.important p.admonition-title,

div.note p.admonition-title, div.tip p.admonition-title {

  font-weight: bold ;

  font-family: sans-serif }



div.dedication {

  margin: 2em 5em ;

  text-align: center ;

  font-style: italic }



div.dedication p.topic-title {

  font-weight: bold ;

  font-style: normal }



div.figure {

  margin-left: 2em }



div.footer, div.header {

  font-size: smaller }



div.system-messages {

  margin: 5em }



div.system-messages h1 {

  color: red }



div.system-message {

  border: medium outset ;

  padding: 1em }



div.system-message p.system-message-title {

  color: red ;

  font-weight: bold }



div.topic {

  margin: 2em }



h1.title {

  text-align: center }



h2.subtitle {

  text-align: center }



hr {

  width: 75% }



ol.simple, ul.simple {

  margin-bottom: 1em }



ol.arabic {

  list-style: decimal }



ol.loweralpha {

  list-style: lower-alpha }



ol.upperalpha {

  list-style: upper-alpha }



ol.lowerroman {

  list-style: lower-roman }



ol.upperroman {

  list-style: upper-roman }



p.caption {

  font-style: italic }



p.credits {

  font-style: italic ;

  font-size: smaller }



p.label {

  white-space: nowrap }



p.topic-title {

  font-weight: bold }



pre.address {

  margin-bottom: 0 ;

  margin-top: 0 ;

  font-family: serif ;

  font-size: 100% }



pre.line-block {

  font-family: serif ;

  font-size: 100% }



pre.literal-block, pre.doctest-block {

  margin-left: 2em ;

  margin-right: 2em ;

  background-color: #eeeeee }



span.classifier {

  font-family: sans-serif ;

  font-style: oblique }



span.classifier-delimiter {

  font-family: sans-serif ;

  font-weight: bold }



span.interpreted {

  font-family: sans-serif }



span.option-argument {

  font-style: italic }



span.pre {

  white-space: pre }



span.problematic {

  color: red }



table {

  margin-top: 0.5em ;

  margin-bottom: 0.5em }



table.citation {

  border-left: solid thin gray ;

  padding-left: 0.5ex }



table.docinfo {

  margin: 2em 4em }



table.footnote {

  border-left: solid thin black ;

  padding-left: 0.5ex }



td, th {

  padding-left: 0.5em ;

  padding-right: 0.5em ;

  vertical-align: top }



th.docinfo-name, th.field-name {

  font-weight: bold ;

  text-align: left ;

  white-space: nowrap }



h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {

  font-size: 100% }



tt {

  background-color: #eeeeee }



ul.auto-toc {

  list-style-type: none }



--></style>

</head>

<body>

<div class="document" id="iterator-facade-and-adaptor">

<h1 class="title">Iterator Facade and Adaptor</h1>

<table class="docinfo" frame="void" rules="none">

<col class="docinfo-name" />

<col class="docinfo-content" />

<tbody valign="top">

<tr><th class="docinfo-name">Author:</th>

<td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>

<tr><th class="docinfo-name">Contact:</th>

<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;acm.org">witt&#64;acm.org</a></td></tr>

<tr><th class="docinfo-name">Organization:</th>

<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems

Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for Transport

Railway Operation and Construction</a></td></tr>

<tr><th class="docinfo-name">Date:</th>

<td>2003-09-22</td></tr>

<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">N1530=03-0113</td>

</tr>

<tr><th class="docinfo-name">Copyright:</th>

<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr>

</tbody>

</table>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">abstract:</th><td class="field-body">We propose a set of class templates that help programmers

build standard-conforming iterators, both from scratch and

by adapting other iterators.</td>

</tr>

</tbody>

</table>

<div class="contents topic" id="table-of-contents">

<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>

<ul class="simple">

<li><a class="reference" href="#motivation" id="id17" name="id17">Motivation</a></li>

<li><a class="reference" href="#impact-on-the-standard" id="id18" name="id18">Impact on the Standard</a></li>

<li><a class="reference" href="#design" id="id19" name="id19">Design</a><ul>

<li><a class="reference" href="#iterator-concepts" id="id20" name="id20">Iterator Concepts</a></li>

<li><a class="reference" href="#interoperability" id="id21" name="id21">Interoperability</a></li>

<li><a class="reference" href="#iterator-facade" id="id22" name="id22">Iterator Facade</a><ul>

<li><a class="reference" href="#usage" id="id23" name="id23">Usage</a></li>

<li><a class="reference" href="#iterator-core-access" id="id24" name="id24">Iterator Core Access</a></li>

<li><a class="reference" href="#operator" id="id25" name="id25"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>

<li><a class="reference" href="#id7" id="id26" name="id26"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li>

</ul>

</li>

<li><a class="reference" href="#iterator-adaptor" id="id27" name="id27">Iterator Adaptor</a></li>

<li><a class="reference" href="#specialized-adaptors" id="id28" name="id28">Specialized Adaptors</a></li>

</ul>

</li>

<li><a class="reference" href="#proposed-text" id="id29" name="id29">Proposed Text</a><ul>

<li><a class="reference" href="#header-iterator-helper-synopsis-lib-iterator-helper-synopsis" id="id30" name="id30">Header <tt class="literal"><span class="pre">&lt;iterator_helper&gt;</span></tt> synopsis    [lib.iterator.helper.synopsis]</a></li>

<li><a class="reference" href="#iterator-facade-lib-iterator-facade" id="id31" name="id31">Iterator facade [lib.iterator.facade]</a><ul>

<li><a class="reference" href="#class-template-iterator-facade" id="id32" name="id32">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul>

<li><a class="reference" href="#id13" id="id33" name="id33"><tt class="literal"><span class="pre">iterator_facade</span></tt> requirements</a></li>

<li><a class="reference" href="#iterator-facade-operations" id="id34" name="id34"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>

</ul>

</li>

</ul>

</li>

<li><a class="reference" href="#iterator-adaptor-lib-iterator-adaptor" id="id35" name="id35">Iterator adaptor [lib.iterator.adaptor]</a><ul>

<li><a class="reference" href="#class-template-iterator-adaptor" id="id36" name="id36">Class template <tt class="literal"><span class="pre">iterator_adaptor</span></tt></a></li>

<li><a class="reference" href="#iterator-adaptor-requirements" id="id37" name="id37"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></li>

<li><a class="reference" href="#iterator-adaptor-public-operations" id="id38" name="id38"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></li>

<li><a class="reference" href="#iterator-adaptor-protected-member-functions" id="id39" name="id39"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></li>

<li><a class="reference" href="#iterator-adaptor-private-member-functions" id="id40" name="id40"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></li>

</ul>

</li>

<li><a class="reference" href="#specialized-adaptors-lib-iterator-special-adaptors" id="id41" name="id41">Specialized adaptors [lib.iterator.special.adaptors]</a><ul>

<li><a class="reference" href="#indirect-iterator" id="id42" name="id42">Indirect iterator</a><ul>

<li><a class="reference" href="#class-template-indirect-iterator" id="id43" name="id43">Class template <tt class="literal"><span class="pre">indirect_iterator</span></tt></a></li>

<li><a class="reference" href="#indirect-iterator-requirements" id="id44" name="id44"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></li>

<li><a class="reference" href="#indirect-iterator-operations" id="id45" name="id45"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></li>

</ul>

</li>

<li><a class="reference" href="#reverse-iterator" id="id46" name="id46">Reverse iterator</a><ul>

<li><a class="reference" href="#class-template-reverse-iterator" id="id47" name="id47">Class template <tt class="literal"><span class="pre">reverse_iterator</span></tt></a></li>

<li><a class="reference" href="#reverse-iterator-requirements" id="id48" name="id48"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></li>

</ul>

</li>

<li><a class="reference" href="#transform-iterator" id="id49" name="id49">Transform iterator</a><ul>

<li><a class="reference" href="#class-template-transform-iterator" id="id50" name="id50">Class template <tt class="literal"><span class="pre">transform_iterator</span></tt></a></li>

<li><a class="reference" href="#transform-iterator-requirements" id="id51" name="id51"><tt class="literal"><span class="pre">transform_iterator</span></tt> requirements</a></li>

<li><a class="reference" href="#transform-iterator-public-operations" id="id52" name="id52"><tt class="literal"><span class="pre">transform_iterator</span></tt> public operations</a></li>

<li><a class="reference" href="#transform-iterator-private-operations" id="id53" name="id53"><tt class="literal"><span class="pre">transform_iterator</span></tt> private operations</a></li>

</ul>

</li>

<li><a class="reference" href="#filter-iterator" id="id54" name="id54">Filter iterator</a><ul>

<li><a class="reference" href="#class-template-filter-iterator" id="id55" name="id55">Class template <tt class="literal"><span class="pre">filter_iterator</span></tt></a></li>

</ul>

</li>

<li><a class="reference" href="#filter-iterator-requirements" id="id56" name="id56"><tt class="literal"><span class="pre">filter_iterator</span></tt> requirements</a></li>

<li><a class="reference" href="#filter-iterator-operations" id="id57" name="id57"><tt class="literal"><span class="pre">filter_iterator</span></tt> operations</a></li>

<li><a class="reference" href="#id16" id="id58" name="id58">Counting iterator</a><ul>

<li><a class="reference" href="#class-template-counting-iterator" id="id59" name="id59">Class template <tt class="literal"><span class="pre">counting_iterator</span></tt></a></li>

</ul>

</li>

<li><a class="reference" href="#counting-iterator-requirements" id="id60" name="id60"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>

<li><a class="reference" href="#counting-iterator-operations" id="id61" name="id61"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></li>

<li><a class="reference" href="#function-output-iterator" id="id62" name="id62">Function output iterator</a><ul>

<li><a class="reference" href="#class-template-function-output-iterator" id="id63" name="id63">Class template <tt class="literal"><span class="pre">function_output_iterator</span></tt></a></li>

</ul>

</li>

<li><a class="reference" href="#function-output-iterator-requirements" id="id64" name="id64"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></li>

<li><a class="reference" href="#function-output-iterator-operations" id="id65" name="id65"><tt class="literal"><span class="pre">function_output_iterator</span></tt> operations</a></li>

<li><a class="reference" href="#function-output-iterator-output-proxy-operations" id="id66" name="id66"><tt class="literal"><span class="pre">function_output_iterator::output_proxy</span></tt> operations</a></li>

</ul>

</li>

</ul>

</li>

</ul>

</div>

<div class="section" id="motivation">

<h1><a class="toc-backref" href="#id17" name="motivation">Motivation</a></h1>

<p>Iterators play an important role in modern C++ programming. The

iterator is the central abstraction of the algorithms of the Standard

Library, allowing algorithms to be re-used in in a wide variety of

contexts.  The C++ Standard Library contains a wide variety of useful

iterators. Every one of the standard containers comes with constant

and mutable iterators <a class="footnote-reference" href="#mutable" id="id1" name="id1"><sup>2</sup></a>, and also reverse versions of those

same iterators which traverse the container in the opposite direction.

The Standard also supplies <tt class="literal"><span class="pre">istream_iterator</span></tt> and

<tt class="literal"><span class="pre">ostream_iterator</span></tt> for reading from and writing to streams,

<tt class="literal"><span class="pre">insert_iterator</span></tt>, <tt class="literal"><span class="pre">front_insert_iterator</span></tt> and

<tt class="literal"><span class="pre">back_insert_iterator</span></tt> for inserting elements into containers, and

<tt class="literal"><span class="pre">raw_storage_iterator</span></tt> for initializing raw memory [7].</p>

<p>Despite the many iterators supplied by the Standard Library, obvious

and useful iterators are missing, and creating new iterator types is

still a common task for C++ programmers.  The literature documents

several of these, for example line_iterator [3] and Constant_iterator

[9].  The iterator abstraction is so powerful that we expect

programmers will always need to invent new iterator types.</p>

<p>Although it is easy to create iterators that <em>almost</em> conform to the

standard, the iterator requirements contain subtleties which can make

creating an iterator which <em>actually</em> conforms quite difficult.

Further, the iterator interface is rich, containing many operators

that are technically redundant and tedious to implement.  To automate

the repetitive work of constructing iterators, we propose

<tt class="literal"><span class="pre">iterator_facade</span></tt>, an iterator base class template which provides

the rich interface of standard iterators and delegates its

implementation to member functions of the derived class.  In addition

to reducing the amount of code necessary to create an iterator, the

<tt class="literal"><span class="pre">iterator_facade</span></tt> also provides compile-time error detection.

Iterator implementation mistakes that often go unnoticed are turned

into compile-time errors because the derived class implementation must

match the expectations of the <tt class="literal"><span class="pre">iterator_facade</span></tt>.</p>

<p>A common pattern of iterator construction is the adaptation of one

iterator to form a new one.  The functionality of an iterator is

composed of four orthogonal aspects: traversal, indirection, equality

comparison and distance measurement.  Adapting an old iterator to

create a new one often saves work because one can reuse one aspect of

functionality while redefining the other.  For example, the Standard

provides <tt class="literal"><span class="pre">reverse_iterator</span></tt>, which adapts any Bidirectional Iterator

by inverting its direction of traversal.  As with plain iterators,

iterator adaptors defined outside the Standard have become commonplace

in the literature:</p>

<ul class="simple">

<li>Checked iter[13] adds bounds-checking to an existing iterator.</li>

<li>The iterators of the View Template Library[14], which adapts

containers, are themselves adaptors over the underlying iterators.</li>

<li>Smart iterators [5] adapt an iterator's dereferencing behavior by

applying a function object to the object being referenced and

returning the result.</li>

<li>Custom iterators [4], in which a variety of adaptor types are enumerated.</li>

<li>Compound iterators [1], which access a slice out of a container of containers.</li>

<li>Several iterator adaptors from the MTL [12].  The MTL contains a

strided iterator, where each call to <tt class="literal"><span class="pre">operator++()</span></tt> moves the

iterator ahead by some constant factor, and a scaled iterator, which

multiplies the dereferenced value by some constant.</li>

</ul>

<table class="footnote" frame="void" id="concept" rules="none">

<colgroup><col class="label" /><col /></colgroup>

<tbody valign="top">

<tr><td class="label"><a name="concept">[1]</a></td><td>We use the term concept to mean a set of requirements

that a type must satisfy to be used with a particular template

parameter.</td></tr>

</tbody>

</table>

<table class="footnote" frame="void" id="mutable" rules="none">

<colgroup><col class="label" /><col /></colgroup>

<tbody valign="top">

<tr><td class="label"><a class="fn-backref" href="#id1" name="mutable">[2]</a></td><td>The term mutable iterator refers to iterators over objects that

can be changed by assigning to the dereferenced iterator, while

constant iterator refers to iterators over objects that cannot be

modified.</td></tr>

</tbody>

</table>

<p>To fulfill the need for constructing adaptors, we propose the

<tt class="literal"><span class="pre">iterator_adaptor</span></tt> class template.  Instantiations of

<tt class="literal"><span class="pre">iterator_adaptor</span></tt> serve as a base classes for new iterators,

providing the default behavior of forwarding all operations to the

underlying iterator.  The user can selectively replace these features

in the derived iterator class.  This proposal also includes a number

of more specialized adaptors, such as the <tt class="literal"><span class="pre">transform_iterator</span></tt> that

applies some user-specified function during the dereference of the

iterator.</p>

</div>

<div class="section" id="impact-on-the-standard">

<h1><a class="toc-backref" href="#id18" name="impact-on-the-standard">Impact on the Standard</a></h1>

<p>This proposal is purely an addition to the C++ standard library.

However, note that this proposal relies on the proposal for New

Iterator Concepts.</p>

</div>

<div class="section" id="design">

<h1><a class="toc-backref" href="#id19" name="design">Design</a></h1>

<div class="section" id="iterator-concepts">

<h2><a class="toc-backref" href="#id20" name="iterator-concepts">Iterator Concepts</a></h2>

<p>This proposal is formulated in terms of the new <tt class="literal"><span class="pre">iterator</span> <span class="pre">concepts</span></tt>

as proposed in <a class="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 <a class="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 <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html">n1477</a> was not accepted.</p>

</div>

<div class="section" id="interoperability">

<h2><a class="toc-backref" href="#id21" name="interoperability">Interoperability</a></h2>

<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 <a class="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

<a class="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 <a class="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>

</div>

<div class="section" id="iterator-facade">

<h2><a class="toc-backref" href="#id22" name="iterator-facade">Iterator Facade</a></h2>

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

<ul class="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:

<tt class="literal"><span class="pre">value_type</span></tt>, <tt class="literal"><span class="pre">reference</span></tt>, <tt class="literal"><span class="pre">difference_type</span></tt>, and

<tt class="literal"><span class="pre">iterator_category</span></tt>.</p>

<p>Iterator facade uses the Curiously Recurring Template Pattern (CRTP)

<a class="citation-reference" href="#cop95" id="id4" name="id4">[Cop95]</a> so that the user can specify the behavior of

<tt class="literal"><span class="pre">iterator_facade</span></tt> in a derived class.  Former designs used policy

objects to specify the behavior.  <tt class="literal"><span class="pre">iterator_facade</span></tt> does not use policy

objects for several reasons:</p>

<blockquote>

<ol class="arabic simple">

<li>the creation and eventual copying of the policy object may create

overhead that can be avoided with the current approach.</li>

<li>The policy object approach does not allow for custom constructors

on the created iterator types, an essential feature if

<tt class="literal"><span class="pre">iterator_facade</span></tt> should be used in other library

implementations.</li>

<li>Without the use of CRTP, the standard requirement that an

iterator's <tt class="literal"><span class="pre">operator++</span></tt> returns the iterator type itself means

that all iterators generated by <tt class="literal"><span class="pre">iterator_facade</span></tt> would be

instantiations of <tt class="literal"><span class="pre">iterator_facade</span></tt>.  Cumbersome type generator

metafunctions would be needed to build new parameterized

iterators, and a separate <tt class="literal"><span class="pre">iterator_adaptor</span></tt> layer would be

impossible.</li>

</ol>

</blockquote>

<div class="section" id="usage">

<h3><a class="toc-backref" href="#id23" name="usage">Usage</a></h3>

<p>The user of <tt class="literal"><span class="pre">iterator_facade</span></tt> derives his iterator class from an

instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt> which takes the derived iterator

class as the first template parameter.  The order of the other

template parameters to <tt class="literal"><span class="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 <tt class="literal"><span class="pre">value_type</span></tt> as <tt class="literal"><span class="pre">iterator_facade</span></tt>'s <tt class="literal"><span class="pre">Value</span></tt>

parameter and omit the <tt class="literal"><span class="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

briefly below and in more detail in the iterator facade

requirements.</p>

<blockquote>

<table border class="table">

<colgroup>

<col width="44%" />

<col width="56%" />

</colgroup>

<thead valign="bottom">

<tr><th>Expression</th>

<th>Effects</th>

</tr>

</thead>

<tbody valign="top">

<tr><td><tt class="literal"><span class="pre">i.dereference()</span></tt></td>

<td>Access the value referred to</td>

</tr>

<tr><td><tt class="literal"><span class="pre">i.equal(j)</span></tt></td>

<td>Compare for equality with <tt class="literal"><span class="pre">j</span></tt></td>

</tr>

<tr><td><tt class="literal"><span class="pre">i.increment()</span></tt></td>

<td>Advance by one position</td>

</tr>

<tr><td><tt class="literal"><span class="pre">i.decrement()</span></tt></td>

<td>Retreat by one position</td>

</tr>

<tr><td><tt class="literal"><span class="pre">i.advance(n)</span></tt></td>

<td>Advance by <tt class="literal"><span class="pre">n</span></tt> positions</td>

</tr>

<tr><td><tt class="literal"><span class="pre">i.distance_to(j)</span></tt></td>

<td>Measure the distance to <tt class="literal"><span class="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 <tt class="literal"><span class="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 <tt class="literal"><span class="pre">X</span></tt> is meant to be automatically interoperate with another

iterator type <tt class="literal"><span class="pre">Y</span></tt> (as with constant and mutable iterators) then

there must be an implicit conversion from <tt class="literal"><span class="pre">X</span></tt> to <tt class="literal"><span class="pre">Y</span></tt> or from <tt class="literal"><span class="pre">Y</span></tt>

to <tt class="literal"><span class="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

required.</p>

</div>

<div class="section" id="iterator-core-access">

<h3><a class="toc-backref" href="#id24" name="iterator-core-access">Iterator Core Access</a></h3>

<p><tt class="literal"><span class="pre">iterator_facade</span></tt> and the operator implementations need to be able

to access the core member functions in the derived class.  Making the

core member functions public would expose an implementation detail to

the user.  The design used here ensures that implementation details do

not appear in the public interface of the derived iterator type.</p>

<p>Preventing direct access to the core member functions has two

advantages.  First, there is no possibility for the user to accidently

use a member function of the iterator when a member of the value_type

was intended.  This has been an issue with smart pointer

implementations in the past.  The second and main advantage is that

library implementers can freely exchange a hand-rolled iterator

implementation for one based on <tt class="literal"><span class="pre">iterator_facade</span></tt> without fear of

breaking code that was accessing the public core member functions

directly.</p>

<p>In a naive implementation, keeping the derived class' core member

functions private would require it to grant friendship to

<tt class="literal"><span class="pre">iterator_facade</span></tt> and each of the seven operators.  In order to

reduce the burden of limiting access, <tt class="literal"><span class="pre">iterator_core_access</span></tt> is

provided, a class that acts as a gateway to the core member functions

in the derived iterator class.  The author of the derived class only

needs to grant friendship to <tt class="literal"><span class="pre">iterator_core_access</span></tt> to make his core

member functions available to the library.</p>

<!-- This is no long uptodate -thw  -->

<!-- Yes it is; I made sure of it! -DWA -->

<p><tt class="literal"><span class="pre">iterator_core_access</span></tt> will be typically implemented as an empty

class containing only private static member functions which invoke the

iterator core member functions. There is, however, no need to

standardize the gateway protocol.  Note that even if

<tt class="literal"><span class="pre">iterator_core_access</span></tt> used public member functions it would not

open a safety loophole, as every core member function preserves the

invariants of the iterator.</p>

</div>

<div class="section" id="operator">

<h3><a class="toc-backref" href="#id25" name="operator"><tt class="literal"><span class="pre">operator[]</span></tt></a></h3>

<p>The indexing operator for a generalized iterator presents special

challenges.  A random access iterator's <tt class="literal"><span class="pre">operator[]</span></tt> is only

required to return something convertible to its <tt class="literal"><span class="pre">value_type</span></tt>.

Requiring that it return an lvalue would rule out currently-legal

random-access iterators which hold the referenced value in a data

member (e.g. <a class="reference" href="counting_iterator.html">counting_iterator</a>), because <tt class="literal"><span class="pre">*(p+n)</span></tt> is a reference

into the temporary iterator <tt class="literal"><span class="pre">p+n</span></tt>, which is destroyed when

<tt class="literal"><span class="pre">operator[]</span></tt> returns.</p>

<p>Writable iterators built with <tt class="literal"><span class="pre">iterator_facade</span></tt> implement the

semantics required by the preferred resolution to <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299">issue 299</a> and

adopted by proposal <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html">n1477</a>: the result of <tt class="literal"><span class="pre">p[n]</span></tt> is a proxy object

containing a copy of <tt class="literal"><span class="pre">p+n</span></tt>, and <tt class="literal"><span class="pre">p[n]</span> <span class="pre">=</span> <span class="pre">x</span></tt> is equivalent to <tt class="literal"><span class="pre">*(p</span>

<span class="pre">+</span> <span class="pre">n)</span> <span class="pre">=</span> <span class="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 <tt class="literal"><span class="pre">operator[]</span></tt> which returns an lvalue in the derived

iterator class; it will hide the one supplied by <tt class="literal"><span class="pre">iterator_facade</span></tt>

from clients of her iterator.</p>

<a class="target" id="operator-arrow" name="operator-arrow"></a></div>

<div class="section" id="id7">

<h3><a class="toc-backref" href="#id26" name="id7"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></h3>

<p>The <tt class="literal"><span class="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 <tt class="literal"><span class="pre">value_type</span></tt>.  When the <tt class="literal"><span class="pre">value_type</span></tt>

is a class, however, it must still be possible to access members

through <tt class="literal"><span class="pre">operator-&gt;</span></tt>.  Therefore, an iterator whose <tt class="literal"><span class="pre">reference</span></tt>

type is not in fact a reference must return a proxy containing a copy

of the referenced value from its <tt class="literal"><span class="pre">operator-&gt;</span></tt>.</p>

<p>The return type for <tt class="literal"><span class="pre">operator-&gt;</span></tt> and <tt class="literal"><span class="pre">operator[]</span></tt> is not

explicitly specified. Instead it requires each <tt class="literal"><span class="pre">iterator_facade</span></tt>

instantiation to meet the requirements of its <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>

<table class="citation" frame="void" id="cop95" rules="none">

<colgroup><col class="label" /><col /></colgroup>

<col />

<tbody valign="top">

<tr><td class="label"><a class="fn-backref" href="#id4" name="cop95">[Cop95]</a></td><td>[Coplien, 1995] Coplien, J., Curiously Recurring Template

Patterns, C++ Report, February 1995, pp. 24-27.</td></tr>

</tbody>

</table>

</div>

</div>

<div class="section" id="iterator-adaptor">

<h2><a class="toc-backref" href="#id27" name="iterator-adaptor">Iterator Adaptor</a></h2>

<p>The <tt class="literal"><span class="pre">iterator_adaptor</span></tt> class template adapts some <tt class="literal"><span class="pre">Base</span></tt> <a class="footnote-reference" href="#base" id="id8" name="id8"><sup>3</sup></a>

type to create a new iterator.  Instantiations of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>

are derived from a corresponding instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt>

and implement the core behaviors in terms of the <tt class="literal"><span class="pre">Base</span></tt> type. In

essence, <tt class="literal"><span class="pre">iterator_adaptor</span></tt> merely forwards all operations to an

instance of the <tt class="literal"><span class="pre">Base</span></tt> type, which it stores as a member.</p>

<table class="footnote" frame="void" id="base" rules="none">

<colgroup><col class="label" /><col /></colgroup>

<tbody valign="top">

<tr><td class="label"><a class="fn-backref" href="#id8" name="base">[3]</a></td><td>The term &quot;Base&quot; 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 <tt class="literal"><span class="pre">reverse_iterator</span></tt> adaptor.</td></tr>

</tbody>

</table>

<p>The user of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> creates a class derived from an

instantiation of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> and then selectively

redefines some of the core member functions described in the table

above. The <tt class="literal"><span class="pre">Base</span></tt> type need not meet the full requirements for an

iterator. It need only support the operations used by the core

interface functions of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> that have not been

redefined in the user's derived class.</p>

<p>Several of the template parameters of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> default

to <tt class="literal"><span class="pre">use_default</span></tt> (or <tt class="literal"><span class="pre">use_default_access</span></tt>). 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

<tt class="literal"><span class="pre">use_default</span></tt> can help to simplify the implementation.  Finally,

the identity of the <tt class="literal"><span class="pre">use_default</span></tt> type is not left unspecified

because specification helps to highlight that the <tt class="literal"><span class="pre">Reference</span></tt>

template parameter may not always be identical to the iterator's

<tt class="literal"><span class="pre">reference</span></tt> type, and will keep users making mistakes based on

that assumption.</p>

</div>

<div class="section" id="specialized-adaptors">

<h2><a class="toc-backref" href="#id28" name="specialized-adaptors">Specialized Adaptors</a></h2>

<p>This proposal also contains several examples of specialized adaptors

which were easily implemented using <tt class="literal"><span class="pre">iterator_adaptor</span></tt>:</p>

<ul class="simple">

<li><tt class="literal"><span class="pre">indirect_iterator</span></tt>, which iterates over iterators, pointers,

or smart pointers and applies an extra level of dereferencing.</li>

<li>A new <tt class="literal"><span class="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><tt class="literal"><span class="pre">transform_iterator</span></tt>, which applies a user-defined function object

to the underlying values when dereferenced.</li>

<li><tt class="literal"><span class="pre">projection_iterator</span></tt>, which is similar to <tt class="literal"><span class="pre">transform_iterator</span></tt>

except that when dereferenced it returns a reference instead of

a value.</li>

<li><tt class="literal"><span class="pre">filter_iterator</span></tt>, which provides a view of an iterator range in

which some elements of the underlying range are skipped.</li>

</ul>

<a class="target" id="counting-iterator" name="counting-iterator"></a><ul class="simple">

<li><tt class="literal"><span class="pre">counting_iterator</span></tt>, which adapts any incrementable type

(e.g. integers, iterators) so that incrementing/decrementing the

adapted iterator and dereferencing it produces successive values of

the Base type.</li>

<li><tt class="literal"><span class="pre">function_output_iterator</span></tt>, which makes it easier to create custom

output iterators.</li>

</ul>

<p>Based on examples in the Boost library, users have generated many new

adaptors, among them a permutation adaptor which applies some

permutation to a random access iterator, and a strided adaptor, which

adapts a random access iterator by multiplying its unit of motion by a

constant factor.  In addition, the Boost Graph Library (BGL) uses

iterator adaptors to adapt other graph libraries, such as LEDA [10]

and Stanford GraphBase [8], to the BGL interface (which requires C++

Standard compliant iterators).</p>

</div>

</div>

<div class="section" id="proposed-text">

<h1><a class="toc-backref" href="#id29" name="proposed-text">Proposed Text</a></h1>

<div class="section" id="header-iterator-helper-synopsis-lib-iterator-helper-synopsis">

<h2><a class="toc-backref" href="#id30" name="header-iterator-helper-synopsis-lib-iterator-helper-synopsis">Header <tt class="literal"><span class="pre">&lt;iterator_helper&gt;</span></tt> synopsis    [lib.iterator.helper.synopsis]</a></h2>

<pre class="literal-block">

struct use_default;

const unsigned use_default_access = -1;



struct iterator_core_access { /* implementation detail */ };



template &lt;

    class Derived

  , class Value

  , unsigned AccessCategory

  , class TraversalCategory

  , class Reference  = Value&amp;

  , class Difference = ptrdiff_t

&gt;

class iterator_facade;



template &lt;

    class Derived

  , class Base

  , class Value      = use_default

  , unsigned Access  = use_default_access

  , class Traversal  = use_default

  , class Reference  = use_default

  , class Difference = use_default

&gt;

class iterator_adaptor;



template &lt;

    class Iterator

  , class Value = use_default

  , unsigned Access  = use_default_access

  , class Traversal  = use_default

  , class Reference = use_default

  , class Difference = use_default

&gt;

class indirect_iterator;



template &lt;class Iterator&gt;

class reverse_iterator;



template &lt;

    class UnaryFunction

  , class Iterator

  , class Reference = use_default

  , class Value = use_default

&gt;

class transform_iterator;



template &lt;class Predicate, class Iterator&gt;

class filter_iterator;



template &lt;

    class Incrementable

  , unsigned Access  = use_default_access

  , class Traversal  = use_default

  , class Difference = use_default

&gt;

class counting_iterator



template &lt;class UnaryFunction&gt;

class function_output_iterator;

</pre>

</div>

<div class="section" id="iterator-facade-lib-iterator-facade">

<h2><a class="toc-backref" href="#id31" name="iterator-facade-lib-iterator-facade">Iterator facade [lib.iterator.facade]</a></h2>

<p><tt class="literal"><span class="pre">iterator_facade</span></tt> is a base class template that implements the

interface of standard iterators in terms of a few core functions

and associated types, to be supplied by a derived iterator class.</p>

<div class="section" id="class-template-iterator-facade">

<h3><a class="toc-backref" href="#id32" name="class-template-iterator-facade">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a></h3>

<pre class="literal-block">

template &lt;

    class Derived

  , class Value

  , unsigned AccessCategory

  , class TraversalCategory

  , class Reference  = /* see <a class="reference" href="#iterator-facade-requirements">below</a> */

  , class Difference = ptrdiff_t

&gt;

class iterator_facade {

public:

    typedef remove_cv&lt;Value&gt;::type value_type;

    typedef Reference reference;

    typedef /* see <a class="reference" href="#operator-arrow">description of operator-&gt;</a> */ pointer;

    typedef Difference difference_type;

    typedef iterator_tag&lt;AccessCategory, TraversalCategory&gt; iterator_category;



    reference operator*() const;

    /* see <a class="reference" href="#operator-arrow">below</a> */ operator-&gt;() const;

    /* see <a class="reference" href="#brackets">below</a> */ operator[](difference_type n) const;

    Derived&amp; operator++();

    Derived operator++(int);

    Derived&amp; operator--();

    Derived operator--(int);

    Derived&amp; operator+=(difference_type n);

    Derived&amp; operator-=(difference_type n);

    Derived operator-(difference_type n) const;

};



// Comparison operators

template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,

          class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;

typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type // exposition

operator ==(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,

            iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);



template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,

          class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;

typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type

operator !=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,

            iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);



template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,

          class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;

typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type

operator &lt;(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,

           iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);



template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,

          class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;

typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type

operator &lt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,

            iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);



template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,

          class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;

typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type

operator &gt;(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,

           iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);



template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,

          class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;

typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type

operator &gt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,

            iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);



template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,

          class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;

typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type

operator &gt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,

            iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);



// Iterator difference

template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,

          class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;

typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type

operator -(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,

           iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);



// Iterator addition

template &lt;class Derived, class V, class AC, class TC, class R, class D&gt;

Derived operator+ (iterator_facade&lt;Derived, V, AC, TC, R, D&gt; const&amp;,

                   typename Derived::difference_type n)

</pre>

<p>[<em>Note:</em> The <tt class="literal"><span class="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 <tt class="literal"><span class="pre">Dr1</span></tt> and <tt class="literal"><span class="pre">Dr2</span></tt> are interoperable, by

which we mean they are convertible to each other.  The

<tt class="literal"><span class="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 -->

<a class="target" id="iterator-facade-requirements" name="iterator-facade-requirements"></a><div class="section" id="id13">

<h4><a class="toc-backref" href="#id33" name="id13"><tt class="literal"><span class="pre">iterator_facade</span></tt> requirements</a></h4>

<p>Some of the constraints on template parameters to

<tt class="literal"><span class="pre">iterator_facade</span></tt> are expressed in terms of resulting nested

types and should be viewed in the context of their impact on

<tt class="literal"><span class="pre">iterator_traits&lt;Derived&gt;</span></tt>.</p>

<p>The <tt class="literal"><span class="pre">Derived</span></tt> template parameter must be a class derived from

<tt class="literal"><span class="pre">iterator_facade</span></tt>.</p>

<p>The nested <tt class="literal"><span class="pre">::value_type</span></tt> type will be the same as

<tt class="literal"><span class="pre">remove_cv&lt;Value&gt;::type</span></tt>, so the <tt class="literal"><span class="pre">Value</span></tt> parameter must be

an (optionally <tt class="literal"><span class="pre">const</span></tt>-qualified) non-reference type.</p>

<p><tt class="literal"><span class="pre">AccessCategory</span></tt> must be an unsigned value which uses no more

bits than the greatest value of <tt class="literal"><span class="pre">iterator_access</span></tt>.</p>

<p>The nested <tt class="literal"><span class="pre">::reference</span></tt> will be the same as the <tt class="literal"><span class="pre">Reference</span></tt>

parameter; it must be a suitable reference type for the resulting

iterator.  The default for the <tt class="literal"><span class="pre">Reference</span></tt> parameter is

<tt class="literal"><span class="pre">Value&amp;</span></tt>.</p>

<p>The following table describes the other requirements on the

<tt class="literal"><span class="pre">Derived</span></tt> parameter.  Depending on the resulting iterator's

<tt class="literal"><span class="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 <tt class="literal"><span class="pre">iterator_core_access</span></tt>.</p>

<p>In the table below, <tt class="literal"><span class="pre">X</span></tt> is the derived iterator type, <tt class="literal"><span class="pre">a</span></tt> is an

object of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">b</span></tt> and <tt class="literal"><span class="pre">c</span></tt> are objects of type <tt class="literal"><span class="pre">const</span> <span class="pre">X</span></tt>,

<tt class="literal"><span class="pre">n</span></tt> is an object of <tt class="literal"><span class="pre">X::difference_type</span></tt>, <tt class="literal"><span class="pre">y</span></tt> is a constant

object of a single pass iterator type interoperable with X, and <tt class="literal"><span class="pre">z</span></tt>

is a constant object of a random access traversal iterator type

interoperable with <tt class="literal"><span class="pre">X</span></tt>.</p>

<table border class="table">

<colgroup>

<col width="19%" />

<col width="18%" />

<col width="36%" />

<col width="26%" />

</colgroup>

<thead valign="bottom">

<tr><th>Expression</th>

<th>Return Type</th>

<th>Assertion/Note</th>

<th>Required to implement

Iterator Concept(s)</th>

</tr>

</thead>

<tbody valign="top">

<tr><td><tt class="literal"><span class="pre">c.dereference()</span></tt></td>

<td><tt class="literal"><span class="pre">X::reference</span></tt></td>

<td>&nbsp;</td>

<td>Readable Iterator, Writable

Iterator</td>

</tr>

<tr><td><tt class="literal"><span class="pre">c.equal(b)</span></tt></td>

<td>convertible to bool</td>

<td>true iff <tt class="literal"><span class="pre">b</span></tt> and <tt class="literal"><span class="pre">c</span></tt> are

equivalent.</td>

<td>Single Pass Iterator</td>

</tr>

<tr><td><tt class="literal"><span class="pre">c.equal(y)</span></tt></td>

<td>convertible to bool</td>

<td>true iff <tt class="literal"><span class="pre">c</span></tt> and <tt class="literal"><span class="pre">y</span></tt> refer to the

same position.  Implements <tt class="literal"><span class="pre">c</span> <span class="pre">==</span> <span class="pre">y</span></tt>

and <tt class="literal"><span class="pre">c</span> <span class="pre">!=</span> <span class="pre">y</span></tt>.</td>

<td>Single Pass Iterator</td>

</tr>

<tr><td><tt class="literal"><span class="pre">a.advance(n)</span></tt></td>

<td>unused</td>

<td>&nbsp;</td>

<td>Random Access Traversal

Iterator</td>

</tr>

<tr><td><tt class="literal"><span class="pre">a.increment()</span></tt></td>

<td>unused</td>

<td>&nbsp;</td>

<td>Incrementable Iterator</td>

</tr>

<tr><td><tt class="literal"><span class="pre">a.decrement()</span></tt></td>

<td>unused</td>

<td>&nbsp;</td>

<td>Bidirectional Traversal

Iterator</td>

</tr>

<tr><td><tt class="literal"><span class="pre">c.distance_to(b)</span></tt></td>

<td>convertible to

X::difference_type</td>

<td>equivalent to <tt class="literal"><span class="pre">distance(c,</span> <span class="pre">b)</span></tt></td>

<td>Random Access Traversal

Iterator</td>

</tr>

<tr><td><tt class="literal"><span class="pre">c.distance_to(z)</span></tt></td>

<td>convertible to

X::difference_type</td>

<td>equivalent to <tt class="literal"><span class="pre">distance(c,</span> <span class="pre">z)</span></tt>.

Implements <tt class="literal"><span class="pre">c</span> <span class="pre">-</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span> <span class="pre">&lt;</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span>

<span class="pre">&lt;=</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span> <span class="pre">&gt;</span> <span class="pre">z</span></tt>, and <tt class="literal"><span class="pre">c</span> <span class="pre">&gt;=</span> <span class="pre">c</span></tt>.</td>

<td>Random Access Traversal

Iterator</td>

</tr>

</tbody>

</table>

<!-- We should explain more about how the

functions in the interface of iterator_facade

are there conditionally. -JGS -->

</div>

<div class="section" id="iterator-facade-operations">

<h4><a class="toc-backref" href="#id34" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h4>

<p>The operations in this section are described in terms of operations on

the core interface of <tt class="literal"><span class="pre">Derived</span></tt> which may be inaccessible

(i.e. private).  The implementation should access these operations

through member functions of class <tt class="literal"><span class="pre">iterator_core_access</span></tt>.</p>

<p><tt class="literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">static_cast&lt;Derived</span> <span class="pre">const*&gt;(this)-&gt;dereference()</span></tt></td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">operator-&gt;()</span> <span class="pre">const;</span></tt> (see <a class="reference" href="#operator-arrow">below</a>)</p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">If <tt class="literal"><span class="pre">X::reference</span></tt> is a reference type, returns an object

of type <tt class="literal"><span class="pre">X::pointer</span></tt> equal to:</p>

<pre class="literal-block">

&amp;static_cast&lt;Derived const*&gt;(this)-&gt;dereference()

</pre>

<p>Otherwise returns an object of unspecified type such that, given an

object <tt class="literal"><span class="pre">a</span></tt> of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">a-&gt;m</span></tt> is equivalent to <tt class="literal"><span class="pre">(w</span> <span class="pre">=</span> <span class="pre">*a,</span>

<span class="pre">w.m)</span></tt> for some temporary object <tt class="literal"><span class="pre">w</span></tt> of type <tt class="literal"><span class="pre">X::value_type</span></tt>.</p>

<p class="last">The type <tt class="literal"><span class="pre">X::pointer</span></tt> is <tt class="literal"><span class="pre">Value*</span></tt> if

<tt class="literal"><span class="pre">is_writable_iterator&lt;X&gt;::value</span></tt> is <tt class="literal"><span class="pre">true</span></tt>, and

<tt class="literal"><span class="pre">Value</span> <span class="pre">const*</span></tt> otherwise.</p>

</td>

</tr>

</tbody>

</table>

<a class="target" id="brackets" name="brackets"></a><p><em>unspecified</em> <tt class="literal"><span class="pre">operator[](difference_type</span> <span class="pre">n)</span> <span class="pre">const;</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">an object convertible to <tt class="literal"><span class="pre">X::reference</span></tt> and holding a copy

<em>p</em> of <tt class="literal"><span class="pre">a+n</span></tt> such that, for a constant object <tt class="literal"><span class="pre">v</span></tt> of type

<tt class="literal"><span class="pre">X::value_type</span></tt>, <tt class="literal"><span class="pre">X::reference(a[n]</span> <span class="pre">=</span> <span class="pre">v)</span></tt> is equivalent

to <tt class="literal"><span class="pre">p</span> <span class="pre">=</span> <span class="pre">v</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">Derived&amp;</span> <span class="pre">operator++();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">

static_cast&lt;Derived*&gt;(this)-&gt;increment();

return *this;

</pre>

</td>

</tr>

</tbody>

</table>

<!-- I realize that the committee is moving away from specifying things

like this in terms of code, but I worried about the imprecision of

saying that a core interface function is invoked without describing

the downcast.  An alternative to what I did would be to mention it

above where we talk about accessibility. -->

<p><tt class="literal"><span class="pre">Derived</span> <span class="pre">operator++(int);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">

Derived tmp(static_cast&lt;Derived const*&gt;(this));

++*this;

return tmp;

</pre>

</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">Derived&amp;</span> <span class="pre">operator--();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">

static_cast&lt;Derived*&gt;(this)-&gt;decrement();

return *this;

</pre>

</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">Derived</span> <span class="pre">operator--(int);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">

Derived tmp(static_cast&lt;Derived const*&gt;(this));

--*this;

return tmp;

</pre>

</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">Derived&amp;</span> <span class="pre">operator+=(difference_type</span> <span class="pre">n);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">

static_cast&lt;Derived*&gt;(this)-&gt;advance(n);

return *this;

</pre>

</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">Derived&amp;</span> <span class="pre">operator-=(difference_type</span> <span class="pre">n);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">

static_cast&lt;Derived*&gt;(this)-&gt;advance(-n);

return *this;

</pre>

</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">Derived</span> <span class="pre">operator-(difference_type</span> <span class="pre">n)</span> <span class="pre">const;</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Derived tmp(static_cast&lt;Derived const*&gt;(this));

return tmp -= n;</td>

</tr>

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">static_cast&lt;Derived</span> <span class="pre">const*&gt;(this)-&gt;advance(-n);</span></tt></td>

</tr>

</tbody>

</table>

</div>

</div>

</div>

<div class="section" id="iterator-adaptor-lib-iterator-adaptor">

<h2><a class="toc-backref" href="#id35" name="iterator-adaptor-lib-iterator-adaptor">Iterator adaptor [lib.iterator.adaptor]</a></h2>

<p>The <tt class="literal"><span class="pre">iterator_adaptor</span></tt> is a base class template derived from an

instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt>. The core interface functions

expected by <tt class="literal"><span class="pre">iterator_facade</span></tt> are implemented in terms of the

<tt class="literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="literal"><span class="pre">Base</span></tt> template parameter. A class derived

from <tt class="literal"><span class="pre">iterator_adaptor</span></tt> typically redefines some of the core

interface functions to adapt the behavior of the <tt class="literal"><span class="pre">Base</span></tt> type.

Whether the derived class models any of the standard iterator concepts

depends on the operations supported by the <tt class="literal"><span class="pre">Base</span></tt> type and which

core interface functions of <tt class="literal"><span class="pre">iterator_facade</span></tt> are redefined in the

<tt class="literal"><span class="pre">Derived</span></tt> class.</p>

<div class="section" id="class-template-iterator-adaptor">

<h3><a class="toc-backref" href="#id36" name="class-template-iterator-adaptor">Class template <tt class="literal"><span class="pre">iterator_adaptor</span></tt></a></h3>

<pre class="literal-block">

bool

template &lt;

    class Derived

  , class Base

  , class Value      = use_default

  , unsigned Access  = use_default_access

  , class Traversal  = use_default

  , class Reference  = use_default

  , class Difference = use_default

&gt;

class iterator_adaptor 

  : public iterator_facade&lt;Derived, /* see <a class="reference" href=":">details</a> ...*/&gt;

{

    friend class iterator_core_access;

 public:

    iterator_adaptor();

    explicit iterator_adaptor(Base iter);

    Base base() const;

 protected:

    Base const&amp; base_reference() const;

    Base&amp; base_reference();

 private: // Core iterator interface for iterator_facade.  

    typename iterator_adaptor::reference dereference() const;



    template &lt;

    class OtherDerived, class OtherIterator, class V, class C, class R, class D

    &gt;   

    bool equal(iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; x) const;



    void advance(typename iterator_adaptor::difference_type n);

    void increment();

    void decrement();



    template &lt;

        class OtherDerived, class OtherIterator, class V, class C, class R, class D

    &gt;   

    typename iterator_adaptor::difference_type distance_to(

        iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; y) const;



 private:

    Base m_iterator;

};

</pre>

</div>

<div class="section" id="iterator-adaptor-requirements">

<h3><a class="toc-backref" href="#id37" name="iterator-adaptor-requirements"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></h3>

<p>The <tt class="literal"><span class="pre">Derived</span></tt> template parameter must be a derived class of

<tt class="literal"><span class="pre">iterator_adaptor</span></tt>. The <tt class="literal"><span class="pre">Base</span></tt> type must implement the

expressions involving <tt class="literal"><span class="pre">m_iterator</span></tt> in the specifications of those

private member functions of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> that are not

redefined by the <tt class="literal"><span class="pre">Derived</span></tt> class and that are needed to model the

concept corresponding to

<tt class="literal"><span class="pre">iterator_traits&lt;Derived&gt;::iterator_category</span></tt> according to the

requirements of <tt class="literal"><span class="pre">iterator_facade</span></tt>.  The rest of the template

parameters specify the types for the member typedefs in

<tt class="literal"><span class="pre">iterator_facade</span></tt>.  The following pseudo-code specifies the

traits types for <tt class="literal"><span class="pre">iterator_adaptor</span></tt>.</p>

<pre class="literal-block">

if (Value != use_default)

     value_type = remove_cv&lt;Value&gt;::type;

else

     value_type = iterator_traits&lt;Base&gt;::value_type;





if (Traversal != use_default)

    traversal_category = Traversal

else

    traversal_category = traversal_category&lt; Base &gt;::type



iterator_category = iterator_tag&lt;

                         access_category

                       , traversal_category

                     &gt;



if (Access != use_default)

{

   access_category = Access

}

else

{

   access_category

     = access_category&lt; Base &gt;::value



   if (is_const&lt;Value&gt;)

       access_category &amp;= ~writable_iterator;

}



iterator_category = iterator_tag&lt;

                         access_category

                       , traversal_category

                     &gt;



if (Reference != use_default)

    reference = Reference

else if (Value != use_default)

    reference = Value&amp;

else

    reference = iterator_traits&lt;Base&gt;::reference

</pre>

</div>

<div class="section" id="iterator-adaptor-public-operations">

<h3><a class="toc-backref" href="#id38" name="iterator-adaptor-public-operations"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></h3>

<p><tt class="literal"><span class="pre">iterator_adaptor();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Requires:</th><td class="field-body">The <tt class="literal"><span class="pre">Base</span></tt> type must be Default Constructible.</td>

</tr>

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> with 

<tt class="literal"><span class="pre">m_iterator</span></tt> default constructed.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">iterator_adaptor(Base</span> <span class="pre">iter);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> with

<tt class="literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="literal"><span class="pre">iter</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">Base</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_iterator</span></tt></td>

</tr>

</tbody>

</table>

</div>

<div class="section" id="iterator-adaptor-protected-member-functions">

<h3><a class="toc-backref" href="#id39" name="iterator-adaptor-protected-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h3>

<p><tt class="literal"><span class="pre">Base</span> <span class="pre">const&amp;</span> <span class="pre">base_reference()</span> <span class="pre">const;</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A const reference to <tt class="literal"><span class="pre">m_iterator</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">Base&amp;</span> <span class="pre">base_reference();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A non-const reference to <tt class="literal"><span class="pre">m_iterator</span></tt>.</td>

</tr>

</tbody>

</table>

</div>

<div class="section" id="iterator-adaptor-private-member-functions">

<h3><a class="toc-backref" href="#id40" name="iterator-adaptor-private-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></h3>

<p><tt class="literal"><span class="pre">typename</span> <span class="pre">iterator_adaptor::reference</span> <span class="pre">dereference()</span> <span class="pre">const;</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*m_iterator</span></tt></td>

</tr>

</tbody>

</table>

<pre class="literal-block">

template &lt;

class OtherDerived, class OtherIterator, class V, class C, class R, class D

&gt;   

bool equal(iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; x) const;

</pre>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_iterator</span> <span class="pre">==</span> <span class="pre">x.base()</span></tt></td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">void</span> <span class="pre">advance(typename</span> <span class="pre">iterator_adaptor::difference_type</span> <span class="pre">n);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="literal"><span class="pre">m_iterator</span> <span class="pre">+=</span> <span class="pre">n;</span></tt></td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">void</span> <span class="pre">increment();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="literal"><span class="pre">++m_iterator;</span></tt></td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">void</span> <span class="pre">decrement();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="literal"><span class="pre">--m_iterator;</span></tt></td>

</tr>

</tbody>

</table>

<pre class="literal-block">

template &lt;

    class OtherDerived, class OtherIterator, class V, class C, class R, class D

&gt;   

typename iterator_adaptor::difference_type distance_to(

    iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; y) const;

</pre>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">y.base()</span> <span class="pre">-</span> <span class="pre">m_iterator</span></tt></td>

</tr>

</tbody>

</table>

</div>

</div>

<div class="section" id="specialized-adaptors-lib-iterator-special-adaptors">

<h2><a class="toc-backref" href="#id41" name="specialized-adaptors-lib-iterator-special-adaptors">Specialized adaptors [lib.iterator.special.adaptors]</a></h2>

<!-- The requirements for all of these need to be written *much* more

formally -DWA -->

<p>[<em>Note:</em> The <tt class="literal"><span class="pre">enable_if_convertible&lt;X,Y&gt;::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 <tt class="literal"><span class="pre">X</span></tt> is implicitly convertible to an object of

type <tt class="literal"><span class="pre">Y</span></tt>.  The <tt class="literal"><span class="pre">enable_if_convertible</span></tt> approach uses SFINAE to

take the constructor out of the overload set when the types are not

implicitly convertible.]</p>

<div class="section" id="indirect-iterator">

<h3><a class="toc-backref" href="#id42" name="indirect-iterator">Indirect iterator</a></h3>

<p>The indirect iterator adapts an iterator by applying an <em>extra</em>

dereference inside of <tt class="literal"><span class="pre">operator*()</span></tt>. For example, this iterator

adaptor makes it possible to view a container of pointers

(e.g. <tt class="literal"><span class="pre">list&lt;foo*&gt;</span></tt>) as if it were a container of the pointed-to type

(e.g. <tt class="literal"><span class="pre">list&lt;foo&gt;</span></tt>) .</p>

<!-- At some point we should add the capability to handle

iterators over smart pointers, which the impl handles. -JGS -->

<div class="section" id="class-template-indirect-iterator">

<h4><a class="toc-backref" href="#id43" name="class-template-indirect-iterator">Class template <tt class="literal"><span class="pre">indirect_iterator</span></tt></a></h4>

<pre class="literal-block">

template &lt;

    class Iterator

  , class Value = use_default

  , unsigned Access  = use_default_access

  , class Traversal  = use_default

  , class Reference = use_default

  , class Difference = use_default

&gt;

class indirect_iterator

  : public iterator_adaptor&lt;/* see discussion */&gt;

{

    friend class iterator_core_access;

 public:

    indirect_iterator();

    indirect_iterator(Iterator x);

    template &lt;

        class Iterator2, class Value2, unsigned Access2, class Traversal2

      , class Reference2, class Difference2

    &gt;

    indirect_iterator(

        indirect_iterator&lt;

             Iterator2, Value2, Access2, Traversal2, Reference2, Difference2

        &gt; const&amp; y

      , typename enable_if_convertible&lt;Iterator2, Iterator&gt;::type* = 0 // exposition

    );

private: // as-if specification

    typename indirect_iterator::reference dereference() const

    {

        return **this-&gt;base();

    }

};

</pre>

</div>

<div class="section" id="indirect-iterator-requirements">

<h4><a class="toc-backref" href="#id44" name="indirect-iterator-requirements"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></h4>

<p>The <tt class="literal"><span class="pre">value_type</span></tt> of the <tt class="literal"><span class="pre">Iterator</span></tt> template parameter should

itself be dereferenceable. The return type of the <tt class="literal"><span class="pre">operator*</span></tt> for

the <tt class="literal"><span class="pre">value_type</span></tt> must be the same type as the <tt class="literal"><span class="pre">Reference</span></tt> template

parameter. The <tt class="literal"><span class="pre">Value</span></tt> template parameter will be the <tt class="literal"><span class="pre">value_type</span></tt>

for the <tt class="literal"><span class="pre">indirect_iterator</span></tt>, unless <tt class="literal"><span class="pre">Value</span></tt> is const. If <tt class="literal"><span class="pre">Value</span></tt>

is <tt class="literal"><span class="pre">const</span> <span class="pre">X</span></tt>, then <tt class="literal"><span class="pre">value_type</span></tt> will be <em>non-</em> <tt class="literal"><span class="pre">const</span> <span class="pre">X</span></tt>.  The

default for <tt class="literal"><span class="pre">Value</span></tt> is</p>

<pre class="literal-block">

iterator_traits&lt; iterator_traits&lt;Iterator&gt;::value_type &gt;::value_type

</pre>

<p>If the default is used for <tt class="literal"><span class="pre">Value</span></tt>, then there must be a valid

specialization of <tt class="literal"><span class="pre">iterator_traits</span></tt> for the value type of the base

iterator.</p>

<p>The <tt class="literal"><span class="pre">Reference</span></tt> parameter will be the <tt class="literal"><span class="pre">reference</span></tt> type of the

<tt class="literal"><span class="pre">indirect_iterator</span></tt>. The default is <tt class="literal"><span class="pre">Value&amp;</span></tt>.</p>

<p>The <tt class="literal"><span class="pre">Access</span></tt> and <tt class="literal"><span class="pre">Traversal</span></tt> parameters are passed unchanged to

the corresponding parameters of the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> base

class, and  the <tt class="literal"><span class="pre">Iterator</span></tt> parameter is passed unchanged as the

<tt class="literal"><span class="pre">Base</span></tt> parameter to the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class.</p>

<p>The indirect iterator will model the most refined standard traversal

concept that is modeled by the <tt class="literal"><span class="pre">Iterator</span></tt> type.  The indirect

iterator will model the most refined standard access concept that is

modeled by the value type of <tt class="literal"><span class="pre">Iterator</span></tt>.</p>

</div>

<div class="section" id="indirect-iterator-operations">

<h4><a class="toc-backref" href="#id45" name="indirect-iterator-operations"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></h4>

<p><tt class="literal"><span class="pre">indirect_iterator();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>

</tr>

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">indirect_iterator</span></tt> with

a default constructed base object.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">indirect_iterator(Iterator</span> <span class="pre">x);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">indirect_iterator</span></tt> with

the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> subobject copy constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>

</tr>

</tbody>

</table>

<pre class="literal-block">

template &lt;

    class Iterator2, class Value2, unsigned Access, class Traversal

  , class Reference2, class Difference2

&gt;

indirect_iterator(

    indirect_iterator&lt;

         Iterator2, Value2, Access, Traversal, Reference2, Difference2

    &gt; const&amp; y

  , typename enable_if_convertible&lt;Iterator2, Iterator&gt;::type* = 0 // exposition

);

</pre>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Iterator2</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">Iterator</span></tt>.</td>

</tr>

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">indirect_iterator</span></tt> that is a copy of <tt class="literal"><span class="pre">y</span></tt>.</td>

</tr>

</tbody>

</table>

</div>

</div>

<div class="section" id="reverse-iterator">

<h3><a class="toc-backref" href="#id46" name="reverse-iterator">Reverse iterator</a></h3>

<!-- I think we'd better strike the old reverse_iterator text from the standard, eh? -->

<p>The reverse iterator adaptor flips the direction of a base iterator's

motion. Invoking <tt class="literal"><span class="pre">operator++()</span></tt> moves the base iterator backward and

invoking <tt class="literal"><span class="pre">operator--()</span></tt> moves the base iterator forward.</p>

<div class="section" id="class-template-reverse-iterator">

<h4><a class="toc-backref" href="#id47" name="class-template-reverse-iterator">Class template <tt class="literal"><span class="pre">reverse_iterator</span></tt></a></h4>

<pre class="literal-block">

template &lt;class Iterator&gt;

class reverse_iterator :

  public iterator_adaptor&lt; reverse_iterator&lt;Iterator&gt;, Iterator &gt;

{

  friend class iterator_core_access;

public:

  reverse_iterator() {}

  explicit reverse_iterator(Iterator x) ;



  template&lt;class OtherIterator&gt;

  reverse_iterator(

      reverse_iterator&lt;OtherIterator&gt; const&amp; r

    , typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition

  );



private: // as-if specification

  typename reverse_iterator::reference dereference() const { return *prior(this-&gt;base()); }



  void increment() { --this-&gt;base_reference(); }

  void decrement() { ++this-&gt;base_reference(); }



  void advance(typename reverse_iterator::difference_type n)

  {

      this-&gt;base_reference() += -n;

  }



  template &lt;class OtherIterator&gt;

  typename reverse_iterator::difference_type

  distance_to(reverse_iterator&lt;OtherIterator&gt; const&amp; y) const

  {

      return this-&gt;base_reference() - y.base();

  }



};

</pre>

</div>

<div class="section" id="reverse-iterator-requirements">

<h4><a class="toc-backref" href="#id48" name="reverse-iterator-requirements"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></h4>

<p>The base <tt class="literal"><span class="pre">Iterator</span></tt> must be a model of Bidirectional Traversal

Iterator. The resulting <tt class="literal"><span class="pre">reverse_iterator</span></tt> will be a model of the

most refined standard traversal and access concepts that are modeled

by <tt class="literal"><span class="pre">Iterator</span></tt>.</p>

<p><tt class="literal"><span class="pre">reverse_iterator();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>

</tr>

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">reverse_iterator</span></tt> with a

default constructed base object.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">reverse_iterator(Iterator</span> <span class="pre">x);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">reverse_iterator</span></tt> with a

base object copy constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>

</tr>

</tbody>

</table>

<pre class="literal-block">

template&lt;class OtherIterator&gt;

reverse_iterator(

    reverse_iterator&lt;OtherIterator&gt; const&amp; r

  , typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition

);

</pre>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">Iterator</span></tt>.</td>

</tr>

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">reverse_iterator</span></tt> that is a copy of <tt class="literal"><span class="pre">r</span></tt>.</td>

</tr>

</tbody>

</table>

</div>

</div>

<div class="section" id="transform-iterator">

<h3><a class="toc-backref" href="#id49" name="transform-iterator">Transform iterator</a></h3>

<p>The transform iterator adapts an iterator by applying some function

object to the result of dereferencing the iterator. In other words,

the <tt class="literal"><span class="pre">operator*</span></tt> of the transform iterator first dereferences the

base iterator, passes the result of this to the function object, and

then returns the result.</p>

<div class="section" id="class-template-transform-iterator">

<h4><a class="toc-backref" href="#id50" name="class-template-transform-iterator">Class template <tt class="literal"><span class="pre">transform_iterator</span></tt></a></h4>

<pre class="literal-block">

template &lt;class UnaryFunction,

          class Iterator, 

          class Reference = use_default, 

          class Value = use_default&gt;

class transform_iterator

  : public iterator_adaptor&lt;/* see discussion */&gt;

{

  friend class iterator_core_access;

public:

  transform_iterator();

  transform_iterator(Iterator const&amp; x, UnaryFunction f);



  template&lt;class OtherIterator, class R2, class V2&gt;

  transform_iterator(

        transform_iterator&lt;UnaryFunction, OtherIterator, R2, V2&gt; const&amp; t

      , typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition

  );



  UnaryFunction functor() const;

private:

  typename transform_iterator::value_type dereference() const;

  UnaryFunction m_f;

};

</pre>

</div>

<div class="section" id="transform-iterator-requirements">

<h4><a class="toc-backref" href="#id51" name="transform-iterator-requirements"><tt class="literal"><span class="pre">transform_iterator</span></tt> requirements</a></h4>

<p>The type <tt class="literal"><span class="pre">UnaryFunction</span></tt> must be Assignable, Copy Constructible, and

the expression <tt class="literal"><span class="pre">f(*i)</span></tt> must be valid where <tt class="literal"><span class="pre">f</span></tt> is an object of

type <tt class="literal"><span class="pre">UnaryFunction</span></tt>, <tt class="literal"><span class="pre">i</span></tt> is an object of type <tt class="literal"><span class="pre">Iterator</span></tt>, and

where the type of <tt class="literal"><span class="pre">f(*i)</span></tt> must be

<tt class="literal"><span class="pre">result_of&lt;UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt>.</p>

<p>The type <tt class="literal"><span class="pre">Iterator</span></tt> must at least model Readable Iterator.  The

resulting <tt class="literal"><span class="pre">transform_iterator</span></tt> models the most refined of the

following options that is also modeled by <tt class="literal"><span class="pre">Iterator</span></tt>.</p>

<blockquote>

<ul class="simple">

<li>Writable Lvalue Iterator if <tt class="literal"><span class="pre">result_of&lt;UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt> is a non-const reference.</li>

<li>Readable Lvalue Iterator if <tt class="literal"><span class="pre">result_of&lt;UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt> is a const

reference.</li>

<li>Readable Iterator otherwise.</li>

</ul>

</blockquote>

<p>The <tt class="literal"><span class="pre">transform_iterator</span></tt> models the most refined standard traversal

concept that is modeled by <tt class="literal"><span class="pre">Iterator</span></tt>.</p>

<p>The <tt class="literal"><span class="pre">reference</span></tt> type of <tt class="literal"><span class="pre">transform_iterator</span></tt> is

<tt class="literal"><span class="pre">result_of&lt;UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt>.

The <tt class="literal"><span class="pre">value_type</span></tt> is <tt class="literal"><span class="pre">remove_cv&lt;remove_reference&lt;reference&gt;</span> <span class="pre">&gt;::type</span></tt>.</p>

</div>

<div class="section" id="transform-iterator-public-operations">

<h4><a class="toc-backref" href="#id52" name="transform-iterator-public-operations"><tt class="literal"><span class="pre">transform_iterator</span></tt> public operations</a></h4>

<p><tt class="literal"><span class="pre">transform_iterator();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">transform_iterator</span></tt> with <tt class="literal"><span class="pre">m_f</span></tt>

and <tt class="literal"><span class="pre">m_iterator</span></tt> default constructed.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">transform_iterator(Iterator</span> <span class="pre">const&amp;</span> <span class="pre">x,</span> <span class="pre">UnaryFunction</span> <span class="pre">f);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">transform_iterator</span></tt> with <tt class="literal"><span class="pre">m_f</span></tt>

initialized to <tt class="literal"><span class="pre">f</span></tt> and <tt class="literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="literal"><span class="pre">x</span></tt>.</td>

</tr>

</tbody>

</table>

<pre class="literal-block">

template&lt;class OtherIterator, class R2, class V2&gt;

transform_iterator(

      transform_iterator&lt;UnaryFunction, OtherIterator, R2, V2&gt; const&amp; t

    , typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition

);

</pre>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">transform_iterator</span></tt> that is a copy of <tt class="literal"><span class="pre">t</span></tt>.</td>

</tr>

<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">Iterator</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">UnaryFunction</span> <span class="pre">functor()</span> <span class="pre">const;</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_f</span></tt></td>

</tr>

</tbody>

</table>

</div>

<div class="section" id="transform-iterator-private-operations">

<h4><a class="toc-backref" href="#id53" name="transform-iterator-private-operations"><tt class="literal"><span class="pre">transform_iterator</span></tt> private operations</a></h4>

<p><tt class="literal"><span class="pre">typename</span> <span class="pre">transform_iterator::value_type</span> <span class="pre">dereference()</span> <span class="pre">const;</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_f(transform_iterator::dereference());</span></tt></td>

</tr>

</tbody>

</table>

</div>

</div>

<div class="section" id="filter-iterator">

<h3><a class="toc-backref" href="#id54" name="filter-iterator">Filter iterator</a></h3>

<p>The filter iterator adaptor creates a view of an iterator range in

which some elements of the range are skipped over. A predicate

function object controls which elements are skipped. When the

predicate is applied to an element, if it returns <tt class="literal"><span class="pre">true</span></tt> then the

element is retained and if it returns <tt class="literal"><span class="pre">false</span></tt> then the element is

skipped over. When skipping over elements, it is necessary for the

filter adaptor to know when to stop so as to avoid going past the end

of the underlying range. Therefore the constructor of the filter

iterator takes two iterator parameters: the position for the filtered

iterator and the end of the range.</p>

<div class="section" id="class-template-filter-iterator">

<h4><a class="toc-backref" href="#id55" name="class-template-filter-iterator">Class template <tt class="literal"><span class="pre">filter_iterator</span></tt></a></h4>

<pre class="literal-block">

template &lt;class Predicate, class Iterator&gt;

class filter_iterator

    : public iterator_adaptor&lt;

          filter_iterator&lt;Predicate, Iterator&gt;, Iterator

        , use_default

        , /* see details */

      &gt;

{

 public:

    filter_iterator();

    filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());

    filter_iterator(Iterator x, Iterator end = Iterator());

    template&lt;class OtherIterator&gt;

    filter_iterator(

        filter_iterator&lt;Predicate, OtherIterator&gt; const&amp; t

        , typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition

        );

    Predicate predicate() const;

    Iterator end() const;



 private: // as-if specification

    void increment()

    {

        ++(this-&gt;base_reference());

        satisfy_predicate();

    }



    void satisfy_predicate()

    {

        while (this-&gt;base() != this-&gt;m_end &amp;&amp; !this-&gt;m_predicate(*this-&gt;base()))

            ++(this-&gt;base_reference());

    }



    Predicate m_predicate;

    Iterator m_end;

};

</pre>

</div>

</div>

<div class="section" id="filter-iterator-requirements">

<h3><a class="toc-backref" href="#id56" name="filter-iterator-requirements"><tt class="literal"><span class="pre">filter_iterator</span></tt> requirements</a></h3>

<p>The base <tt class="literal"><span class="pre">Iterator</span></tt> parameter must be a model of Readable

Iterator and Single Pass Iterator. The resulting

<tt class="literal"><span class="pre">filter_iterator</span></tt> will be a model of Forward Traversal Iterator

if <tt class="literal"><span class="pre">Iterator</span></tt> is, otherwise the <tt class="literal"><span class="pre">filter_iterator</span></tt> will be a

model of Single Pass Iterator. The access category of the

<tt class="literal"><span class="pre">filter_iterator</span></tt> will be the same as the access category of

<tt class="literal"><span class="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 <tt class="literal"><span class="pre">Predicate</span></tt> must be Assignable, Copy Constructible, and the

expression <tt class="literal"><span class="pre">p(x)</span></tt> must be valid where <tt class="literal"><span class="pre">p</span></tt> is an object of type

<tt class="literal"><span class="pre">Predicate</span></tt>, <tt class="literal"><span class="pre">x</span></tt> is an object of type

<tt class="literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>, and where the type of

<tt class="literal"><span class="pre">p(x)</span></tt> must be convertible to <tt class="literal"><span class="pre">bool</span></tt>.</p>

</div>

<div class="section" id="filter-iterator-operations">

<h3><a class="toc-backref" href="#id57" name="filter-iterator-operations"><tt class="literal"><span class="pre">filter_iterator</span></tt> operations</a></h3>

<p><tt class="literal"><span class="pre">filter_iterator();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Predicate</span></tt> and <tt class="literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>

</tr>

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">a <tt class="literal"><span class="pre">filter_iterator</span></tt> whose

predicate is a default constructed <tt class="literal"><span class="pre">Predicate</span></tt> and

whose <tt class="literal"><span class="pre">end</span></tt> is a default constructed <tt class="literal"><span class="pre">Iterator</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">filter_iterator(Predicate</span> <span class="pre">f,</span> <span class="pre">Iterator</span> <span class="pre">x,</span> <span class="pre">Iterator</span> <span class="pre">end</span> <span class="pre">=</span> <span class="pre">Iterator());</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A <tt class="literal"><span class="pre">filter_iterator</span></tt> at position <tt class="literal"><span class="pre">x</span></tt> that filters according

to predicate <tt class="literal"><span class="pre">f</span></tt> and that will not increment past <tt class="literal"><span class="pre">end</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">filter_iterator(Iterator</span> <span class="pre">x,</span> <span class="pre">Iterator</span> <span class="pre">end</span> <span class="pre">=</span> <span class="pre">Iterator());</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Predicate</span></tt> must be Default Constructible.</td>

</tr>

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A <tt class="literal"><span class="pre">filter_iterator</span></tt> at position <tt class="literal"><span class="pre">x</span></tt> that filters 

according to a default constructed <tt class="literal"><span class="pre">Predicate</span></tt>

and that will not increment past <tt class="literal"><span class="pre">end</span></tt>.</td>

</tr>

</tbody>

</table>

<pre class="literal-block">

template &lt;class OtherIterator&gt;

filter_iterator(

    filter_iterator&lt;Predicate, OtherIterator&gt; const&amp; t

    , typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition

    );``

</pre>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">Iterator</span></tt>.</td>

</tr>

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A copy of iterator <tt class="literal"><span class="pre">t</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">Predicate</span> <span class="pre">predicate()</span> <span class="pre">const;</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A copy of the predicate object used to construct <tt class="literal"><span class="pre">*this</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">end()</span> <span class="pre">const;</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">The object <tt class="literal"><span class="pre">end</span></tt> used to construct <tt class="literal"><span class="pre">*this</span></tt>.</td>

</tr>

</tbody>

</table>

</div>

<div class="section" id="id16">

<h3><a class="toc-backref" href="#id58" name="id16">Counting iterator</a></h3>

<p>The counting iterator adaptor implements dereference by returning a

reference to the base object. The other operations are implemented by

the base <tt class="literal"><span class="pre">m_iterator</span></tt>, as per the inheritance from

<tt class="literal"><span class="pre">iterator_adaptor</span></tt>.</p>

<div class="section" id="class-template-counting-iterator">

<h4><a class="toc-backref" href="#id59" name="class-template-counting-iterator">Class template <tt class="literal"><span class="pre">counting_iterator</span></tt></a></h4>

<pre class="literal-block">

template &lt;

    class Incrementable

  , unsigned Access = use_default_access

  , class Traversal = use_default

  , class Difference = use_default

&gt;

class counting_iterator

  : public iterator_adaptor&lt;

        counting_iterator&lt;Incrementable, Access, Traversal, Difference&gt;

      , Incrementable

      , Incrementable

      , Access

      , /* see details for traversal category */

      , Incrementable const&amp;

      , Incrementable const*

      , /* distance = Difference or a signed integral type */&gt;

{

    friend class iterator_core_access;

 public:

    counting_iterator();

    counting_iterator(counting_iterator const&amp; rhs);

    counting_iterator(Incrementable x);

 private:

    typename counting_iterator::reference dereference() const

    {

        return this-&gt;base_reference();

    }

  };

</pre>

<dl>

<dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt>

<dd><tt class="literal"><span class="pre">distance_to</span></tt> and a <tt class="literal"><span class="pre">difference_type</span></tt> that avoids overflows in

the cases when the <tt class="literal"><span class="pre">Incrementable</span></tt> type is a numeric type.]</dd>

</dl>

</div>

</div>

<div class="section" id="counting-iterator-requirements">

<h3><a class="toc-backref" href="#id60" name="counting-iterator-requirements"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></h3>

<p>The <tt class="literal"><span class="pre">Incrementable</span></tt> type must be Default Constructible, Copy

Constructible, and Assignable.  The default distance is

an implementation defined signed integegral type.</p>

<p>The resulting <tt class="literal"><span class="pre">counting_iterator</span></tt> models Readable Lvalue Iterator.</p>

<p>Furthermore, if you wish to create a counting iterator that is a Forward

Traversal Iterator, then the following expressions must be valid:</p>

<pre class="literal-block">

Incrementable i, j;

++i         // pre-increment

i == j      // operator equal

</pre>

<p>If you wish to create a counting iterator that is a 

Bidirectional Traversal Iterator, then pre-decrement is also required:</p>

<pre class="literal-block">

--i

</pre>

<p>If you wish to create a counting iterator that is a Random Access

Traversal Iterator, then these additional expressions are also

required:</p>

<pre class="literal-block">

counting_iterator::difference_type n;

i += n

n = i - j

i &lt; j

</pre>

</div>

<div class="section" id="counting-iterator-operations">

<h3><a class="toc-backref" href="#id61" name="counting-iterator-operations"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></h3>

<p><tt class="literal"><span class="pre">counting_iterator();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A default constructed instance of <tt class="literal"><span class="pre">counting_iterator</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">counting_iterator(counting_iterator</span> <span class="pre">const&amp;</span> <span class="pre">rhs);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">counting_iterator</span></tt> that is a copy of <tt class="literal"><span class="pre">rhs</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">counting_iterator(Incrementable</span> <span class="pre">x);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">counting_iterator</span></tt> with its base

object copy constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>

</tr>

</tbody>

</table>

</div>

<div class="section" id="function-output-iterator">

<h3><a class="toc-backref" href="#id62" name="function-output-iterator">Function output iterator</a></h3>

<p>The function output iterator adaptor makes it easier to create custom

output iterators. The adaptor takes a unary function and creates a

model of Output Iterator. Each item assigned to the output iterator is

passed as an argument to the unary function.  The motivation for this

iterator is that creating a conforming output iterator is non-trivial,

particularly because the proper implementation usually requires a

proxy object.</p>

<div class="section" id="class-template-function-output-iterator">

<h4><a class="toc-backref" href="#id63" name="class-template-function-output-iterator">Class template <tt class="literal"><span class="pre">function_output_iterator</span></tt></a></h4>

<pre class="literal-block">

template &lt;class UnaryFunction&gt;

class function_output_iterator {

public:

  typedef iterator_tag&lt;

        writable_iterator

      , incrementable_traversal_tag

  &gt; iterator_category;

  typedef void                value_type;

  typedef void                difference_type;

  typedef void                pointer;

  typedef void                reference;



  explicit function_output_iterator(const UnaryFunction&amp; f = UnaryFunction());



  struct output_proxy {

    output_proxy(UnaryFunction&amp; f);

    template &lt;class T&gt; output_proxy&amp; operator=(const T&amp; value);

  };

  output_proxy operator*();

  function_output_iterator&amp; operator++();

  function_output_iterator&amp; operator++(int);

};

</pre>

</div>

</div>

<div class="section" id="function-output-iterator-requirements">

<h3><a class="toc-backref" href="#id64" name="function-output-iterator-requirements"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></h3>

<p>The <tt class="literal"><span class="pre">UnaryFunction</span></tt> must be Assignable, Copy Constructible, and the

expression <tt class="literal"><span class="pre">f(x)</span></tt> must be valid, where <tt class="literal"><span class="pre">f</span></tt> is an object of type

<tt class="literal"><span class="pre">UnaryFunction</span></tt> and <tt class="literal"><span class="pre">x</span></tt> is an object of a type accepted by <tt class="literal"><span class="pre">f</span></tt>.

The resulting <tt class="literal"><span class="pre">function_output_iterator</span></tt> is a model of the Writable

and Incrementable Iterator concepts.</p>

</div>

<div class="section" id="function-output-iterator-operations">

<h3><a class="toc-backref" href="#id65" name="function-output-iterator-operations"><tt class="literal"><span class="pre">function_output_iterator</span></tt> operations</a></h3>

<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">function_output_iterator(const</span> <span class="pre">UnaryFunction&amp;</span> <span class="pre">f</span> <span class="pre">=</span> <span class="pre">UnaryFunction());</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">function_output_iterator</span></tt> with

<tt class="literal"><span class="pre">f</span></tt> stored as a data member.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">output_proxy</span> <span class="pre">operator*();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">output_proxy</span></tt> constructed with

a copy of the unary function <tt class="literal"><span class="pre">f</span></tt>.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++(int);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>

</tr>

</tbody>

</table>

</div>

<div class="section" id="function-output-iterator-output-proxy-operations">

<h3><a class="toc-backref" href="#id66" name="function-output-iterator-output-proxy-operations"><tt class="literal"><span class="pre">function_output_iterator::output_proxy</span></tt> operations</a></h3>

<p><tt class="literal"><span class="pre">output_proxy(UnaryFunction&amp;</span> <span class="pre">f);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">output_proxy</span></tt> with <tt class="literal"><span class="pre">f</span></tt> stored as

a data member.</td>

</tr>

</tbody>

</table>

<p><tt class="literal"><span class="pre">template</span> <span class="pre">&lt;class</span> <span class="pre">T&gt;</span> <span class="pre">output_proxy&amp;</span> <span class="pre">operator=(const</span> <span class="pre">T&amp;</span> <span class="pre">value);</span></tt></p>

<table class="field-list" frame="void" rules="none">

<col class="field-name" />

<col class="field-body" />

<tbody valign="top">

<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">

m_f(value); 

return *this; 

</pre>

</td>

</tr>

</tbody>

</table>

<!-- LocalWords:  Abrahams Siek Witt istream ostream iter MTL strided interoperate

LocalWords:  CRTP metafunctions inlining lvalue JGS incrementable BGL LEDA cv

LocalWords:  GraphBase struct ptrdiff UnaryFunction const int typename bool pp

LocalWords:  lhs rhs SFINAE markup iff tmp OtherDerived OtherIterator DWA foo

LocalWords:  dereferenceable subobject AdaptableUnaryFunction impl pre ifdef'd

LocalWords:  OtherIncrementable Coplien -->

</div>

</div>

</div>

</div>

<hr class="footer" />

<div class="footer">

<a class="reference" href="facade-and-adaptor.rst">View document source</a>.

Generated on: 2003-09-22 16:48 UTC.

Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.

</div>

</body>

</html>

