boostorg/iterator
1
0
Fork 1
mirror of https://github.com/boostorg/iterator.git synced 2025-08-01 05:44:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation updates, added GNUMakefile for building

Browse Source 
[SVN r20931]
This commit is contained in:
Dave Abrahams
2003-11-24 05:02:46 +00:00
parent ca1ee306b7
commit 09ea8d27e2
21 changed files with 3074 additions and 1270 deletions
Download Patch File Download Diff File Expand all files Collapse all files

328
doc/index.html
View File

@@ -4,12 +4,203 @@
<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>The Boost Iterator Library Boost</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
<title>The Boost.Iterator Library Boost</title>
<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="the-boost-iterator-library-logo">
<h1 class="title">The Boost Iterator Library <a class="reference" href="../../../index.htm"><img alt="Boost" src="../../../c++boost.gif" /></a></h1>
<h1 class="title">The Boost.Iterator Library <a class="reference" href="../../../index.htm"><img alt="Boost" src="../../../c++boost.gif" /></a></h1>
<hr />
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@@ -35,38 +226,40 @@ Railway Operation and Construction</a></td>
<tbody valign="top">
<tr class="field"><th class="field-name">Abstract:</th><td class="field-body">The Boost Iterator Library contains two parts. The first
is a system of <a class="reference" href="../../../more/generic_programming.html#concept">concepts</a> which extend the C++ standard
iterator requirements. The second is a framework
of components for building iterators based on these
iterator requirements. The second is a framework of
components for building iterators based on these
extended concepts and includes several useful iterator
adaptors. The extended iterator concepts have
been carefully designed so that new-style iterators will be
compatible with old-style algorithms, though algorithms may
need to be updated if they want to take full advantage of
the new-style iterators. Several components of this
library have been proposed for the C++ standard technical
report. The components of the Boost Iterator Library
replace the older Boost Iterator Adaptor Library.</td>
adaptors. The extended iterator concepts have been
carefully designed so that so that old-style iterators
can fit in the new concepts and so that new-style
iterators will be compatible with old-style algorithms,
though algorithms may need to be updated if they want to
take full advantage of the new-style iterator
capabilities. Several components of this library have
been accepted into the C++ standard technical report.
The components of the Boost Iterator Library replace the
older Boost Iterator Adaptor Library.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title"><a name="table-of-contents"><strong>Table of Contents</strong></a></p>
<ul class="simple">
<li><a class="reference" href="#new-style-iterators" id="id5" name="id5">New-Style Iterators</a></li>
<li><a class="reference" href="#iterator-facade-and-adaptor" id="id6" name="id6">Iterator Facade and Adaptor</a></li>
<li><a class="reference" href="#specialized-adaptors" id="id7" name="id7">Specialized Adaptors</a></li>
<li><a class="reference" href="#iterator-utilities" id="id8" name="id8">Iterator Utilities</a><ul>
<li><a class="reference" href="#traits" id="id9" name="id9">Traits</a></li>
<li><a class="reference" href="#testing-and-concept-checking" id="id10" name="id10">Testing and Concept Checking</a></li>
<li><a class="reference" href="#new-style-iterators" id="id6" name="id6">New-Style Iterators</a></li>
<li><a class="reference" href="#iterator-facade-and-adaptor" id="id7" name="id7">Iterator Facade and Adaptor</a></li>
<li><a class="reference" href="#specialized-adaptors" id="id8" name="id8">Specialized Adaptors</a></li>
<li><a class="reference" href="#iterator-utilities" id="id9" name="id9">Iterator Utilities</a><ul>
<li><a class="reference" href="#traits" id="id10" name="id10">Traits</a></li>
<li><a class="reference" href="#testing-and-concept-checking" id="id11" name="id11">Testing and Concept Checking</a></li>
</ul>
</li>
<li><a class="reference" href="#upgrading-from-the-old-boost-iterator-adaptor-library" id="id11" name="id11">Upgrading from the old Boost Iterator Adaptor Library</a></li>
<li><a class="reference" href="#history" id="id12" name="id12">History</a></li>
<li><a class="reference" href="#upgrading-from-the-old-boost-iterator-adaptor-library" id="id12" name="id12">Upgrading from the old Boost Iterator Adaptor Library</a></li>
<li><a class="reference" href="#history" id="id13" name="id13">History</a></li>
</ul>
</div>
<hr />
<div class="section" id="new-style-iterators">
<h1><a class="toc-backref" href="#id5" name="new-style-iterators">New-Style Iterators</a></h1>
<h1><a class="toc-backref" href="#id6" name="new-style-iterators">New-Style Iterators</a></h1>
<p>The iterator categories defined in C++98 are extremely limiting
because they bind together two orthogonal concepts: traversal and
element access. For example, because a random access iterator is
@@ -85,26 +278,26 @@ concepts, see our</p>
<a class="reference" href="new-iter-concepts.html">Standard Proposal For New-Style Iterators</a></blockquote>
</div>
<div class="section" id="iterator-facade-and-adaptor">
<h1><a class="toc-backref" href="#id6" name="iterator-facade-and-adaptor">Iterator Facade and Adaptor</a></h1>
<p>Writing standard-conforming iterators is tricky. In order to ease the
implementation of new iterators, the iterator library provides the
<a class="reference" href="iterator_facade.html"><tt class="literal"><span class="pre">iterator_facade</span></tt></a> class template, which implements many useful
defaults and compile-time checks designed to help the author iterator
ensure that his iterator is correct. It is common to define a new
iterator which behaves like another iterator, but modifies some aspect
of its behavior. For that purpose, the library supplies the
<a class="reference" href="iterator_adaptor.html"><tt class="literal"><span class="pre">iterator_adaptor</span></tt></a> class template, which is specially designed to
take advantage of as much of the underlying iterator's behavior as
possible.</p>
<p>Both <a class="reference" href="iterator_facade.html"><tt class="literal"><span class="pre">iterator_facade</span></tt></a> and <a class="reference" href="iterator_adaptor.html"><tt class="literal"><span class="pre">iterator_adaptor</span></tt></a> as well as many of
the <a class="reference" href="#specialized-adaptors">specialized adaptors</a> mentioned below have been proposed for
standardization; see our</p>
<h1><a class="toc-backref" href="#id7" name="iterator-facade-and-adaptor">Iterator Facade and Adaptor</a></h1>
<p>Writing standard-conforming iterators is tricky, but the need comes
up often. In order to ease the implementation of new iterators,
the Boost.Iterator library provides the <a class="reference" href="iterator_facade.html"><tt class="literal"><span class="pre">iterator_facade</span></tt></a> class template,
which implements many useful defaults and compile-time checks
designed to help the author iterator ensure that his iterator is
correct. It is common to define a new iterator which behaves like
another iterator, but which modifies some aspect of its behavior.
For that purpose, the library supplies the <a class="reference" href="iterator_adaptor.html"><tt class="literal"><span class="pre">iterator_adaptor</span></tt></a> class
template, which is specially designed to take advantage of as much
of the underlying iterator's behavior as possible.</p>
<p>Both <a class="reference" href="iterator_facade.html"><tt class="literal"><span class="pre">iterator_facade</span></tt></a> and <a class="reference" href="iterator_adaptor.html"><tt class="literal"><span class="pre">iterator_adaptor</span></tt></a> as well as many of the <a class="reference" href="#specialized-adaptors">specialized
adaptors</a> mentioned below have been proposed for standardization,
and accepted into the first C++ technical report; see our</p>
<blockquote>
<a class="reference" href="facade-and-adaptor.html">Standard Proposal For Iterator Facade and Adaptor</a></blockquote>
<p>for more details.</p>
</div>
<div class="section" id="specialized-adaptors">
<h1><a class="toc-backref" href="#id7" name="specialized-adaptors">Specialized Adaptors</a></h1>
<h1><a class="toc-backref" href="#id8" name="specialized-adaptors">Specialized Adaptors</a></h1>
<p>The iterator library supplies a useful suite of standard-conforming
iterator templates based on the Boost <a class="reference" href="#iterator-facade-and-adaptor">iterator facade and adaptor</a>.</p>
<ul class="simple">
@@ -126,9 +319,9 @@ underlying sequence. This component also replaces the old
</ul>
</div>
<div class="section" id="iterator-utilities">
<h1><a class="toc-backref" href="#id8" name="iterator-utilities">Iterator Utilities</a></h1>
<h1><a class="toc-backref" href="#id9" name="iterator-utilities">Iterator Utilities</a></h1>
<div class="section" id="traits">
<h2><a class="toc-backref" href="#id9" name="traits">Traits</a></h2>
<h2><a class="toc-backref" href="#id10" name="traits">Traits</a></h2>
<ul class="simple">
<li><a class="reference" href="iterator_traits.html"><tt class="literal"><span class="pre">iterator_traits.hpp</span></tt></a>: Provides <a class="reference" href="../../mpl/doc/index.html">MPL</a>-compatible metafunctions which
retrieve an iterator's traits. Also corrects for the deficiencies
@@ -138,7 +331,7 @@ testing iterator interoperability</li>
</ul>
</div>
<div class="section" id="testing-and-concept-checking">
<h2><a class="toc-backref" href="#id10" name="testing-and-concept-checking">Testing and Concept Checking</a></h2>
<h2><a class="toc-backref" href="#id11" name="testing-and-concept-checking">Testing and Concept Checking</a></h2>
<ul class="simple">
<li><a class="reference" href="iterator_archetypes.html"><tt class="literal"><span class="pre">iterator_archetypes.hpp</span></tt></a>: Add summary here</li>
<li><a class="reference" href="iterator_concepts.html"><tt class="literal"><span class="pre">iterator_concepts.hpp</span></tt></a>: Add summary</li>
@@ -146,13 +339,32 @@ testing iterator interoperability</li>
</div>
</div>
<div class="section" id="upgrading-from-the-old-boost-iterator-adaptor-library">
<h1><a class="toc-backref" href="#id11" name="upgrading-from-the-old-boost-iterator-adaptor-library">Upgrading from the old Boost Iterator Adaptor Library</a></h1>
<p>Turn your policy class into the body of the iterator</p>
<p>Use transform_iterator with a true reference type for
projection_iterator.</p>
<h1><a class="toc-backref" href="#id12" name="upgrading-from-the-old-boost-iterator-adaptor-library">Upgrading from the old Boost Iterator Adaptor Library</a></h1>
<a class="target" id="upgrading" name="upgrading"></a><p>If you have been using the old Boost Iterator Adaptor library to
implement iterators, you probably wrote a <tt class="literal"><span class="pre">Policies</span></tt> class which
captures the core operations of your iterator. In the new library
design, you'll move those same core operations into the body of the
iterator class itself. If you were writing a family of iterators,
you probably wrote a <a class="reference" href="../../../more/generic_programming.html#type_generator">type generator</a> to build the
<tt class="literal"><span class="pre">iterator_adaptor</span></tt> specialization you needed; in the new library
design you don't need a type generator (though may want to keep it
around as a compatibility aid for older code) because, due to the
use of the Curiously Recurring Template Pattern (CRTP) <a class="citation-reference" href="#cop95" id="id5" name="id5">[Cop95]</a>,
you can now define the iterator class yourself and acquire
functionality through inheritance from <tt class="literal"><span class="pre">iterator_facade</span></tt> or
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>. As a result, you also get much finer control
over how your iterator works: you can add additional constructors,
or even override the iterator functionality provided by the
library.</p>
<p>If you're looking for the old <tt class="literal"><span class="pre">projection_iterator</span></tt> component,
its functionality has been merged into <tt class="literal"><span class="pre">transform_iterator</span></tt>: as
long as the function object's <tt class="literal"><span class="pre">result_type</span></tt> (or the <tt class="literal"><span class="pre">Reference</span></tt>
template argument, if explicitly specified) is a true reference
type, <tt class="literal"><span class="pre">transform_iterator</span></tt> will behave like
<tt class="literal"><span class="pre">projection_iterator</span></tt> used to.</p>
</div>
<div class="section" id="history">
<h1><a class="toc-backref" href="#id12" name="history">History</a></h1>
<h1><a class="toc-backref" href="#id13" name="history">History</a></h1>
<p>In 2000 Dave Abrahams was writing an iterator for a container of
pointers, which would access the pointed-to elements when
dereferenced. Naturally, being a library writer, he decided to
@@ -165,10 +377,26 @@ library and they worked together to produce a &quot;Boostified&quot; version,
which was reviewed and accepted into the library. They wrote a paper
and made several important revisions of the code.</p>
<p>Eventually, several shortcomings of the older library began to make
the need for a rewrite apparent. Dave and Jeremy started working at
the Santa Cruz C++ committee meeting in 2002, and had quickly
generated a working prototype. Thomas Witt expressed interest and
became the voice of compile-time checking for the project...</p>
the need for a rewrite apparent. Dave and Jeremy started working
at the Santa Cruz C++ committee meeting in 2002, and had quickly
generated a working prototype. At the urging of Mat Marcus, they
decided to use the GenVoca/CRTP pattern approach, and moved the
policies into the iterator class itself. Thomas Witt expressed
interest and became the voice of strict compile-time checking for
the project, adding uses of the SFINAE technique to eliminate false
converting constructors and operators from the overload set. He
also recognized the need for a separate <tt class="literal"><span class="pre">iterator_facade</span></tt>, and
factored it out of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>. Finally, after a
near-complete rewrite of the prototype, they came up with the
library you see today.</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="#id5" 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>
<!-- LocalWords: Abrahams Siek Witt const bool Sutter's WG int UL LI href Lvalue
LocalWords: ReadableIterator WritableIterator SwappableIterator cv pre iter
LocalWords: ConstantLvalueIterator MutableLvalueIterator CopyConstructible TR
@@ -181,7 +409,7 @@ LocalWords: TraversalTag typename lvalues DWA Hmm JGS -->
<hr class="footer" />
<div class="footer">
<a class="reference" href="index.rst">View document source</a>.
Generated on: 2003-09-21 09:34 UTC.
Generated on: 2003-11-24 04:21 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>