mirror of
https://github.com/boostorg/iterator.git
synced 2025-05-11 13:33:56 +00:00
2142 lines
115 KiB
HTML
Executable File
2142 lines
115 KiB
HTML
Executable File
<?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-11-24" />
|
|
<style type="text/css"><!--
|
|
|
|
/*
|
|
:Author: David Goodger
|
|
:Contact: goodger@users.sourceforge.net
|
|
:date: $Date$
|
|
:version: $Revision$
|
|
: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@boost-consulting.com">dave@boost-consulting.com</a>, <a class="reference" href="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</a>, <a class="last reference" href="mailto:witt@acm.org">witt@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-11-24</td></tr>
|
|
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">This is a revised version of <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1530.html">N1530</a>=03-0113, which was
|
|
accepted for Technical Report 1 by the C++ standard
|
|
committee's library working group.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<!-- Version 1.9 of this ReStructuredText document corresponds to
|
|
n1530_, the paper accepted by the LWG. -->
|
|
<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">copyright:</th><td class="field-body">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="id13" name="id13">Motivation</a></li>
|
|
<li><a class="reference" href="#impact-on-the-standard" id="id14" name="id14">Impact on the Standard</a></li>
|
|
<li><a class="reference" href="#design" id="id15" name="id15">Design</a><ul>
|
|
<li><a class="reference" href="#iterator-concepts" id="id16" name="id16">Iterator Concepts</a></li>
|
|
<li><a class="reference" href="#interoperability" id="id17" name="id17">Interoperability</a></li>
|
|
<li><a class="reference" href="#iterator-facade" id="id18" name="id18">Iterator Facade</a><ul>
|
|
<li><a class="reference" href="#usage" id="id19" name="id19">Usage</a></li>
|
|
<li><a class="reference" href="#iterator-core-access" id="id20" name="id20">Iterator Core Access</a></li>
|
|
<li><a class="reference" href="#operator" id="id21" name="id21"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>
|
|
<li><a class="reference" href="#id6" id="id22" name="id22"><tt class="literal"><span class="pre">operator-></span></tt></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#iterator-adaptor" id="id23" name="id23">Iterator Adaptor</a></li>
|
|
<li><a class="reference" href="#specialized-adaptors" id="id24" name="id24">Specialized Adaptors</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#proposed-text" id="id25" name="id25">Proposed Text</a><ul>
|
|
<li><a class="reference" href="#header-iterator-helper-synopsis-lib-iterator-helper-synopsis" id="id26" name="id26">Header <tt class="literal"><span class="pre"><iterator_helper></span></tt> synopsis [lib.iterator.helper.synopsis]</a></li>
|
|
<li><a class="reference" href="#iterator-facade-lib-iterator-facade" id="id27" name="id27">Iterator facade [lib.iterator.facade]</a><ul>
|
|
<li><a class="reference" href="#class-template-iterator-facade" id="id28" name="id28">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul>
|
|
<li><a class="reference" href="#iterator-facade-usage" id="id29" name="id29"><tt class="literal"><span class="pre">iterator_facade</span></tt> usage</a></li>
|
|
<li><a class="reference" href="#iterator-facade-iterator-category" id="id30" name="id30"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></li>
|
|
<li><a class="reference" href="#iterator-facade-operations" id="id31" name="id31"><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="id32" name="id32">Iterator adaptor [lib.iterator.adaptor]</a><ul>
|
|
<li><a class="reference" href="#class-template-iterator-adaptor" id="id33" name="id33">Class template <tt class="literal"><span class="pre">iterator_adaptor</span></tt></a></li>
|
|
<li><a class="reference" href="#iterator-adaptor-base-class-parameters" id="id34" name="id34"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></li>
|
|
<li><a class="reference" href="#iterator-adaptor-usage" id="id35" name="id35"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> usage</a></li>
|
|
<li><a class="reference" href="#iterator-adaptor-public-operations" id="id36" name="id36"><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="id37" name="id37"><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="id38" name="id38"><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="id39" name="id39">Specialized adaptors [lib.iterator.special.adaptors]</a><ul>
|
|
<li><a class="reference" href="#indirect-iterator" id="id40" name="id40">Indirect iterator</a><ul>
|
|
<li><a class="reference" href="#class-template-indirect-iterator" id="id41" name="id41">Class template <tt class="literal"><span class="pre">indirect_iterator</span></tt></a></li>
|
|
<li><a class="reference" href="#indirect-iterator-requirements" id="id42" name="id42"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></li>
|
|
<li><a class="reference" href="#indirect-iterator-operations" id="id43" name="id43"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#reverse-iterator" id="id44" name="id44">Reverse iterator</a><ul>
|
|
<li><a class="reference" href="#class-template-reverse-iterator" id="id45" name="id45">Class template <tt class="literal"><span class="pre">reverse_iterator</span></tt></a></li>
|
|
<li><a class="reference" href="#reverse-iterator-requirements" id="id46" name="id46"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#transform-iterator" id="id47" name="id47">Transform iterator</a><ul>
|
|
<li><a class="reference" href="#class-template-transform-iterator" id="id48" name="id48">Class template <tt class="literal"><span class="pre">transform_iterator</span></tt></a></li>
|
|
<li><a class="reference" href="#transform-iterator-requirements" id="id49" name="id49"><tt class="literal"><span class="pre">transform_iterator</span></tt> requirements</a></li>
|
|
<li><a class="reference" href="#transform-iterator-public-operations" id="id50" name="id50"><tt class="literal"><span class="pre">transform_iterator</span></tt> public operations</a></li>
|
|
<li><a class="reference" href="#transform-iterator-private-operations" id="id51" name="id51"><tt class="literal"><span class="pre">transform_iterator</span></tt> private operations</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#filter-iterator" id="id52" name="id52">Filter iterator</a><ul>
|
|
<li><a class="reference" href="#class-template-filter-iterator" id="id53" name="id53">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="id54" name="id54"><tt class="literal"><span class="pre">filter_iterator</span></tt> requirements</a></li>
|
|
<li><a class="reference" href="#filter-iterator-operations" id="id55" name="id55"><tt class="literal"><span class="pre">filter_iterator</span></tt> operations</a></li>
|
|
<li><a class="reference" href="#counting-iterator" id="id56" name="id56">Counting iterator</a><ul>
|
|
<li><a class="reference" href="#class-template-counting-iterator" id="id57" name="id57">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="id58" name="id58"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
|
|
<li><a class="reference" href="#counting-iterator-operations" id="id59" name="id59"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
|
|
<li><a class="reference" href="#function-output-iterator" id="id60" name="id60">Function output iterator</a><ul>
|
|
<li><a class="reference" href="#class-template-function-output-iterator" id="id61" name="id61">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="id62" name="id62"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></li>
|
|
<li><a class="reference" href="#function-output-iterator-operations" id="id63" name="id63"><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="id64" name="id64"><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="#id13" 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="#id14" 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="#id15" name="design">Design</a></h1>
|
|
<div class="section" id="iterator-concepts">
|
|
<h2><a class="toc-backref" href="#id16" 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/n1550.html">n1550</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/n1550.html">n1550</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/n1550.html">n1550</a> was not accepted.</p>
|
|
</div>
|
|
<div class="section" id="interoperability">
|
|
<h2><a class="toc-backref" href="#id17" 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="#id18" name="iterator-facade">Iterator Facade</a></h2>
|
|
<!-- Version 1.1 of this ReStructuredText document corresponds to
|
|
n1530_, the paper accepted by the LWG for TR1. -->
|
|
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
|
|
rights reserved -->
|
|
<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
|
|
specializations 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="#id19" 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
|
|
specialization 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="#id20" 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="#id21" 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"><tt class="literal"><span class="pre">counting_iterator</span></tt></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/n1550.html">n1550</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="id6">
|
|
<h3><a class="toc-backref" href="#id22" name="id6"><tt class="literal"><span class="pre">operator-></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-></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-></span></tt>.</p>
|
|
<p>The return type for <tt class="literal"><span class="pre">operator-></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>
|
|
specialization 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="#id23" name="iterator-adaptor">Iterator Adaptor</a></h2>
|
|
<!-- Version 1.2 of this ReStructuredText document corresponds to
|
|
n1530_, the paper accepted by the LWG for TR1. -->
|
|
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
|
|
rights reserved -->
|
|
<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="id7" name="id7"><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="#id7" name="base">[3]</a></td><td>The term "Base" here does not refer to a base class and is
|
|
not meant to imply the use of derivation. We have followed the lead
|
|
of the standard library, which provides a base() function to access
|
|
the underlying iterator object of a <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>. 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 from making mistakes based on
|
|
that assumption.</p>
|
|
</div>
|
|
<div class="section" id="specialized-adaptors">
|
|
<h2><a class="toc-backref" href="#id24" 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" name="counting"></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="#id25" 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="#id26" name="header-iterator-helper-synopsis-lib-iterator-helper-synopsis">Header <tt class="literal"><span class="pre"><iterator_helper></span></tt> synopsis [lib.iterator.helper.synopsis]</a></h2>
|
|
<pre class="literal-block">
|
|
struct use_default;
|
|
|
|
struct iterator_core_access { /* implementation detail */ };
|
|
|
|
template <
|
|
class Derived
|
|
, class Value
|
|
, class CategoryOrTraversal
|
|
, class Reference = Value&
|
|
, class Difference = ptrdiff_t
|
|
>
|
|
class iterator_facade;
|
|
|
|
template <
|
|
class Derived
|
|
, class Base
|
|
, class Value = use_default
|
|
, class CategoryOrTraversal = use_default
|
|
, class Reference = use_default
|
|
, class Difference = use_default
|
|
>
|
|
class iterator_adaptor;
|
|
|
|
template <
|
|
class Iterator
|
|
, class Value = use_default
|
|
, class CategoryOrTraversal = use_default
|
|
, class Reference = use_default
|
|
, class Difference = use_default
|
|
>
|
|
class indirect_iterator;
|
|
|
|
template <class Iterator>
|
|
class reverse_iterator;
|
|
|
|
template <
|
|
class UnaryFunction
|
|
, class Iterator
|
|
, class Reference = use_default
|
|
, class Value = use_default
|
|
>
|
|
class transform_iterator;
|
|
|
|
template <class Predicate, class Iterator>
|
|
class filter_iterator;
|
|
|
|
template <
|
|
class Incrementable
|
|
, class CategoryOrTraversal = use_default
|
|
, class Difference = use_default
|
|
>
|
|
class counting_iterator
|
|
|
|
template <class UnaryFunction>
|
|
class function_output_iterator;
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="iterator-facade-lib-iterator-facade">
|
|
<h2><a class="toc-backref" href="#id27" 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="#id28" name="class-template-iterator-facade">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a></h3>
|
|
<!-- Version 1.3 of this ReStructuredText document corresponds to
|
|
n1530_, the paper accepted by the LWG for TR1. -->
|
|
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
|
|
rights reserved -->
|
|
<pre class="literal-block">
|
|
template <
|
|
class Derived
|
|
, class Value
|
|
, class CategoryOrTraversal
|
|
, class Reference = Value&
|
|
, class Difference = ptrdiff_t
|
|
>
|
|
class iterator_facade {
|
|
public:
|
|
typedef remove_const<Value>::type value_type;
|
|
typedef Reference reference;
|
|
typedef Value* pointer;
|
|
typedef Difference difference_type;
|
|
typedef /* see <a class="reference" href="#facade-iterator-category">below</a> */ iterator_category;
|
|
|
|
reference operator*() const;
|
|
/* see <a class="reference" href="#operator-arrow">below</a> */ operator->() const;
|
|
/* see <a class="reference" href="#brackets">below</a> */ operator[](difference_type n) const;
|
|
Derived& operator++();
|
|
Derived operator++(int);
|
|
Derived& operator--();
|
|
Derived operator--(int);
|
|
Derived& operator+=(difference_type n);
|
|
Derived& operator-=(difference_type n);
|
|
Derived operator-(difference_type n) const;
|
|
};
|
|
|
|
// Comparison operators
|
|
template <class Dr1, class V1, class TC1, class R1, class D1,
|
|
class Dr2, class V2, class TC2, class R2, class D2>
|
|
typename enable_if_interoperable<Dr1, Dr2, bool>::type // exposition
|
|
operator ==(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
|
|
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
|
|
|
|
template <class Dr1, class V1, class TC1, class R1, class D1,
|
|
class Dr2, class V2, class TC2, class R2, class D2>
|
|
typename enable_if_interoperable<Dr1, Dr2, bool>::type
|
|
operator !=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
|
|
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
|
|
|
|
template <class Dr1, class V1, class TC1, class R1, class D1,
|
|
class Dr2, class V2, class TC2, class R2, class D2>
|
|
typename enable_if_interoperable<Dr1, Dr2, bool>::type
|
|
operator <(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
|
|
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
|
|
|
|
template <class Dr1, class V1, class TC1, class R1, class D1,
|
|
class Dr2, class V2, class TC2, class R2, class D2>
|
|
typename enable_if_interoperable<Dr1, Dr2, bool>::type
|
|
operator <=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
|
|
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
|
|
|
|
template <class Dr1, class V1, class TC1, class R1, class D1,
|
|
class Dr2, class V2, class TC2, class R2, class D2>
|
|
typename enable_if_interoperable<Dr1, Dr2, bool>::type
|
|
operator >(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
|
|
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
|
|
|
|
template <class Dr1, class V1, class TC1, class R1, class D1,
|
|
class Dr2, class V2, class TC2, class R2, class D2>
|
|
typename enable_if_interoperable<Dr1, Dr2, bool>::type
|
|
operator >=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
|
|
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
|
|
|
|
template <class Dr1, class V1, class TC1, class R1, class D1,
|
|
class Dr2, class V2, class TC2, class R2, class D2>
|
|
typename enable_if_interoperable<Dr1, Dr2, bool>::type
|
|
operator >=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
|
|
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
|
|
|
|
// Iterator difference
|
|
template <class Dr1, class V1, class TC1, class R1, class D1,
|
|
class Dr2, class V2, class TC2, class R2, class D2>
|
|
typename enable_if_interoperable<Dr1, Dr2, bool>::type
|
|
operator -(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
|
|
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
|
|
|
|
// Iterator addition
|
|
template <class Derived, class V, class TC, class R, class D>
|
|
Derived operator+ (iterator_facade<Derived, V, TC, R, D> const&,
|
|
typename Derived::difference_type n)
|
|
</pre>
|
|
<p>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,
|
|
meaning that at least one of the types is convertible to the 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.
|
|
The operators should behave <em>as-if</em> <tt class="literal"><span class="pre">enable_if_interoperable</span></tt>
|
|
were defined to be:</p>
|
|
<pre class="literal-block">
|
|
template <bool, typename> enable_if_interoperable_impl
|
|
{};
|
|
|
|
template <typename T> enable_if_interoperable_impl<true,T>
|
|
{ typedef T type; };
|
|
|
|
template<typename Dr1, typename Dr2, typename T>
|
|
struct enable_if_interoperable
|
|
: enable_if_interoperable_impl<
|
|
is_convertible<Dr1,Dr2>::value || is_convertible<Dr2,Dr1>::value
|
|
, T
|
|
>
|
|
{};
|
|
</pre>
|
|
<div class="section" id="iterator-facade-usage">
|
|
<h4><a class="toc-backref" href="#id29" name="iterator-facade-usage"><tt class="literal"><span class="pre">iterator_facade</span></tt> usage</a></h4>
|
|
<p>The following table describes the typical valid expressions on
|
|
<tt class="literal"><span class="pre">iterator_facade</span></tt>'s <tt class="literal"><span class="pre">Derived</span></tt> parameter, depending on the
|
|
iterator concept(s) it will model. The operations in the first
|
|
column must be made 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">F</span></tt> is <tt class="literal"><span class="pre">iterator_facade<X,V,C,R,D></span></tt>, <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">F::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 <tt class="literal"><span class="pre">X</span></tt>, 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="21%" />
|
|
<col width="35%" />
|
|
<col width="25%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th>Expression</th>
|
|
<th>Return Type</th>
|
|
<th>Assertion/Note</th>
|
|
<th>Used 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">F::reference</span></tt></td>
|
|
<td> </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> </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> </td>
|
|
<td>Incrementable Iterator</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">a.decrement()</span></tt></td>
|
|
<td>unused</td>
|
|
<td> </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
|
|
<tt class="literal"><span class="pre">F::difference_type</span></tt></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
|
|
<tt class="literal"><span class="pre">F::difference_type</span></tt></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"><</span> <span class="pre">z</span></tt>, <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">></span> <span class="pre">z</span></tt>, and <tt class="literal"><span class="pre">c</span> <span class="pre">>=</span> <span class="pre">c</span></tt>.</td>
|
|
<td>Random Access Traversal
|
|
Iterator</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<a class="target" id="facade-iterator-category" name="facade-iterator-category"></a></div>
|
|
<div class="section" id="iterator-facade-iterator-category">
|
|
<h4><a class="toc-backref" href="#id30" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h4>
|
|
<p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">iterator_facade<X,V,R,C,D></span></tt>
|
|
is a type which satisfies the following conditions:</p>
|
|
<blockquote>
|
|
<ul>
|
|
<li><p class="first">if <tt class="literal"><span class="pre">C</span></tt> is convertible to <tt class="literal"><span class="pre">std::input_iterator_tag</span></tt> or
|
|
<tt class="literal"><span class="pre">C</span></tt> is convertible to <tt class="literal"><span class="pre">std::output_iterator_tag</span></tt>,
|
|
<tt class="literal"><span class="pre">iterator_category</span></tt> is the same as <tt class="literal"><span class="pre">C</span></tt>.</p>
|
|
</li>
|
|
<li><p class="first">Otherwise, if <tt class="literal"><span class="pre">C</span></tt> is not convertible to
|
|
<tt class="literal"><span class="pre">incrementable_traversal_tag</span></tt>, the program is ill-formed</p>
|
|
</li>
|
|
<li><p class="first">Otherwise:</p>
|
|
<ul>
|
|
<li><p class="first"><tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to the iterator
|
|
category tag or tags given by the following algorithm, and
|
|
not to any more-derived iterator category tag or tags:</p>
|
|
<pre class="literal-block">
|
|
if (R is a reference type
|
|
&& C is convertible to forward_traversal_tag)
|
|
{
|
|
if (C is convertible to random_access_traversal_tag)
|
|
return random_access_iterator_tag
|
|
else if (C is convertible to bidirectional_traversal_tag)
|
|
return bidirectional_iterator_tag
|
|
else
|
|
return forward_traversal_tag
|
|
}
|
|
else
|
|
{
|
|
if (C is convertible to single_pass_traversal_tag
|
|
&& R is convertible to V)
|
|
{
|
|
if (V is const)
|
|
return input_iterator_tag
|
|
else
|
|
return input_iterator_tag and output_iterator_tag
|
|
}
|
|
else
|
|
return output_iterator_tag
|
|
}
|
|
</pre>
|
|
</li>
|
|
<li><p class="first"><tt class="literal"><span class="pre">iterator_traversal<X>::type</span></tt> is convertible to the most
|
|
derived traversal tag type to which <tt class="literal"><span class="pre">C</span></tt> is also
|
|
convertible, and not to any more-derived traversal tag type.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</blockquote>
|
|
</div>
|
|
<div class="section" id="iterator-facade-operations">
|
|
<h4><a class="toc-backref" href="#id31" 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<Derived</span> <span class="pre">const*>(this)->dereference()</span></tt></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><tt class="literal"><span class="pre">operator->()</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">reference</span></tt> is a reference type, an object
|
|
of type <tt class="literal"><span class="pre">pointer</span></tt> equal to:</p>
|
|
<pre class="literal-block">
|
|
&static_cast<Derived const*>(this)->dereference()
|
|
</pre>
|
|
<p class="last">Otherwise returns an object of unspecified type such that,
|
|
<tt class="literal"><span class="pre">(*static_cast<Derived</span> <span class="pre">const*>(this))->m</span></tt> is equivalent to <tt class="literal"><span class="pre">(w</span> <span class="pre">=</span> <span class="pre">**static_cast<Derived</span> <span class="pre">const*>(this),</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">value_type</span></tt>.</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">reference</span></tt> and holding a copy
|
|
<em>p</em> of <tt class="literal"><span class="pre">*static_cast<Derived</span> <span class="pre">const*>(this)</span> <span class="pre">+</span> <span class="pre">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">value_type</span></tt>, <tt class="literal"><span class="pre">(*static_cast<Derived</span> <span class="pre">const*>(this))[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&</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<Derived*>(this)->increment();
|
|
return *static_cast<Derived*>(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<Derived const*>(this));
|
|
++*this;
|
|
return tmp;
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><tt class="literal"><span class="pre">Derived&</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<Derived*>(this)->decrement();
|
|
return static_cast<Derived*>(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<Derived const*>(this));
|
|
--*this;
|
|
return tmp;
|
|
</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></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<Derived*>(this)->advance(n);
|
|
return static_cast<Derived*>(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></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<Derived*>(this)->advance(-n);
|
|
return static_cast<Derived*>(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"><pre class="first last literal-block">
|
|
Derived tmp(static_cast<Derived const*>(this));
|
|
return tmp -= n;
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="iterator-adaptor-lib-iterator-adaptor">
|
|
<h2><a class="toc-backref" href="#id32" name="iterator-adaptor-lib-iterator-adaptor">Iterator adaptor [lib.iterator.adaptor]</a></h2>
|
|
<!-- Version 1.1 of this ReStructuredText document corresponds to
|
|
n1530_, the paper accepted by the LWG. -->
|
|
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
|
|
rights reserved -->
|
|
<p>Each specialization of the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> class template is derived from
|
|
a specialization 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="#id33" name="class-template-iterator-adaptor">Class template <tt class="literal"><span class="pre">iterator_adaptor</span></tt></a></h3>
|
|
<!-- Version 1.4 of this ReStructuredText document corresponds to
|
|
n1530_, the paper accepted by the LWG for TR1. -->
|
|
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
|
|
rights reserved. -->
|
|
<pre class="literal-block">
|
|
template <
|
|
class Derived
|
|
, class Base
|
|
, class Value = use_default
|
|
, class CategoryOrTraversal = use_default
|
|
, class Reference = use_default
|
|
, class Difference = use_default
|
|
>
|
|
class iterator_adaptor
|
|
: public iterator_facade<Derived, <em>V</em>, <em>C</em>, <em>R</em>, <em>D</em>> // see <a class="reference" href="#base-parameters">details</a>
|
|
{
|
|
friend class iterator_core_access;
|
|
public:
|
|
iterator_adaptor();
|
|
explicit iterator_adaptor(Base iter);
|
|
Base base() const;
|
|
protected:
|
|
Base const& base_reference() const;
|
|
Base& base_reference();
|
|
private: // Core iterator interface for iterator_facade.
|
|
typename iterator_adaptor::reference dereference() const;
|
|
|
|
template <
|
|
class OtherDerived, class OtherIterator, class V, class C, class R, class D
|
|
>
|
|
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
|
|
|
|
void advance(typename iterator_adaptor::difference_type n);
|
|
void increment();
|
|
void decrement();
|
|
|
|
template <
|
|
class OtherDerived, class OtherIterator, class V, class C, class R, class D
|
|
>
|
|
typename iterator_adaptor::difference_type distance_to(
|
|
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
|
|
|
|
private:
|
|
Base m_iterator; // exposition only
|
|
};
|
|
</pre>
|
|
<a class="target" id="base-parameters" name="base-parameters"></a></div>
|
|
<div class="section" id="iterator-adaptor-base-class-parameters">
|
|
<h3><a class="toc-backref" href="#id34" name="iterator-adaptor-base-class-parameters"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></h3>
|
|
<p>The <em>V</em>, <em>C</em>, <em>R</em>, and <em>D</em> parameters of the <tt class="literal"><span class="pre">iterator_facade</span></tt>
|
|
used as a base class in the summary of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>
|
|
above are defined as follows:</p>
|
|
<pre class="literal-block">
|
|
<em>V</em> = if (Value is use_default)
|
|
return iterator_traits<Base>::value_type
|
|
else
|
|
return Value
|
|
|
|
<em>C</em> = if (CategoryOrTraversal is use_default)
|
|
return iterator_traversal<Base>::type
|
|
else
|
|
return CategoryOrTraversal
|
|
|
|
<em>R</em> = if (Reference is use_default)
|
|
if (Value is use_default)
|
|
return iterator_traits<Base>::reference
|
|
else
|
|
return Value&
|
|
else
|
|
return Reference
|
|
|
|
<em>D</em> = if (Difference is use_default)
|
|
return iterator_traits<Base>::difference_type
|
|
else
|
|
return Difference
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="iterator-adaptor-usage">
|
|
<h3><a class="toc-backref" href="#id35" name="iterator-adaptor-usage"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> usage</a></h3>
|
|
<p>The <tt class="literal"><span class="pre">Derived</span></tt> template parameter must be a publicly derived from
|
|
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>. In order for <tt class="literal"><span class="pre">Derived</span></tt> to model the
|
|
iterator concepts corresponding to
|
|
<tt class="literal"><span class="pre">iterator_traits<Derived>::iterator_category</span></tt>, 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 may be called by
|
|
<tt class="literal"><span class="pre">iterator_facade<Derived,</span> <span class="pre">``\</span> <span class="pre">*V*\</span></tt>, <tt class="literal"><span class="pre">\</span> <span class="pre">*C*\</span></tt>, <tt class="literal"><span class="pre">\</span> <span class="pre">*R*\</span></tt>, <tt class="literal"><span class="pre">\</span>
|
|
<span class="pre">*D*\</span></tt>>`` in evaluating any valid expression involving <tt class="literal"><span class="pre">Derived</span></tt>
|
|
in those concepts' requirements.</p>
|
|
</div>
|
|
<div class="section" id="iterator-adaptor-public-operations">
|
|
<h3><a class="toc-backref" href="#id36" 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="#id37" 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&</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&</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="#id38" 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 <
|
|
class OtherDerived, class OtherIterator, class V, class C, class R, class D
|
|
>
|
|
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
|
|
</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 <
|
|
class OtherDerived, class OtherIterator, class V, class C, class R, class D
|
|
>
|
|
typename iterator_adaptor::difference_type distance_to(
|
|
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
|
|
</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="#id39" name="specialized-adaptors-lib-iterator-special-adaptors">Specialized adaptors [lib.iterator.special.adaptors]</a></h2>
|
|
<p>The <tt class="literal"><span class="pre">enable_if_convertible<X,Y>::type</span></tt> expression used in
|
|
this section is for exposition purposes. The converting constructors
|
|
for specialized adaptors should be only be in an overload set provided
|
|
that an object of type <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 signatures involving <tt class="literal"><span class="pre">enable_if_convertible</span></tt> should behave
|
|
<em>as-if</em> <tt class="literal"><span class="pre">enable_if_convertible</span></tt> were defined to be:</p>
|
|
<pre class="literal-block">
|
|
template <bool> enable_if_convertible_impl
|
|
{};
|
|
|
|
template <> enable_if_convertible_impl<true>
|
|
{ struct type; };
|
|
|
|
template<typename From, typename To>
|
|
struct enable_if_convertible
|
|
: enable_if_convertible_impl<is_convertible<From,To>::value>
|
|
{};
|
|
</pre>
|
|
<p>If an expression other than the default argument is used to supply
|
|
the value of a function parameter whose type is written in terms
|
|
of <tt class="literal"><span class="pre">enable_if_convertible</span></tt>, the program is ill-formed, no
|
|
diagnostic required.</p>
|
|
<p>[<em>Note:</em> 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="#id40" 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<foo*></span></tt>) as if it were a container of the pointed-to type
|
|
(e.g. <tt class="literal"><span class="pre">list<foo></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="#id41" name="class-template-indirect-iterator">Class template <tt class="literal"><span class="pre">indirect_iterator</span></tt></a></h4>
|
|
<pre class="literal-block">
|
|
template <
|
|
class Iterator
|
|
, class Value = use_default
|
|
, unsigned Access = use_default_access
|
|
, class Traversal = use_default
|
|
, class Reference = use_default
|
|
, class Difference = use_default
|
|
>
|
|
class indirect_iterator
|
|
: public iterator_adaptor</* see discussion */>
|
|
{
|
|
friend class iterator_core_access;
|
|
public:
|
|
indirect_iterator();
|
|
indirect_iterator(Iterator x);
|
|
template <
|
|
class Iterator2, class Value2, unsigned Access2, class Traversal2
|
|
, class Reference2, class Difference2
|
|
>
|
|
indirect_iterator(
|
|
indirect_iterator<
|
|
Iterator2, Value2, Access2, Traversal2, Reference2, Difference2
|
|
> const& y
|
|
, typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
|
|
);
|
|
private: // as-if specification
|
|
typename indirect_iterator::reference dereference() const
|
|
{
|
|
return **this->base();
|
|
}
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="indirect-iterator-requirements">
|
|
<h4><a class="toc-backref" href="#id42" 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< iterator_traits<Iterator>::value_type >::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&</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="#id43" 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 <
|
|
class Iterator2, class Value2, unsigned Access, class Traversal
|
|
, class Reference2, class Difference2
|
|
>
|
|
indirect_iterator(
|
|
indirect_iterator<
|
|
Iterator2, Value2, Access, Traversal, Reference2, Difference2
|
|
> const& y
|
|
, typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
|
|
);
|
|
</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="#id44" 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="#id45" name="class-template-reverse-iterator">Class template <tt class="literal"><span class="pre">reverse_iterator</span></tt></a></h4>
|
|
<pre class="literal-block">
|
|
template <class Iterator>
|
|
class reverse_iterator :
|
|
public iterator_adaptor< reverse_iterator<Iterator>, Iterator >
|
|
{
|
|
friend class iterator_core_access;
|
|
public:
|
|
reverse_iterator() {}
|
|
explicit reverse_iterator(Iterator x) ;
|
|
|
|
template<class OtherIterator>
|
|
reverse_iterator(
|
|
reverse_iterator<OtherIterator> const& r
|
|
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
|
|
);
|
|
|
|
private: // as-if specification
|
|
typename reverse_iterator::reference dereference() const { return *prior(this->base()); }
|
|
|
|
void increment() { --this->base_reference(); }
|
|
void decrement() { ++this->base_reference(); }
|
|
|
|
void advance(typename reverse_iterator::difference_type n)
|
|
{
|
|
this->base_reference() += -n;
|
|
}
|
|
|
|
template <class OtherIterator>
|
|
typename reverse_iterator::difference_type
|
|
distance_to(reverse_iterator<OtherIterator> const& y) const
|
|
{
|
|
return this->base_reference() - y.base();
|
|
}
|
|
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="reverse-iterator-requirements">
|
|
<h4><a class="toc-backref" href="#id46" 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<class OtherIterator>
|
|
reverse_iterator(
|
|
reverse_iterator<OtherIterator> const& r
|
|
, typename enable_if_convertible<OtherIterator, Iterator>::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="#id47" 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="#id48" name="class-template-transform-iterator">Class template <tt class="literal"><span class="pre">transform_iterator</span></tt></a></h4>
|
|
<!-- Version 1.3 of this document was accepted for TR1 -->
|
|
<pre class="literal-block">
|
|
template <class UnaryFunction,
|
|
class Iterator,
|
|
class Reference = use_default,
|
|
class Value = use_default>
|
|
class transform_iterator
|
|
: public iterator_adaptor</* see discussion */>
|
|
{
|
|
friend class iterator_core_access;
|
|
public:
|
|
transform_iterator();
|
|
transform_iterator(Iterator const& x, UnaryFunction f);
|
|
|
|
template<class F2, class I2, class R2, class V2>
|
|
transform_iterator(
|
|
transform_iterator<F2, I2, R2, V2> const& t
|
|
, typename enable_if_convertible<I2, Iterator>::type* = 0 // exposition
|
|
, typename enable_if_convertible<F2, UnaryFunction>::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="#id49" 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<UnaryFunction(iterator_traits<Iterator>::reference)>::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<UnaryFunction(iterator_traits<Iterator>::reference)>::type</span></tt> is a non-const reference.</li>
|
|
<li>Readable Lvalue Iterator if <tt class="literal"><span class="pre">result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::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<UnaryFunction(iterator_traits<Iterator>::reference)>::type</span></tt>.
|
|
The <tt class="literal"><span class="pre">value_type</span></tt> is <tt class="literal"><span class="pre">remove_cv<remove_reference<reference></span> <span class="pre">>::type</span></tt>.</p>
|
|
</div>
|
|
<div class="section" id="transform-iterator-public-operations">
|
|
<h4><a class="toc-backref" href="#id50" 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&</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<class OtherIterator, class R2, class V2>
|
|
transform_iterator(
|
|
transform_iterator<UnaryFunction, OtherIterator, R2, V2> const& t
|
|
, typename enable_if_convertible<OtherIterator, Iterator>::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="#id51" 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="#id52" 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="#id53" name="class-template-filter-iterator">Class template <tt class="literal"><span class="pre">filter_iterator</span></tt></a></h4>
|
|
<pre class="literal-block">
|
|
template <class Predicate, class Iterator>
|
|
class filter_iterator
|
|
: public iterator_adaptor<
|
|
filter_iterator<Predicate, Iterator>, Iterator
|
|
, use_default
|
|
, /* see details */
|
|
>
|
|
{
|
|
public:
|
|
filter_iterator();
|
|
filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
|
|
filter_iterator(Iterator x, Iterator end = Iterator());
|
|
template<class OtherIterator>
|
|
filter_iterator(
|
|
filter_iterator<Predicate, OtherIterator> const& t
|
|
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
|
|
);
|
|
Predicate predicate() const;
|
|
Iterator end() const;
|
|
|
|
private: // as-if specification
|
|
void increment()
|
|
{
|
|
++(this->base_reference());
|
|
satisfy_predicate();
|
|
}
|
|
|
|
void satisfy_predicate()
|
|
{
|
|
while (this->base() != this->m_end && !this->m_predicate(*this->base()))
|
|
++(this->base_reference());
|
|
}
|
|
|
|
Predicate m_predicate;
|
|
Iterator m_end;
|
|
};
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="filter-iterator-requirements">
|
|
<h3><a class="toc-backref" href="#id54" 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<Iterator>::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="#id55" 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 <class OtherIterator>
|
|
filter_iterator(
|
|
filter_iterator<Predicate, OtherIterator> const& t
|
|
, typename enable_if_convertible<OtherIterator, Iterator>::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="counting-iterator">
|
|
<h3><a class="toc-backref" href="#id56" name="counting-iterator">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="#id57" name="class-template-counting-iterator">Class template <tt class="literal"><span class="pre">counting_iterator</span></tt></a></h4>
|
|
<pre class="literal-block">
|
|
template <
|
|
class Incrementable
|
|
, unsigned Access = use_default_access
|
|
, class Traversal = use_default
|
|
, class Difference = use_default
|
|
>
|
|
class counting_iterator
|
|
: public iterator_adaptor<
|
|
counting_iterator<Incrementable, Access, Traversal, Difference>
|
|
, Incrementable
|
|
, Incrementable
|
|
, Access
|
|
, /* see details for traversal category */
|
|
, Incrementable const&
|
|
, Incrementable const*
|
|
, /* distance = Difference or a signed integral type */>
|
|
{
|
|
friend class iterator_core_access;
|
|
public:
|
|
counting_iterator();
|
|
counting_iterator(counting_iterator const& rhs);
|
|
counting_iterator(Incrementable x);
|
|
private:
|
|
typename counting_iterator::reference dereference() const
|
|
{
|
|
return this->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="#id58" 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 < j
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="counting-iterator-operations">
|
|
<h3><a class="toc-backref" href="#id59" 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&</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="#id60" 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="#id61" 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 <class UnaryFunction>
|
|
class function_output_iterator {
|
|
public:
|
|
typedef iterator_tag<
|
|
writable_iterator
|
|
, incrementable_traversal_tag
|
|
> iterator_category;
|
|
typedef void value_type;
|
|
typedef void difference_type;
|
|
typedef void pointer;
|
|
typedef void reference;
|
|
|
|
explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
|
|
|
|
struct output_proxy {
|
|
output_proxy(UnaryFunction& f);
|
|
template <class T> output_proxy& operator=(const T& value);
|
|
};
|
|
output_proxy operator*();
|
|
function_output_iterator& operator++();
|
|
function_output_iterator& operator++(int);
|
|
};
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="function-output-iterator-requirements">
|
|
<h3><a class="toc-backref" href="#id62" 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="#id63" 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&</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&</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&</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="#id64" 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&</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"><class</span> <span class="pre">T></span> <span class="pre">output_proxy&</span> <span class="pre">operator=(const</span> <span class="pre">T&</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-12-07 20:30 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>
|