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 ECHO = /bin/echo
PERL = /usr/bin/perl
CAT = /bin/cat
TOUCH = /bin/touch
ZIP = /usr/bin/zip
# ... TeX & postprocessors all:
PPOWER4 = ppower4 @${ECHO} "<boost-root>/libs/iterator/doc/GNUmakefile should be replaced by"
PDFLATEX = pdflatex @${ECHO}
METAPOST = mpost @${ECHO} " http://www.boost-consulting.com/writing/GNUmakefile,"
FIG2DEV = fig2dev @${ECHO}
BIBTEX = bibtex @${ECHO} "before proceeding. That file is not included in the Boost"
FOLIAGECUTTER = foliageCutter --verbose @${ECHO} "distribution because it is licensed under the GPL, which violates"
RST2LATEX = rst2latex --documentclass book --documentoptions 10pt,twoside,pdftex # --use-latex-toc @${ECHO} "Boost license requirements."
RST2HTML = rst2html
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> <title>Counting Iterator</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" /> <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="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" /> <meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<style type="text/css"><!-- <link rel="stylesheet" href="default.css" 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> </head>
<body> <body>
<div class="document" id="counting-iterator"> <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 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> Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th> <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> <tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr> <td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr>
</tbody> </tbody>
@ -227,92 +36,137 @@ Railway Operation and Construction</a></td></tr>
<col class="field-name" /> <col class="field-name" />
<col class="field-body" /> <col class="field-body" />
<tbody valign="top"> <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> </tr>
</tbody> </tbody>
</table> </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"> <div class="contents topic" id="table-of-contents">
<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p> <p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple"> <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-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-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-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> </ul>
</div> </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"> <pre class="literal-block">
template &lt; template &lt;
class Incrementable class Incrementable
, unsigned Access = use_default_access , class CategoryOrTraversal = use_default
, class Traversal = use_default
, class Difference = use_default , class Difference = use_default
&gt; &gt;
class counting_iterator 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(counting_iterator const&amp; rhs); counting_iterator(counting_iterator const&amp; rhs);
counting_iterator(Incrementable x); explicit counting_iterator(Incrementable x);
private: Incrementable const&amp; base() const;
typename counting_iterator::reference dereference() const reference operator*() const;
{ counting_iterator&amp; operator++();
return this-&gt;base_reference(); 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> </pre>
<dl> <dl>
<dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt> <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 <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 when the <tt class="literal"><span class="pre">Incrementable</span></tt> type is a numeric type.]</dd> the cases where <tt class="literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>
is true.]</dd>
</dl> </dl>
</div>
<div class="section" id="counting-iterator-requirements"> <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> <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> type must be Default Constructible, Copy <p>The <tt class="literal"><span class="pre">Incrementable</span></tt> argument shall be Copy Constructible and Assignable.</p>
Constructible, and Assignable. The default distance is <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>
an implementation defined signed integegral type.</p> or <tt class="literal"><span class="pre">forward_traversal_tag</span></tt>, the following must be well-formed:</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"> <pre class="literal-block">
Incrementable i, j; Incrementable i, j;
++i // pre-increment ++i; // pre-increment
i == j // operator equal i == j; // operator equal
</pre> </pre>
<p>If you wish to create a counting iterator that is a <p>If <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
Bidirectional Traversal Iterator, then pre-decrement is also required:</p> <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"> <pre class="literal-block">
--i --i
</pre> </pre>
<p>If you wish to create a counting iterator that is a Random Access <p>If <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
Traversal Iterator, then these additional expressions are also <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>,
required:</p> the following must must also be valid:</p>
<pre class="literal-block"> <pre class="literal-block">
counting_iterator::difference_type n; counting_iterator::difference_type n;
i += n i += n;
n = i - j n = i - j;
i &lt; j i &lt; j;
</pre> </pre>
</div> </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"> <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> <p><tt class="literal"><span class="pre">counting_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none"> <table class="field-list" frame="void" rules="none">
<col class="field-name" /> <col class="field-name" />
<col class="field-body" /> <col class="field-body" />
<tbody valign="top"> <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> </tr>
</tbody> </tbody>
</table> </table>
@ -321,26 +175,110 @@ i &lt; j
<col class="field-name" /> <col class="field-name" />
<col class="field-body" /> <col class="field-body" />
<tbody valign="top"> <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> </tr>
</tbody> </tbody>
</table> </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"> <table class="field-list" frame="void" rules="none">
<col class="field-name" /> <col class="field-name" />
<col class="field-body" /> <col class="field-body" />
<tbody valign="top"> <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 <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>
object copy constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>
</tr> </tr>
</tbody> </tbody>
</table> </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>
</div> </div>
<hr class="footer" /> <hr class="footer" />
<div class="footer"> <div class="footer">
<a class="reference" href="counting_iterator.rst">View document source</a>. <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. 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> </div>
</body> </body>

20
doc/counting_iterator.rst
View File

@ -14,10 +14,26 @@
.. _`Open Systems Lab`: http://www.osl.iu.edu .. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de .. _`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 .. contents:: Table of Contents
``counting_iterator`` synopsis
..............................
.. include:: counting_iterator_ref.rst .. 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 ``counting_iterator`` adapts an object by adding an ``operator*`` that
reference to the base object. The other operations are implemented by returns the current value of the object. All other iterator operations
the base ``m_iterator``, as per the inheritance from are forwarded to the adapted object.
``iterator_adaptor``.

146
doc/counting_iterator_ref.rst
View File

@ -2,90 +2,144 @@
template < template <
class Incrementable class Incrementable
, unsigned Access = use_default_access , class CategoryOrTraversal = use_default
, class Traversal = use_default
, class Difference = use_default , class Difference = use_default
> >
class counting_iterator 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(counting_iterator const& rhs); counting_iterator(counting_iterator const& rhs);
counting_iterator(Incrementable x); explicit counting_iterator(Incrementable x);
Incrementable const& base() const;
reference operator*() const;
counting_iterator& operator++();
counting_iterator& operator--();
private: private:
typename counting_iterator::reference dereference() const Incrementable m_inc; // exposition
{
return this->base_reference();
}
}; };
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 [*Note:* implementers are encouraged to provide an implementation of
``distance_to`` and a ``difference_type`` that avoids overflows in ``operator-`` and a ``difference_type`` that avoids overflows in
the cases when the ``Incrementable`` type is a numeric type.] the cases where ``std::numeric_limits<Incrementable>::is_specialized``
is true.]
``counting_iterator`` requirements ``counting_iterator`` requirements
---------------------------------- ..................................
The ``Incrementable`` type must be Default Constructible, Copy The ``Incrementable`` argument shall be Copy Constructible and Assignable.
Constructible, and Assignable. The default distance is
an implementation defined signed integegral type.
The resulting ``counting_iterator`` models Readable Lvalue Iterator. If ``iterator_category`` is convertible to ``forward_iterator_tag``
or ``forward_traversal_tag``, the following must be well-formed::
Furthermore, if you wish to create a counting iterator that is a Forward
Traversal Iterator, then the following expressions must be valid:
::
Incrementable i, j; Incrementable i, j;
++i // pre-increment ++i; // pre-increment
i == j // operator equal 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 --i
If you wish to create a counting iterator that is a Random Access If ``iterator_category`` is convertible to
Traversal Iterator, then these additional expressions are also ``random_access_iterator_tag`` or ``random_access_traversal_tag``,
required: the following must must also be valid::
::
counting_iterator::difference_type n; counting_iterator::difference_type n;
i += n i += n;
n = i - j n = i - j;
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 ``counting_iterator`` operations
-------------------------------- ................................
In addition to the operations required by the concepts modeled by
``counting_iterator``, ``counting_iterator`` provides the following
operations.
``counting_iterator();`` ``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);`` ``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 :Effects: Construct member ``m_inc`` from ``x``.
object copy constructed 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 } text-align: center }
div.attention, div.caution, div.danger, div.error, div.hint, 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 ; margin: 2em ;
border: medium outset ; border: medium outset ;
padding: 1em } padding: 1em }
@ -42,7 +42,8 @@ div.warning p.admonition-title {
font-family: sans-serif } font-family: sans-serif }
div.hint p.admonition-title, div.important p.admonition-title, 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-weight: bold ;
font-family: sans-serif } font-family: sans-serif }
@ -61,6 +62,19 @@ div.figure {
div.footer, div.header { div.footer, div.header {
font-size: smaller } 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 { div.system-messages {
margin: 5em } margin: 5em }
@ -105,6 +119,10 @@ ol.lowerroman {
ol.upperroman { ol.upperroman {
list-style: upper-roman } list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption { p.caption {
font-style: italic } font-style: italic }
@ -115,6 +133,21 @@ p.credits {
p.label { p.label {
white-space: nowrap } 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 { p.topic-title {
font-weight: bold } font-weight: bold }
@ -144,6 +177,9 @@ span.classifier-delimiter {
span.interpreted { span.interpreted {
font-family: sans-serif } font-family: sans-serif }
span.option {
white-space: nowrap }
span.option-argument { span.option-argument {
font-style: italic } font-style: italic }