feedc0de/boost_iterator
1
0
Fork 0
forked from boostorg/iterator
Code Pull Requests Activity

merged from trunk

Browse Source 
[SVN r21991]
This commit is contained in:
Dave Abrahams
2004-01-27 04:18:44 +00:00
parent a4dbdcb00c
commit 189533437f
6 changed files with 355 additions and 533 deletions
Download Patch File Download Diff File Expand all files Collapse all files

237
doc/GNUmakefile
View File

@ -1,232 +1,11 @@
# GNUmakefile for postprocessing PDF files
#
# <20> 2000 IBM Corporation.
# Licensed under the GNU GPL.
########################################################################
# Make sure that the following macros are correct for your setup
########################################################################
# ... System utilities
RMRF = /bin/rm -rf
MV = /bin/mv
EGREP = /bin/egrep
ECHO = /bin/echo
PERL = /usr/bin/perl
CAT = /bin/cat
TOUCH = /bin/touch
ZIP = /usr/bin/zip
# ... TeX & postprocessors
PPOWER4 = ppower4
PDFLATEX = pdflatex
METAPOST = mpost
FIG2DEV = fig2dev
BIBTEX = bibtex
FOLIAGECUTTER = foliageCutter --verbose
RST2LATEX = rst2latex --documentclass book --documentoptions 10pt,twoside,pdftex # --use-latex-toc
RST2HTML = rst2html
all:
@${ECHO} "<boost-root>/libs/iterator/doc/GNUmakefile should be replaced by"
@${ECHO}
@${ECHO} " http://www.boost-consulting.com/writing/GNUmakefile,"
@${ECHO}
@${ECHO} "before proceeding. That file is not included in the Boost"
@${ECHO} "distribution because it is licensed under the GPL, which violates"
@${ECHO} "Boost license requirements."
TEX = latex
export TEX
########################################################################
# End of user servicable parts; don't fiddle with the remainder of this
# makefile unless you know what you do.
#
# You have been warned ;=)
########################################################################
# ... Variables
TEXFILES = $(strip $(wildcard *.tex))
RSTFILES = $(strip $(wildcard *.rst))
-include GNUmakefile.local
TEXSTEMS = $(strip $(patsubst %.tex,%,${TEXFILES}))
RSTSTEMS = $(strip $(patsubst %.rst,%,${RSTFILES}))
CUTFOILS = $(strip $(patsubst %,%---toc.tex,${TEXSTEMS}))
PDFFILES = $(strip $(patsubst %.tex,%.pdf,${TEXFILES}))
PRINTS = $(patsubst %.pdf,%-print.pdf,${PDFFILES})
PRINTZIP = prints.zip
SLIDEZIP = slides.zip
# ... Depend
DEPENDFILE = .depend
GENFILE = .generated
# ... List of extensions and files generated
texcrap = *.mpx *.log *.aux *.blg *-print.brf *-print.tex *.out
mpxcrap = mpxerr.tex mpxerr.pdf
generated = *.out *.[0-9] *.[0-9][0-9] *.bbl *.brf \
*.mp *.mmp *.pdf .depend *.ps TMP-*.pdf *.ftoc\
${PRINTZIP} ${SLIDEZIP} ${GENFILE} ${DEPENDFILE} \
${texcrap} ${mpxcrap} ${CUTFOILS} $(strip $(wildcard *---*.tex))
# ... canned command to run PDFLaTeX
define run-pdflatex
@${ECHO} ""
@${ECHO} "---- Running PDFLaTeX on $<" && ${PDFLATEX} $<
@${ECHO} "---- Running PDFLaTeX on $< again" && ${PDFLATEX} $<
-@(${EGREP} -qi 'Rerun to get' $*.log && \
${ECHO} "---- Rerunning PDFLaTeX on $* to get cross-refs right" && \
${PDFLATEX} $<) || \
${ECHO} "---- No cross-refs correcting PDFLaTeX rerun required for $*"
-@(${EGREP} -qi $*.ftoc $*.log && \
${ECHO} "---- Rerunning PDFLaTeX on $* for FTOC" && \
${PDFLATEX} $<) || \
${ECHO} "---- No FTOC PDFLaTeX run required for $*"
-@(${EGREP} -qi 'Warning: Citation' $*.log && \
${ECHO} "---- Running BIBTeX on $*" && \
${BIBTEX} $* && \
${ECHO} "---- Running PDFLaTeX on $<" && \
${PDFLATEX} $<) || \
${ECHO} "---- No BIBTeX run required for $*"
-@(${EGREP} -qi 'Warning: .+undefined references' $*.log && \
${ECHO} "---- Running PDFLaTeX on $<" && \
${PDFLATEX} $<) || \
${ECHO} "---- No further PDFLaTex run required for $<"
@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
@${RMRF} ${texcrap}
endef
# ... canned command to run PDFLaTeX for printable versions
define run-pdflatex-for-print
@${ECHO} ""
@${ECHO} "---- Running PDFLaTeX on $*-print.tex" && ${PDFLATEX} $*-print.tex
@${ECHO} "---- Running PDFLaTeX on $< again" && ${PDFLATEX} $<
-@(${EGREP} -qi 'Warning: Citation' $*-print.log && \
${ECHO} "---- Running BIBTeX on $*-print" && \
${BIBTEX} $*-print && \
${ECHO} "---- Running PDFLaTeX on $*-print.tex" && \
${PDFLATEX} $*-print.tex) || \
${ECHO} "---- No BIBTeX run required for $*"
-@(${EGREP} -qi 'Warning: .+undefined references' $*-print.log && \
${ECHO} "---- Running PDFLaTeX on $*-print" && \
${PDFLATEX} $*-print.tex) || \
${ECHO} "---- No further PDFLaTex run required for $*-print"
@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
@${RMRF} ${texcrap}
endef
# DWA begin modifications
# ... Rule: How to generate TeX from ReST
%.tex: %.txt
@${ECHO} "---- Running rst2latex on $<"
${RST2LATEX} $< $@
@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
# ... Rule: How to generate TeX from ReST
%.tex: %.rst
@${ECHO} "---- Running rst2latex on $<"
${RST2LATEX} $< $@
@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
# ... Rule: How to generate HTML from ReST
%.html: %.txt
@${ECHO} "---- Running rst2html on $<"
${RST2HTML} $< $@
@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
# ... Rule: How to generate HTML from ReST
%.html: %.rst
@${ECHO} "---- Running rst2html on $<"
${RST2HTML} $< $@
@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
# DWA end modifications
# ... Rule: How to generate PDF from TeX
%.pdf: %.tex
$(run-pdflatex)
@${MV} $@ TMP-$@
@${ECHO} "---- Running PPower4 on $*"
${PPOWER4} -v TMP-$@ $@
@${RMRF} TMP-$@
@${ECHO} "Postprocessed: $*.pdf {$*.pdf}" >> ${GENFILE}
# ... Rule: How to generate printable PDF from TeX
%-print.pdf: %.tex
${PERL} -pe 's/^\\documentclass\[(.*?)\]/\\documentclass\[$$1,prints\]/;' < $< > $*-print.tex
$(run-pdflatex-for-print)
@${ECHO} "Generated: $*-print.pdf {$*.pdf}" >> ${GENFILE}
# ... Rule: How to generate cut foils from TeX master
%---toc.tex: %.tex
${FOLIAGECUTTER} --prefix=$* $<
# ... Rule: How to generate MetaPost from FIG
%.mp: %.fig
@${ECHO} "---- Running Fig2Dev (mp) on $<"
${FIG2DEV} -L mp $< $@
@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
# ... Rule: How to generate MultiMetaPost from FIG
%.mmp: %.fig
@${ECHO} "---- Running Fig2Dev (mmp) on $<"
${FIG2DEV} -L mmp $< $@
@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
# ... Rule: How to generate includable PS from FIG via MetaPost
%.mps: %.fig
@${ECHO} "---- Running Fig2Dev (mps) on $<"
${FIG2DEV} -L mp $< $*.mps.mp
@${RMRF} $*.mps.[0-9]
${METAPOST} $*.mps.mp
@${MV} $*.mps.0 $@
@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
# ... Rule: How to generate includable PS files from MultiMetaPost
%.0: %.mmp
@${ECHO} "---- Running MetaPost on $<"
@${RMRF} $*.[0-9] $*.[0-9][0-9]
${METAPOST} $<
@${ECHO} "Generated: $*.0{...} {$<}" >> ${GENFILE}
cleanup-crap:
@${RMRF} ${mpxcrap}
# ... Target: all
all: cleanup-crap .depend ${PDFFILES} ${PRINTS} ${PRINTZIP} ${SLIDEZIP}
@${ECHO} ""
@${TOUCH} ${GENFILE}
@${CAT} ${GENFILE}
@${RMRF} ${GENFILE}
# ... Target: ZIP files
zip zips: ${PRINTZIP} ${SLIDEZIP}
# ... Target: ZIP file containing printable versions of slides
${PRINTZIP}: .depend ${PDFFILES}
@${RMRF} ${PRINTZIP}
${ZIP} -r ${PRINTZIP} ${PRINTS}
@${ECHO} "Generated: ${PRINTZIP}" >> ${GENFILE}
# ... Target: ZIP file containing screen versions of slides
${SLIDEZIP}: .depend ${PDFFILES}
@${RMRF} ${SLIDEZIP}
${ZIP} -r ${SLIDEZIP} ${PDFFILES}
@${ECHO} "Generated: ${SLIDEZIP}" >> ${GENFILE}
# ... Target: clean up
clean:
${RMRF} ${generated}
# ... Target: create dependencies
depend: .depend
# ... Target: dependency file (parse TEXFILES for multiinclude and includegraphics)
.depend: GNUmakefile ${TEXFILES}
${RMRF} $@
@for t in ${TEXSTEMS} ; do \
${ECHO} "Scanning $$t.tex"; \
${PERL} -e 'my $$target = shift @ARGV;' -e 'while (<>) { /\\multiinclude(\[.*?\])?{(.*?)}/ && print "$$target: $$2.0\n";}' $$t.pdf < $$t.tex >> $@; \
${PERL} -e 'my $$target = shift @ARGV;' -e 'while (<>) { /\\includegraphics(\[.*?\])?{(.*?)\.(.*?)}/ && print "$$target: $$2.$$3\n";}' $$t.pdf < $$t.tex >> $@; \
done
@for t in ${RSTSTEMS} ; do \
${ECHO} "Scanning $$t.rst"; \
${PERL} -e 'my $$target = shift @ARGV;' -e 'while (<>) { /^\.\. include::\s+(.*)/ && print "$$target: $$1\n";}' $$t.html < $$t.rst >> $@; \
${PERL} -e 'my $$target = shift @ARGV;' -e 'while (<>) { /^\.\. include::\s+(.*)/ && print "$$target: $$1\n";}' $$t.tex < $$t.rst >> $@; \
done
# ... include dependency file
-include .depend

432
doc/counting_iterator.html
View File

@ -7,200 +7,9 @@
<title>Counting Iterator</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2003-09-14" />
<meta name="date" content="2004-01-15" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<style type="text/css"><!--
/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date$
: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>
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="counting-iterator">
@ -218,7 +27,7 @@ ul.auto-toc {
Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for Transport
Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2003-09-14</td></tr>
<td>2004-01-15</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr>
</tbody>
@ -227,92 +36,137 @@ Railway Operation and Construction</a></td></tr>
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">abstract:</th><td class="field-body"></td>
<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><p class="first">How would you fill up a vector with the numbers zero
through one hundred using <tt class="literal"><span class="pre">std::copy()</span></tt>? The only iterator
operation missing from builtin integer types is an
<tt class="literal"><span class="pre">operator*()</span></tt> that returns the current value of the integer.
The counting iterator adaptor adds this crucial piece of
functionality to whatever type it wraps. One can use the
counting iterator adaptor not only with integer types, but with
any incrementable type.</p>
<p class="last"><tt class="literal"><span class="pre">counting_iterator</span></tt> adapts an object by adding an <tt class="literal"><span class="pre">operator*</span></tt> that
returns the current value of the object. All other iterator operations
are forwarded to the adapted object.</p>
</td>
</tr>
</tbody>
</table>
<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="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="#counting-iterator-requirements" id="id1" name="id1"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#counting-iterator-operations" id="id2" name="id2"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#counting-iterator-synopsis" id="id2" name="id2"><tt class="literal"><span class="pre">counting_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#counting-iterator-requirements" id="id3" name="id3"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#counting-iterator-models" id="id4" name="id4"><tt class="literal"><span class="pre">counting_iterator</span></tt> models</a></li>
<li><a class="reference" href="#counting-iterator-operations" id="id5" name="id5"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#example" id="id6" name="id6">Example</a></li>
</ul>
</div>
<div class="section" id="counting-iterator-synopsis">
<h1><a class="toc-backref" href="#id2" name="counting-iterator-synopsis"><tt class="literal"><span class="pre">counting_iterator</span></tt> synopsis</a></h1>
<pre class="literal-block">
template &lt;
class Incrementable
, unsigned Access = use_default_access
, class Traversal = use_default
, class CategoryOrTraversal = use_default
, class Difference = use_default
&gt;
class counting_iterator
: public iterator_adaptor&lt;
counting_iterator&lt;Incrementable, Access, Traversal, Difference&gt;
, Incrementable
, Incrementable
, Access
, /* see details for traversal category */
, Incrementable const&amp;
, Incrementable const*
, /* distance = Difference or a signed integral type */&gt;
{
friend class iterator_core_access;
public:
public:
typedef Incrementable value_type;
typedef const Incrementable&amp; reference;
typedef const Incrementable* pointer;
typedef /* see below */ difference_type;
typedef /* see below */ iterator_category;
counting_iterator();
counting_iterator(counting_iterator const&amp; rhs);
counting_iterator(Incrementable x);
private:
typename counting_iterator::reference dereference() const
{
return this-&gt;base_reference();
}
};
explicit counting_iterator(Incrementable x);
Incrementable const&amp; base() const;
reference operator*() const;
counting_iterator&amp; operator++();
counting_iterator&amp; operator--();
private:
Incrementable m_inc; // exposition
};
</pre>
<p>If the <tt class="literal"><span class="pre">Difference</span></tt> argument is <tt class="literal"><span class="pre">use_default</span></tt> then
<tt class="literal"><span class="pre">difference_type</span></tt> is an unspecified signed integral
type. Otherwise <tt class="literal"><span class="pre">difference_type</span></tt> is <tt class="literal"><span class="pre">Difference</span></tt>.</p>
<p><tt class="literal"><span class="pre">iterator_category</span></tt> is determined according to the following
algorithm:</p>
<pre class="literal-block">
if (CategoryOrTraversal is not use_default)
return CategoryOrTraversal
else if (numeric_limits&lt;Incrementable&gt;::is_specialized)
return <a class="reference" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
random_access_traversal_tag, Incrementable, const Incrementable&amp;)
else
return <a class="reference" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
iterator_traversal&lt;Incrementable&gt;::type,
Incrementable, const Incrementable&amp;)
</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>
<dd><tt class="literal"><span class="pre">operator-</span></tt> and a <tt class="literal"><span class="pre">difference_type</span></tt> that avoids overflows in
the cases where <tt class="literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>
is true.]</dd>
</dl>
</div>
<div class="section" id="counting-iterator-requirements">
<h1><a class="toc-backref" href="#id1" name="counting-iterator-requirements"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
<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>
<h1><a class="toc-backref" href="#id3" name="counting-iterator-requirements"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
<p>The <tt class="literal"><span class="pre">Incrementable</span></tt> argument shall be Copy Constructible and Assignable.</p>
<p>If <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to <tt class="literal"><span class="pre">forward_iterator_tag</span></tt>
or <tt class="literal"><span class="pre">forward_traversal_tag</span></tt>, the following must be well-formed:</p>
<pre class="literal-block">
Incrementable i, j;
++i // pre-increment
i == j // operator equal
++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>
<p>If <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="literal"><span class="pre">bidirectional_iterator_tag</span></tt> or <tt class="literal"><span class="pre">bidirectional_traversal_tag</span></tt>,
the following expression must also be well-formed:</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>
<p>If <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="literal"><span class="pre">random_access_iterator_tag</span></tt> or <tt class="literal"><span class="pre">random_access_traversal_tag</span></tt>,
the following must must also be valid:</p>
<pre class="literal-block">
counting_iterator::difference_type n;
i += n
n = i - j
i &lt; j
i += n;
n = i - j;
i &lt; j;
</pre>
</div>
<div class="section" id="counting-iterator-models">
<h1><a class="toc-backref" href="#id4" name="counting-iterator-models"><tt class="literal"><span class="pre">counting_iterator</span></tt> models</a></h1>
<p>Specializations of <tt class="literal"><span class="pre">counting_iterator</span></tt> model Readable Lvalue
Iterator. In addition, they model the concepts corresponding to the
iterator tags to which their <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible.
Also, if <tt class="literal"><span class="pre">CategoryOrTraversal</span></tt> is not <tt class="literal"><span class="pre">use_default</span></tt> then
<tt class="literal"><span class="pre">counting_iterator</span></tt> models the concept corresponding to the iterator
tag <tt class="literal"><span class="pre">CategoryOrTraversal</span></tt>. Otherwise, if
<tt class="literal"><span class="pre">numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>, then
<tt class="literal"><span class="pre">counting_iterator</span></tt> models Random Access Traversal Iterator.
Otherwise, <tt class="literal"><span class="pre">counting_iterator</span></tt> models the same iterator traversal
concepts modeled by <tt class="literal"><span class="pre">Incrementable</span></tt>.</p>
<p><tt class="literal"><span class="pre">counting_iterator&lt;X,C1,D1&gt;</span></tt> is interoperable with
<tt class="literal"><span class="pre">counting_iterator&lt;Y,C2,D2&gt;</span></tt> if and only if <tt class="literal"><span class="pre">X</span></tt> is
interoperable with <tt class="literal"><span class="pre">Y</span></tt>.</p>
</div>
<div class="section" id="counting-iterator-operations">
<h1><a class="toc-backref" href="#id2" name="counting-iterator-operations"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></h1>
<h1><a class="toc-backref" href="#id5" name="counting-iterator-operations"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></h1>
<p>In addition to the operations required by the concepts modeled by
<tt class="literal"><span class="pre">counting_iterator</span></tt>, <tt class="literal"><span class="pre">counting_iterator</span></tt> provides the following
operations.</p>
<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 class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Incrementable</span></tt> is Default Constructible.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Default construct the member <tt class="literal"><span class="pre">m_inc</span></tt>.</td>
</tr>
</tbody>
</table>
@ -321,26 +175,110 @@ i &lt; j
<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 class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="literal"><span class="pre">m_inc</span></tt> from <tt class="literal"><span class="pre">rhs.m_inc</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">counting_iterator(Incrementable</span> <span class="pre">x);</span></tt></p>
<p><tt class="literal"><span class="pre">explicit</span> <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 class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="literal"><span class="pre">m_inc</span></tt> from <tt class="literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
<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">m_inc</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="literal"><span class="pre">++m_inc</span></tt></td>
</tr>
<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">counting_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="literal"><span class="pre">--m_inc</span></tt></td>
</tr>
<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">Incrementable</span> <span class="pre">const&amp;</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_inc</span></tt></td>
</tr>
</tbody>
</table>
<pre class="literal-block">
template &lt;class Incrementable&gt;
counting_iterator&lt;Incrementable&gt; make_counting_iterator(Incrementable x);
</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">counting_iterator&lt;Incrementable&gt;</span></tt>
with <tt class="literal"><span class="pre">current</span></tt> constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="example">
<h1><a class="toc-backref" href="#id6" name="example">Example</a></h1>
<p>This example fills an array with numbers and a second array with
pointers into the first array, using <tt class="literal"><span class="pre">counting_iterator</span></tt> for both
tasks. Finally <tt class="literal"><span class="pre">indirect_iterator</span></tt> is used to print out the numbers
into the first array via indirection through the second array.</p>
<pre class="literal-block">
int N = 7;
std::vector&lt;int&gt; numbers;
typedef std::vector&lt;int&gt;::iterator n_iter;
std::copy(boost::counting_iterator&lt;int&gt;(0),
boost::counting_iterator&lt;int&gt;(N),
std::back_inserter(numbers));
std::vector&lt;std::vector&lt;int&gt;::iterator&gt; pointers;
std::copy(boost::make_counting_iterator(numbers.begin()),
boost::make_counting_iterator(numbers.end()),
std::back_inserter(pointers));
std::cout &lt;&lt; &quot;indirectly printing out the numbers from 0 to &quot;
&lt;&lt; N &lt;&lt; std::endl;
std::copy(boost::make_indirect_iterator(pointers.begin()),
boost::make_indirect_iterator(pointers.end()),
std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
std::cout &lt;&lt; std::endl;
</pre>
<p>The output is:</p>
<pre class="literal-block">
indirectly printing out the numbers from 0 to 7
0 1 2 3 4 5 6
</pre>
<p>The source code for this example can be found <a class="reference" href="../example/counting_iterator_example.cpp">here</a>.</p>
</div>
</div>
<hr class="footer" />
<div class="footer">
<a class="reference" href="counting_iterator.rst">View document source</a>.
Generated on: 2003-11-24 05:00 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>

20
doc/counting_iterator.rst
View File

@ -14,10 +14,26 @@
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
:abstract:
:abstract: How would you fill up a vector with the numbers zero
through one hundred using ``std::copy()``? The only iterator
operation missing from builtin integer types is an
``operator*()`` that returns the current value of the integer.
The counting iterator adaptor adds this crucial piece of
functionality to whatever type it wraps. One can use the
counting iterator adaptor not only with integer types, but with
any incrementable type.
.. include:: counting_iterator_abstract.rst
.. include:: counting_iterator_abstract.rst
.. contents:: Table of Contents
``counting_iterator`` synopsis
..............................
.. include:: counting_iterator_ref.rst
.. include:: make_counting_iterator.rst
.. include:: counting_iterator_eg.rst
.. _iterator-category: iterator_facade.html#iterator-category
.. |iterator-category| replace:: *iterator-category*

7
doc/counting_iterator_abstract.rst
View File

@ -1,5 +1,4 @@
The counting iterator adaptor implements dereference by returning a
reference to the base object. The other operations are implemented by
the base ``m_iterator``, as per the inheritance from
``iterator_adaptor``.
``counting_iterator`` adapts an object by adding an ``operator*`` that
returns the current value of the object. All other iterator operations
are forwarded to the adapted object.

152
doc/counting_iterator_ref.rst
View File

@ -2,90 +2,144 @@
template <
class Incrementable
, unsigned Access = use_default_access
, class Traversal = use_default
, class CategoryOrTraversal = 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:
public:
typedef Incrementable value_type;
typedef const Incrementable& reference;
typedef const Incrementable* pointer;
typedef /* see below */ difference_type;
typedef /* see below */ iterator_category;
counting_iterator();
counting_iterator(counting_iterator const& rhs);
counting_iterator(Incrementable x);
private:
typename counting_iterator::reference dereference() const
{
return this->base_reference();
}
};
explicit counting_iterator(Incrementable x);
Incrementable const& base() const;
reference operator*() const;
counting_iterator& operator++();
counting_iterator& operator--();
private:
Incrementable m_inc; // exposition
};
If the ``Difference`` argument is ``use_default`` then
``difference_type`` is an unspecified signed integral
type. Otherwise ``difference_type`` is ``Difference``.
``iterator_category`` is determined according to the following
algorithm:
.. parsed-literal::
if (CategoryOrTraversal is not use_default)
return CategoryOrTraversal
else if (numeric_limits<Incrementable>::is_specialized)
return |iterator-category|_\ (
random_access_traversal_tag, Incrementable, const Incrementable&)
else
return |iterator-category|_\ (
iterator_traversal<Incrementable>::type,
Incrementable, const Incrementable&)
[*Note:* implementers are encouraged to provide an implementation of
``distance_to`` and a ``difference_type`` that avoids overflows in
the cases when the ``Incrementable`` type is a numeric type.]
``operator-`` and a ``difference_type`` that avoids overflows in
the cases where ``std::numeric_limits<Incrementable>::is_specialized``
is true.]
``counting_iterator`` requirements
----------------------------------
..................................
The ``Incrementable`` type must be Default Constructible, Copy
Constructible, and Assignable. The default distance is
an implementation defined signed integegral type.
The ``Incrementable`` argument shall be Copy Constructible and Assignable.
The resulting ``counting_iterator`` models Readable Lvalue Iterator.
Furthermore, if you wish to create a counting iterator that is a Forward
Traversal Iterator, then the following expressions must be valid:
::
If ``iterator_category`` is convertible to ``forward_iterator_tag``
or ``forward_traversal_tag``, the following must be well-formed::
Incrementable i, j;
++i // pre-increment
i == j // operator equal
++i; // pre-increment
i == j; // operator equal
If you wish to create a counting iterator that is a
Bidirectional Traversal Iterator, then pre-decrement is also required:
::
If ``iterator_category`` is convertible to
``bidirectional_iterator_tag`` or ``bidirectional_traversal_tag``,
the following expression must also be well-formed::
--i
If you wish to create a counting iterator that is a Random Access
Traversal Iterator, then these additional expressions are also
required:
::
If ``iterator_category`` is convertible to
``random_access_iterator_tag`` or ``random_access_traversal_tag``,
the following must must also be valid::
counting_iterator::difference_type n;
i += n
n = i - j
i < j
i += n;
n = i - j;
i < j;
``counting_iterator`` models
............................
Specializations of ``counting_iterator`` model Readable Lvalue
Iterator. In addition, they model the concepts corresponding to the
iterator tags to which their ``iterator_category`` is convertible.
Also, if ``CategoryOrTraversal`` is not ``use_default`` then
``counting_iterator`` models the concept corresponding to the iterator
tag ``CategoryOrTraversal``. Otherwise, if
``numeric_limits<Incrementable>::is_specialized``, then
``counting_iterator`` models Random Access Traversal Iterator.
Otherwise, ``counting_iterator`` models the same iterator traversal
concepts modeled by ``Incrementable``.
``counting_iterator<X,C1,D1>`` is interoperable with
``counting_iterator<Y,C2,D2>`` if and only if ``X`` is
interoperable with ``Y``.
``counting_iterator`` operations
--------------------------------
................................
In addition to the operations required by the concepts modeled by
``counting_iterator``, ``counting_iterator`` provides the following
operations.
``counting_iterator();``
:Returns: A default constructed instance of ``counting_iterator``.
:Requires: ``Incrementable`` is Default Constructible.
:Effects: Default construct the member ``m_inc``.
``counting_iterator(counting_iterator const& rhs);``
:Returns: An instance of ``counting_iterator`` that is a copy of ``rhs``.
:Effects: Construct member ``m_inc`` from ``rhs.m_inc``.
``counting_iterator(Incrementable x);``
``explicit counting_iterator(Incrementable x);``
:Returns: An instance of ``counting_iterator`` with its base
object copy constructed from ``x``.
:Effects: Construct member ``m_inc`` from ``x``.
``reference operator*() const;``
:Returns: ``m_inc``
``counting_iterator& operator++();``
:Effects: ``++m_inc``
:Returns: ``*this``
``counting_iterator& operator--();``
:Effects: ``--m_inc``
:Returns: ``*this``
``Incrementable const& base() const;``
:Returns: ``m_inc``

40
doc/default.css
View File

@ -29,7 +29,7 @@ div.abstract p.topic-title {
text-align: center }
div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning {
div.important, div.note, div.tip, div.warning, div.admonition {
margin: 2em ;
border: medium outset ;
padding: 1em }
@ -42,7 +42,8 @@ div.warning p.admonition-title {
font-family: sans-serif }
div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title {
div.note p.admonition-title, div.tip p.admonition-title,
div.admonition p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
@ -61,6 +62,19 @@ div.figure {
div.footer, div.header {
font-size: smaller }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
@ -105,6 +119,10 @@ ol.lowerroman {
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
@ -115,6 +133,21 @@ p.credits {
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
@ -144,6 +177,9 @@ span.classifier-delimiter {
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.option-argument {
font-style: italic }