diff --git a/doc/generate.py b/doc/generate.py new file mode 100644 index 0000000..86572ba --- /dev/null +++ b/doc/generate.py @@ -0,0 +1,29 @@ +#!/usr/bin/python + +# +# Generate html, TeX, and PDF versions of all the source files +# +import os +import sys + +from syscmd import syscmd +from sources import sources + +if 0: + for s in sources: + syscmd('boosthtml %s' % s) +else: + extensions = ('html', 'tex', 'pdf') + + if len(sys.argv) > 1: + extensions = sys.argv[1:] + + all = [ '%s.%s' % (os.path.splitext(s)[0],ext) + for ext in extensions + for s in sources + ] + + print 'make %s' % ' '.join(all) + syscmd('make %s' % ' '.join(all)) + + diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html index 5c21289..e845544 100755 --- a/doc/new-iter-concepts.html +++ b/doc/new-iter-concepts.html @@ -3,13 +3,204 @@ - + New Iterator Concepts - +
@@ -107,7 +298,7 @@ geared towards iterator traversal (hence the category names), while requirements that address value access sneak in at various places. The following table gives a summary of the current value access requirements in the iterator categories.

- +
@@ -317,16 +508,24 @@ given in the following diagram.

Like the old iterator requirements, we provide tags for purposes of dispatching based on the traversal concepts. The tags are related via inheritance so that a tag is convertible to another tag if the concept -associated with the first tag is a refinement of the second tag. Our -design reuses iterator_traits<Iter>::iterator_category as the -access mechanism for the traversal tag. If an iterator wishes to meet -the requirements of both a new iterator concept and an old iterator -concept, it can use an iterator category type that inherits from both -the the old iterator tag and the new traversal tag.

+associated with the first tag is a refinement of the second tag.

+

Our design reuses iterator_traits<Iter>::iterator_category to +indicate an iterator's traversal capability. To specify +capabilities not captured by any old-style iterator category, an +iterator designer can use an iterator_category type that is +convertible to both the the most-derived old iterator category tag +which fits, and the appropriate new iterator traversal tag.

+

We do not provide tags for the purposes of dispatching based on the -access concepts. There are two reasons: we could not find a way to -automatically infer the right access tags for old-style iterators and -the need for dispatching based on the access concepts is not as great.

+access concepts, in part because we could not find a way to +automatically infer the right access tags for old-style iterators. +An iterator's writability may be dependent on the assignability of +its value_type and there's no known way to detect whether an +arbitrary type is assignable. Fortunately, the need for +dispatching based on access capability is not as great as the need +for dispatching based on traversal capability.

A difficult design decision concerned the operator[]. The direct approach for specifying operator[] would have a return type of reference; the same as operator*. However, going in this @@ -355,7 +554,7 @@ object of type T.

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.

-
+
@@ -402,6 +601,10 @@ to (*a).m
+

Writable Iterators [lib.writable.iterators]

@@ -410,7 +613,7 @@ if the following expressions are valid and respect the stated semantics. In addition, a model of Writable Iterator must include in its documentation the set of value types that it allows for output.

- +
@@ -439,7 +642,7 @@ value types of X

A class or built-in type X models the Swappable Iterator concept if the following expressions are valid and respect the stated semantics.

-
+
@@ -470,7 +673,7 @@ exchanged

Lvalue Iterators [lib.lvalue.iterators]

The Lvalue Iterator concept adds the requirement that the reference type be a reference to the value type of the iterator.

-
+
@@ -507,7 +710,7 @@ type X, A class or built-in type X models the Incrementable Iterator concept if the following expressions are valid and respect the stated semantics.

-
+
@@ -544,13 +747,15 @@ semantics.

+

Single Pass Iterators [lib.single.pass.iterators]

A class or built-in type X models the Single Pass Iterator concept if the following expressions are valid and respect the stated semantics.

- +
@@ -590,13 +795,15 @@ relation over its domain
+

Forward Traversal Iterators [lib.forward.traversal.iterators]

A class or built-in type X models the Forward Traversal Iterator concept if the following expressions are valid and respect the stated semantics.

- +
@@ -637,13 +844,15 @@ the distance between iterators
+

Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]

A class or built-in type X models the Bidirectional Traversal Iterator concept if the following expressions are valid and respect the stated semantics.

- +
@@ -689,6 +898,8 @@ implies r ==
+

Random Access Traversal Iterators [lib.random.access.traversal.iterators]

@@ -697,7 +908,7 @@ Iterator concept if the following expressions are valid and respect the stated semantics. In the table below, Distance is iterator_traits<X>::difference_type and n represents a constant object of type Distance.

- +
@@ -801,6 +1012,8 @@ ordering relation
+
@@ -861,5 +1074,11 @@ LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct LocalWords: TraversalTag typename lvalues DWA Hmm JGS mis enum --> +
+
+View document source. +Generated on: 2003-12-02 13:08 UTC. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst index 53835d4..d48f039 100644 --- a/doc/new-iter-concepts.rst +++ b/doc/new-iter-concepts.rst @@ -299,17 +299,27 @@ given in the following diagram. Like the old iterator requirements, we provide tags for purposes of dispatching based on the traversal concepts. The tags are related via inheritance so that a tag is convertible to another tag if the concept -associated with the first tag is a refinement of the second tag. Our -design reuses ``iterator_traits::iterator_category`` as the -access mechanism for the traversal tag. If an iterator wishes to meet -the requirements of both a new iterator concept and an old iterator -concept, it can use an iterator category type that inherits from both -the the old iterator tag and the new traversal tag. +associated with the first tag is a refinement of the second tag. + +Our design reuses ``iterator_traits::iterator_category`` to +indicate an iterator's traversal capability. To specify +capabilities not captured by any old-style iterator category, an +iterator designer can use an ``iterator_category`` type that is +convertible to both the the most-derived old iterator category tag +which fits, and the appropriate new iterator traversal tag. + +.. dwa2003/1/2: Note that we are not *requiring* convertibility to + a new-style traversal tag in order to meet new concepts. + Old-style iterators still fit, after all. We do not provide tags for the purposes of dispatching based on the -access concepts. There are two reasons: we could not find a way to -automatically infer the right access tags for old-style iterators and -the need for dispatching based on the access concepts is not as great. +access concepts, in part because we could not find a way to +automatically infer the right access tags for old-style iterators. +An iterator's writability may be dependent on the assignability of +its ``value_type`` and there's no known way to detect whether an +arbitrary type is assignable. Fortunately, the need for +dispatching based on access capability is not as great as the need +for dispatching based on traversal capability. A difficult design decision concerned the ``operator[]``. The direct approach for specifying ``operator[]`` would have a return type of @@ -373,6 +383,10 @@ member of type ``T``. | | |to ``(*a).m`` | +-----------------------------------+------------------------+-------------------------+ +.. TR1: the originally-proposed requirement that typeof(*a) == R + was too restrictive. Now we just require that it's + convertible to R and that accessing a T through that conversion + is equivalent to accessing a T directly. .. _Writable Iterator: @@ -395,8 +409,6 @@ output. | | | value types of ``X`` | +-------------------------+--------------+----------------------------+ - - Swappable Iterators [lib.swappable.iterators] --------------------------------------------- @@ -472,6 +484,8 @@ semantics. | |``incrementable_traversal_tag``| | +--------------------------------+-------------------------------+--------------------+ +.. TR1: incrementable_iterator_tag changed to + incrementable_traversal_tag for consistency. Single Pass Iterators [lib.single.pass.iterators] ------------------------------------------------- @@ -502,6 +516,9 @@ semantics. | |``single_pass_traversal_tag``| | +--------------------------------+-----------------------------+---------------------------+ +.. TR1: single_pass_iterator_tag changed to + single_pass_traversal_tag for consistency + Forward Traversal Iterators [lib.forward.traversal.iterators] ------------------------------------------------------------- @@ -533,6 +550,9 @@ semantics. | |``forward_traversal_tag`` | | +---------------------------------------+-----------------------------------+---------------+ +.. TR1: forward_traversal_iterator_tag changed to + forward_traversal_tag for consistency + Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators] ------------------------------------------------------------------------- @@ -570,6 +590,8 @@ the stated semantics. | | | | +------------------------------------+---------------------------------------------+---------------------+ +.. TR1: bidirectional_traversal_iterator_tag changed to + bidirectional_traversal_tag for consistency Random Access Traversal Iterators [lib.random.access.traversal.iterators] ------------------------------------------------------------------------- @@ -635,6 +657,8 @@ constant object of type ``Distance``. | |``random_access_traversal_tag`` | | | +-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +.. TR1: random_access_traversal_iterator_tag changed to + random_access_traversal_tag for consistency Addition to [lib.iterator.synopsis] diff --git a/doc/sources.py b/doc/sources.py new file mode 100644 index 0000000..a69b4a7 --- /dev/null +++ b/doc/sources.py @@ -0,0 +1,18 @@ +# This is where we list the ReStructuredText source files that form +# the book. When you're ready to expose a new chapter, add the +# filename here and put links in index.rst + +sources = [ +'counting_iterator.rst', +'facade-and-adaptor.rst', +'filter_iterator.rst', +'function_output_iterator.rst', +'index.rst', +'indirect_iterator.rst', +'iterator_adaptor.rst', +'iterator_facade.rst', +'new-iter-concepts.rst', +'permutation_iterator.rst', +'reverse_iterator.rst' + ] +