feedc0de/boost_iterator
1
0
Fork 0
forked from boostorg/iterator
Code Pull Requests 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

232
doc/GNUmakefile Executable file
View File

@ -0,0 +1,232 @@
# 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
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

207
doc/counting_iterator.html
View File

@ -9,7 +9,198 @@
<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="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
<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="counting-iterator">
@ -52,13 +243,19 @@ the base <tt class="literal"><span class="pre">m_iterator</span></tt>, as per th
</ul>
</div>
<pre class="literal-block">
template &lt;class Incrementable, class Category = use_default, class Difference = use_default&gt;
template &lt;
class Incrementable
, unsigned Access = use_default_access
, class Traversal = use_default
, class Difference = use_default
&gt;
class counting_iterator
: public iterator_adaptor&lt;
counting_iterator&lt;Incrementable, Category, Difference&gt;
counting_iterator&lt;Incrementable, Access, Traversal, Difference&gt;
, Incrementable
, Incrementable
, /* see details for category */
, Access
, /* see details for traversal category */
, Incrementable const&amp;
, Incrementable const*
, /* distance = Difference or a signed integral type */&gt;
@ -143,7 +340,7 @@ object copy constructed from <tt class="literal"><span class="pre">x</span></tt>
<hr class="footer" />
<div class="footer">
<a class="reference" href="counting_iterator.rst">View document source</a>.
Generated on: 2003-09-21 09:34 UTC.
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>

654
doc/facade-and-adaptor.html
View File

File diff suppressed because it is too large Load Diff

77
doc/facade-and-adaptor.rst
View File

@ -8,7 +8,16 @@
Lab`_, University of Hanover `Institute for Transport
Railway Operation and Construction`_
:date: $Date$
:Number: N1530=03-0113
:Number: This is a revised version of N1530_\ =03-0113, which was
accepted for Technical Report 1 by the C++ standard
committee's library working group.
.. Version 1.9 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG.
.. _n1530: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1530.html
:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
@ -124,15 +133,15 @@ Iterator Concepts
=================
This proposal is formulated in terms of the new ``iterator concepts``
as proposed in `n1477`_, since user-defined and especially adapted
as proposed in n1550_, since user-defined and especially adapted
iterators suffer from the well known categorization problems that are
inherent to the current iterator categories.
.. _`n1477`: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html
.. _n1550: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1550.html
This proposal does not strictly depend on proposal `n1477`_, as there
This proposal does not strictly depend on proposal n1550_, as there
is a direct mapping between new and old categories. This proposal
could be reformulated using this mapping if `n1477`_ was not accepted.
could be reformulated using this mapping if n1550_ was not accepted.
Interoperability
================
@ -141,24 +150,24 @@ The question of iterator interoperability is poorly addressed in the
current standard. There are currently two defect reports that are
concerned with interoperability issues.
Issue `179`_ concerns the fact that mutable container iterator types
Issue 179_ concerns the fact that mutable container iterator types
are only required to be convertible to the corresponding constant
iterator types, but objects of these types are not required to
interoperate in comparison or subtraction expressions. This situation
is tedious in practice and out of line with the way built in types
work. This proposal implements the proposed resolution to issue
`179`_, as most standard library implementations do nowadays. In other
179_, as most standard library implementations do nowadays. In other
words, if an iterator type A has an implicit or user defined
conversion to an iterator type B, the iterator types are interoperable
and the usual set of operators are available.
Issue `280`_ concerns the current lack of interoperability between
Issue 280_ concerns the current lack of interoperability between
reverse iterator types. The proposed new reverse_iterator template
fixes the issues raised in 280. It provides the desired
interoperability without introducing unwanted overloads.
.. _`179`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-defects.html#179
.. _`280`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#280
.. _179: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-defects.html#179
.. _280: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#280
Iterator Facade
@ -195,7 +204,7 @@ which were easily implemented using ``iterator_adaptor``:
* ``filter_iterator``, which provides a view of an iterator range in
which some elements of the underlying range are skipped.
.. _counting_iterator:
.. _counting:
* ``counting_iterator``, which adapts any incrementable type
(e.g. integers, iterators) so that incrementing/decrementing the
@ -226,15 +235,13 @@ Header ``<iterator_helper>`` synopsis [lib.iterator.helper.synopsis]
::
struct use_default;
const unsigned use_default_access = -1;
struct iterator_core_access { /* implementation detail */ };
template <
class Derived
, class Value
, unsigned AccessCategory
, class TraversalCategory
, class CategoryOrTraversal
, class Reference = Value&
, class Difference = ptrdiff_t
>
@ -244,8 +251,7 @@ Header ``<iterator_helper>`` synopsis [lib.iterator.helper.synopsis]
class Derived
, class Base
, class Value = use_default
, unsigned Access = use_default_access
, class Traversal = use_default
, class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
@ -254,8 +260,7 @@ Header ``<iterator_helper>`` synopsis [lib.iterator.helper.synopsis]
template <
class Iterator
, class Value = use_default
, unsigned Access = use_default_access
, class Traversal = use_default
, class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
@ -277,8 +282,7 @@ Header ``<iterator_helper>`` synopsis [lib.iterator.helper.synopsis]
template <
class Incrementable
, unsigned Access = use_default_access
, class Traversal = use_default
, class CategoryOrTraversal = use_default
, class Difference = use_default
>
class counting_iterator
@ -312,17 +316,35 @@ Class template ``iterator_adaptor``
Specialized adaptors [lib.iterator.special.adaptors]
====================================================
.. The requirements for all of these need to be written *much* more
formally -DWA
[*Note:* The ``enable_if_convertible<X,Y>::type`` expression used in
The ``enable_if_convertible<X,Y>::type`` expression used in
this section is for exposition purposes. The converting constructors
for specialized adaptors should be only be in an overload set provided
that an object of type ``X`` is implicitly convertible to an object of
type ``Y``. The ``enable_if_convertible`` approach uses SFINAE to
type ``Y``.
The signatures involving ``enable_if_convertible`` should behave
*as-if* ``enable_if_convertible`` were defined to be::
template <bool> enable_if_convertible_impl
{};
template <> enable_if_convertible_impl<true>
{ struct type; };
template<typename From, typename To>
struct enable_if_convertible
: enable_if_convertible_impl<is_convertible<From,To>::value>
{};
If an expression other than the default argument is used to supply
the value of a function parameter whose type is written in terms
of ``enable_if_convertible``, the program is ill-formed, no
diagnostic required.
[*Note:* The ``enable_if_convertible`` approach uses SFINAE to
take the constructor out of the overload set when the types are not
implicitly convertible.]
implicitly convertible.
]
Indirect iterator
@ -393,8 +415,7 @@ Class template ``function_output_iterator``
..
LocalWords: Abrahams Siek Witt istream ostream iter MTL strided interoperate
.. LocalWords: Abrahams Siek Witt istream ostream iter MTL strided interoperate
LocalWords: CRTP metafunctions inlining lvalue JGS incrementable BGL LEDA cv
LocalWords: GraphBase struct ptrdiff UnaryFunction const int typename bool pp
LocalWords: lhs rhs SFINAE markup iff tmp OtherDerived OtherIterator DWA foo

208
doc/filter_iterator.html
View File

@ -9,7 +9,198 @@
<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="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
<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="filter-iterator">
@ -97,12 +288,13 @@ class filter_iterator
</pre>
<div class="section" id="filter-iterator-requirements">
<h1><a class="toc-backref" href="#id1" name="filter-iterator-requirements"><tt class="literal"><span class="pre">filter_iterator</span></tt> requirements</a></h1>
<p>The base <tt class="literal"><span class="pre">Iterator</span></tt> parameter must be a model of Readable Iterator
and Single Pass Iterator. The resulting <tt class="literal"><span class="pre">filter_iterator</span></tt> will be a
model of Forward Traversal Iterator if <tt class="literal"><span class="pre">Iterator</span></tt> is, otherwise the
<tt class="literal"><span class="pre">filter_iterator</span></tt> will be a model of Single Pass Iterator. The
access category of the <tt class="literal"><span class="pre">filter_iterator</span></tt> will be the most refined
standard access category that is modeled by <tt class="literal"><span class="pre">Iterator</span></tt>.</p>
<p>The base <tt class="literal"><span class="pre">Iterator</span></tt> parameter must be a model of Readable
Iterator and Single Pass Iterator. The resulting
<tt class="literal"><span class="pre">filter_iterator</span></tt> will be a model of Forward Traversal Iterator
if <tt class="literal"><span class="pre">Iterator</span></tt> is, otherwise the <tt class="literal"><span class="pre">filter_iterator</span></tt> will be a
model of Single Pass Iterator. The access category of the
<tt class="literal"><span class="pre">filter_iterator</span></tt> will be the same as the access category of
<tt class="literal"><span class="pre">Iterator</span></tt>.</p>
<!-- Thomas is going to try implementing filter_iterator so that
it will be bidirectional if the underlying iterator is. -JGS -->
<p>The <tt class="literal"><span class="pre">Predicate</span></tt> must be Assignable, Copy Constructible, and the
@ -189,7 +381,7 @@ filter_iterator(
<hr class="footer" />
<div class="footer">
<a class="reference" href="filter_iterator.rst">View document source</a>.
Generated on: 2003-09-21 09:34 UTC.
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>

197
doc/function_output_iterator.html
View File

@ -9,7 +9,198 @@
<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="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
<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="function-output-iterator">
@ -60,7 +251,7 @@ template &lt;class UnaryFunction&gt;
class function_output_iterator {
public:
typedef iterator_tag&lt;
writable_iterator_tag
writable_iterator
, incrementable_traversal_tag
&gt; iterator_category;
typedef void value_type;
@ -158,7 +349,7 @@ return *this;
<hr class="footer" />
<div class="footer">
<a class="reference" href="function_output_iterator.rst">View document source</a>.
Generated on: 2003-09-21 09:34 UTC.
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>

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>

98
doc/index.rst
View File

@ -1,5 +1,5 @@
+++++++++++++++++++++++++++++++++++++++++++++++++
The Boost Iterator Library |(logo)|__
The Boost.Iterator Library |(logo)|__
+++++++++++++++++++++++++++++++++++++++++++++++++
.. |(logo)| image:: ../../../c++boost.gif
@ -25,17 +25,19 @@ __ ../../../index.htm
:Abstract: The Boost Iterator Library contains two parts. The first
is a system of concepts_ 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.
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.
.. _concepts: ../../../more/generic_programming.html#concept
@ -77,25 +79,25 @@ __ new-iter-concepts.html
Iterator Facade and Adaptor
=============================
Writing standard-conforming iterators is tricky. In order to ease the
implementation of new iterators, the iterator library provides the
|facade|_ 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
|adaptor|_ class template, which is specially designed to
take advantage of as much of the underlying iterator's behavior as
possible.
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 |facade|_ 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 |adaptor|_ class
template, which is specially designed to take advantage of as much
of the underlying iterator's behavior as possible.
.. |facade| replace:: ``iterator_facade``
.. _facade: iterator_facade.html
.. |adaptor| replace:: ``iterator_adaptor``
.. _adaptor: iterator_adaptor.html
Both |facade|_ and |adaptor|_ as well as many of
the `specialized adaptors`_ mentioned below have been proposed for
standardization; see our
Both |facade|_ and |adaptor|_ as well as many of the `specialized
adaptors`_ mentioned below have been proposed for standardization,
and accepted into the first C++ technical report; see our
`Standard Proposal For Iterator Facade and Adaptor`__
@ -189,10 +191,33 @@ Testing and Concept Checking
Upgrading from the old Boost Iterator Adaptor Library
=======================================================
Turn your policy class into the body of the iterator
.. _Upgrading:
Use transform_iterator with a true reference type for
projection_iterator.
If you have been using the old Boost Iterator Adaptor library to
implement iterators, you probably wrote a ``Policies`` 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 `type generator`_ to build the
``iterator_adaptor`` 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) [Cop95]_,
you can now define the iterator class yourself and acquire
functionality through inheritance from ``iterator_facade`` or
``iterator_adaptor``. 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.
.. _`type generator`: ../../../more/generic_programming.html#type_generator
If you're looking for the old ``projection_iterator`` component,
its functionality has been merged into ``transform_iterator``: as
long as the function object's ``result_type`` (or the ``Reference``
template argument, if explicitly specified) is a true reference
type, ``transform_iterator`` will behave like
``projection_iterator`` used to.
=========
History
@ -211,10 +236,21 @@ which was reviewed and accepted into the library. They wrote a paper
and made several important revisions of the code.
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...
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 ``iterator_facade``, and
factored it out of ``iterator_adaptor``. Finally, after a
near-complete rewrite of the prototype, they came up with the
library you see today.
.. [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template
Patterns, C++ Report, February 1995, pp. 24-27.
..
LocalWords: Abrahams Siek Witt const bool Sutter's WG int UL LI href Lvalue

213
doc/indirect_iterator.html
View File

@ -9,7 +9,198 @@
<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="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
<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="indirect-iterator">
@ -58,7 +249,8 @@ iterators over smart pointers, which the impl handles. -JGS -->
template &lt;
class Iterator
, class Value = use_default
, class Category = use_default
, unsigned Access = use_default_access
, class Traversal = use_default
, class Reference = use_default
, class Difference = use_default
&gt;
@ -70,12 +262,12 @@ class indirect_iterator
indirect_iterator();
indirect_iterator(Iterator x);
template &lt;
class Iterator2, class Value2, class Category2
class Iterator2, class Value2, unsigned Access2, class Traversal2
, class Reference2, class Difference2
&gt;
indirect_iterator(
indirect_iterator&lt;
Iterator2, Value2, Category2, Reference2, Difference2
Iterator2, Value2, Access2, Traversal2, Reference2, Difference2
&gt; const&amp; y
, typename enable_if_convertible&lt;Iterator2, Iterator&gt;::type* = 0 // exposition
);
@ -103,9 +295,10 @@ specialization of <tt class="literal"><span class="pre">iterator_traits</span></
iterator.</p>
<p>The <tt class="literal"><span class="pre">Reference</span></tt> parameter will be the <tt class="literal"><span class="pre">reference</span></tt> type of the
<tt class="literal"><span class="pre">indirect_iterator</span></tt>. The default is <tt class="literal"><span class="pre">Value&amp;</span></tt>.</p>
<p>The <tt class="literal"><span class="pre">Category</span></tt> parameter is the <tt class="literal"><span class="pre">iterator_category</span></tt> type for the
<tt class="literal"><span class="pre">indirect_iterator</span></tt>. The default is
<tt class="literal"><span class="pre">iterator_traits&lt;Iterator&gt;::iterator_category</span></tt>.</p>
<p>The <tt class="literal"><span class="pre">Access</span></tt> and <tt class="literal"><span class="pre">Traversal</span></tt> parameters are passed unchanged to
the corresponding parameters of the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> base
class, and the <tt class="literal"><span class="pre">Iterator</span></tt> parameter is passed unchanged as the
<tt class="literal"><span class="pre">Base</span></tt> parameter to the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class.</p>
<p>The indirect iterator will model the most refined standard traversal
concept that is modeled by the <tt class="literal"><span class="pre">Iterator</span></tt> type. The indirect
iterator will model the most refined standard access concept that is
@ -137,12 +330,12 @@ the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> subobject
</table>
<pre class="literal-block">
template &lt;
class Iterator2, class Value2, class Category2
class Iterator2, class Value2, unsigned Access, class Traversal
, class Reference2, class Difference2
&gt;
indirect_iterator(
indirect_iterator&lt;
Iterator2, Value2, Category2, Reference2, Difference2
Iterator2, Value2, Access, Traversal, Reference2, Difference2
&gt; const&amp; y
, typename enable_if_convertible&lt;Iterator2, Iterator&gt;::type* = 0 // exposition
);
@ -162,7 +355,7 @@ indirect_iterator(
<hr class="footer" />
<div class="footer">
<a class="reference" href="indirect_iterator.rst">View document source</a>.
Generated on: 2003-09-21 09:34 UTC.
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>

332
doc/iterator_adaptor.html
View File

@ -9,7 +9,198 @@
<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="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
<style type="text/css"><!--
/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date$
:version: $Revision$
:copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
*/
.first {
margin-top: 0 }
.last {
margin-bottom: 0 }
a.toc-backref {
text-decoration: none ;
color: black }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr {
width: 75% }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.line-block {
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em ;
background-color: #eeeeee }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option-argument {
font-style: italic }
span.pre {
white-space: pre }
span.problematic {
color: red }
table {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.citation {
border-left: solid thin gray ;
padding-left: 0.5ex }
table.docinfo {
margin: 2em 4em }
table.footnote {
border-left: solid thin black ;
padding-left: 0.5ex }
td, th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
th.docinfo-name, th.field-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap }
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
font-size: 100% }
tt {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
--></style>
</head>
<body>
<div class="document" id="iterator-adaptor">
@ -40,8 +231,12 @@ Railway Operation and Construction</a></td></tr>
</tr>
</tbody>
</table>
<p>The <tt class="literal"><span class="pre">iterator_adaptor</span></tt> is a base class template derived from an
instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt>. The core interface functions
<!-- Version 1.1 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved -->
<p>Each specialization of the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> class template is derived from
a specialization of <tt class="literal"><span class="pre">iterator_facade</span></tt>. The core interface functions
expected by <tt class="literal"><span class="pre">iterator_facade</span></tt> are implemented in terms of the
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="literal"><span class="pre">Base</span></tt> template parameter. A class derived
from <tt class="literal"><span class="pre">iterator_adaptor</span></tt> typically redefines some of the core
@ -55,16 +250,21 @@ core interface functions of <tt class="literal"><span class="pre">iterator_facad
<ul class="simple">
<li><a class="reference" href="#introduction" id="id3" name="id3">Introduction</a></li>
<li><a class="reference" href="#reference" id="id4" name="id4">Reference</a><ul>
<li><a class="reference" href="#iterator-adaptor-requirements" id="id5" name="id5"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></li>
<li><a class="reference" href="#iterator-adaptor-public-operations" id="id6" name="id6"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></li>
<li><a class="reference" href="#iterator-adaptor-protected-member-functions" id="id7" name="id7"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></li>
<li><a class="reference" href="#iterator-adaptor-private-member-functions" id="id8" name="id8"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></li>
<li><a class="reference" href="#iterator-adaptor-base-class-parameters" id="id5" name="id5"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></li>
<li><a class="reference" href="#iterator-adaptor-usage" id="id6" name="id6"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> usage</a></li>
<li><a class="reference" href="#iterator-adaptor-public-operations" id="id7" name="id7"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></li>
<li><a class="reference" href="#iterator-adaptor-protected-member-functions" id="id8" name="id8"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></li>
<li><a class="reference" href="#iterator-adaptor-private-member-functions" id="id9" name="id9"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id3" name="introduction">Introduction</a></h1>
<!-- Version 1.2 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved -->
<p>The <tt class="literal"><span class="pre">iterator_adaptor</span></tt> class template adapts some <tt class="literal"><span class="pre">Base</span></tt> <a class="footnote-reference" href="#base" id="id1" name="id1"><sup>1</sup></a>
type to create a new iterator. Instantiations of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>
are derived from a corresponding instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt>
@ -87,31 +287,36 @@ above. The <tt class="literal"><span class="pre">Base</span></tt> type need not
iterator. It need only support the operations used by the core
interface functions of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> that have not been
redefined in the user's derived class.</p>
<p>Several of the template parameters of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> default to
<tt class="literal"><span class="pre">use_default</span></tt>. This allows the user to make use of a default
parameter even when the user wants to specify a parameter later in the
parameter list. Also, the defaults for the corresponding associated
types are fairly complicated, so metaprogramming is required to
compute them, and <tt class="literal"><span class="pre">use_default</span></tt> can help to simplify the
implementation. Finally, <tt class="literal"><span class="pre">use_default</span></tt> is not left unspecified
<p>Several of the template parameters of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> default
to <tt class="literal"><span class="pre">use_default</span></tt>. This allows the
user to make use of a default parameter even when she wants to
specify a parameter later in the parameter list. Also, the
defaults for the corresponding associated types are somewhat
complicated, so metaprogramming is required to compute them, and
<tt class="literal"><span class="pre">use_default</span></tt> can help to simplify the implementation. Finally,
the identity of the <tt class="literal"><span class="pre">use_default</span></tt> type is not left unspecified
because specification helps to highlight that the <tt class="literal"><span class="pre">Reference</span></tt>
template parameter may not always be identical to the iterator's
<tt class="literal"><span class="pre">reference</span></tt> type, and will keep users making mistakes based on that
assumption.</p>
<tt class="literal"><span class="pre">reference</span></tt> type, and will keep users from making mistakes based on
that assumption.</p>
</div>
<div class="section" id="reference">
<h1><a class="toc-backref" href="#id4" name="reference">Reference</a></h1>
<!-- Version 1.4 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved. -->
<pre class="literal-block">
template &lt;
class Derived
, class Base
, class Value = use_default
, class Category = use_default
, class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
&gt;
class iterator_adaptor
: public iterator_facade&lt;Derived, /* see <a class="reference" href=":">details</a> ...*/&gt;
: public iterator_facade&lt;Derived, <em>V</em>, <em>C</em>, <em>R</em>, <em>D</em>&gt; // see <a class="reference" href=":">details</a>
{
friend class iterator_core_access;
public:
@ -140,68 +345,53 @@ class iterator_adaptor
iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; y) const;
private:
Base m_iterator;
Base m_iterator; // exposition only
};
</pre>
<div class="section" id="iterator-adaptor-requirements">
<h2><a class="toc-backref" href="#id5" name="iterator-adaptor-requirements"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></h2>
<p>The <tt class="literal"><span class="pre">Derived</span></tt> template parameter must be a derived class of
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>. The <tt class="literal"><span class="pre">Base</span></tt> type must implement the
expressions involving <tt class="literal"><span class="pre">m_iterator</span></tt> in the specifications of those
private member functions of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> that are not
redefined by the <tt class="literal"><span class="pre">Derived</span></tt> class and that are needed to model the
concept corresponding to the <tt class="literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="literal"><span class="pre">category</span></tt>
typedef according to the requirements of <tt class="literal"><span class="pre">iterator_facade</span></tt>. The
rest of the template parameters specify the types for the member
typedefs in <tt class="literal"><span class="pre">iterator_facade</span></tt>. The following pseudo-code
specifies the traits types for <tt class="literal"><span class="pre">iterator_adaptor</span></tt>.</p>
<div class="section" id="iterator-adaptor-base-class-parameters">
<h2><a class="toc-backref" href="#id5" name="iterator-adaptor-base-class-parameters"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></h2>
<p>The <em>V</em>, <em>C</em>, <em>R</em>, and <em>D</em> parameters of the <tt class="literal"><span class="pre">iterator_facade</span></tt>
used as a base class in the summary of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>
above are defined as follows:</p>
<pre class="literal-block">
if (Value == use_default)
value_type = iterator_traits&lt;Base&gt;::value_type;
<em>V</em> = if (Value is use_default)
return iterator_traits&lt;Base&gt;::value_type
else
value_type = remove_cv&lt;Value&gt;::type;
return Value
if (Reference == use_default) {
if (Value == use_default)
reference = iterator_traits&lt;Base&gt;::reference;
<em>C</em> = if (CategoryOrTraversal is use_default)
return iterator_traversal&lt;Base&gt;::type
else
reference = Value&amp;;
} else
reference = Reference;
return CategoryOrTraversal
if (Distance == use_default)
difference_type = iterator_traits&lt;Base&gt;::difference_type;
<em>R</em> = if (Reference is use_default)
if (Value is use_default)
return iterator_traits&lt;Base&gt;::reference
else
difference_type = Distance;
if (Category == use_default)
iterator_category = iterator_tag&lt;
access_category&lt; Base &gt;,
traversal_category&lt; Base &gt;
&gt;
else if (Category is an access tag)
iterator_category = iterator_tag&lt;
Category
...
else if (Category is a traversal tag)
...
return Value&amp;
else
iterator_category = Category;
// Actually the above is wrong. See the use of
// access_category_tag and
// new_category_to_access/iter_category_to_access.
return Reference
<em>D</em> = if (Difference is use_default)
return iterator_traits&lt;Base&gt;::difference_type
else
return Difference
</pre>
<!-- Replaced with new semantics - -thw
if (Category == use_default)
iterator_category = iterator_traits<Base>::iterator_category;
else
iterator_category = Category;
Fix this up!! -->
</div>
<div class="section" id="iterator-adaptor-usage">
<h2><a class="toc-backref" href="#id6" name="iterator-adaptor-usage"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> usage</a></h2>
<p>The <tt class="literal"><span class="pre">Derived</span></tt> template parameter must be a publicly derived from
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>. In order for <tt class="literal"><span class="pre">Derived</span></tt> to model the
iterator concepts corresponding to
<tt class="literal"><span class="pre">iterator_traits&lt;Derived&gt;::iterator_category</span></tt>, the expressions
involving <tt class="literal"><span class="pre">m_iterator</span></tt> in the specifications of those private
member functions of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> that may be called by
<tt class="literal"><span class="pre">iterator_facade&lt;Derived,</span> <span class="pre">``\</span> <span class="pre">*V*\</span></tt>, <tt class="literal"><span class="pre">\</span> <span class="pre">*C*\</span></tt>, <tt class="literal"><span class="pre">\</span> <span class="pre">*R*\</span></tt>, <tt class="literal"><span class="pre">\</span>
<span class="pre">*D*\</span></tt>&gt;`` in evaluating any valid expression involving <tt class="literal"><span class="pre">Derived</span></tt>
in those concepts' requirements.</p>
</div>
<div class="section" id="iterator-adaptor-public-operations">
<h2><a class="toc-backref" href="#id6" name="iterator-adaptor-public-operations"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></h2>
<h2><a class="toc-backref" href="#id7" name="iterator-adaptor-public-operations"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></h2>
<p><tt class="literal"><span class="pre">iterator_adaptor();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -235,7 +425,7 @@ Fix this up!! -->
</table>
</div>
<div class="section" id="iterator-adaptor-protected-member-functions">
<h2><a class="toc-backref" href="#id7" name="iterator-adaptor-protected-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h2>
<h2><a class="toc-backref" href="#id8" name="iterator-adaptor-protected-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h2>
<p><tt class="literal"><span class="pre">Base</span> <span class="pre">const&amp;</span> <span class="pre">base_reference()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -256,7 +446,7 @@ Fix this up!! -->
</table>
</div>
<div class="section" id="iterator-adaptor-private-member-functions">
<h2><a class="toc-backref" href="#id8" name="iterator-adaptor-private-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></h2>
<h2><a class="toc-backref" href="#id9" name="iterator-adaptor-private-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></h2>
<p><tt class="literal"><span class="pre">typename</span> <span class="pre">iterator_adaptor::reference</span> <span class="pre">dereference()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -328,7 +518,7 @@ typename iterator_adaptor::difference_type distance_to(
<hr class="footer" />
<div class="footer">
<a class="reference" href="iterator_adaptor.rst">View document source</a>.
Generated on: 2003-09-21 09:34 UTC.
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>

10
doc/iterator_adaptor_abstract.rst
View File

@ -1,5 +1,11 @@
The ``iterator_adaptor`` is a base class template derived from an
instantiation of ``iterator_facade``. The core interface functions
.. Version 1.1 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG.
.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved
Each specialization of the ``iterator_adaptor`` class template is derived from
a specialization of ``iterator_facade``. The core interface functions
expected by ``iterator_facade`` are implemented in terms of the
``iterator_adaptor``\ 's ``Base`` template parameter. A class derived
from ``iterator_adaptor`` typically redefines some of the core

10
doc/iterator_adaptor_body.rst
View File

@ -1,3 +1,9 @@
.. Version 1.2 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1.
.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved
The ``iterator_adaptor`` class template adapts some ``Base`` [#base]_
type to create a new iterator. Instantiations of ``iterator_adaptor``
are derived from a corresponding instantiation of ``iterator_facade``
@ -19,7 +25,7 @@ interface functions of ``iterator_adaptor`` that have not been
redefined in the user's derived class.
Several of the template parameters of ``iterator_adaptor`` default
to ``use_default`` (or ``use_default_access``). This allows the
to ``use_default``. This allows the
user to make use of a default parameter even when she wants to
specify a parameter later in the parameter list. Also, the
defaults for the corresponding associated types are somewhat
@ -28,6 +34,6 @@ complicated, so metaprogramming is required to compute them, and
the identity of the ``use_default`` type is not left unspecified
because specification helps to highlight that the ``Reference``
template parameter may not always be identical to the iterator's
``reference`` type, and will keep users making mistakes based on
``reference`` type, and will keep users from making mistakes based on
that assumption.

98
doc/iterator_adaptor_ref.rst
View File

@ -1,17 +1,21 @@
.. Version 1.4 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1.
.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved.
.. parsed-literal::
bool
template <
class Derived
, class Base
, class Value = use_default
, unsigned Access = use_default_access
, class Traversal = use_default
, class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
class iterator_adaptor
: public iterator_facade<Derived, /* see details__ ...\*/>
: public iterator_facade<Derived, *V*, *C*, *R*, *D*> // see details__
{
friend class iterator_core_access;
public:
@ -40,69 +44,55 @@
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
private:
Base m_iterator;
Base m_iterator; // exposition only
};
__ : THE LINK HERE IS MISSING!
__ :
``iterator_adaptor`` requirements
---------------------------------
``iterator_adaptor`` base class parameters
------------------------------------------
The ``Derived`` template parameter must be a derived class of
``iterator_adaptor``. The ``Base`` type must implement the
expressions involving ``m_iterator`` in the specifications of those
private member functions of ``iterator_adaptor`` that are not
redefined by the ``Derived`` class and that are needed to model the
concept corresponding to
``iterator_traits<Derived>::iterator_category`` according to the
requirements of ``iterator_facade``. The rest of the template
parameters specify the types for the member typedefs in
``iterator_facade``. The following pseudo-code specifies the
traits types for ``iterator_adaptor``.
The *V*, *C*, *R*, and *D* parameters of the ``iterator_facade``
used as a base class in the summary of ``iterator_adaptor``
above are defined as follows:
::
.. parsed-literal::
if (Value != use_default)
value_type = remove_cv<Value>::type;
*V* = if (Value is use_default)
return iterator_traits<Base>::value_type
else
value_type = iterator_traits<Base>::value_type;
return Value
if (Traversal != use_default)
traversal_category = Traversal
*C* = if (CategoryOrTraversal is use_default)
return iterator_traversal<Base>::type
else
traversal_category = traversal_category< Base >::type
return CategoryOrTraversal
iterator_category = iterator_tag<
access_category
, traversal_category
>
if (Access != use_default)
{
access_category = Access
}
*R* = if (Reference is use_default)
if (Value is use_default)
return iterator_traits<Base>::reference
else
{
access_category
= access_category< Base >::value
if (is_const<Value>)
access_category &= ~writable_iterator;
}
iterator_category = iterator_tag<
access_category
, traversal_category
>
if (Reference != use_default)
reference = Reference
else if (Value != use_default)
reference = Value&
return Value&
else
reference = iterator_traits<Base>::reference
return Reference
*D* = if (Difference is use_default)
return iterator_traits<Base>::difference_type
else
return Difference
``iterator_adaptor`` usage
--------------------------
The ``Derived`` template parameter must be a publicly derived from
``iterator_adaptor``. In order for ``Derived`` to model the
iterator concepts corresponding to
``iterator_traits<Derived>::iterator_category``, the expressions
involving ``m_iterator`` in the specifications of those private
member functions of ``iterator_adaptor`` that may be called by
``iterator_facade<Derived, ``\ *V*\``, ``\ *C*\``, ``\ *R*\``, ``\
*D*\``>`` in evaluating any valid expression involving ``Derived``
in those concepts' requirements.
``iterator_adaptor`` public operations
--------------------------------------

490
doc/iterator_facade.html
View File

@ -9,7 +9,198 @@
<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="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
<style type="text/css"><!--
/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date$
:version: $Revision$
:copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
*/
.first {
margin-top: 0 }
.last {
margin-bottom: 0 }
a.toc-backref {
text-decoration: none ;
color: black }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr {
width: 75% }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.line-block {
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em ;
background-color: #eeeeee }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option-argument {
font-style: italic }
span.pre {
white-space: pre }
span.problematic {
color: red }
table {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.citation {
border-left: solid thin gray ;
padding-left: 0.5ex }
table.docinfo {
margin: 2em 4em }
table.footnote {
border-left: solid thin black ;
padding-left: 0.5ex }
td, th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
th.docinfo-name, th.field-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap }
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
font-size: 100% }
tt {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
--></style>
</head>
<body>
<div class="document" id="iterator-facade">
@ -46,20 +237,25 @@ and associated types, to be supplied by a derived iterator class.</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="#motivation" id="id10" name="id10">Motivation</a></li>
<li><a class="reference" href="#usage" id="id11" name="id11">Usage</a></li>
<li><a class="reference" href="#iterator-core-access" id="id12" name="id12">Iterator Core Access</a></li>
<li><a class="reference" href="#operator" id="id13" name="id13"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>
<li><a class="reference" href="#id3" id="id14" name="id14"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li>
<li><a class="reference" href="#reference" id="id15" name="id15">Reference</a><ul>
<li><a class="reference" href="#id8" id="id16" name="id16"><tt class="literal"><span class="pre">iterator_facade</span></tt> requirements</a></li>
<li><a class="reference" href="#iterator-facade-operations" id="id17" name="id17"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>
<li><a class="reference" href="#motivation" id="id7" name="id7">Motivation</a></li>
<li><a class="reference" href="#usage" id="id8" name="id8">Usage</a></li>
<li><a class="reference" href="#iterator-core-access" id="id9" name="id9">Iterator Core Access</a></li>
<li><a class="reference" href="#operator" id="id10" name="id10"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>
<li><a class="reference" href="#id2" id="id11" name="id11"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li>
<li><a class="reference" href="#reference" id="id12" name="id12">Reference</a><ul>
<li><a class="reference" href="#iterator-facade-usage" id="id13" name="id13"><tt class="literal"><span class="pre">iterator_facade</span></tt> usage</a></li>
<li><a class="reference" href="#iterator-facade-iterator-category" id="id14" name="id14"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></li>
<li><a class="reference" href="#iterator-facade-operations" id="id15" name="id15"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="motivation">
<h1><a class="toc-backref" href="#id10" name="motivation">Motivation</a></h1>
<h1><a class="toc-backref" href="#id7" name="motivation">Motivation</a></h1>
<!-- Version 1.1 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved -->
<p>While the iterator interface is rich, there is a core subset of the
interface that is necessary for all the functionality. We have
identified the following core behaviors for iterators:</p>
@ -91,7 +287,7 @@ implementations.</li>
<li>Without the use of CRTP, the standard requirement that an
iterator's <tt class="literal"><span class="pre">operator++</span></tt> returns the iterator type itself means
that all iterators generated by <tt class="literal"><span class="pre">iterator_facade</span></tt> would be
instantiations of <tt class="literal"><span class="pre">iterator_facade</span></tt>. Cumbersome type generator
specializations of <tt class="literal"><span class="pre">iterator_facade</span></tt>. Cumbersome type generator
metafunctions would be needed to build new parameterized
iterators, and a separate <tt class="literal"><span class="pre">iterator_adaptor</span></tt> layer would be
impossible.</li>
@ -99,9 +295,9 @@ impossible.</li>
</blockquote>
</div>
<div class="section" id="usage">
<h1><a class="toc-backref" href="#id11" name="usage">Usage</a></h1>
<h1><a class="toc-backref" href="#id8" name="usage">Usage</a></h1>
<p>The user of <tt class="literal"><span class="pre">iterator_facade</span></tt> derives his iterator class from an
instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt> which takes the derived iterator
specialization of <tt class="literal"><span class="pre">iterator_facade</span></tt> which takes the derived iterator
class as the first template parameter. The order of the other
template parameters to <tt class="literal"><span class="pre">iterator_facade</span></tt> have been carefully chosen
to take advantage of useful defaults. For example, when defining a
@ -162,7 +358,7 @@ Iterator or a more-refined iterator concept, a default constructor is
required.</p>
</div>
<div class="section" id="iterator-core-access">
<h1><a class="toc-backref" href="#id12" name="iterator-core-access">Iterator Core Access</a></h1>
<h1><a class="toc-backref" href="#id9" name="iterator-core-access">Iterator Core Access</a></h1>
<p><tt class="literal"><span class="pre">iterator_facade</span></tt> and the operator implementations need to be able
to access the core member functions in the derived class. Making the
core member functions public would expose an implementation detail to
@ -196,18 +392,18 @@ open a safety loophole, as every core member function preserves the
invariants of the iterator.</p>
</div>
<div class="section" id="operator">
<h1><a class="toc-backref" href="#id13" name="operator"><tt class="literal"><span class="pre">operator[]</span></tt></a></h1>
<h1><a class="toc-backref" href="#id10" name="operator"><tt class="literal"><span class="pre">operator[]</span></tt></a></h1>
<p>The indexing operator for a generalized iterator presents special
challenges. A random access iterator's <tt class="literal"><span class="pre">operator[]</span></tt> is only
required to return something convertible to its <tt class="literal"><span class="pre">value_type</span></tt>.
Requiring that it return an lvalue would rule out currently-legal
random-access iterators which hold the referenced value in a data
member (e.g. <a class="reference" href="counting_iterator.html">counting_iterator</a>), because <tt class="literal"><span class="pre">*(p+n)</span></tt> is a reference
member (e.g. <a class="reference" href="counting_iterator.html"><tt class="literal"><span class="pre">counting_iterator</span></tt></a>), because <tt class="literal"><span class="pre">*(p+n)</span></tt> is a reference
into the temporary iterator <tt class="literal"><span class="pre">p+n</span></tt>, which is destroyed when
<tt class="literal"><span class="pre">operator[]</span></tt> returns.</p>
<p>Writable iterators built with <tt class="literal"><span class="pre">iterator_facade</span></tt> implement the
semantics required by the preferred resolution to <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299">issue 299</a> and
adopted by proposal <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html">n1477</a>: the result of <tt class="literal"><span class="pre">p[n]</span></tt> is a proxy object
adopted by proposal <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1550.html">n1550</a>: the result of <tt class="literal"><span class="pre">p[n]</span></tt> is a proxy object
containing a copy of <tt class="literal"><span class="pre">p+n</span></tt>, and <tt class="literal"><span class="pre">p[n]</span> <span class="pre">=</span> <span class="pre">x</span></tt> is equivalent to <tt class="literal"><span class="pre">*(p</span>
<span class="pre">+</span> <span class="pre">n)</span> <span class="pre">=</span> <span class="pre">x</span></tt>. This approach will work properly for any random-access
iterator regardless of the other details of its implementation. A
@ -216,8 +412,8 @@ to implement an <tt class="literal"><span class="pre">operator[]</span></tt> whi
iterator class; it will hide the one supplied by <tt class="literal"><span class="pre">iterator_facade</span></tt>
from clients of her iterator.</p>
<a class="target" id="operator-arrow" name="operator-arrow"></a></div>
<div class="section" id="id3">
<h1><a class="toc-backref" href="#id14" name="id3"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></h1>
<div class="section" id="id2">
<h1><a class="toc-backref" href="#id11" name="id2"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></h1>
<p>The <tt class="literal"><span class="pre">reference</span></tt> type of a readable iterator (and today's input
iterator) need not in fact be a reference, so long as it is
convertible to the iterator's <tt class="literal"><span class="pre">value_type</span></tt>. When the <tt class="literal"><span class="pre">value_type</span></tt>
@ -227,7 +423,7 @@ type is not in fact a reference must return a proxy containing a copy
of the referenced value from its <tt class="literal"><span class="pre">operator-&gt;</span></tt>.</p>
<p>The return type for <tt class="literal"><span class="pre">operator-&gt;</span></tt> and <tt class="literal"><span class="pre">operator[]</span></tt> is not
explicitly specified. Instead it requires each <tt class="literal"><span class="pre">iterator_facade</span></tt>
instantiation to meet the requirements of its <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
specialization to meet the requirements of its <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
<table class="citation" frame="void" id="cop95" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<col />
@ -238,23 +434,26 @@ Patterns, C++ Report, February 1995, pp. 24-27.</td></tr>
</table>
</div>
<div class="section" id="reference">
<h1><a class="toc-backref" href="#id15" name="reference">Reference</a></h1>
<h1><a class="toc-backref" href="#id12" name="reference">Reference</a></h1>
<!-- Version 1.3 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved -->
<pre class="literal-block">
template &lt;
class Derived
, class Value
, class AccessCategory
, class TraversalCategory
, class Reference = /* see <a class="reference" href="#iterator-facade-requirements">below</a> */
, class CategoryOrTraversal
, class Reference = Value&amp;
, class Difference = ptrdiff_t
&gt;
class iterator_facade {
public:
typedef remove_cv&lt;Value&gt;::type value_type;
typedef remove_const&lt;Value&gt;::type value_type;
typedef Reference reference;
typedef /* see <a class="reference" href="#operator-arrow">description of operator-&gt;</a> */ pointer;
typedef Value* pointer;
typedef Difference difference_type;
typedef iterator_tag&lt;AccessCategory, TraversalCategory&gt; iterator_category;
typedef /* see <a class="reference" href="#facade-iterator-category">below</a> */ iterator_category;
reference operator*() const;
/* see <a class="reference" href="#operator-arrow">below</a> */ operator-&gt;() const;
@ -269,104 +468,114 @@ public:
};
// Comparison operators
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
template &lt;class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type // exposition
operator ==(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator ==(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
template &lt;class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator !=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator !=(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
template &lt;class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator &lt;(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator &lt;(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
template &lt;class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator &lt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator &lt;=(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
template &lt;class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator &gt;(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator &gt;(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
template &lt;class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator &gt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator &gt;=(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
template &lt;class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator &gt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator &gt;=(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
// Iterator difference
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
template &lt;class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator -(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator -(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
// Iterator addition
template &lt;class Derived, class V, class AC, class TC, class R, class D&gt;
Derived operator+ (iterator_facade&lt;Derived, V, AC, TC, R, D&gt; const&amp;,
template &lt;class Derived, class V, class TC, class R, class D&gt;
Derived operator+ (iterator_facade&lt;Derived, V, TC, R, D&gt; const&amp;,
typename Derived::difference_type n)
</pre>
<p>[<em>Note:</em> The <tt class="literal"><span class="pre">enable_if_interoperable</span></tt> template used above is for exposition
<p>The <tt class="literal"><span class="pre">enable_if_interoperable</span></tt> template used above is for exposition
purposes. The member operators should be only be in an overload set
provided the derived types <tt class="literal"><span class="pre">Dr1</span></tt> and <tt class="literal"><span class="pre">Dr2</span></tt> are interoperable, by
which we mean they are convertible to each other. The
provided the derived types <tt class="literal"><span class="pre">Dr1</span></tt> and <tt class="literal"><span class="pre">Dr2</span></tt> are interoperable,
meaning that at least one of the types is convertible to the other. The
<tt class="literal"><span class="pre">enable_if_interoperable</span></tt> approach uses SFINAE to take the operators
out of the overload set when the types are not interoperable.]</p>
<!-- we need a new label here because the presence of markup in the
title prevents an automatic link from being generated -->
<a class="target" id="iterator-facade-requirements" name="iterator-facade-requirements"></a><div class="section" id="id8">
<h2><a class="toc-backref" href="#id16" name="id8"><tt class="literal"><span class="pre">iterator_facade</span></tt> requirements</a></h2>
<p>The <tt class="literal"><span class="pre">Derived</span></tt> template parameter must be a class derived from
<tt class="literal"><span class="pre">iterator_facade</span></tt>.</p>
<p>The default for the <tt class="literal"><span class="pre">Reference</span></tt> parameter is <tt class="literal"><span class="pre">Value&amp;</span></tt> if the
access category for <tt class="literal"><span class="pre">iterator_facade</span></tt> is implicitly convertible to
<tt class="literal"><span class="pre">writable_iterator_tag</span></tt>, and <tt class="literal"><span class="pre">const</span> <span class="pre">Value&amp;</span></tt> otherwise.</p>
<p>The following table describes the other requirements on the
<tt class="literal"><span class="pre">Derived</span></tt> parameter. Depending on the resulting iterator's
<tt class="literal"><span class="pre">iterator_category</span></tt>, a subset of the expressions listed in the table
are required to be valid. The operations in the first column must be
accessible to member functions of class <tt class="literal"><span class="pre">iterator_core_access</span></tt>.</p>
<p>In the table below, <tt class="literal"><span class="pre">X</span></tt> is the derived iterator type, <tt class="literal"><span class="pre">a</span></tt> is an
out of the overload set when the types are not interoperable.
The operators should behave <em>as-if</em> <tt class="literal"><span class="pre">enable_if_interoperable</span></tt>
were defined to be:</p>
<pre class="literal-block">
template &lt;bool, typename&gt; enable_if_interoperable_impl
{};
template &lt;typename T&gt; enable_if_interoperable_impl&lt;true,T&gt;
{ typedef T type; };
template&lt;typename Dr1, typename Dr2, typename T&gt;
struct enable_if_interoperable
: enable_if_interoperable_impl&lt;
is_convertible&lt;Dr1,Dr2&gt;::value || is_convertible&lt;Dr2,Dr1&gt;::value
, T
&gt;
{};
</pre>
<div class="section" id="iterator-facade-usage">
<h2><a class="toc-backref" href="#id13" name="iterator-facade-usage"><tt class="literal"><span class="pre">iterator_facade</span></tt> usage</a></h2>
<p>The following table describes the typical valid expressions on
<tt class="literal"><span class="pre">iterator_facade</span></tt>'s <tt class="literal"><span class="pre">Derived</span></tt> parameter, depending on the
iterator concept(s) it will model. The operations in the first
column must be made accessible to member functions of class
<tt class="literal"><span class="pre">iterator_core_access</span></tt>.</p>
<p>In the table below, <tt class="literal"><span class="pre">F</span></tt> is <tt class="literal"><span class="pre">iterator_facade&lt;X,V,C,R,D&gt;</span></tt>, <tt class="literal"><span class="pre">a</span></tt> is an
object of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">b</span></tt> and <tt class="literal"><span class="pre">c</span></tt> are objects of type <tt class="literal"><span class="pre">const</span> <span class="pre">X</span></tt>,
<tt class="literal"><span class="pre">n</span></tt> is an object of <tt class="literal"><span class="pre">X::difference_type</span></tt>, <tt class="literal"><span class="pre">y</span></tt> is a constant
object of a single pass iterator type interoperable with X, and <tt class="literal"><span class="pre">z</span></tt>
<tt class="literal"><span class="pre">n</span></tt> is an object of <tt class="literal"><span class="pre">F::difference_type</span></tt>, <tt class="literal"><span class="pre">y</span></tt> is a constant
object of a single pass iterator type interoperable with <tt class="literal"><span class="pre">X</span></tt>, and <tt class="literal"><span class="pre">z</span></tt>
is a constant object of a random access traversal iterator type
interoperable with <tt class="literal"><span class="pre">X</span></tt>.</p>
<table border class="table">
<colgroup>
<col width="19%" />
<col width="18%" />
<col width="36%" />
<col width="26%" />
<col width="21%" />
<col width="35%" />
<col width="25%" />
</colgroup>
<thead valign="bottom">
<tr><th>Expression</th>
<th>Return Type</th>
<th>Assertion/Note</th>
<th>Required to implement
Iterator Concept(s)</th>
<th>Used to implement Iterator
Concept(s)</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">c.dereference()</span></tt></td>
<td><tt class="literal"><span class="pre">X::reference</span></tt></td>
<td><tt class="literal"><span class="pre">F::reference</span></tt></td>
<td>&nbsp;</td>
<td>Readable Iterator, Writable
Iterator</td>
@ -403,14 +612,14 @@ Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">c.distance_to(b)</span></tt></td>
<td>convertible to
X::difference_type</td>
<tt class="literal"><span class="pre">F::difference_type</span></tt></td>
<td>equivalent to <tt class="literal"><span class="pre">distance(c,</span> <span class="pre">b)</span></tt></td>
<td>Random Access Traversal
Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">c.distance_to(z)</span></tt></td>
<td>convertible to
X::difference_type</td>
<tt class="literal"><span class="pre">F::difference_type</span></tt></td>
<td>equivalent to <tt class="literal"><span class="pre">distance(c,</span> <span class="pre">z)</span></tt>.
Implements <tt class="literal"><span class="pre">c</span> <span class="pre">-</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span> <span class="pre">&lt;</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span>
<span class="pre">&lt;=</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span> <span class="pre">&gt;</span> <span class="pre">z</span></tt>, and <tt class="literal"><span class="pre">c</span> <span class="pre">&gt;=</span> <span class="pre">c</span></tt>.</td>
@ -419,12 +628,62 @@ Iterator</td>
</tr>
</tbody>
</table>
<!-- We should explain more about how the
functions in the interface of iterator_facade
are there conditionally. -JGS -->
<a class="target" id="facade-iterator-category" name="facade-iterator-category"></a></div>
<div class="section" id="iterator-facade-iterator-category">
<h2><a class="toc-backref" href="#id14" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h2>
<p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">iterator_facade&lt;X,V,R,C,D&gt;</span></tt>
is a type which satisfies the following conditions:</p>
<blockquote>
<ul>
<li><p class="first">if <tt class="literal"><span class="pre">C</span></tt> is convertible to <tt class="literal"><span class="pre">std::input_iterator_tag</span></tt> or
<tt class="literal"><span class="pre">C</span></tt> is convertible to <tt class="literal"><span class="pre">std::output_iterator_tag</span></tt>,
<tt class="literal"><span class="pre">iterator_category</span></tt> is the same as <tt class="literal"><span class="pre">C</span></tt>.</p>
</li>
<li><p class="first">Otherwise, if <tt class="literal"><span class="pre">C</span></tt> is not convertible to
<tt class="literal"><span class="pre">incrementable_traversal_tag</span></tt>, the program is ill-formed</p>
</li>
<li><p class="first">Otherwise:</p>
<ul>
<li><p class="first"><tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to the iterator
category tag or tags given by the following algorithm, and
not to any more-derived iterator category tag or tags:</p>
<pre class="literal-block">
if (R is a reference type
&amp;&amp; C is convertible to forward_traversal_tag)
{
if (C is convertible to random_access_traversal_tag)
return random_access_iterator_tag
else if (C is convertible to bidirectional_traversal_tag)
return bidirectional_iterator_tag
else
return forward_traversal_tag
}
else
{
if (C is convertible to single_pass_traversal_tag
&amp;&amp; R is convertible to V)
{
if (V is const)
return input_iterator_tag
else
return input_iterator_tag and output_iterator_tag
}
else
return output_iterator_tag
}
</pre>
</li>
<li><p class="first"><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt> is convertible to the most
derived traversal tag type to which <tt class="literal"><span class="pre">C</span></tt> is also
convertible, and not to any more-derived traversal tag type.</p>
</li>
</ul>
</li>
</ul>
</blockquote>
</div>
<div class="section" id="iterator-facade-operations">
<h2><a class="toc-backref" href="#id17" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h2>
<h2><a class="toc-backref" href="#id15" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h2>
<p>The operations in this section are described in terms of operations on
the core interface of <tt class="literal"><span class="pre">Derived</span></tt> which may be inaccessible
(i.e. private). The implementation should access these operations
@ -443,17 +702,14 @@ through member functions of class <tt class="literal"><span class="pre">iterator
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">If <tt class="literal"><span class="pre">X::reference</span></tt> is a reference type, returns an object
of type <tt class="literal"><span class="pre">X::pointer</span></tt> equal to:</p>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">If <tt class="literal"><span class="pre">reference</span></tt> is a reference type, an object
of type <tt class="literal"><span class="pre">pointer</span></tt> equal to:</p>
<pre class="literal-block">
&amp;static_cast&lt;Derived const*&gt;(this)-&gt;dereference()
</pre>
<p>Otherwise returns an object of unspecified type such that, given an
object <tt class="literal"><span class="pre">a</span></tt> of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">a-&gt;m</span></tt> is equivalent to <tt class="literal"><span class="pre">(w</span> <span class="pre">=</span> <span class="pre">*a,</span>
<span class="pre">w.m)</span></tt> for some temporary object <tt class="literal"><span class="pre">w</span></tt> of type <tt class="literal"><span class="pre">X::value_type</span></tt>.</p>
<p class="last">The type <tt class="literal"><span class="pre">X::pointer</span></tt> is <tt class="literal"><span class="pre">Value*</span></tt> if the access category for
<tt class="literal"><span class="pre">X</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">writable_iterator_tag</span></tt>, and
<tt class="literal"><span class="pre">Value</span> <span class="pre">const*</span></tt> otherwise.</p>
<p class="last">Otherwise returns an object of unspecified type such that,
<tt class="literal"><span class="pre">(*static_cast&lt;Derived</span> <span class="pre">const*&gt;(this))-&gt;m</span></tt> is equivalent to <tt class="literal"><span class="pre">(w</span> <span class="pre">=</span> <span class="pre">**static_cast&lt;Derived</span> <span class="pre">const*&gt;(this),</span>
<span class="pre">w.m)</span></tt> for some temporary object <tt class="literal"><span class="pre">w</span></tt> of type <tt class="literal"><span class="pre">value_type</span></tt>.</p>
</td>
</tr>
</tbody>
@ -463,9 +719,9 @@ object <tt class="literal"><span class="pre">a</span></tt> of type <tt class="li
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">an object convertible to <tt class="literal"><span class="pre">X::reference</span></tt> and holding a copy
<em>p</em> of <tt class="literal"><span class="pre">a+n</span></tt> such that, for a constant object <tt class="literal"><span class="pre">v</span></tt> of type
<tt class="literal"><span class="pre">X::value_type</span></tt>, <tt class="literal"><span class="pre">X::reference(a[n]</span> <span class="pre">=</span> <span class="pre">v)</span></tt> is equivalent
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">an object convertible to <tt class="literal"><span class="pre">reference</span></tt> and holding a copy
<em>p</em> of <tt class="literal"><span class="pre">*static_cast&lt;Derived</span> <span class="pre">const*&gt;(this)</span> <span class="pre">+</span> <span class="pre">n</span></tt> such that, for a constant object <tt class="literal"><span class="pre">v</span></tt> of type
<tt class="literal"><span class="pre">value_type</span></tt>, <tt class="literal"><span class="pre">(*static_cast&lt;Derived</span> <span class="pre">const*&gt;(this))[n]</span> <span class="pre">=</span> <span class="pre">v</span></tt> is equivalent
to <tt class="literal"><span class="pre">p</span> <span class="pre">=</span> <span class="pre">v</span></tt>.</td>
</tr>
</tbody>
@ -477,17 +733,12 @@ to <tt class="literal"><span class="pre">p</span> <span class="pre">=</span> <sp
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;increment();
return *this;
return *static_cast&lt;Derived*&gt;(this);
</pre>
</td>
</tr>
</tbody>
</table>
<!-- I realize that the committee is moving away from specifying things
like this in terms of code, but I worried about the imprecision of
saying that a core interface function is invoked without describing
the downcast. An alternative to what I did would be to mention it
above where we talk about accessibility. -->
<p><tt class="literal"><span class="pre">Derived</span> <span class="pre">operator++(int);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -509,7 +760,7 @@ return tmp;
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;decrement();
return *this;
return static_cast&lt;Derived*&gt;(this);
</pre>
</td>
</tr>
@ -536,7 +787,7 @@ return tmp;
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;advance(n);
return *this;
return static_cast&lt;Derived*&gt;(this);
</pre>
</td>
</tr>
@ -549,7 +800,7 @@ return *this;
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;advance(-n);
return *this;
return static_cast&lt;Derived*&gt;(this);
</pre>
</td>
</tr>
@ -560,10 +811,11 @@ return *this;
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Derived tmp(static_cast&lt;Derived const*&gt;(this));
return tmp -= n;</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">static_cast&lt;Derived</span> <span class="pre">const*&gt;(this)-&gt;advance(-n);</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
Derived tmp(static_cast&lt;Derived const*&gt;(this));
return tmp -= n;
</pre>
</td>
</tr>
</tbody>
</table>
@ -573,7 +825,7 @@ return tmp -= n;</td>
<hr class="footer" />
<div class="footer">
<a class="reference" href="iterator_facade.rst">View document source</a>.
Generated on: 2003-09-21 09:34 UTC.
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>

2
doc/iterator_facade.rst
View File

@ -31,3 +31,5 @@ Reference
---------
.. include:: iterator_facade_ref.rst
.. _counting: counting_iterator.html

23
doc/iterator_facade_body.rst
View File

@ -1,3 +1,10 @@
.. Version 1.1 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1.
.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved
While the iterator interface is rich, there is a core subset of the
interface that is necessary for all the functionality. We have
identified the following core behaviors for iterators:
@ -31,7 +38,7 @@ objects for several reasons:
3. Without the use of CRTP, the standard requirement that an
iterator's ``operator++`` returns the iterator type itself means
that all iterators generated by ``iterator_facade`` would be
instantiations of ``iterator_facade``. Cumbersome type generator
specializations of ``iterator_facade``. Cumbersome type generator
metafunctions would be needed to build new parameterized
iterators, and a separate ``iterator_adaptor`` layer would be
impossible.
@ -40,7 +47,7 @@ Usage
-----
The user of ``iterator_facade`` derives his iterator class from an
instantiation of ``iterator_facade`` which takes the derived iterator
specialization of ``iterator_facade`` which takes the derived iterator
class as the first template parameter. The order of the other
template parameters to ``iterator_facade`` have been carefully chosen
to take advantage of useful defaults. For example, when defining a
@ -135,15 +142,15 @@ challenges. A random access iterator's ``operator[]`` is only
required to return something convertible to its ``value_type``.
Requiring that it return an lvalue would rule out currently-legal
random-access iterators which hold the referenced value in a data
member (e.g. `counting_iterator`__), because ``*(p+n)`` is a reference
member (e.g. |counting|_), because ``*(p+n)`` is a reference
into the temporary iterator ``p+n``, which is destroyed when
``operator[]`` returns.
__ counting_iterator.html
.. |counting| replace:: ``counting_iterator``
Writable iterators built with ``iterator_facade`` implement the
semantics required by the preferred resolution to `issue 299`_ and
adopted by proposal `n1477`_: the result of ``p[n]`` is a proxy object
adopted by proposal n1550_: the result of ``p[n]`` is a proxy object
containing a copy of ``p+n``, and ``p[n] = x`` is equivalent to ``*(p
+ n) = x``. This approach will work properly for any random-access
iterator regardless of the other details of its implementation. A
@ -152,9 +159,9 @@ to implement an ``operator[]`` which returns an lvalue in the derived
iterator class; it will hide the one supplied by ``iterator_facade``
from clients of her iterator.
.. _`n1477`: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html
.. _n1550: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1550.html
.. _issue 299: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299
.. _`issue 299`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299
.. _`operator arrow`:
@ -172,7 +179,7 @@ of the referenced value from its ``operator->``.
The return type for ``operator->`` and ``operator[]`` is not
explicitly specified. Instead it requires each ``iterator_facade``
instantiation to meet the requirements of its ``iterator_category``.
specialization to meet the requirements of its ``iterator_category``.
.. [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template

279
doc/iterator_facade_ref.rst
View File

@ -1,20 +1,26 @@
.. Version 1.3 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1.
.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved
.. parsed-literal::
template <
class Derived
, class Value
, unsigned AccessCategory
, class TraversalCategory
, class Reference = /* see below__ \*/
, class CategoryOrTraversal
, class Reference = Value&
, class Difference = ptrdiff_t
>
class iterator_facade {
public:
typedef remove_cv<Value>::type value_type;
typedef remove_const<Value>::type value_type;
typedef Reference reference;
typedef /* see `description of operator->`__ \*/ pointer;
typedef Value* pointer;
typedef Difference difference_type;
typedef iterator_tag<AccessCategory, TraversalCategory> iterator_category;
typedef /* see below__ \*/ iterator_category;
reference operator\*() const;
/* see below__ \*/ operator->() const;
@ -29,151 +35,185 @@
};
// Comparison operators
template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2>
template <class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2>
typename enable_if_interoperable<Dr1, Dr2, bool>::type // exposition
operator ==(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
operator ==(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2>
template <class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2>
typename enable_if_interoperable<Dr1, Dr2, bool>::type
operator !=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
operator !=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2>
template <class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2>
typename enable_if_interoperable<Dr1, Dr2, bool>::type
operator <(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
operator <(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2>
template <class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2>
typename enable_if_interoperable<Dr1, Dr2, bool>::type
operator <=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
operator <=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2>
template <class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2>
typename enable_if_interoperable<Dr1, Dr2, bool>::type
operator >(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
operator >(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2>
template <class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2>
typename enable_if_interoperable<Dr1, Dr2, bool>::type
operator >=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
operator >=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2>
template <class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2>
typename enable_if_interoperable<Dr1, Dr2, bool>::type
operator >=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
operator >=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
// Iterator difference
template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2>
template <class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2>
typename enable_if_interoperable<Dr1, Dr2, bool>::type
operator -(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
operator -(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
// Iterator addition
template <class Derived, class V, class AC, class TC, class R, class D>
Derived operator+ (iterator_facade<Derived, V, AC, TC, R, D> const&,
template <class Derived, class V, class TC, class R, class D>
Derived operator+ (iterator_facade<Derived, V, TC, R, D> const&,
typename Derived::difference_type n)
__ `iterator facade requirements`_
__ `operator arrow`_
__ `facade iterator category`_
__ `operator arrow`_
__ brackets_
[*Note:* The ``enable_if_interoperable`` template used above is for exposition
The ``enable_if_interoperable`` template used above is for exposition
purposes. The member operators should be only be in an overload set
provided the derived types ``Dr1`` and ``Dr2`` are interoperable, by
which we mean they are convertible to each other. The
provided the derived types ``Dr1`` and ``Dr2`` are interoperable,
meaning that at least one of the types is convertible to the other. The
``enable_if_interoperable`` approach uses SFINAE to take the operators
out of the overload set when the types are not interoperable.]
out of the overload set when the types are not interoperable.
The operators should behave *as-if* ``enable_if_interoperable``
were defined to be::
template <bool, typename> enable_if_interoperable_impl
{};
template <typename T> enable_if_interoperable_impl<true,T>
{ typedef T type; };
template<typename Dr1, typename Dr2, typename T>
struct enable_if_interoperable
: enable_if_interoperable_impl<
is_convertible<Dr1,Dr2>::value || is_convertible<Dr2,Dr1>::value
, T
>
{};
.. we need a new label here because the presence of markup in the
title prevents an automatic link from being generated
``iterator_facade`` usage
.........................
.. _iterator facade requirements:
The following table describes the typical valid expressions on
``iterator_facade``\ 's ``Derived`` parameter, depending on the
iterator concept(s) it will model. The operations in the first
column must be made accessible to member functions of class
``iterator_core_access``.
``iterator_facade`` requirements
................................
Some of the constraints on template parameters to
``iterator_facade`` are expressed in terms of resulting nested
types and should be viewed in the context of their impact on
``iterator_traits<Derived>``.
The ``Derived`` template parameter must be a class derived from
``iterator_facade``.
The nested ``::value_type`` type will be the same as
``remove_cv<Value>::type``, so the ``Value`` parameter must be
an (optionally ``const``\ -qualified) non-reference type.
``AccessCategory`` must be an unsigned value which uses no more
bits than the greatest value of ``iterator_access``.
The nested ``::reference`` will be the same as the ``Reference``
parameter; it must be a suitable reference type for the resulting
iterator. The default for the ``Reference`` parameter is
``Value&``.
The following table describes the other requirements on the
``Derived`` parameter. Depending on the resulting iterator's
``iterator_category``, a subset of the expressions listed in the table
are required to be valid. The operations in the first column must be
accessible to member functions of class ``iterator_core_access``.
In the table below, ``X`` is the derived iterator type, ``a`` is an
In the table below, ``F`` is ``iterator_facade<X,V,C,R,D>``, ``a`` is an
object of type ``X``, ``b`` and ``c`` are objects of type ``const X``,
``n`` is an object of ``X::difference_type``, ``y`` is a constant
object of a single pass iterator type interoperable with X, and ``z``
``n`` is an object of ``F::difference_type``, ``y`` is a constant
object of a single pass iterator type interoperable with ``X``, and ``z``
is a constant object of a random access traversal iterator type
interoperable with ``X``.
+--------------------+-------------------+-------------------------------------+---------------------------+
|Expression |Return Type |Assertion/Note |Required to implement |
| | | |Iterator Concept(s) |
+====================+===================+=====================================+===========================+
|``c.dereference()`` |``X::reference`` | |Readable Iterator, Writable|
+--------------------+----------------------+-------------------------------------+---------------------------+
|Expression |Return Type |Assertion/Note |Used to implement Iterator |
| | | |Concept(s) |
+====================+======================+=====================================+===========================+
|``c.dereference()`` |``F::reference`` | |Readable Iterator, Writable|
| | | |Iterator |
+--------------------+-------------------+-------------------------------------+---------------------------+
+--------------------+----------------------+-------------------------------------+---------------------------+
|``c.equal(b)`` |convertible to bool |true iff ``b`` and ``c`` are |Single Pass Iterator |
| | |equivalent. | |
+--------------------+-------------------+-------------------------------------+---------------------------+
+--------------------+----------------------+-------------------------------------+---------------------------+
|``c.equal(y)`` |convertible to bool |true iff ``c`` and ``y`` refer to the|Single Pass Iterator |
| | |same position. Implements ``c == y``| |
| | |and ``c != y``. | |
+--------------------+-------------------+-------------------------------------+---------------------------+
+--------------------+----------------------+-------------------------------------+---------------------------+
|``a.advance(n)`` |unused | |Random Access Traversal |
| | | |Iterator |
+--------------------+-------------------+-------------------------------------+---------------------------+
+--------------------+----------------------+-------------------------------------+---------------------------+
|``a.increment()`` |unused | |Incrementable Iterator |
+--------------------+-------------------+-------------------------------------+---------------------------+
+--------------------+----------------------+-------------------------------------+---------------------------+
|``a.decrement()`` |unused | |Bidirectional Traversal |
| | | |Iterator |
+--------------------+-------------------+-------------------------------------+---------------------------+
+--------------------+----------------------+-------------------------------------+---------------------------+
|``c.distance_to(b)``|convertible to |equivalent to ``distance(c, b)`` |Random Access Traversal |
| |X::difference_type | |Iterator |
+--------------------+-------------------+-------------------------------------+---------------------------+
| |``F::difference_type``| |Iterator |
+--------------------+----------------------+-------------------------------------+---------------------------+
|``c.distance_to(z)``|convertible to |equivalent to ``distance(c, z)``. |Random Access Traversal |
| |X::difference_type |Implements ``c - z``, ``c < z``, ``c |Iterator |
| |``F::difference_type``|Implements ``c - z``, ``c < z``, ``c |Iterator |
| | |<= z``, ``c > z``, and ``c >= c``. | |
+--------------------+-------------------+-------------------------------------+---------------------------+
+--------------------+----------------------+-------------------------------------+---------------------------+
.. We should explain more about how the
functions in the interface of iterator_facade
are there conditionally. -JGS
.. _facade iterator category:
``iterator_facade`` iterator category
.....................................
The ``iterator_category`` member of ``iterator_facade<X,V,R,C,D>``
is a type which satisfies the following conditions:
* if ``C`` is convertible to ``std::input_iterator_tag`` or
``C`` is convertible to ``std::output_iterator_tag``,
``iterator_category`` is the same as ``C``.
* Otherwise, if ``C`` is not convertible to
``incrementable_traversal_tag``, the program is ill-formed
* Otherwise:
- ``iterator_category`` is convertible to the iterator
category tag or tags given by the following algorithm, and
not to any more-derived iterator category tag or tags::
if (R is a reference type
&& C is convertible to forward_traversal_tag)
{
if (C is convertible to random_access_traversal_tag)
return random_access_iterator_tag
else if (C is convertible to bidirectional_traversal_tag)
return bidirectional_iterator_tag
else
return forward_traversal_tag
}
else
{
if (C is convertible to single_pass_traversal_tag
&& R is convertible to V)
{
if (V is const)
return input_iterator_tag
else
return input_iterator_tag and output_iterator_tag
}
else
return output_iterator_tag
}
- ``iterator_traversal<X>::type`` is convertible to the most
derived traversal tag type to which ``C`` is also
convertible, and not to any more-derived traversal tag type.
``iterator_facade`` operations
@ -192,27 +232,22 @@ through member functions of class ``iterator_core_access``.
__ `operator arrow`_
:Returns: If ``X::reference`` is a reference type, returns an object
of type ``X::pointer`` equal to::
:Returns: If ``reference`` is a reference type, an object
of type ``pointer`` equal to::
&static_cast<Derived const*>(this)->dereference()
Otherwise returns an object of unspecified type such that, given an
object ``a`` of type ``X``, ``a->m`` is equivalent to ``(w = *a,
w.m)`` for some temporary object ``w`` of type ``X::value_type``.
The type ``X::pointer`` is ``Value*`` if
``is_writable_iterator<X>::value`` is ``true``, and
``Value const*`` otherwise.
Otherwise returns an object of unspecified type such that,
``(*static_cast<Derived const*>(this))->m`` is equivalent to ``(w = **static_cast<Derived const*>(this),
w.m)`` for some temporary object ``w`` of type ``value_type``.
.. _brackets:
*unspecified* ``operator[](difference_type n) const;``
:Returns: an object convertible to ``X::reference`` and holding a copy
*p* of ``a+n`` such that, for a constant object ``v`` of type
``X::value_type``, ``X::reference(a[n] = v)`` is equivalent
:Returns: an object convertible to ``reference`` and holding a copy
*p* of ``*static_cast<Derived const*>(this) + n`` such that, for a constant object ``v`` of type
``value_type``, ``(*static_cast<Derived const*>(this))[n] = v`` is equivalent
to ``p = v``.
@ -224,14 +259,7 @@ __ `operator arrow`_
::
static_cast<Derived*>(this)->increment();
return *this;
.. I realize that the committee is moving away from specifying things
like this in terms of code, but I worried about the imprecision of
saying that a core interface function is invoked without describing
the downcast. An alternative to what I did would be to mention it
above where we talk about accessibility.
return *static_cast<Derived*>(this);
``Derived operator++(int);``
@ -251,7 +279,7 @@ __ `operator arrow`_
::
static_cast<Derived*>(this)->decrement();
return *this;
return static_cast<Derived*>(this);
``Derived operator--(int);``
@ -272,7 +300,7 @@ __ `operator arrow`_
::
static_cast<Derived*>(this)->advance(n);
return *this;
return static_cast<Derived*>(this);
``Derived& operator-=(difference_type n);``
@ -282,16 +310,17 @@ __ `operator arrow`_
::
static_cast<Derived*>(this)->advance(-n);
return *this;
return static_cast<Derived*>(this);
``Derived operator-(difference_type n) const;``
:Effects:
::
Derived tmp(static_cast<Derived const*>(this));
return tmp -= n;
:Returns: ``static_cast<Derived const*>(this)->advance(-n);``

276
doc/new-iter-concepts.html
View File

@ -7,7 +7,7 @@
<title>New Iterator Concepts</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-10-16" />
<meta name="date" content="2003-11-22" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<style type="text/css"><!--
@ -218,13 +218,19 @@ ul.auto-toc {
Systems Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for
Transport Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2003-10-16</td></tr>
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">N1530=03-0133</td>
<td>2003-11-22</td></tr>
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">This is a revised version of <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1550.html">n1550</a>=03-0133, which was
accepted for Technical Report 1 by the C++ standard
committee's library working group. This proposal is a
revision of paper <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2001/n1297.html">n1297</a>, <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1477.html">n1477</a>, and <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1531.html">n1531</a>.</td>
</tr>
<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>
</table>
<!-- Version 1.25 of this ReStructuredText document is the same as
n1550_, the paper accepted by the LWG. -->
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
@ -233,8 +239,7 @@ Transport Railway Operation and Construction</a></td></tr>
access and positioning independently. This allows the
concepts to more closely match the requirements
of algorithms and provides better categorizations
of iterators that are used in practice. This proposal
is a revision of paper <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2001/n1297.html">n1297</a>, <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1477.html">n1477</a>, and <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1531.html">n1531</a>.</td>
of iterators that are used in practice.</td>
</tr>
</tbody>
</table>
@ -276,6 +281,7 @@ is a revision of paper <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc
<li><a class="reference" href="#addition-to-lib-iterator-traits" id="id23" name="id23">Addition to [lib.iterator.traits]</a></li>
</ul>
</li>
<li><a class="reference" href="#footnotes" id="id24" name="id24">Footnotes</a></li>
</ul>
</div>
<div class="section" id="motivation">
@ -295,15 +301,12 @@ following table gives a summary of the current value access
requirements in the iterator categories.</p>
<table border class="table">
<colgroup>
<col width="39%" />
<col width="61%" />
<col width="31%" />
<col width="69%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="2">Value Access Requirements in Existing Iterator Categories</th>
</tr>
<tr><th>Existing Category</th>
<th>Requirement</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Output Iterator</td>
@ -313,13 +316,12 @@ requirements in the iterator categories.</p>
<td><tt class="literal"><span class="pre">*i</span></tt> is convertible to <tt class="literal"><span class="pre">T</span></tt></td>
</tr>
<tr><td>Forward Iterator</td>
<td><tt class="literal"><span class="pre">*i</span></tt> is <tt class="literal"><span class="pre">T&amp;</span></tt> (or <tt class="literal"><span class="pre">const</span> <span class="pre">T&amp;</span></tt>
once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#200">issue 200</a> is resolved)</td>
<td><tt class="literal"><span class="pre">*i</span></tt> is <tt class="literal"><span class="pre">T&amp;</span></tt> (or <tt class="literal"><span class="pre">const</span> <span class="pre">T&amp;</span></tt> once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#200">issue 200</a>
is resolved)</td>
</tr>
<tr><td>Random Access Iterator</td>
<td><tt class="literal"><span class="pre">i[n]</span></tt> is convertible to <tt class="literal"><span class="pre">T</span></tt>
(also <tt class="literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt> is required for
mutable iterators once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#299">issue 299</a>
<td><tt class="literal"><span class="pre">i[n]</span></tt> is convertible to <tt class="literal"><span class="pre">T</span></tt> (also <tt class="literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt>
is required for mutable iterators once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#299">issue 299</a>
is resolved)</td>
</tr>
</tbody>
@ -384,6 +386,11 @@ is convertible to input_iterator_tag? -JGS -->
concepts because the new concepts provide a more accurate way to
express their type requirements. The result is algorithms that are
usable in more situations and have fewer type requirements.</p>
<p>Note that as currently specified, <tt class="literal"><span class="pre">istreambuf_iterator</span></tt> doesn't
meet the Readable Iterator requirements because its <tt class="literal"><span class="pre">value_type</span></tt>
is not convertible to its <tt class="literal"><span class="pre">reference</span></tt> type. We believe this to
be a defect in the standard; it should be fixed by changing its
<tt class="literal"><span class="pre">reference</span></tt> type from <tt class="literal"><span class="pre">value_type&amp;</span></tt> to <tt class="literal"><span class="pre">value_type</span> <span class="pre">const&amp;</span></tt>.</p>
</div>
<div class="section" id="possible-but-not-proposed-changes-to-the-working-paper">
<h2><a class="toc-backref" href="#id4" name="possible-but-not-proposed-changes-to-the-working-paper">Possible (but not proposed) Changes to the Working Paper</a></h2>
@ -392,9 +399,11 @@ to the working paper for the next standard. These changes are not
a formal part of this proposal for TR1.</p>
<div class="section" id="changes-to-algorithm-requirements">
<h3><a class="toc-backref" href="#id5" name="changes-to-algorithm-requirements">Changes to Algorithm Requirements</a></h3>
<p>The following lists possible (but not proposed) changes to the type
requirements of algorithms, phrased as textual substitutions,
listing the algorithms to which each textual substitution applies.</p>
<p>For the next working paper (but not for TR1), the committee should
consider the following changes to the type requirements of
algorithms. These changes are phrased as phrased as textual
substitutions, listing the algorithms to which each textual
substitution applies.</p>
<p>Forward Iterator -&gt; Forward Traversal Iterator and Readable Iterator</p>
<blockquote>
<tt class="literal"><span class="pre">find_end,</span> <span class="pre">adjacent_find,</span> <span class="pre">search,</span> <span class="pre">search_n,</span> <span class="pre">rotate_copy,</span>
@ -575,7 +584,8 @@ only required to return something convertible to the <tt class="literal"><span c
<div class="section" id="iterator-value-access-concepts-lib-iterator-value-access">
<h3><a class="toc-backref" href="#id11" name="iterator-value-access-concepts-lib-iterator-value-access">Iterator Value Access Concepts [lib.iterator.value.access]</a></h3>
<p>In the tables below, <tt class="literal"><span class="pre">X</span></tt> is an iterator type, <tt class="literal"><span class="pre">a</span></tt> is a constant
object of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">T</span></tt> is
object of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">R</span></tt> is
<tt class="literal"><span class="pre">std::iterator_traits&lt;X&gt;::reference</span></tt>, <tt class="literal"><span class="pre">T</span></tt> is
<tt class="literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and <tt class="literal"><span class="pre">v</span></tt> is a constant
object of type <tt class="literal"><span class="pre">T</span></tt>.</p>
<a class="target" id="readable-iterator" name="readable-iterator"></a><div class="section" id="readable-iterators-lib-readable-iterators">
@ -586,9 +596,9 @@ respect the stated semantics. <tt class="literal"><span class="pre">U</span></tt
member of type <tt class="literal"><span class="pre">T</span></tt>.</p>
<table border class="table">
<colgroup>
<col width="37%" />
<col width="37%" />
<col width="26%" />
<col width="42%" />
<col width="29%" />
<col width="30%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="3">Readable Iterator Requirements (in addition to CopyConstructible)</th>
@ -599,28 +609,30 @@ member of type <tt class="literal"><span class="pre">T</span></tt>.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">iterator_traits&lt;</span> <span class="pre">X</span>
<span class="pre">&gt;::value_type</span></tt></td>
<tr><td><tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt></td>
<td><tt class="literal"><span class="pre">T</span></tt></td>
<td>Any non-reference,
non-cv-qualified type</td>
</tr>
<tr><td><tt class="literal"><span class="pre">iterator_traits&lt;</span> <span class="pre">X&gt;::reference</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">is_readable&lt;X&gt;::type</span></tt></td>
<td><tt class="literal"><span class="pre">true_type</span></tt></td>
<tr><td><tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::reference</span></tt></td>
<td><tt class="literal"><span class="pre">R</span></tt>, Convertible to
<tt class="literal"><span class="pre">T</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">*a</span></tt></td>
<td><tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::reference</span></tt></td>
<td>Convertible to <tt class="literal"><span class="pre">R</span></tt>,
Convertible to <tt class="literal"><span class="pre">T</span></tt></td>
<td>pre: <tt class="literal"><span class="pre">a</span></tt> is
dereferenceable. If <tt class="literal"><span class="pre">a</span>
<span class="pre">==</span> <span class="pre">b</span></tt> then <tt class="literal"><span class="pre">*a</span></tt> is
equivalent to <tt class="literal"><span class="pre">*b</span></tt></td>
</tr>
<tr><td><tt class="literal"><span class="pre">static_cast&lt;T&gt;(</span>
<span class="pre">static_cast&lt;R&gt;(*a)</span> <span class="pre">)</span></tt></td>
<td><tt class="literal"><span class="pre">T</span></tt></td>
<td>equivalent to
<tt class="literal"><span class="pre">static_cast&lt;T&gt;(*a)</span></tt></td>
</tr>
<tr><td><tt class="literal"><span class="pre">a-&gt;m</span></tt></td>
<td><tt class="literal"><span class="pre">U&amp;</span></tt></td>
<td>pre: <tt class="literal"><span class="pre">(*a).m</span></tt> is
@ -652,10 +664,6 @@ output.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">is_writable&lt;X&gt;::type</span></tt></td>
<td><tt class="literal"><span class="pre">true_type</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">*a</span> <span class="pre">=</span> <span class="pre">o</span></tt></td>
<td>&nbsp;</td>
<td>pre: The type of <tt class="literal"><span class="pre">o</span></tt>
@ -685,10 +693,6 @@ semantics.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">is_swappable&lt;X&gt;::type</span></tt></td>
<td><tt class="literal"><span class="pre">true_type</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">iter_swap(a,</span> <span class="pre">b)</span></tt></td>
<td><tt class="literal"><span class="pre">void</span></tt></td>
<td>the pointed to values are
@ -774,7 +778,7 @@ semantics.</p>
</tr>
<tr><td><tt class="literal"><span class="pre">traversal_category&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">incrementable_iterator_tag</span></tt></td>
<tt class="literal"><span class="pre">incrementable_traversal_tag</span></tt></td>
<td>&nbsp;</td>
</tr>
</tbody>
@ -820,7 +824,7 @@ relation over its domain</td>
</tr>
<tr><td><tt class="literal"><span class="pre">traversal_category&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">single_pass_iterator_tag</span></tt></td>
<tt class="literal"><span class="pre">single_pass_traversal_tag</span></tt></td>
<td>&nbsp;</td>
</tr>
</tbody>
@ -867,7 +871,7 @@ the distance between iterators</td>
</tr>
<tr><td><tt class="literal"><span class="pre">traversal_category&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">forward_traversal_iterator_tag</span></tt></td>
<tt class="literal"><span class="pre">forward_traversal_tag</span></tt></td>
<td>&nbsp;</td>
</tr>
</tbody>
@ -880,8 +884,8 @@ Iterator</em> concept if the following expressions are valid and respect
the stated semantics.</p>
<table border class="table">
<colgroup>
<col width="37%" />
<col width="42%" />
<col width="35%" />
<col width="44%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
@ -919,7 +923,7 @@ implies <tt class="literal"><span class="pre">r</span> <span class="pre">==</spa
</tr>
<tr><td><tt class="literal"><span class="pre">traversal_category&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">bidirectional_traversal_iterator_tag</span></tt></td>
<tt class="literal"><span class="pre">bidirectional_traversal_tag</span></tt></td>
<td>&nbsp;</td>
</tr>
</tbody>
@ -935,8 +939,8 @@ constant object of type <tt class="literal"><span class="pre">Distance</span></t
<table border class="table">
<colgroup>
<col width="31%" />
<col width="38%" />
<col width="15%" />
<col width="35%" />
<col width="18%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
@ -969,8 +973,8 @@ Precondition</th>
</tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span></tt>, <tt class="literal"><span class="pre">n</span> <span class="pre">+</span> <span class="pre">a</span></tt></td>
<td><tt class="literal"><span class="pre">X</span></tt></td>
<td><tt class="literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span>
<span class="pre">tmp</span> <span class="pre">+=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
<td><tt class="literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span>
<span class="pre">+=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">r</span> <span class="pre">-=</span> <span class="pre">n</span></tt></td>
@ -980,15 +984,14 @@ Precondition</th>
</tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">-</span> <span class="pre">n</span></tt></td>
<td><tt class="literal"><span class="pre">X</span></tt></td>
<td><tt class="literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span>
<span class="pre">tmp</span> <span class="pre">-=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
<td><tt class="literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span>
<span class="pre">-=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span></tt></td>
<td><tt class="literal"><span class="pre">Distance</span></tt></td>
<td><tt class="literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span> <span class="pre">?</span>
<span class="pre">distance(a,b)</span> <span class="pre">:</span>
<span class="pre">-distance(b,a)</span></tt></td>
<td><tt class="literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span> <span class="pre">?</span>&nbsp; <span class="pre">distance(a,b)</span>
<span class="pre">:</span> <span class="pre">-distance(b,a)</span></tt></td>
<td>pre: there exists a
value <tt class="literal"><span class="pre">n</span></tt> of
<tt class="literal"><span class="pre">Distance</span></tt> such that
@ -1031,7 +1034,7 @@ ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">traversal_category&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">random_access_traversal_iterator_tag</span></tt></td>
<tt class="literal"><span class="pre">random_access_traversal_tag</span></tt></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
@ -1044,118 +1047,30 @@ ordering relation</td>
<h2><a class="toc-backref" href="#id22" name="addition-to-lib-iterator-synopsis">Addition to [lib.iterator.synopsis]</a></h2>
<pre class="literal-block">
// lib.iterator.traits, traits and tags
template &lt;class Iterator&gt; struct is_readable;
template &lt;class Iterator&gt; struct is_writable;
template &lt;class Iterator&gt; struct is_swappable;
template &lt;class Iterator&gt; struct traversal_category;
template &lt;class Iterator&gt; struct is_readable_iterator;
template &lt;class Iterator&gt; struct iterator_traversal;
enum iterator_access { readable_iterator = 1, writable_iterator = 2,
swappable_iterator = 4, lvalue_iterator = 8 };
template &lt;unsigned int access_bits, class TraversalTag&gt;
struct iterator_tag : /* appropriate old category or categories */ {
static const iterator_access access =
(iterator_access)access_bits &amp;
(readable_iterator | writable_iterator | swappable_iterator);
typedef TraversalTag traversal;
};
struct incrementable_iterator_tag { };
struct single_pass_iterator_tag : incrementable_iterator_tag { };
struct forward_traversal_tag : single_pass_iterator_tag { };
struct incrementable_traversal_tag { };
struct single_pass_traversal_tag : incrementable_traversal_tag { };
struct forward_traversal_tag : single_pass_traversal_tag { };
struct bidirectional_traversal_tag : forward_traversal_tag { };
struct random_access_traversal_tag : bidirectional_traversal_tag { };
struct null_category_tag { };
struct input_output_iterator_tag : input_iterator_tag, output_iterator_tag {};
</pre>
</div>
<div class="section" id="addition-to-lib-iterator-traits">
<h2><a class="toc-backref" href="#id23" name="addition-to-lib-iterator-traits">Addition to [lib.iterator.traits]</a></h2>
<p>The <tt class="literal"><span class="pre">iterator_tag</span></tt> class template is an iterator category tag that
encodes the access enum and traversal tag in addition to being compatible
with the original iterator tags. The <tt class="literal"><span class="pre">iterator_tag</span></tt> class inherits
from one of the original iterator tags according to the following
pseudo-code.</p>
<p>The <tt class="literal"><span class="pre">is_readable_iterator</span></tt> and <tt class="literal"><span class="pre">iterator_traversal</span></tt> class
templates satisfy the <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1519.htm">UnaryTypeTrait</a> requirements.</p>
<p>Given an iterator type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">is_readable_iterator&lt;X&gt;::value</span></tt>
yields <tt class="literal"><span class="pre">true</span></tt> if, for an object <tt class="literal"><span class="pre">a</span></tt> of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">*a</span></tt> is
convertible to <tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt>, and <tt class="literal"><span class="pre">false</span></tt>
otherwise.</p>
<p><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::value_type</span></tt> is defined to be:</p>
<pre class="literal-block">
inherit-category(access, traversal-tag) =
if ((access &amp; readable_iterator) &amp;&amp; (access &amp; lvalue_iterator)) {
if (traversal-tag is convertible to random_access_traversal_tag)
return random_access_iterator_tag;
else if (traversal-tag is convertible to bidirectional_traversal_tag)
return bidirectional_iterator_tag;
else if (traversal-tag is convertible to forward_traversal_tag)
return forward_iterator_tag;
else if (traversal-tag is convertible to single_pass_traversal_tag)
if (access-tag is convertible to writable_iterator_tag)
return input_output_iterator_tag;
else
return input_iterator_tag;
else
return null_category_tag;
} else if ((access &amp; readable_iterator) and (access &amp; writable_iterator)
and traversal-tag is convertible to single_pass_iterator_tag)
return input_output_iterator_tag;
else if (access &amp; readable_iterator
and traversal-tag is convertible to single_pass_iterator_tag)
return input_iterator_tag;
else if (access &amp; writable_iterator
and traversal-tag is convertible to incrementable_iterator_tag)
return output_iterator_tag;
else
return null_category_tag;
</pre>
<p>If the argument for <tt class="literal"><span class="pre">TraversalTag</span></tt> is not convertible to
<tt class="literal"><span class="pre">incrementable_iterator_tag</span></tt> then the program is ill-formed.</p>
<p>The <tt class="literal"><span class="pre">is_readable</span></tt>, <tt class="literal"><span class="pre">is_writable</span></tt>, <tt class="literal"><span class="pre">is_swappable</span></tt>, and
<tt class="literal"><span class="pre">traversal_category</span></tt> class templates are traits classes. For
iterators whose <tt class="literal"><span class="pre">iterator_traits&lt;Iter&gt;::iterator_category</span></tt> type is
<tt class="literal"><span class="pre">iterator_tag</span></tt>, these traits obtain the <tt class="literal"><span class="pre">access</span></tt> enum and
<tt class="literal"><span class="pre">traversal</span></tt> member type from within <tt class="literal"><span class="pre">iterator_tag</span></tt>. For iterators
whose <tt class="literal"><span class="pre">iterator_traits&lt;Iter&gt;::iterator_category</span></tt> type is not
<tt class="literal"><span class="pre">iterator_tag</span></tt> and instead is a tag convertible to one of the
original tags, the appropriate traversal tag and access bits are
deduced. The following pseudo-code describes the algorithm.</p>
<pre class="literal-block">
is-readable(Iterator) =
cat = iterator_traits&lt;Iterator&gt;::iterator_category;
if (cat == iterator_tag&lt;Access,Traversal&gt;)
return Access &amp; readable_iterator;
else if (cat is convertible to input_iterator_tag)
return true;
else
return false;
is-writable(Iterator) =
cat = iterator_traits&lt;Iterator&gt;::iterator_category;
if (cat == iterator_tag&lt;Access,Traversal&gt;)
return Access &amp; writable_iterator;
else if (cat is convertible to output_iterator_tag)
return true;
else if (
cat is convertible to forward_iterator_tag
and iterator_traits&lt;Iterator&gt;::reference is a
mutable reference)
return true;
else
return false;
is-swappable(Iterator) =
cat = iterator_traits&lt;Iterator&gt;::iterator_category;
if (cat == iterator_tag&lt;Access,Traversal&gt;)
return Access &amp; swappable_iterator;
else if (cat is convertible to forward_iterator_tag) {
if (iterator_traits&lt;Iterator&gt;::reference is a const reference)
return false;
else
return true;
} else
return false;
traversal-category(Iterator) =
cat = iterator_traits&lt;Iterator&gt;::iterator_category;
if (cat == iterator_tag&lt;Access,Traversal&gt;)
return Traversal;
traversal-category(X) =
cat = iterator_traits&lt;X&gt;::iterator_category;
if (cat is convertible to incrementable_traversal_tag)
return cat;
else if (cat is convertible to random_access_iterator_tag)
return random_access_traversal_tag;
else if (cat is convertible to bidirectional_iterator_tag)
@ -1163,35 +1078,19 @@ traversal-category(Iterator) =
else if (cat is convertible to forward_iterator_tag)
return forward_traversal_tag;
else if (cat is convertible to input_iterator_tag)
return single_pass_iterator_tag;
return single_pass_traversal_tag;
else if (cat is convertible to output_iterator_tag)
return incrementable_iterator_tag;
return incrementable_traversal_tag;
else
return null_category_tag;
</pre>
<p>The following specializations provide the access and traversal
category tags for pointer types.</p>
<pre class="literal-block">
template &lt;typename T&gt;
struct is_readable&lt;const T*&gt; { typedef true_type type; };
template &lt;typename T&gt;
struct is_writable&lt;const T*&gt; { typedef false_type type; };
template &lt;typename T&gt;
struct is_swappable&lt;const T*&gt; { typedef false_type type; };
template &lt;typename T&gt;
struct is_readable&lt;T*&gt; { typedef true_type type; };
template &lt;typename T&gt;
struct is_writable&lt;T*&gt; { typedef true_type type; };
template &lt;typename T&gt;
struct is_swappable&lt;T*&gt; { typedef true_type type; };
template &lt;typename T&gt;
struct traversal_category&lt;T*&gt;
{
typedef random_access_traversal_tag type;
};
<em>the program is ill-formed</em>
</pre>
</div>
</div>
<div class="section" id="footnotes">
<h1><a class="toc-backref" href="#id24" name="footnotes">Footnotes</a></h1>
<p>The UnaryTypeTrait concept is defined in <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1519.htm">n1519</a>; the LWG added the
requirement that specializations are derived from their nested
<tt class="literal"><span class="pre">::type</span></tt>.</p>
<!-- 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
@ -1201,11 +1100,10 @@ LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct
LocalWords: TraversalTag typename lvalues DWA Hmm JGS mis enum -->
</div>
</div>
</div>
<hr class="footer" />
<div class="footer">
<a class="reference" href="new-iter-concepts.rst">View document source</a>.
Generated on: 2003-10-30 20:56 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>

227
doc/new-iter-concepts.rst
View File

@ -2,14 +2,23 @@
New Iterator Concepts
++++++++++++++++++++++
.. Version 1.25 of this ReStructuredText document is the same as
n1550_, the paper accepted by the LWG.
:Author: David Abrahams, Jeremy Siek, Thomas Witt
:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@acm.org
:organization: `Boost Consulting`_, Indiana University `Open
Systems Lab`_, University of Hanover `Institute for
Transport Railway Operation and Construction`_
:date: $Date$
:Number: N1550=03-0133
:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
:Number: This is a revised version of n1550_\ =03-0133, which was
accepted for Technical Report 1 by the C++ standard
committee's library working group. This proposal is a
revision of paper n1297_, n1477_, and n1531_.
:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt
2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
@ -21,14 +30,14 @@
access and positioning independently. This allows the
concepts to more closely match the requirements
of algorithms and provides better categorizations
of iterators that are used in practice. This proposal
is a revision of paper n1297_, n1477_, and n1531_.
of iterators that are used in practice.
.. contents:: Table of Contents
.. _n1297: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2001/n1297.html
.. _n1477: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1477.html
.. _n1531: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1531.html
.. _n1550: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1550.html
============
Motivation
@ -145,6 +154,12 @@ concepts because the new concepts provide a more accurate way to
express their type requirements. The result is algorithms that are
usable in more situations and have fewer type requirements.
Note that as currently specified, ``istreambuf_iterator`` doesn't
meet the Readable Iterator requirements because its ``value_type``
is not convertible to its ``reference`` type. We believe this to
be a defect in the standard; it should be fixed by changing its
``reference`` type from ``value_type&`` to ``value_type const&``.
Possible (but not proposed) Changes to the Working Paper
========================================================
@ -374,7 +389,8 @@ Iterator Value Access Concepts [lib.iterator.value.access]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
In the tables below, ``X`` is an iterator type, ``a`` is a constant
object of type ``X``, ``T`` is
object of type ``X``, ``R`` is
``std::iterator_traits<X>::reference``, ``T`` is
``std::iterator_traits<X>::value_type``, and ``v`` is a constant
object of type ``T``.
@ -388,28 +404,29 @@ for the value type ``T`` if the following expressions are valid and
respect the stated semantics. ``U`` is the type of any specified
member of type ``T``.
+-------------------------------------------------------------------------------------------------+
+--------------------------------------------------------------------------------------+
|Readable Iterator Requirements (in addition to CopyConstructible) |
+-----------------------------------+-----------------------------------+-------------------------+
+-----------------------------------+------------------------+-------------------------+
|Expression |Return Type |Note/Precondition |
+===================================+===================================+=========================+
+===================================+========================+=========================+
|``iterator_traits<X>::value_type`` |``T`` |Any non-reference, |
| | |non-cv-qualified type |
+-----------------------------------+-----------------------------------+-------------------------+
|``iterator_traits<X>::reference`` |Convertible to | |
| |``iterator_traits<X>::value_type`` | |
+-----------------------------------+-----------------------------------+-------------------------+
|``is_readable<X>::type`` |``true_type`` | |
+-----------------------------------+-----------------------------------+-------------------------+
|``*a`` |``iterator_traits<X>::reference`` |pre: ``a`` is |
| | |dereferenceable. If ``a |
+-----------------------------------+------------------------+-------------------------+
|``iterator_traits<X>::reference`` |``R``, Convertible to | |
| |``T`` | |
+-----------------------------------+------------------------+-------------------------+
|``*a`` |Convertible to ``R``, |pre: ``a`` is |
| |Convertible to ``T`` |dereferenceable. If ``a |
| | |== b`` then ``*a`` is |
| | |equivalent to ``*b`` |
+-----------------------------------+-----------------------------------+-------------------------+
+-----------------------------------+------------------------+-------------------------+
|``static_cast<T>( |``T`` |equivalent to |
|static_cast<R>(*a) )`` | |``static_cast<T>(*a)`` |
+-----------------------------------+------------------------+-------------------------+
|``a->m`` |``U&`` |pre: ``(*a).m`` is |
| | |well-defined. Equivalent|
| | |to ``(*a).m`` |
+-----------------------------------+-----------------------------------+-------------------------+
+-----------------------------------+------------------------+-------------------------+
.. _Writable Iterator:
@ -428,8 +445,6 @@ output.
+-------------------------+--------------+----------------------------+
|Expression |Return Type |Precondition |
+=========================+==============+============================+
|``is_writable<X>::type`` |``true_type`` | |
+-------------------------+--------------+----------------------------+
|``*a = o`` | | pre: The type of ``o`` |
| | | is in the set of |
| | | value types of ``X`` |
@ -449,8 +464,6 @@ semantics.
+-------------------------+-------------+-----------------------------+
|Expression |Return Type |Postcondition |
+=========================+=============+=============================+
|``is_swappable<X>::type``|``true_type``| |
+-------------------------+-------------+-----------------------------+
|``iter_swap(a, b)`` |``void`` |the pointed to values are |
| | |exchanged |
+-------------------------+-------------+-----------------------------+
@ -511,7 +524,7 @@ semantics.
| | | } |
+--------------------------------+-------------------------------+--------------------+
|``traversal_category<X>::type`` |Convertible to | |
| |``incrementable_iterator_tag`` | |
| |``incrementable_traversal_tag``| |
+--------------------------------+-------------------------------+--------------------+
@ -541,7 +554,7 @@ semantics.
|``a != b`` |convertible to ``bool`` |``!(a == b)`` |
+--------------------------------+-----------------------------+---------------------------+
|``traversal_category<X>::type`` |Convertible to | |
| |``single_pass_iterator_tag`` | |
| |``single_pass_traversal_tag``| |
+--------------------------------+-----------------------------+---------------------------+
@ -572,7 +585,7 @@ semantics.
| | | |
+---------------------------------------+-----------------------------------+---------------+
|``traversal_category<X>::type`` |Convertible to | |
| |``forward_traversal_iterator_tag`` | |
| |``forward_traversal_tag`` | |
+---------------------------------------+-----------------------------------+---------------+
@ -608,7 +621,7 @@ the stated semantics.
| | | } |
+------------------------------------+---------------------------------------------+---------------------+
|``traversal_category<X>::type`` |Convertible to | |
| |``bidirectional_traversal_iterator_tag`` | |
| |``bidirectional_traversal_tag`` | |
| | | |
+------------------------------------+---------------------------------------------+---------------------+
@ -674,7 +687,7 @@ constant object of type ``Distance``.
|``a <= b`` |convertible to ``bool`` |``!(a > b)`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``traversal_category<X>::type`` |Convertible to | | |
| |``random_access_traversal_iterator_tag`` | | |
| |``random_access_traversal_tag`` | | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
@ -686,123 +699,34 @@ Addition to [lib.iterator.synopsis]
::
// lib.iterator.traits, traits and tags
template <class Iterator> struct is_readable;
template <class Iterator> struct is_writable;
template <class Iterator> struct is_swappable;
template <class Iterator> struct traversal_category;
template <class Iterator> struct is_readable_iterator;
template <class Iterator> struct iterator_traversal;
enum iterator_access { readable_iterator = 1, writable_iterator = 2,
swappable_iterator = 4, lvalue_iterator = 8 };
template <unsigned int access_bits, class TraversalTag>
struct iterator_tag : /* appropriate old category or categories */ {
static const iterator_access access =
(iterator_access)access_bits &
(readable_iterator | writable_iterator | swappable_iterator);
typedef TraversalTag traversal;
};
struct incrementable_iterator_tag { };
struct single_pass_iterator_tag : incrementable_iterator_tag { };
struct forward_traversal_tag : single_pass_iterator_tag { };
struct incrementable_traversal_tag { };
struct single_pass_traversal_tag : incrementable_traversal_tag { };
struct forward_traversal_tag : single_pass_traversal_tag { };
struct bidirectional_traversal_tag : forward_traversal_tag { };
struct random_access_traversal_tag : bidirectional_traversal_tag { };
struct null_category_tag { };
struct input_output_iterator_tag : input_iterator_tag, output_iterator_tag {};
Addition to [lib.iterator.traits]
=================================
The ``iterator_tag`` class template is an iterator category tag that
encodes the access enum and traversal tag in addition to being compatible
with the original iterator tags. The ``iterator_tag`` class inherits
from one of the original iterator tags according to the following
pseudo-code.
The ``is_readable_iterator`` and ``iterator_traversal`` class
templates satisfy the UnaryTypeTrait_ requirements.
::
Given an iterator type ``X``, ``is_readable_iterator<X>::value``
yields ``true`` if, for an object ``a`` of type ``X``, ``*a`` is
convertible to ``iterator_traits<X>::value_type``, and ``false``
otherwise.
inherit-category(access, traversal-tag) =
if ((access & readable_iterator) && (access & lvalue_iterator)) {
if (traversal-tag is convertible to random_access_traversal_tag)
return random_access_iterator_tag;
else if (traversal-tag is convertible to bidirectional_traversal_tag)
return bidirectional_iterator_tag;
else if (traversal-tag is convertible to forward_traversal_tag)
return forward_iterator_tag;
else if (traversal-tag is convertible to single_pass_traversal_tag)
if (access-tag is convertible to writable_iterator_tag)
return input_output_iterator_tag;
else
return input_iterator_tag;
else
return null_category_tag;
} else if ((access & readable_iterator) and (access & writable_iterator)
and traversal-tag is convertible to single_pass_iterator_tag)
return input_output_iterator_tag;
else if (access & readable_iterator
and traversal-tag is convertible to single_pass_iterator_tag)
return input_iterator_tag;
else if (access & writable_iterator
and traversal-tag is convertible to incrementable_iterator_tag)
return output_iterator_tag;
else
return null_category_tag;
``iterator_traversal<X>::value_type`` is defined to be:
If the argument for ``TraversalTag`` is not convertible to
``incrementable_iterator_tag`` then the program is ill-formed.
.. parsed-literal::
The ``is_readable``, ``is_writable``, ``is_swappable``, and
``traversal_category`` class templates are traits classes. For
iterators whose ``iterator_traits<Iter>::iterator_category`` type is
``iterator_tag``, these traits obtain the ``access`` enum and
``traversal`` member type from within ``iterator_tag``. For iterators
whose ``iterator_traits<Iter>::iterator_category`` type is not
``iterator_tag`` and instead is a tag convertible to one of the
original tags, the appropriate traversal tag and access bits are
deduced. The following pseudo-code describes the algorithm.
::
is-readable(Iterator) =
cat = iterator_traits<Iterator>::iterator_category;
if (cat == iterator_tag<Access,Traversal>)
return Access & readable_iterator;
else if (cat is convertible to input_iterator_tag)
return true;
else
return false;
is-writable(Iterator) =
cat = iterator_traits<Iterator>::iterator_category;
if (cat == iterator_tag<Access,Traversal>)
return Access & writable_iterator;
else if (cat is convertible to output_iterator_tag)
return true;
else if (
cat is convertible to forward_iterator_tag
and iterator_traits<Iterator>::reference is a
mutable reference)
return true;
else
return false;
is-swappable(Iterator) =
cat = iterator_traits<Iterator>::iterator_category;
if (cat == iterator_tag<Access,Traversal>)
return Access & swappable_iterator;
else if (cat is convertible to forward_iterator_tag) {
if (iterator_traits<Iterator>::reference is a const reference)
return false;
else
return true;
} else
return false;
traversal-category(Iterator) =
cat = iterator_traits<Iterator>::iterator_category;
if (cat == iterator_tag<Access,Traversal>)
return Traversal;
traversal-category(X) =
cat = iterator_traits<X>::iterator_category;
if (cat is convertible to incrementable_traversal_tag)
return cat;
else if (cat is convertible to random_access_iterator_tag)
return random_access_traversal_tag;
else if (cat is convertible to bidirectional_iterator_tag)
@ -810,39 +734,24 @@ deduced. The following pseudo-code describes the algorithm.
else if (cat is convertible to forward_iterator_tag)
return forward_traversal_tag;
else if (cat is convertible to input_iterator_tag)
return single_pass_iterator_tag;
return single_pass_traversal_tag;
else if (cat is convertible to output_iterator_tag)
return incrementable_iterator_tag;
return incrementable_traversal_tag;
else
return null_category_tag;
*the program is ill-formed*
The following specializations provide the access and traversal
category tags for pointer types.
===========
Footnotes
===========
::
template <typename T>
struct is_readable<const T*> { typedef true_type type; };
template <typename T>
struct is_writable<const T*> { typedef false_type type; };
template <typename T>
struct is_swappable<const T*> { typedef false_type type; };
template <typename T>
struct is_readable<T*> { typedef true_type type; };
template <typename T>
struct is_writable<T*> { typedef true_type type; };
template <typename T>
struct is_swappable<T*> { typedef true_type type; };
template <typename T>
struct traversal_category<T*>
{
typedef random_access_traversal_tag type;
};
.. _UnaryTypeTrait: n1519_
The UnaryTypeTrait concept is defined in n1519_; the LWG added the
requirement that specializations are derived from their nested
``::type``.
.. _n1519: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1519.htm
..
LocalWords: Abrahams Siek Witt const bool Sutter's WG int UL LI href Lvalue

198
doc/permutation_iterator.html
View File

@ -9,7 +9,198 @@
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab" />
<meta name="date" content="2003-09-14" />
<meta name="copyright" content="Copyright Toon Knapen, David Abrahams, Roland Richter, and Jeremy Siek 2003. All rights reserved" />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
<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="permutation-iterator">
@ -79,7 +270,8 @@ past-the-end iterator to the indices.</p>
template&lt; class ElementIterator
, class IndexIterator
, class ValueT = use_default
, class CategoryT = use_default
, unsigned access = use_default_access
, class Traversal = use_default
, class ReferenceT = use_default
, class DifferenceT = use_default &gt;
class permutation_iterator
@ -121,7 +313,7 @@ ForwardIterator instead of amortized constant time.</p>
<hr class="footer" />
<div class="footer">
<a class="reference" href="permutation_iterator.rst">View document source</a>.
Generated on: 2003-09-21 09:35 UTC.
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>

77
doc/style.tex
View File

@ -1,60 +1,3 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%% docutils.sty: A style for docutils latex output %%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% o author: Alexander Schmolck (a.schmolck@gmx.net)
%% o created: 2002-07-07 10:50:31+00:40
%% o last modified: $Date: 2003/09/22 19:55:01 $
%% o keywords:
%% o license:
%XXX titlesec
%% XXX geometry
\usepackage{graphicx}
\usepackage{latexsym} % extra symbols
\usepackage{url} % !!!: pay attention when using in other commands!!!
\usepackage{verbatim} % normal verbatim has lenght-limit
\usepackage{enumerate} % easy style choice with e.g: ``\begin{enumerate}[Ex i.]``
\usepackage{hyperref} %href, htarget and hlink XXX: pdfauthor, pdfcreator etc.
\usepackage{xr} %XXX do we need this?
% need this to have ``fboxes`` in ``enviroments``, as well as ``verbatim``s
\usepackage{fancybox}
\usepackage{mdwtab} % better tables and arrays (fixes spacing and adds
% vertical align and multirows (m))
\usepackage{ltxtable} % long and autoscaling tables (use X for autoscaled
% columns)
\newcommand{\transition}{\vspace{2em}\par\hrule{}\par\vspace{2em}}
\newcommand{\classifier}[1]{(\textit{#1})}
\newenvironment{topic}[1]%
{\begin{Sbox}%
\begin{minipage}{.8\textwidth}%
\protect{\large{\textbf{#1}}}\par\vspace{.5em}}%
{\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}}
%XXX shadow box for warnings?
\newenvironment{admonition}[1]%
{\begin{center}%
\begin{Sbox}%
\begin{minipage}{.9\textwidth}%
\protect{\textsc{#1}}\par\vspace{.2em}}%
{\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}\end{center}}
\newenvironment{doctest}%
{\VerbatimEnvironment
\begin{Verbatim}}%
{\end{Verbatim}}
% {%
% \begin{Sbox}%
% \begin{minipage}{.8\textwidth}%
% \protect{\large{\textsc{#1}}\par\vspace{.5em}}}%
% {\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}}
%{\end{minipage}\end{Sbox}\fbox{\TheSbox}}
%% just a piece of example code
% \newcommand{\vitem}%
% {\SaveVerb[{\item[\UseVerb{\MyTemp}]}]{\MyTemp}}
%%%%%%%%%%%%%%%%%%% Added by DWA %%%%%%%%%%%%%%%%%%%%%%%%%
% donot indent first line.
\setlength{\parindent}{0pt}
\setlength{\parskip}{5pt plus 2pt minus 1pt}
@ -75,4 +18,24 @@
\usepackage{pslatex}
% pagestyle
% \usepackage{fancyhdr}
\pagestyle{headings}
\setlength{\paperwidth}{7.375in}
\setlength{\paperheight}{9.25in}
\setlength{\oddsidemargin}{0.375in}
\setlength{\evensidemargin}{0.375in}
\setlength{\textwidth}{5in}
\setlength{\textheight}{7.125in}
\setlength{\topmargin}{-0.375in}
\setlength{\headheight}{0.25in}
\setlength{\headsep}{0.25in}
\setlength{\footskip}{0.25in}
\setlength{\admonitionwidth}{0.9\textwidth}
\setlength{\docinfowidth}{0.9\textwidth}