diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html index f50727a..5901c3c 100755 --- a/doc/new-iter-concepts.html +++ b/doc/new-iter-concepts.html @@ -3,13 +3,291 @@ - + New Iterator Concepts - +
@@ -27,7 +305,7 @@ Lab, Zephyr Associates, Inc. Date: 2004-11-01 -Number:This is a revised version of n1550=03-0133, which was +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. @@ -51,8 +329,8 @@ of iterators that are used in practice. -
-

Table of Contents

+
+

Table of Contents

-
-

Motivation

+
+

Motivation

The standard iterator categories and requirements are flawed because they use a single hierarchy of concepts to address two orthogonal issues: iterator traversal and value access. As a result, many @@ -113,7 +391,7 @@ requirements in the iterator categories.

-Value Access Requirements in Existing Iterator Categories +Value Access Requirements in Existing Iterator Categories @@ -146,7 +424,7 @@ In paragraph 23.2.4/1 it says that a transform_iterator). +value of the some underlying iterator (see transform_iterator). For unary functions such as times, the return type of operator* clearly needs to be the result_type of the function object, which is typically not a reference. Because random access @@ -173,8 +451,8 @@ cannot separate the need for random access or bidirectional traversal from the need for a true reference return type.
-
-

Impact on the Standard

+
+

Impact on the Standard

This proposal for TR1 is a pure extension. Further, the new iterator concepts are backward-compatible with the old iterator requirements, and old iterators are forward-compatible with the new iterator @@ -189,13 +467,13 @@ made it). -DWA --> standards conforming input iterator is allowed to have a tag that is not input_iterator_tag but that is convertible to input_iterator_tag? -JGS --> -

-

Possible (but not proposed) Changes to the Working Paper

+
+

Possible (but not proposed) Changes to the Working Paper

The extensions in this paper suggest several changes we might make to the working paper for the next standard. These changes are not a formal part of this proposal for TR1.

-
-

Changes to Algorithm Requirements

+
+

Changes to Algorithm Requirements

The algorithms in the standard library could benefit from the new iterator concepts because the new concepts provide a more accurate way to express their type requirements. The result is algorithms that are @@ -239,7 +517,7 @@ Forward Iterator (2) -> Swappable Iterator and Incrementable Iterator

Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable and Swappable Iterator
partition
-

Bidirectional Iterator (1) -> Bidirectional Traversal Iterator and Readable Iterator, +

Bidirectional Iterator (1) -> Bidirectional Traversal Iterator and Readable Iterator, Bidirectional Iterator (2) -> Bidirectional Traversal Iterator and Writable Iterator

copy_backwards
@@ -259,15 +537,15 @@ Bidirectional Iterator (2) -> Bidirectional Traversal Iterator and Writable I
transform
-
-

Deprecations

+
+

Deprecations

For the next working paper (but not for TR1), the committee should consider deprecating the old iterator tags, and std::iterator_traits, since it will be superceded by individual traits metafunctions.

-
-

vector<bool>

+
+

vector<bool>

For the next working paper (but not for TR1), the committee should consider reclassifying vector<bool>::iterator as a Random Access Traversal Iterator and Readable Iterator and Writable @@ -275,8 +553,8 @@ Iterator.

-
-

Design

+
+

Design

The iterator requirements are to be separated into two groups. One set of concepts handles the syntax and semantics of value access:

    @@ -298,7 +576,7 @@ of concepts handles the syntax and semantics of value access:

The refinement relationships for the traversal concepts are in the following diagram.

-
traversal.png
+traversal.png

In addition to the iterator movement operators, such as operator++, the traversal concepts also include requirements on position comparison such as operator== and operator<. The @@ -313,7 +591,7 @@ interoperable with int

The relationship between the new iterator concepts and the old are given in the following diagram.

-
oldeqnew.png
+oldeqnew.png

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 @@ -346,19 +624,19 @@ only required to return something convertible to the i[n] = t (for a Writable Iterator).

-
-

Proposed Text

-
-

Addition to [lib.iterator.requirements]

-
-

Iterator Value Access Concepts [lib.iterator.value.access]

+
+

Proposed Text

+
+

Addition to [lib.iterator.requirements]

+
+

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, R is std::iterator_traits<X>::reference, T is std::iterator_traits<X>::value_type, and v is a constant object of type T.

-
-

Readable Iterators [lib.readable.iterators]

+
+

Readable Iterators [lib.readable.iterators]

A class or built-in type X models the Readable Iterator concept for value type T if, in addition to X being Assignable and Copy Constructible, the following expressions are valid and respect @@ -371,11 +649,11 @@ type T.

-Readable Iterator Requirements (in addition to Assignable and Copy Constructible) +Readable Iterator Requirements (in addition to Assignable and Copy Constructible) -Expression -Return Type -Note/Precondition +Expression +Return Type +Note/Precondition @@ -399,9 +677,9 @@ non-cv-qualified type -
- +
+

Writable Iterators [lib.writable.iterators]

A class or built-in type X models the Writable Iterator concept if, in addition to X being Copy Constructible, the following expressions are valid and respect the stated semantics. Writable @@ -413,11 +691,11 @@ Iterators have an associated set of value types.

-Writable Iterator Requirements (in addition to Copy Constructible) +Writable Iterator Requirements (in addition to Copy Constructible) -Expression -Return Type -Precondition +Expression +Return Type +Precondition @@ -430,8 +708,8 @@ value types of X
-
-

Swappable Iterators [lib.swappable.iterators]

+
+

Swappable Iterators [lib.swappable.iterators]

A class or built-in type X models the Swappable Iterator concept if, in addition to X being Copy Constructible, the following expressions are valid and respect the stated semantics.

@@ -442,11 +720,11 @@ expressions are valid and respect the stated semantics.

-Swappable Iterator Requirements (in addition to Copy Constructible) +Swappable Iterator Requirements (in addition to Copy Constructible) -Expression -Return Type -Postcondition +Expression +Return Type +Postcondition @@ -461,8 +739,8 @@ exchanged Writable Iterator concepts is also a model of Swappable Iterator. --end note]

-
-

Lvalue Iterators [lib.lvalue.iterators]

+
+

Lvalue Iterators [lib.lvalue.iterators]

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

@@ -473,11 +751,11 @@ iterator.

-Lvalue Iterator Requirements +Lvalue Iterator Requirements -Expression -Return Type -Note/Assertion +Expression +Return Type +Note/Assertion @@ -497,14 +775,14 @@ Iterator then a *b.

-
-

Iterator Traversal Concepts [lib.iterator.traversal]

+
+

Iterator Traversal Concepts [lib.iterator.traversal]

In the tables below, X is an iterator type, a and b are constant objects of type X, r and s are mutable objects of type X, T is std::iterator_traits<X>::value_type, and v is a constant object of type T.

-
-

Incrementable Iterators [lib.incrementable.iterators]

+
+

Incrementable Iterators [lib.incrementable.iterators]

A class or built-in type X models the Incrementable Iterator concept if, in addition to X being Assignable and Copy Constructible, the following expressions are valid and respect the @@ -516,11 +794,11 @@ stated semantics.

-Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible) +Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible) -Expression -Return Type -Assertion +Expression +Return Type +Assertion @@ -551,27 +829,26 @@ to T z(*
-
-

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

+
+

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.

---+++ - + - - - + + - @@ -595,6 +872,13 @@ relation over its domain + + + + + @@ -606,8 +890,8 @@ relation over its domain -
-

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

+
+

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

A class or built-in type X models the Forward Traversal Iterator concept if, in addition to X meeting the requirements of Default Constructible and Single Pass Iterator, the following expressions are @@ -619,11 +903,11 @@ valid and respect the stated semantics.

- + - - - + + + @@ -638,11 +922,6 @@ singular value. dereferenceable implies ++r == ++s. - - - - @@ -653,8 +932,8 @@ the distance between iterators -
-

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

+
+

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

A class or built-in type X models the Bidirectional Traversal Iterator concept if, in addition to X meeting the requirements of Forward Traversal Iterator, the following expressions are valid and @@ -667,14 +946,14 @@ respect the stated semantics.

- - - - + + - @@ -716,8 +995,8 @@ implies r -

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

+
+

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

A class or built-in type X models the Random Access Traversal Iterator concept if the following expressions are valid and respect the stated semantics. In the table below, Distance is @@ -731,12 +1010,12 @@ constant object of type Distance<

- + - - - - + + + @@ -830,8 +1109,8 @@ ordering relation -
-

Interoperable Iterators [lib.interoperable.iterators]

+
+

Interoperable Iterators [lib.interoperable.iterators]

A class or built-in type X that models Single Pass Iterator is interoperable with a class or built-in type Y that also models Single Pass Iterator if the following expressions are valid and @@ -846,9 +1125,9 @@ constant object of type Distance<

- - - + + + @@ -888,10 +1167,10 @@ the following additional requirements must be met.

 - - - - + + + + @@ -954,8 +1233,8 @@ the following additional requirements must be met.

-
-

Addition to [lib.iterator.synopsis]

+
+

Addition to [lib.iterator.synopsis]

 // lib.iterator.traits, traits and tags
 template <class Iterator> struct is_readable_iterator;
@@ -968,8 +1247,8 @@ struct bidirectional_traversal_tag : forward_traversal_tag { };
 struct random_access_traversal_tag : bidirectional_traversal_tag { };
-
-

Addition to [lib.iterator.traits]

+
+

Addition to [lib.iterator.traits]

The is_readable_iterator class template satisfies the UnaryTypeTrait requirements.

Given an iterator type X, is_readable_iterator<X>::value @@ -978,10 +1257,10 @@ convertible to iterator_traits< otherwise.

iterator_traversal<X>::type is

-category-to-traversal(iterator_traits<X>::iterator_category) 
+category-to-traversal(iterator_traits<X>::iterator_category)

where category-to-traversal is defined as follows

-
+
 category-to-traversal(C) =
     if (C is convertible to incrementable_traversal_tag)
         return C;
@@ -1000,8 +1279,8 @@ otherwise.
-
-

Footnotes

+
+

Footnotes

The UnaryTypeTrait concept is defined in n1519; the LWG is considering adding the requirement that specializations are derived from their nested ::type.

@@ -1014,10 +1293,11 @@ LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct LocalWords: TraversalTag typename lvalues DWA Hmm JGS mis enum -->
-
+
View document source. Generated by Docutils from reStructuredText source. +
diff --git a/doc/new-iter-concepts.pdf b/doc/new-iter-concepts.pdf index 636aaab..aa680ec 100755 Binary files a/doc/new-iter-concepts.pdf and b/doc/new-iter-concepts.pdf differ diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst index 389e52c..df4a70f 100644 --- a/doc/new-iter-concepts.rst +++ b/doc/new-iter-concepts.rst @@ -492,26 +492,30 @@ concept if the following expressions are valid and respect the stated semantics. -+--------------------------------------------------------------------------------------------------------+ -|Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality | -|Comparable) | -+--------------------------------+-----------------------------+-------------+---------------------------+ -|Expression |Return Type | Operational |Assertion/ | -| | | Semantics |Pre-/Post-condition | -+================================+=============================+=============+===========================+ -|``++r`` |``X&`` | |pre: ``r`` is | -| | | |dereferenceable; post: | -| | | |``r`` is dereferenceable or| -| | | |``r`` is past-the-end | -+--------------------------------+-----------------------------+-------------+---------------------------+ -|``a == b`` |convertible to ``bool`` | |``==`` is an equivalence | -| | | |relation over its domain | -+--------------------------------+-----------------------------+-------------+---------------------------+ -|``a != b`` |convertible to ``bool`` |``!(a == b)``| | -+--------------------------------+-----------------------------+-------------+---------------------------+ -|``iterator_traversal::type`` |Convertible to | | | -| |``single_pass_traversal_tag``| | | -+--------------------------------+-----------------------------+-------------+---------------------------+ ++----------------------------------------------------------------------------------------------------------------+ +|Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality Comparable) | +| | ++----------------------------------------+-----------------------------+-------------+---------------------------+ +|Expression |Return Type | Operational |Assertion/ | +| | | Semantics |Pre-/Post-condition | ++========================================+=============================+=============+===========================+ +|``++r`` |``X&`` | |pre: ``r`` is | +| | | |dereferenceable; post: | +| | | |``r`` is dereferenceable or| +| | | |``r`` is past-the-end | ++----------------------------------------+-----------------------------+-------------+---------------------------+ +|``a == b`` |convertible to ``bool`` | |``==`` is an equivalence | +| | | |relation over its domain | ++----------------------------------------+-----------------------------+-------------+---------------------------+ +|``a != b`` |convertible to ``bool`` |``!(a == b)``| | ++----------------------------------------+-----------------------------+-------------+---------------------------+ +|``iterator_traits::difference_type`` |A signed integral type | | | +| |representing the distance | | | +| |between iterators | | | ++----------------------------------------+-----------------------------+-------------+---------------------------+ +|``iterator_traversal::type`` |Convertible to | | | +| |``single_pass_traversal_tag``| | | ++----------------------------------------+-----------------------------+-------------+---------------------------+ .. TR1: single_pass_iterator_tag changed to single_pass_traversal_tag for consistency @@ -537,10 +541,6 @@ valid and respect the stated semantics. | | |dereferenceable implies | | | |``++r == ++s.`` | +---------------------------------------+-----------------------------------+----------------------------+ -|``iterator_traits::difference_type``|A signed integral type representing| | -| |the distance between iterators | | -| | | | -+---------------------------------------+-----------------------------------+----------------------------+ |``iterator_traversal::type`` |Convertible to | | | |``forward_traversal_tag`` | | +---------------------------------------+-----------------------------------+----------------------------+ diff --git a/include/boost/iterator/iterator_archetypes.hpp b/include/boost/iterator/iterator_archetypes.hpp index 9ffa420..039de1c 100644 --- a/include/boost/iterator/iterator_archetypes.hpp +++ b/include/boost/iterator/iterator_archetypes.hpp @@ -196,6 +196,8 @@ namespace detail explicit archetype(ctor_arg arg) : traversal_archetype_(arg) {} + + typedef std::ptrdiff_t difference_type; }; }; @@ -219,7 +221,6 @@ namespace detail archetype() : traversal_archetype_(ctor_arg()) {} - typedef std::ptrdiff_t difference_type; }; };
Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality -Comparable)
Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality Comparable)
ExpressionReturn TypeOperational +
ExpressionReturn TypeOperational SemanticsAssertion/ +Assertion/ Pre-/Post-condition
!(a == b)  
iterator_traits<X>::difference_typeA signed integral type +representing the distance +between iterators  
iterator_traversal<X>::type Convertible to single_pass_traversal_tag
Forward Traversal Iterator Requirements (in addition to Default Constructible and Single Pass Iterator)
Forward Traversal Iterator Requirements (in addition to Default Constructible and Single Pass Iterator)
ExpressionReturn TypeAssertion/Note
ExpressionReturn TypeAssertion/Note
iterator_traits<X>::difference_typeA signed integral type representing -the distance between iterators 
iterator_traversal<X>::type Convertible to forward_traversal_tag
Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal +
Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal Iterator)
ExpressionReturn TypeOperational +
ExpressionReturn TypeOperational SemanticsAssertion/ +Assertion/ Pre-/Post-condition
Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator)
Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator)
ExpressionReturn TypeOperational SemanticsAssertion/ +
ExpressionReturn TypeOperational SemanticsAssertion/ Precondition
ExpressionReturn TypeAssertion/Precondition/Postcondition
ExpressionReturn TypeAssertion/Precondition/Postcondition
ExpressionReturn TypeOperational SemanticsAssertion/ Precondition
ExpressionReturn TypeOperational SemanticsAssertion/ Precondition