From f34109aa26abea25681f06a9d645bb7d719eabae Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Sat, 3 Nov 2007 03:25:13 +0000 Subject: [PATCH] Merging some of the more obvious changes from RC_1_34_0 [SVN r40714] --- doc/BidirectionalTraversal.html | 293 +----------- doc/ForwardTraversal.html | 293 +----------- doc/IncrementableIterator.html | 293 +----------- doc/LvalueIterator.html | 293 +----------- doc/RandomAccessTraversal.html | 293 +----------- doc/ReadableIterator.html | 293 +----------- doc/SinglePassIterator.html | 293 +----------- doc/SwappableIterator.html | 293 +----------- doc/WritableIterator.html | 293 +----------- doc/counting_iterator.html | 342 ++------------ doc/facade-and-adaptor.html | 716 +++++++++-------------------- doc/filter_iterator.html | 338 ++------------ doc/function_output_iterator.html | 336 ++------------ doc/index.html | 408 +++------------- doc/indirect_iterator.html | 338 ++------------ doc/interoperability-revisited.rst | 283 ++++++------ doc/issues.html | 451 ------------------ doc/iterator_adaptor.html | 374 ++------------- doc/iterator_archetypes.html | 344 ++------------ doc/iterator_concepts.html | 338 ++------------ doc/iterator_facade.html | 516 +++++---------------- doc/iterator_traits.html | 320 +------------ doc/new-iter-concepts.html | 491 +++++--------------- doc/permutation_iterator.html | 342 ++------------ doc/pointee.html | 326 +------------ doc/reverse_iterator.html | 338 ++------------ doc/rst2html | 2 +- doc/transform_iterator.html | 338 ++------------ doc/zip_iterator.html | 334 ++------------ example/Jamfile | 17 - 30 files changed, 1151 insertions(+), 8778 deletions(-) delete mode 100755 doc/issues.html delete mode 100644 example/Jamfile diff --git a/doc/BidirectionalTraversal.html b/doc/BidirectionalTraversal.html index 5bc8342..9c45f40 100644 --- a/doc/BidirectionalTraversal.html +++ b/doc/BidirectionalTraversal.html @@ -3,295 +3,14 @@ - + Bidirectional Traversal Concept - +

Bidirectional Traversal Concept

+ @@ -346,6 +65,12 @@ implies r +
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/ForwardTraversal.html b/doc/ForwardTraversal.html index 934aa56..702064d 100644 --- a/doc/ForwardTraversal.html +++ b/doc/ForwardTraversal.html @@ -3,295 +3,14 @@ - + Forward Traversal Concept - +

Forward Traversal Concept

+ @@ -337,6 +56,12 @@ the distance between iterators +
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/IncrementableIterator.html b/doc/IncrementableIterator.html index c42cfff..ae47b99 100644 --- a/doc/IncrementableIterator.html +++ b/doc/IncrementableIterator.html @@ -3,295 +3,14 @@ - + Incrementable Iterator Concept - +

Incrementable Iterator Concept

+ @@ -336,6 +55,12 @@ stated semantics.

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/LvalueIterator.html b/doc/LvalueIterator.html index 6575694..c20626c 100644 --- a/doc/LvalueIterator.html +++ b/doc/LvalueIterator.html @@ -3,295 +3,14 @@ - + Lvalue Iterator Concept - +

Lvalue Iterator Concept

+ @@ -326,6 +45,12 @@ equivalent to *b. +
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/RandomAccessTraversal.html b/doc/RandomAccessTraversal.html index 4dd09ca..4c681a6 100644 --- a/doc/RandomAccessTraversal.html +++ b/doc/RandomAccessTraversal.html @@ -3,295 +3,14 @@ - + Random Access Traversal Concept - +

Random Access Traversal Concept

+ @@ -404,6 +123,12 @@ ordering relation +
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/ReadableIterator.html b/doc/ReadableIterator.html index b6873c4..04be021 100644 --- a/doc/ReadableIterator.html +++ b/doc/ReadableIterator.html @@ -3,295 +3,14 @@ - + Readable Iterator Concept - +

Readable Iterator Concept

+ @@ -334,6 +53,12 @@ non-cv-qualified type +
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/SinglePassIterator.html b/doc/SinglePassIterator.html index 9a725e7..bc2835d 100644 --- a/doc/SinglePassIterator.html +++ b/doc/SinglePassIterator.html @@ -3,295 +3,14 @@ - + Single Pass Iterator Concept - +

Single Pass Iterator Concept

+ @@ -338,6 +57,12 @@ relation over its domain +
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/SwappableIterator.html b/doc/SwappableIterator.html index c11b570..e3c1eae 100644 --- a/doc/SwappableIterator.html +++ b/doc/SwappableIterator.html @@ -3,295 +3,14 @@ - + Swappable Iterator Concept - +

Swappable Iterator Concept

+ @@ -324,6 +43,12 @@ exchanged
[Note: An iterator that is a model of the Readable and Writable Iterator concepts
is also a model of Swappable Iterator. --end note]
+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/WritableIterator.html b/doc/WritableIterator.html index 76d621d..7247474 100644 --- a/doc/WritableIterator.html +++ b/doc/WritableIterator.html @@ -3,295 +3,14 @@ - + Writable Iterator Concept - +

Writable Iterator Concept

+ @@ -322,6 +41,12 @@ value types of X +
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/counting_iterator.html b/doc/counting_iterator.html index 63136f0..1cb5a17 100644 --- a/doc/counting_iterator.html +++ b/doc/counting_iterator.html @@ -3,295 +3,13 @@ - + Counting Iterator - + - +
@@ -303,13 +21,13 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de Organization: -Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport +Boost Consulting, Indiana University Open Systems +Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. @@ -339,18 +57,18 @@ are forwarded to the adapted object.

-
-

Table of Contents

+ -
-

counting_iterator synopsis

+
+

counting_iterator synopsis

@@ -389,10 +107,10 @@ algorithm:

if (CategoryOrTraversal is not use_default) return CategoryOrTraversal else if (numeric_limits<Incrementable>::is_specialized) - return iterator-category( + return iterator-category( random_access_traversal_tag, Incrementable, const Incrementable&) else - return iterator-category( + return iterator-category( iterator_traversal<Incrementable>::type, Incrementable, const Incrementable&) @@ -403,8 +121,8 @@ the cases where std::numeric_limi is true.]
-
-

counting_iterator requirements

+
+

counting_iterator requirements

The Incrementable argument shall be Copy Constructible and Assignable.

If iterator_category is convertible to forward_iterator_tag or forward_traversal_tag, the following must be well-formed:

@@ -429,8 +147,8 @@ n = i - j; i < j;
-
-

counting_iterator models

+
+

counting_iterator models

Specializations of counting_iterator model Readable Lvalue Iterator. In addition, they model the concepts corresponding to the iterator tags to which their iterator_category is convertible. @@ -445,8 +163,8 @@ concepts modeled by Incrementable counting_iterator<Y,C2,D2> if and only if X is interoperable with Y.

-
-

counting_iterator operations

+
+

counting_iterator operations

In addition to the operations required by the concepts modeled by counting_iterator, counting_iterator provides the following operations.

@@ -539,8 +257,8 @@ with current construc
-
-

Example

+
+

Example

This example fills an array with numbers and a second array with pointers into the first array, using counting_iterator for both tasks. Finally indirect_iterator is used to print out the numbers @@ -570,8 +288,14 @@ std::cout << std::endl; indirectly printing out the numbers from 0 to 7 0 1 2 3 4 5 6 -

The source code for this example can be found here.

+

The source code for this example can be found here.

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/facade-and-adaptor.html b/doc/facade-and-adaptor.html index d2199e6..630ddcb 100755 --- a/doc/facade-and-adaptor.html +++ b/doc/facade-and-adaptor.html @@ -3,294 +3,12 @@ - + Iterator Facade and Adaptor - - + +
@@ -302,13 +20,13 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com Organization: -Boost Consulting, Indiana University Open Systems -Lab, Zephyr Associates, Inc. +Boost Consulting, Indiana University Open Systems +Lab, Zephyr Associates, Inc. Date: -2004-11-01 -Number:This is a revised version of N1530=03-0113, which was +2006-09-11 +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. @@ -337,86 +55,86 @@ by adapting other iterators. -
-

Table of Contents

+
+

Table of Contents

-
-

Motivation

+
+

Motivation

Iterators play an important role in modern C++ programming. The iterator is the central abstraction of the algorithms of the Standard Library, allowing algorithms to be re-used in in a wide variety of contexts. The C++ Standard Library contains a wide variety of useful iterators. Every one of the standard containers comes with constant -and mutable iterators [2], and also reverse versions of those +and mutable iterators2, and also reverse versions of those same iterators which traverse the container in the opposite direction. The Standard also supplies istream_iterator and ostream_iterator for reading from and writing to streams, @@ -486,7 +204,7 @@ multiplies the dereferenced value by some constant. - @@ -494,7 +212,7 @@ parameter.
[1]We use the term concept to mean a set of requirements +
[1]We use the term concept to mean a set of requirements that a type must satisfy to be used with a particular template parameter.
- @@ -510,46 +228,46 @@ of more specialized adaptors, such as the -
-

Impact on the Standard

+
+

Impact on the Standard

This proposal is purely an addition to the C++ standard library. However, note that this proposal relies on the proposal for New Iterator Concepts.

-
-

Design

-
-

Iterator Concepts

+
+

Design

+
+

Iterator Concepts

This proposal is formulated in terms of the new iterator concepts -as proposed in n1550, 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.

-

This proposal does not strictly depend on proposal n1550, 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 n1550 was not accepted.

+could be reformulated using this mapping if n1550 was not accepted.

-
-

Interoperability

+
+

Interoperability

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.

-
-

Iterator Facade

+
+

Iterator Facade

@@ -572,7 +290,7 @@ include the associated types exposed through iterator traits: value_type, reference, difference_type, and iterator_category.

Iterator facade uses the Curiously Recurring Template -Pattern (CRTP) [Cop95] so that the user can specify the behavior +Pattern (CRTP) [Cop95] so that the user can specify the behavior of iterator_facade in a derived class. Former designs used policy objects to specify the behavior, but that approach was discarded for several reasons:

@@ -595,8 +313,8 @@ iterators, and a separate iterato impossible. -
-

Usage

+
+

Usage

The user of iterator_facade derives his iterator class from a specialization of iterator_facade and passes the derived iterator class as iterator_facade's first template parameter. @@ -659,8 +377,8 @@ constructor. Finally, if the iterator is to model Forward Traversal Iterator or a more-refined iterator concept, a default constructor is required.

-
-

Iterator Core Access

+
+

Iterator Core Access

iterator_facade 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 @@ -693,19 +411,19 @@ standardize the gateway protocol. Note that even if open a safety loophole, as every core member function preserves the invariants of the iterator.

-
-

operator[]

+
+

operator[]

The indexing operator for a generalized iterator presents special 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_iterator), because *(p+n) is a reference into the temporary iterator p+n, which is destroyed when operator[] returns.

Writable iterators built with iterator_facade implement the -semantics required by the preferred resolution to issue 299 and -adopted by proposal n1550: the result of p[n] is an object +semantics required by the preferred resolution to issue 299 and +adopted by proposal n1550: the result of p[n] is an object convertible to the iterator's value_type, and p[n] = x is equivalent to *(p + n) = x (Note: This result object may be implemented as a proxy containing a copy of p+n). This approach @@ -716,8 +434,8 @@ the implementation of her iterator is free to implement an class; it will hide the one supplied by iterator_facade from clients of her iterator.

-
-

operator->

+
+

operator->

The reference 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 value_type. When the value_type @@ -732,21 +450,21 @@ satisfied by the iterator_facade<

[2]The term mutable iterator refers to iterators over objects that +
[2]The term mutable iterator refers to iterators over objects that can be changed by assigning to the dereferenced iterator, while constant iterator refers to iterators over objects that cannot be modified.
-
[Cop95][Coplien, 1995] Coplien, J., Curiously Recurring Template +
[Cop95][Coplien, 1995] Coplien, J., Curiously Recurring Template Patterns, C++ Report, February 1995, pp. 24-27.

-
-

Iterator Adaptor

+
+

Iterator Adaptor

-

The iterator_adaptor class template adapts some Base [3] +

The iterator_adaptor class template adapts some Base3 type to create a new iterator. Instantiations of iterator_adaptor are derived from a corresponding instantiation of iterator_facade and implement the core behaviors in terms of the Base type. In @@ -755,7 +473,7 @@ instance of the Base - @@ -782,8 +500,8 @@ template parameter may not always be identical to the iterator's reference type, and will keep users from making mistakes based on that assumption.

-
-

Specialized Adaptors

+
+

Specialized Adaptors

This proposal also contains several examples of specialized adaptors which were easily implemented using iterator_adaptor:

    @@ -816,10 +534,10 @@ and Stanford GraphBase [8], to the BGL interface (which requires C++ Standard compliant iterators).

-
-

Proposed Text

-
-

Header <iterator_helper> synopsis [lib.iterator.helper.synopsis]

+
+

Proposed Text

+
+

Header <iterator_helper> synopsis [lib.iterator.helper.synopsis]

 struct use_default;
 
@@ -884,16 +602,16 @@ template <class UnaryFunction>
 class function_output_iterator;
-
-

Iterator facade [lib.iterator.facade]

+
+

Iterator facade [lib.iterator.facade]

iterator_facade is a base class template that implements the interface of standard iterators in terms of a few core functions and associated types, to be supplied by a derived iterator class.

-
-

Class template iterator_facade

+
+

Class template iterator_facade

@@ -914,11 +632,11 @@ class iterator_facade { typedef Reference reference; typedef Value* pointer; typedef Difference difference_type; - typedef /* see below */ iterator_category; + typedef /* see below */ iterator_category; reference operator*() const; - /* see below */ operator->() const; - /* see below */ operator[](difference_type n) const; + /* see below */ operator->() const; + /* see below */ operator[](difference_type n) const; Derived& operator++(); Derived operator++(int); Derived& operator--(); @@ -970,7 +688,7 @@ operator >=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, // Iterator difference template <class Dr1, class V1, class TC1, class R1, class D1, class Dr2, class V2, class TC2, class R2, class D2> -/* see below */ +/* see below */ operator-(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs); @@ -1022,7 +740,7 @@ Derived operator+ (typename Derived::difference_type n, X1 = C } - 2. category-to-traversal(X) is convertible to the most + 2. category-to-traversal(X) is convertible to the most derived traversal tag type to which X is also convertible, and not to any more-derived traversal tag type. @@ -1057,8 +775,8 @@ struct enable_if_interoperable {};
-
-

iterator_facade Requirements

+
+

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 @@ -1071,8 +789,8 @@ object of type X, X, and z is a constant object of a random access traversal iterator type interoperable with X.

-
-

iterator_facade Core Operations

+
+

iterator_facade Core Operations

[3]The term "Base" here does not refer to a base class and is +
[3]The term "Base" here does not refer to a base class and is not meant to imply the use of derivation. We have followed the lead of the standard library, which provides a base() function to access the underlying iterator object of a reverse_iterator adaptor.
@@ -1131,8 +849,8 @@ Iterator

-
-

iterator_facade operations

+
+

iterator_facade operations

The operations in this section are described in terms of operations on the core interface of Derived which may be inaccessible (i.e. private). The implementation should access these operations @@ -1146,7 +864,7 @@ through member functions of class -

operator->() const; (see below)

+

operator->() const; (see below)

@@ -1475,8 +1193,8 @@ operator -(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
-
-

Iterator adaptor [lib.iterator.adaptor]

+
+

Iterator adaptor [lib.iterator.adaptor]

@@ -1493,8 +1211,8 @@ Whether the derived class models any of the standard iterator concepts depends on the operations supported by the Base type and which core interface functions of iterator_facade are redefined in the Derived class.

-
-

Class template iterator_adaptor

+
+

Class template iterator_adaptor

@@ -1511,7 +1229,7 @@ template < , class Difference = use_default > class iterator_adaptor - : public iterator_facade<Derived, V', C', R', D'> // see details + : public iterator_facade<Derived, V', C', R', D'> // see details { friend class iterator_core_access; public: @@ -1546,13 +1264,13 @@ class iterator_adaptor };
-
-

iterator_adaptor requirements

+
+

iterator_adaptor requirements

static_cast<Derived*>(iterator_adaptor*) shall be well-formed. The Base argument shall be Assignable and Copy Constructible.

-
-

iterator_adaptor base class parameters

+
+

iterator_adaptor base class parameters

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:

@@ -1592,8 +1310,8 @@ expression involving ``Derived`` in those concepts' requirements. -->
-
-

iterator_adaptor public operations

+
+

iterator_adaptor public operations

iterator_adaptor();

@@ -1626,8 +1344,8 @@ expression involving ``Derived`` in those concepts' requirements. -->
-
-

iterator_adaptor protected member functions

+
+

iterator_adaptor protected member functions

Base const& base_reference() const;

@@ -1647,8 +1365,8 @@ expression involving ``Derived`` in those concepts' requirements. -->
-
-

iterator_adaptor private member functions

+
+

iterator_adaptor private member functions

typename iterator_adaptor::reference dereference() const;

@@ -1716,8 +1434,8 @@ typename iterator_adaptor::difference_type distance_to(
-
-

Specialized adaptors [lib.iterator.special.adaptors]

+
+

Specialized adaptors [lib.iterator.special.adaptors]

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 @@ -1745,8 +1463,8 @@ diagnostic required.

take the constructor out of the overload set when the types are not implicitly convertible. ]

-
-

Indirect iterator

+
+

Indirect iterator

@@ -1758,8 +1476,8 @@ iterator adaptor makes it possible to view a container of pointers auxiliary traits, pointee and indirect_reference, to provide support for underlying iterators whose value_type is not an iterator.

-
-

Class template pointee

+
+

Class template pointee

@@ -1802,8 +1520,8 @@ else }
-
-

Class template indirect_reference

+
+

Class template indirect_reference

@@ -1837,8 +1555,8 @@ else std::iterator_traits<Dereferenceable>::reference
-
-

Class template indirect_iterator

+
+

Class template indirect_iterator

@@ -1918,8 +1636,8 @@ else ) iterator_category;
-
-

indirect_iterator requirements

+
+

indirect_iterator requirements

The expression *v, where v is an object of iterator_traits<Iterator>::value_type, shall be valid expression and convertible to reference. Iterator shall @@ -1932,8 +1650,8 @@ the requirements indicated by ite parameter is not use_default, as implied by the algorithm for deducing the default for the value_type member.]

-
-

indirect_iterator models

+
+

indirect_iterator models

In addition to the concepts indicated by iterator_category and by iterator_traversal<indirect_iterator>::type, a specialization of indirect_iterator models the following @@ -1953,8 +1671,8 @@ expression (where t i indirect_iterator<Y,V2,C2,R2,D2> if and only if X is interoperable with Y.

-
-

indirect_iterator operations

+
+

indirect_iterator operations

In addition to the operations required by the concepts described above, specializations of indirect_iterator provide the following operations.

@@ -2045,15 +1763,15 @@ indirect_iterator(
-
-

Reverse iterator

+
+

Reverse iterator

The reverse iterator adaptor iterates through the adapted iterator range in the opposite direction.

-
-

Class template reverse_iterator

+
+

Class template reverse_iterator

@@ -2092,14 +1810,14 @@ Lvalue Iterator, then iterator_ca bidirectional_iterator_tag. Otherwise, iterator_category is convertible to input_iterator_tag.

-
-

reverse_iterator requirements

+
+

reverse_iterator requirements

Iterator must be a model of Bidirectional Traversal Iterator. The type iterator_traits<Iterator>::reference must be the type of *i, where i is an object of type Iterator.

-
-

reverse_iterator models

+
+

reverse_iterator models

A specialization of reverse_iterator models the same iterator traversal and iterator access concepts modeled by its Iterator argument. In addition, it may model old iterator concepts @@ -2137,8 +1855,8 @@ Random Access Traversal Iterator reverse_iterator<Y> if and only if X is interoperable with Y.

-
-

reverse_iterator operations

+
+

reverse_iterator operations

In addition to the operations required by the concepts modeled by reverse_iterator, reverse_iterator provides the following operations.

@@ -2228,16 +1946,16 @@ return *--tmp;
-
-

Transform iterator

+
+

Transform iterator

The transform iterator adapts an iterator by modifying the operator* to apply a function object to the result of dereferencing the iterator and returning the result.

-
-

Class template transform_iterator

+
+

Class template transform_iterator

@@ -2292,8 +2010,8 @@ convertible to forward_iterator_t model Readable Lvalue Iterator then iterator_category is convertible to input_iterator_tag.

-
-

transform_iterator requirements

+
+

transform_iterator requirements

The type UnaryFunction must be Assignable, Copy Constructible, and the expression f(*i) must be valid where f is an object of type UnaryFunction, i is an object of type Iterator, and @@ -2301,8 +2019,8 @@ where the type of f(*i)result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type.

The argument Iterator shall model Readable Iterator.

-
-

transform_iterator models

+
+

transform_iterator models

The resulting transform_iterator models the most refined of the following that is also modeled by Iterator.

@@ -2348,8 +2066,8 @@ mutable iterator (as defined in the old iterator requirements).

transform_iterator<F2, Y, R2, V2> if and only if X is interoperable with Y.

-
-

transform_iterator operations

+
+

transform_iterator operations

In addition to the operations required by the concepts modeled by transform_iterator, transform_iterator provides the following operations.

@@ -2444,8 +2162,8 @@ initialized to t.functor()
-
-

Filter iterator

+
+

Filter iterator

@@ -2459,8 +2177,8 @@ adaptor to know when to stop so as to avoid going past the end of the underlying range. A filter iterator is therefore constructed with pair of iterators indicating the range of elements in the unfiltered sequence to be traversed.

-
-

Class template filter_iterator

+
+

Class template filter_iterator

@@ -2504,8 +2222,8 @@ Iterator then iterator_categoryiterator_category is convertible to std::input_iterator_tag.

-
-

filter_iterator requirements

+
+

filter_iterator requirements

The Iterator argument shall meet the requirements of Readable Iterator and Single Pass Iterator or it shall meet the requirements of Input Iterator.

@@ -2515,8 +2233,8 @@ the expression p(x) m iterator_traits<Iterator>::value_type, and where the type of p(x) must be convertible to bool.

-
-

filter_iterator models

+
+

filter_iterator models

The concepts that filter_iterator models are dependent on which concepts the Iterator argument models, as specified in the following tables.

@@ -2592,8 +2310,8 @@ following tables.

filter_iterator<P1, X> is interoperable with filter_iterator<P2, Y> if and only if X is interoperable with Y.

-
-

filter_iterator operations

+
+

filter_iterator operations

In addition to those operations required by the concepts that filter_iterator models, filter_iterator provides the following operations.

@@ -2703,16 +2421,16 @@ or m_pred(*m_iter)
-
-

Counting iterator

+
+

Counting iterator

counting_iterator adapts an object by adding an operator* that returns the current value of the object. All other iterator operations are forwarded to the adapted object.

-
-

Class template counting_iterator

+
+

Class template counting_iterator

@@ -2751,10 +2469,10 @@ algorithm:

if (CategoryOrTraversal is not use_default) return CategoryOrTraversal else if (numeric_limits<Incrementable>::is_specialized) - return iterator-category( + return iterator-category( random_access_traversal_tag, Incrementable, const Incrementable&) else - return iterator-category( + return iterator-category( iterator_traversal<Incrementable>::type, Incrementable, const Incrementable&) @@ -2765,8 +2483,8 @@ the cases where std::numeric_limi is true.]
-
-

counting_iterator requirements

+
+

counting_iterator requirements

The Incrementable argument shall be Copy Constructible and Assignable.

If iterator_category is convertible to forward_iterator_tag or forward_traversal_tag, the following must be well-formed:

@@ -2791,8 +2509,8 @@ n = i - j; i < j;
-
-

counting_iterator models

+
+

counting_iterator models

Specializations of counting_iterator model Readable Lvalue Iterator. In addition, they model the concepts corresponding to the iterator tags to which their iterator_category is convertible. @@ -2807,8 +2525,8 @@ concepts modeled by Incrementable counting_iterator<Y,C2,D2> if and only if X is interoperable with Y.

-
-

counting_iterator operations

+
+

counting_iterator operations

In addition to the operations required by the concepts modeled by counting_iterator, counting_iterator provides the following operations.

@@ -2883,8 +2601,8 @@ operations.

-
-

Function output iterator

+
+

Function output iterator

@@ -2895,14 +2613,14 @@ passed as an argument to the unary function. The motivation for this iterator is that creating a conforming output iterator is non-trivial, particularly because the proper implementation usually requires a proxy object.

-
-

Class template function_output_iterator

+ -
-

Header

+ -
-

function_output_iterator requirements

+
+

function_output_iterator requirements

UnaryFunction must be Assignable and Copy Constructible.

-
-

function_output_iterator models

+
+

function_output_iterator models

function_output_iterator is a model of the Writable and Incrementable Iterator concepts.

-
-

function_output_iterator operations

+
+

function_output_iterator operations

explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());

@@ -2987,6 +2705,12 @@ LocalWords: OtherIncrementable Coplien --> + +
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/filter_iterator.html b/doc/filter_iterator.html index 9b3eaa9..bd574f0 100644 --- a/doc/filter_iterator.html +++ b/doc/filter_iterator.html @@ -3,295 +3,13 @@ - +Filter Iterator - + - +
@@ -303,13 +21,13 @@ ul.auto-toc {
- + - - + @@ -337,18 +55,18 @@ sequence to be traversed.
Author: David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport +Boost Consulting, Indiana University Open Systems +Lab, University of Hanover Institute for Transport Railway Operation and Construction
Date:2004-11-01
2006-09-11
Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.
-
-

Table of Contents

+ -
-

filter_iterator synopsis

+
+

filter_iterator synopsis

@@ -392,8 +110,8 @@ Iterator then iterator_categoryiterator_category is convertible to std::input_iterator_tag.

-
-

filter_iterator requirements

+
+

filter_iterator requirements

The Iterator argument shall meet the requirements of Readable Iterator and Single Pass Iterator or it shall meet the requirements of Input Iterator.

@@ -403,8 +121,8 @@ the expression p(x) m iterator_traits<Iterator>::value_type, and where the type of p(x) must be convertible to bool.

-
-

filter_iterator models

+
+

filter_iterator models

The concepts that filter_iterator models are dependent on which concepts the Iterator argument models, as specified in the following tables.

@@ -480,8 +198,8 @@ following tables.

filter_iterator<P1, X> is interoperable with filter_iterator<P2, Y> if and only if X is interoperable with Y.

-
-

filter_iterator operations

+
+

filter_iterator operations

In addition to those operations required by the concepts that filter_iterator models, filter_iterator provides the following operations.

@@ -622,8 +340,8 @@ make_filter_iterator(Iterator x, Iterator end = Iterator());
-
-

Example

+
+

Example

This example uses filter_iterator and then make_filter_iterator to output only the positive integers from an array of integers. Then make_filter_iterator is is used to output @@ -682,8 +400,14 @@ int main() 4 5 8 0 -1 4 5 8 -

The source code for this example can be found here.

+

The source code for this example can be found here.

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/function_output_iterator.html b/doc/function_output_iterator.html index bea15ba..1bae71b 100644 --- a/doc/function_output_iterator.html +++ b/doc/function_output_iterator.html @@ -3,295 +3,13 @@ - + Function Output Iterator - + - +
@@ -303,13 +21,13 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de Organization: -Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport +Boost Consulting, Indiana University Open Systems +Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. @@ -334,21 +52,21 @@ proxy object. -
-

Table of Contents

+ -
-

Header

+ -
-

function_output_iterator requirements

+
+

function_output_iterator requirements

UnaryFunction must be Assignable and Copy Constructible.

-
-

function_output_iterator models

+
+

function_output_iterator models

function_output_iterator is a model of the Writable and Incrementable Iterator concepts.

-
-

function_output_iterator operations

+
+

function_output_iterator operations

explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());

@@ -427,8 +145,8 @@ is equivalent to m_f(t) -
-

Example

+
+

Example

 struct string_appender
 {
@@ -462,6 +180,12 @@ int main(int, char*[])
 }
+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/index.html b/doc/index.html index eef53b1..6963fc9 100755 --- a/doc/index.html +++ b/doc/index.html @@ -3,295 +3,17 @@ - + The Boost.Iterator Library Boost - + - + - + @@ -318,7 +40,7 @@ Lab, Zephyr Associat
Authors:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com
organizations:Boost Consulting, Indiana University Open Systems -Lab, Zephyr Associates, Inc.
organizations:Boost Consulting, Indiana University Open Systems +Lab, Zephyr Associates, Inc.
date:$Date$
Abstract:The Boost Iterator Library contains two parts. The first -is a system of concepts which extend the C++ standard +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 extended concepts and includes several useful iterator @@ -335,24 +57,24 @@ older Boost Iterator Adaptor Library.
-
-

Table of Contents

+
-
-

New-Style Iterators

+
+

New-Style Iterators

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 @@ -361,17 +83,17 @@ it is impossible to capture the capabilities of vector<bool>::iterator using the C++98 categories. This is the infamous "vector<bool> is not a container, and its iterators aren't random access iterators", debacle about which Herb Sutter -wrote two papers for the standards comittee (n1185 and n1211), -and a Guru of the Week. New-style iterators go well beyond +wrote two papers for the standards comittee (n1185 and n1211), +and a Guru of the Week. New-style iterators go well beyond patching up vector<bool>, though: there are lots of other iterators already in use which can't be adequately represented by the existing concepts. For details about the new iterator concepts, see our

-Standard Proposal For New-Style Iterators (PDF)
+Standard Proposal For New-Style Iterators (PDF)
-
-

Iterator Facade and Adaptor

+
+

Iterator Facade and Adaptor

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 iterator_facade class template, @@ -387,54 +109,54 @@ behavior as possible.

The documentation for these two classes can be found at the following web pages:

-

Both iterator_facade and iterator_adaptor as well as many of the specialized +

Both iterator_facade and iterator_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 (PDF)
+Standard Proposal For Iterator Facade and Adaptor (PDF)

for more details.

-
-

Specialized Adaptors

+
+

Specialized Adaptors

The iterator library supplies a useful suite of standard-conforming -iterator templates based on the Boost iterator facade and adaptor.

+iterator templates based on the Boost iterator facade and adaptor.

    -
  • counting_iterator (PDF): an iterator over a sequence of consecutive values. +
  • counting_iterator (PDF): an iterator over a sequence of consecutive values. Implements a "lazy sequence"
    • -
  • filter_iterator (PDF): an iterator over the subset of elements of some +
  • filter_iterator (PDF): an iterator over the subset of elements of some sequence which satisfy a given predicate
    • -
  • function_output_iterator (PDF): an output iterator wrapping a unary function +
  • function_output_iterator (PDF): an output iterator wrapping a unary function object; each time an element is written into the dereferenced iterator, it is passed as a parameter to the function object.
    • -
  • indirect_iterator (PDF): an iterator over the objects pointed-to by the +
  • indirect_iterator (PDF): an iterator over the objects pointed-to by the elements of some sequence.
    • -
  • permutation_iterator (PDF): an iterator over the elements of some random-access +
  • permutation_iterator (PDF): an iterator over the elements of some random-access sequence, rearranged according to some sequence of integer indices.
    • -
  • reverse_iterator (PDF): an iterator which traverses the elements of some +
  • reverse_iterator (PDF): an iterator which traverses the elements of some bidirectional sequence in reverse. Corrects many of the shortcomings of C++98's std::reverse_iterator.
    • -
  • shared_container_iterator: an iterator over elements of a container whose -lifetime is maintained by a shared_ptr stored in the iterator.
    • -
  • transform_iterator (PDF): an iterator over elements which are the result of +
  • shared_container_iterator: an iterator over elements of a container whose +lifetime is maintained by a shared_ptr stored in the iterator.
    • +
  • transform_iterator (PDF): an iterator over elements which are the result of applying some functional transformation to the elements of an underlying sequence. This component also replaces the old projection_iterator_adaptor.
    • -
  • zip_iterator (PDF): an iterator over tuples of the elements at corresponding +
  • zip_iterator (PDF): an iterator over tuples of the elements at corresponding positions of heterogeneous underlying iterators.
-
-

Iterator Utilities

-
-

Traits

+
+

Iterator Utilities

+
+

Traits

    -
  • pointee.hpp (PDF): Provides the capability to deduce the referent types +
  • pointee.hpp (PDF): Provides the capability to deduce the referent types of pointers, smart pointers and iterators in generic code. Used in indirect_iterator.
    • -
  • iterator_traits.hpp (PDF): Provides MPL-compatible metafunctions which +
  • iterator_traits.hpp (PDF): Provides MPL-compatible metafunctions which retrieve an iterator's traits. Also corrects for the deficiencies of broken implementations of std::iterator_traits.
@@ -442,26 +164,26 @@ of broken implementations of std: testing iterator interoperability -->
-
-

Testing and Concept Checking

+
+

Testing and Concept Checking

-
-

Upgrading from the old Boost Iterator Adaptor Library

+
+

Upgrading from the old Boost Iterator Adaptor Library

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 +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], +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 @@ -475,8 +197,8 @@ template argument, if explicitly specified) is a true reference type, transform_iterator will behave like projection_iterator used to.

-
-

History

+
+

History

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 @@ -504,7 +226,7 @@ library you see today.

-
[Cop95][Coplien, 1995] Coplien, J., Curiously Recurring Template +
[Cop95][Coplien, 1995] Coplien, J., Curiously Recurring Template Patterns, C++ Report, February 1995, pp. 24-27.
@@ -516,6 +238,12 @@ LocalWords: RandomAccessTraversalIterator dereferenceable Incrementable tmp LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct LocalWords: TraversalTag typename lvalues DWA Hmm JGS -->
+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/indirect_iterator.html b/doc/indirect_iterator.html index 11ea71f..61d9c95 100644 --- a/doc/indirect_iterator.html +++ b/doc/indirect_iterator.html @@ -3,295 +3,13 @@ - + Indirect Iterator - + - +
@@ -303,13 +21,13 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de Organization: -Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport +Boost Consulting, Indiana University Open Systems +Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. @@ -335,18 +53,18 @@ not an iterator. -
-

Table of Contents

+ -
-

indirect_iterator synopsis

+
+

indirect_iterator synopsis

@@ -426,8 +144,8 @@ else ) iterator_category;
-
-

indirect_iterator requirements

+
+

indirect_iterator requirements

The expression *v, where v is an object of iterator_traits<Iterator>::value_type, shall be valid expression and convertible to reference. Iterator shall @@ -440,8 +158,8 @@ the requirements indicated by ite parameter is not use_default, as implied by the algorithm for deducing the default for the value_type member.]

-
-

indirect_iterator models

+
+

indirect_iterator models

In addition to the concepts indicated by iterator_category and by iterator_traversal<indirect_iterator>::type, a specialization of indirect_iterator models the following @@ -461,8 +179,8 @@ expression (where t i indirect_iterator<Y,V2,C2,R2,D2> if and only if X is interoperable with Y.

-
-

indirect_iterator operations

+
+

indirect_iterator operations

In addition to the operations required by the concepts described above, specializations of indirect_iterator provide the following operations.

@@ -555,8 +273,8 @@ indirect_iterator(
-
-

Example

+
+

Example

This example prints an array of characters, using indirect_iterator to access the array of characters through an array of pointers. Next indirect_iterator is used with the @@ -614,8 +332,14 @@ a,b,c,d,e,f,g, b,c,d,e,f,g,h, a,b,c,d,e,f,g, -

The source code for this example can be found here.

+

The source code for this example can be found here.

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/interoperability-revisited.rst b/doc/interoperability-revisited.rst index add3546..6fb6acf 100755 --- a/doc/interoperability-revisited.rst +++ b/doc/interoperability-revisited.rst @@ -18,86 +18,87 @@ implement interoperable iterators. In the following text a simplified example of the current iterator_facade specification is used to illustrate the problem. -In the current specification binary operators are implemented in the following way: +In the current specification binary operators are implemented in the following way:: -template -struct Facade -{ -}; + template + struct Facade + { + }; -template -struct is_interoperable : - or_< - is_convertible - , is_convertible - > -{}; + template + struct is_interoperable : + or_< + is_convertible + , is_convertible + > + {}; -template< - class Derived1 - , class Derived2 -> -enable_if, bool> operator==( - Derived1 const& lhs - , Derived2 const& rhs -) -{ - return static_cast(lhs).equal_to(static_cast + enable_if, bool> operator==( + Derived1 const& lhs + , Derived2 const& rhs + ) + { + return static_cast(lhs).equal_to(static_cast -{ - bool equal_to(Mutable const&); -}; + struct Mutable : Facade + { + bool equal_to(Mutable const&); + }; -struct Constant : Facade -{ - Constant(); - Constant(Constant const&); - Constant(Mutable const&); - - ... + struct Constant : Facade + { + Constant(); + Constant(Constant const&); + Constant(Mutable const&); - bool equal_to(Constant const&); -}; + ... -Constant c; -Mutable m; + bool equal_to(Constant const&); + }; -c == m; // ok, dispatched to Constant::equal_to -m == c; // !! error, dispatched to Mutable::equal_to + Constant c; + Mutable m; -Instead the following "slightly" more complicated implementation is necessary + c == m; // ok, dispatched to Constant::equal_to + m == c; // !! error, dispatched to Mutable::equal_to -struct Mutable : Facade -{ - template - enable_if || is_convertible, bool>::type equal_to(T const&); -}; + Instead the following "slightly" more complicated implementation is necessary -struct Constant : Tag -{ - Constant(); - Constant(Constant const&); - Constant(Mutable const&); + struct Mutable : Facade + { + template + enable_if || is_convertible, bool>::type equal_to(T const&); + }; - template - enable_if || is_convertible, bool>::type equal_to(T const&); -}; + struct Constant : Tag + { + Constant(); + Constant(Constant const&); + Constant(Mutable const&); + + template + enable_if || is_convertible, bool>::type equal_to(T const&); + }; Beside the fact that the code is significantly more complex to understand and to teach there is a major design problem lurking here. Note that in both types equal_to is a function template with an unconstrained argument T. This is necessary so that further types can be made interoperable with -Mutable or Constant. Would Mutable be defined as +Mutable or Constant. Would Mutable be defined as :: -struct Mutable : Facade -{ - bool equal_to(Mutable const&); - bool equal_to(Constant const&); -}; + struct Mutable : Facade + { + bool equal_to(Mutable const&); + bool equal_to(Constant const&); + }; Constant and Mutable would still be interoperable but no further interoperable could be added without changing Mutable. Even if this would be considered acceptable the current specification forces @@ -111,44 +112,45 @@ The two way dependency can be avoided by enabling type conversion in the binary implementation. Note that this is the usual way interoperability betwween types is achieved for binary operators and one reason why binary operators are usually implemented as non-members. -A simple implementation of this strategy would look like this +A simple implementation of this strategy would look like this :: -template< - class T1 - , class T2 -> -struct interoperable_base : - if_< - is_convertible< - T2 - , T1 - > - , T1 - , T2> -{}; + template< + class T1 + , class T2 + > + struct interoperable_base : + if_< + is_convertible< + T2 + , T1 + > + , T1 + , T2> + {}; -template< - class Derived1 - , class Derived2 -> -enable_if, bool> operator==( - Derived1 const& lhs - , Derived2 const& rhs -) -{ - typedef interoperable_base< - Derived1 - , Derived2 - >::type Base; + template< + class Derived1 + , class Derived2 + > + enable_if, bool> operator==( + Derived1 const& lhs + , Derived2 const& rhs + ) + { + typedef interoperable_base< + Derived1 + , Derived2 + >::type Base; - return static_cast(lhs).equal_to(static_cast(lhs).equal_to(static_cast -enable_if, bool> operator==( - Derived1 const& lhs - , Derived2 const& rhs -) -{ - return static_cast(lhs).equal_to(static_cast + enable_if, bool> operator==( + Derived1 const& lhs + , Derived2 const& rhs + ) + { + return static_cast(lhs).equal_to(static_cast -enable_if, bool> operator==( - Derived1 const& lhs - , Derived2 const& rhs -) -{ - return static_cast(rhs).equal_to(static_cast + enable_if, bool> operator==( + Derived1 const& lhs + , Derived2 const& rhs + ) + { + return static_cast(rhs).equal_to(static_cast -{ - Constant(); - Constant(Constant const&); - Constant(Mutable const&); - - ... + struct Constant : Facade + { + Constant(); + Constant(Constant const&); + Constant(Mutable const&); - bool equal_to(Constant const&); - bool equal_to(Mutable const&); -}; + ... -c == m; // ok, dispatched to Constant::equal_to(Mutable const&), no conversion -m == c; // ok, dispatched to Constant::equal_to(Mutable const&), no conversion + bool equal_to(Constant const&); + bool equal_to(Mutable const&); + }; + + c == m; // ok, dispatched to Constant::equal_to(Mutable const&), no conversion + m == c; // ok, dispatched to Constant::equal_to(Mutable const&), no conversion This definition of operator== introduces a possible ambiguity when both types are convertible to each other. I don't think this is a problem as this behaviour is the same with concrete types. -I.e. +I.e. :: -struct A {}; + struct A {}; -bool operator==(A, A); + bool operator==(A, A); -struct B { B(A); }; + struct B { B(A); }; -bool operator==(B, B); + bool operator==(B, B); -A a; -B b(a); + A a; + B b(a); -a == b; // error, ambiguous overload + a == b; // error, ambiguous overload Effect ====== diff --git a/doc/issues.html b/doc/issues.html deleted file mode 100755 index f8ab29c..0000000 --- a/doc/issues.html +++ /dev/null @@ -1,451 +0,0 @@ - - - - - - -Problem with is_writable and is_swappable in N1550 - - - - - - - -
-

Problem with is_writable and is_swappable in N1550

- --- - - - - - - - - - - - -
Author:David Abrahams and Jeremy Siek
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu
Organization:Boost Consulting, Indiana University Bloomington
Date:2003-11-19
Copyright:Copyright David Abrahams, Jeremy Siek 2003. Use, modification and -distribution is subject to the Boost Software License, -Version 1.0. (See accompanying file LICENSE_1_0.txt or copy -at http://www.boost.org/LICENSE_1_0.txt)
-
-

Table of Contents

- -
-
-

Introduction

-

The is_writable and is_swappable traits classes in N1550 -provide a mechanism for determining at compile time if an iterator -type is a model of the new Writable Iterator and Swappable Iterator -concepts, analogous to iterator_traits<X>::iterator_category -for the old iterator concepts. For backward compatibility, -is_writable and is_swappable not only work with new -iterators, but they also are intended to work for old -iterators (iterators that meet the requirements for one of the -iterator concepts in the current standard). In the case of old -iterators, the writability and swapability is deduced based on the -iterator_category and also the reference type. The -specification for this deduction gives false positives for forward -iterators that have non-assignable value types.

-

To review, the part of the is_writable trait definition which -applies to old iterators is:

-
-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;
-
-

Suppose the value_type of the iterator It has a private -assignment operator:

-
-class B {
-public:
-  ...
-private:
-  B& operator=(const B&);
-};
-
-

and suppose the reference type of the iterator is B&. In -that case, is_writable<It>::value will be true when in fact -attempting to write into B will cause an error.

-

The same problem applies to is_swappable.

-
-
-

Proposed Resolution

-
    -

  1. Remove the is_writable and is_swappable traits, and remove the -requirements in the Writable Iterator and Swappable Iterator concepts -that require their models to support these traits.

    -
    2. -

  2. Change the is_readable specification to be: -is_readable<X>::type is true_type if the -result type of X::operator* is convertible to -iterator_traits<X>::value_type and is false_type -otherwise. Also, is_readable is required to satisfy -the requirements for the UnaryTypeTrait concept -(defined in the type traits proposal).

    -

    Remove the requirement for support of the is_readable trait from -the Readable Iterator concept.

    -
    3. -

  3. Remove the iterator_tag class.

    -
    4. -

  4. Change the specification of traversal_category to:

    -
    -traversal-category(Iterator) =
-    let cat = iterator_traits<Iterator>::iterator_category
-    if (cat is convertible to incrementable_iterator_tag)
-      return cat; // Iterator is a new iterator
-    else if (cat is convertible to random_access_iterator_tag)
-        return random_access_traversal_tag;
-    else if (cat is convertible to bidirectional_iterator_tag)
-        return bidirectional_traversal_tag;
-    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;
-    else if (cat is convertible to output_iterator_tag)
-        return incrementable_iterator_tag;
-    else
-        return null_category_tag;
-
    -
    5. -
-
-
-

Rationale

-
    -
  1. There are two reasons for removing is_writable -and is_swappable. The first is that we do not know of -a way to fix the specification so that it gives the correct -answer for all iterators. Second, there was only a weak -motivation for having is_writable and is_swappable -there in the first place. The main motivation was simply -uniformity: we have tags for the old iterator categories -so we should have tags for the new iterator categories. -While having tags and the capability to dispatch based -on the traversal categories is often used, we see -less of a need for dispatching based on writability -and swappability, since typically algorithms -that need these capabilities have no alternative if -they are not provided.
    2. -
  2. We discovered that the is_readable trait can be implemented -using only the iterator type itself and its value_type. -Therefore we remove the requirement for is_readable from the -Readable Iterator concept, and change the definition of -is_readable so that it works for any iterator type.
    3. -
  3. The purpose of the iterator_tag class was to -bundle the traversal and access category tags -into the iterator_category typedef. -With is_writable and is_swappable gone, and -is_readable no longer in need of special hints, -there is no reason for iterators to provide -information about the access capabilities of an iterator. -Thus there is no need for the iterator_tag. The -traversal tag can be directly used for the -iterator_category. If a new iterator is intended to be backward -compatible with old iterator concepts, a tag type -that is convertible to both one of the new traversal tags -and also to an old iterator tag can be created and use -for the iterator_category.
    4. -
  4. The changes to the specification of traversal_category are a -direct result of the removal of iterator_tag.
    5. -
-
-
- - diff --git a/doc/iterator_adaptor.html b/doc/iterator_adaptor.html index 1a559d7..e023d82 100644 --- a/doc/iterator_adaptor.html +++ b/doc/iterator_adaptor.html @@ -3,295 +3,13 @@ - + Iterator Adaptor - + - +
@@ -303,13 +21,13 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de Organization: -Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport +Boost Consulting, Indiana University Open Systems +Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. @@ -341,30 +59,30 @@ Whether the derived class models any of the standard iterator concepts depends on the operations supported by the Base type and which core interface functions of iterator_facade are redefined in the Derived class.

-
-

Table of Contents

+ -
-

Overview

+
+

Overview

-

The iterator_adaptor class template adapts some Base [1] +

The iterator_adaptor class template adapts some Base1 type to create a new iterator. Instantiations of iterator_adaptor are derived from a corresponding instantiation of iterator_facade and implement the core behaviors in terms of the Base type. In @@ -373,7 +91,7 @@ instance of the Base - @@ -400,8 +118,8 @@ template parameter may not always be identical to the iterator's reference type, and will keep users from making mistakes based on that assumption.

-
-

Reference

+
+

Reference

@@ -418,7 +136,7 @@ template < , class Difference = use_default > class iterator_adaptor - : public iterator_facade<Derived, V', C', R', D'> // see details + : public iterator_facade<Derived, V', C', R', D'> // see details { friend class iterator_core_access; public: @@ -452,13 +170,13 @@ class iterator_adaptor Base m_iterator; // exposition only }; -
-

iterator_adaptor requirements

+
+

iterator_adaptor requirements

static_cast<Derived*>(iterator_adaptor*) shall be well-formed. The Base argument shall be Assignable and Copy Constructible.

-
-

iterator_adaptor base class parameters

+
+

iterator_adaptor base class parameters

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:

@@ -498,8 +216,8 @@ expression involving ``Derived`` in those concepts' requirements. -->
-
-

iterator_adaptor public operations

+
+

iterator_adaptor public operations

iterator_adaptor();

[1](1, 2) The term "Base" here does not refer to a base class and is +
[1](1, 2) The term "Base" here does not refer to a base class and is not meant to imply the use of derivation. We have followed the lead of the standard library, which provides a base() function to access the underlying iterator object of a reverse_iterator adaptor.
@@ -532,8 +250,8 @@ expression involving ``Derived`` in those concepts' requirements. -->

-
-

iterator_adaptor protected member functions

+
+

iterator_adaptor protected member functions

Base const& base_reference() const;

@@ -553,8 +271,8 @@ expression involving ``Derived`` in those concepts' requirements. -->
-
-

iterator_adaptor private member functions

+
+

iterator_adaptor private member functions

typename iterator_adaptor::reference dereference() const;

@@ -622,13 +340,13 @@ typename iterator_adaptor::difference_type distance_to(
-
-

Tutorial Example

+
+

Tutorial Example

In this section we'll further refine the node_iter class -template we developed in the iterator_facade tutorial. If you haven't already +template we developed in the iterator_facade tutorial. If you haven't already read that material, you should go back now and check it out because we're going to pick up right where it left off.

@@ -651,12 +369,12 @@ of the same associated types (val core functionality is the same: operator* and operator== on the node_iterator return the result of invoking the same operations on the underlying pointer, via the node_iterator's -dereference and equal member functions). The only real behavioral difference +dereference and equal member functions). The only real behavioral difference between node_base* and node_iterator can be observed when they are incremented: node_iterator follows the m_next pointer, while node_base* just applies an address offset.

It turns out that the pattern of building an iterator on another -iterator-like type (the Base [1] type) while modifying +iterator-like type (the Base1 type) while modifying just a few aspects of the underlying type's behavior is an extremely common one, and it's the pattern addressed by iterator_adaptor. Using iterator_adaptor is very much like @@ -707,7 +425,7 @@ the complicated base class type of here.

+node iterators here.

In the case of node_iter, it's not very compelling to pass boost::use_default as iterator_adaptor's Value argument; we could have just passed node_iter's Value @@ -725,13 +443,19 @@ std::iterator_traits<Iterator>::some-associated-type

at least four times.

We urge you to review the documentation and implementations of -reverse_iterator and the other Boost specialized iterator +reverse_iterator and the other Boost specialized iterator adaptors to get an idea of the sorts of things you can do with iterator_adaptor. In particular, have a look at -transform_iterator, which is perhaps the most straightforward -adaptor, and also counting_iterator, which demonstrates that +transform_iterator, which is perhaps the most straightforward +adaptor, and also counting_iterator, which demonstrates that iterator_adaptor's Base type needn't be an iterator.

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/iterator_archetypes.html b/doc/iterator_archetypes.html index 323a214..cba66fa 100755 --- a/doc/iterator_archetypes.html +++ b/doc/iterator_archetypes.html @@ -3,295 +3,13 @@ - + Iterator Archetype - + - +
@@ -303,12 +21,12 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com Organization: -Boost Consulting, Indiana University Open Systems -Lab, Zephyr Associates, Inc. +Boost Consulting, Indiana University Open Systems +Lab, Zephyr Associates, Inc. Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004. @@ -324,27 +42,27 @@ Lab, Zephyr Ass one of the iterator access concepts and one of the iterator traversal concepts. This is used for doing a compile-time check to see if a the type requirements of a template are really enough to cover the implementation of the template. -For further information see the documentation for the boost::concept_check library. +For further information see the documentation for the boost::concept_check library. -
-

Table of Contents

+ -
-

Reference

-
-

iterator_archetype Synopsis

+
+

Reference

+
+

iterator_archetype Synopsis

 namespace iterator_archetypes
 {
@@ -373,8 +91,8 @@ class iterator_archetype
 };
-
-

Access Category Tags

+
+

Access Category Tags

The access category types provided correspond to the following standard iterator access concept combinations:

@@ -399,23 +117,23 @@ writeable_lvalue_iterator_t :=
   Readable Iterator & Writeable Iterator & Swappable Iterator & Lvalue Iterator
-
-

iterator_archetype Requirements

+
+

iterator_archetype Requirements

The AccessCategory argument must be one of the predefined access category tags. The TraversalCategory must be one of the standard traversal tags. The Value type must satisfy the requirements of the iterator concept specified by AccessCategory and TraversalCategory as implied by the nested traits types.

-
-

iterator_archetype Models

+
+

iterator_archetype Models

iterator_archetype models the iterator concepts specified by the AccessCategory and TraversalCategory arguments. iterator_archetype does not model any other access concepts or any more derived traversal concepts.

-
-

Traits

+
+

Traits

The nested trait types are defined as follows:

 if (AccessCategory == readable_iterator_t)
@@ -495,6 +213,12 @@ iterator_category :=
+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/iterator_concepts.html b/doc/iterator_concepts.html index 2bcb2e7..0a48838 100644 --- a/doc/iterator_concepts.html +++ b/doc/iterator_concepts.html @@ -3,295 +3,13 @@ - + Iterator Concepts - + - +
@@ -303,12 +21,12 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com Organization: -Boost Consulting, Indiana University Open Systems -Lab, Zephyr Associates, Inc. +Boost Consulting, Indiana University Open Systems +Lab, Zephyr Associates, Inc. Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004. @@ -328,30 +46,30 @@ the template.

For an introduction to using concept checking classes, see -the documentation for the boost::concept_check library.

-
-

Reference

-
-

Iterator Access Concepts

+the documentation for the boost::concept_check library.

+
+

Reference

+ -
-

Iterator Traversal Concepts

+ -
-

iterator_concepts.hpp Synopsis

+
+

iterator_concepts.hpp Synopsis

 namespace boost_concepts {
 
@@ -398,6 +116,12 @@ namespace boost_concepts {
+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/iterator_facade.html b/doc/iterator_facade.html index 10fdc34..c576743 100644 --- a/doc/iterator_facade.html +++ b/doc/iterator_facade.html @@ -3,295 +3,13 @@ - + Iterator Facade - + - +
@@ -303,13 +21,13 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de Organization: -Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport +Boost Consulting, Indiana University Open Systems +Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. @@ -330,46 +48,46 @@ and associated types, to be supplied by a derived iterator class. -
-

Table of Contents

+ -
-

Overview

+
+

Overview

@@ -392,7 +110,7 @@ include the associated types exposed through iterator traits: value_type, reference, difference_type, and iterator_category.

Iterator facade uses the Curiously Recurring Template -Pattern (CRTP) [Cop95] so that the user can specify the behavior +Pattern (CRTP) [Cop95] so that the user can specify the behavior of iterator_facade in a derived class. Former designs used policy objects to specify the behavior, but that approach was discarded for several reasons:

@@ -415,8 +133,8 @@ iterators, and a separate iterato impossible. -
-

Usage

+
+

Usage

The user of iterator_facade derives his iterator class from a specialization of iterator_facade and passes the derived iterator class as iterator_facade's first template parameter. @@ -479,8 +197,8 @@ constructor. Finally, if the iterator is to model Forward Traversal Iterator or a more-refined iterator concept, a default constructor is required.

-
-

Iterator Core Access

+
+

Iterator Core Access

iterator_facade 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 @@ -513,19 +231,19 @@ standardize the gateway protocol. Note that even if open a safety loophole, as every core member function preserves the invariants of the iterator.

-
-

operator[]

+
+

operator[]

The indexing operator for a generalized iterator presents special 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_iterator), because *(p+n) is a reference into the temporary iterator p+n, which is destroyed when operator[] returns.

Writable iterators built with iterator_facade implement the -semantics required by the preferred resolution to issue 299 and -adopted by proposal n1550: the result of p[n] is an object +semantics required by the preferred resolution to issue 299 and +adopted by proposal n1550: the result of p[n] is an object convertible to the iterator's value_type, and p[n] = x is equivalent to *(p + n) = x (Note: This result object may be implemented as a proxy containing a copy of p+n). This approach @@ -536,8 +254,8 @@ the implementation of her iterator is free to implement an class; it will hide the one supplied by iterator_facade from clients of her iterator.

-
-

operator->

+
+

operator->

The reference 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 value_type. When the value_type @@ -552,14 +270,14 @@ satisfied by the iterator_facade< -
[Cop95](1, 2) [Coplien, 1995] Coplien, J., Curiously Recurring Template +
[Cop95](1, 2) [Coplien, 1995] Coplien, J., Curiously Recurring Template Patterns, C++ Report, February 1995, pp. 24-27.

-
-

Reference

+
+

Reference

@@ -580,11 +298,11 @@ class iterator_facade { typedef Reference reference; typedef Value* pointer; typedef Difference difference_type; - typedef /* see below */ iterator_category; + typedef /* see below */ iterator_category; reference operator*() const; - /* see below */ operator->() const; - /* see below */ operator[](difference_type n) const; + /* see below */ operator->() const; + /* see below */ operator[](difference_type n) const; Derived& operator++(); Derived operator++(int); Derived& operator--(); @@ -636,7 +354,7 @@ operator >=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, // Iterator difference template <class Dr1, class V1, class TC1, class R1, class D1, class Dr2, class V2, class TC2, class R2, class D2> -/* see below */ +/* see below */ operator-(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs); @@ -688,7 +406,7 @@ Derived operator+ (typename Derived::difference_type n, X1 = C } - 2. category-to-traversal(X) is convertible to the most + 2. category-to-traversal(X) is convertible to the most derived traversal tag type to which X is also convertible, and not to any more-derived traversal tag type. @@ -722,8 +440,8 @@ struct enable_if_interoperable > {}; -
-

iterator_facade Requirements

+
+

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 @@ -736,8 +454,8 @@ object of type X, X, and z is a constant object of a random access traversal iterator type interoperable with X.

-
-

iterator_facade Core Operations

+
+

iterator_facade Core Operations

@@ -796,8 +514,8 @@ Iterator
-
-

iterator_facade operations

+
+

iterator_facade operations

The operations in this section are described in terms of operations on the core interface of Derived which may be inaccessible (i.e. private). The implementation should access these operations @@ -811,7 +529,7 @@ through member functions of class -

operator->() const; (see below)

+

operator->() const; (see below)

@@ -1140,18 +858,18 @@ operator -(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
-
-

Tutorial Example

+
+

Tutorial Example

In this section we'll walk through the implementation of a few iterators using iterator_facade, based around the simple example of a linked list of polymorphic objects. This example was -inspired by a posting by Keith Macdonald on the Boost-Users +inspired by a posting by Keith Macdonald on the Boost-Users mailing list.

-
-

The Problem

+
+

The Problem

Say we've written a polymorphic linked list node base class:

 # include <iostream>
@@ -1212,8 +930,8 @@ inline std::ostream& operator<<(std::ostream& s, node_base const&a
 
Our first challenge is to build an appropriate iterator over these
 lists.
-
-

A Basic Iterator Using iterator_facade

+
+

A Basic Iterator Using iterator_facade

We will construct a node_iterator class using inheritance from iterator_facade to implement most of the iterator's operations.

@@ -1226,45 +944,45 @@ class node_iterator
    ...
 };
-
-

Template Arguments for iterator_facade

+
+

Template Arguments for iterator_facade

iterator_facade has several template parameters, so we must decide what types to use for the arguments. The parameters are Derived, Value, CategoryOrTraversal, Reference, and Difference.

-
-

Derived

+
+

Derived

Because iterator_facade is meant to be used with the CRTP -[Cop95] the first parameter is the iterator class name itself, +[Cop95] the first parameter is the iterator class name itself, node_iterator.

-
-

Value

+
+

Value

The Value parameter determines the node_iterator's value_type. In this case, we are iterating over node_base objects, so Value will be node_base.

-
-

CategoryOrTraversal

-

Now we have to determine which iterator traversal concept our +

+

CategoryOrTraversal

+

Now we have to determine which iterator traversal concept our node_iterator is going to model. Singly-linked lists only have -forward links, so our iterator can't can't be a bidirectional +forward links, so our iterator can't can't be a bidirectional traversal iterator. Our iterator should be able to make multiple passes over the same linked list (unlike, say, an istream_iterator which consumes the stream it traverses), so it -must be a forward traversal iterator. Therefore, we'll pass -boost::forward_traversal_tag in this position [1].

+must be a forward traversal iterator. Therefore, we'll pass +boost::forward_traversal_tag in this position1.

-
[1]iterator_facade also supports old-style category +
[1]iterator_facade also supports old-style category tags, so we could have passed std::forward_iterator_tag here; either way, the resulting iterator's iterator_category will end up being std::forward_iterator_tag.
-
-

Reference

+
+

Reference

The Reference argument becomes the type returned by node_iterator's dereference operation, and will also be the same as std::iterator_traits<node_iterator>::reference. The @@ -1272,8 +990,8 @@ library's default for this parameter is node_base& is a good choice for the iterator's reference type, we can omit this argument, or pass use_default.

-
-

Difference

+
+

Difference

The Difference argument determines how the distance between two node_iterators will be measured and will also be the same as std::iterator_traits<node_iterator>::difference_type. @@ -1299,15 +1017,15 @@ class node_iterator

-
-

Constructors and Data Members

+
+

Constructors and Data Members

Next we need to decide how to represent the iterator's position. This representation will take the form of data members, so we'll also need to write constructors to initialize them. The node_iterator's position is quite naturally represented using a pointer to a node_base. We'll need a constructor to build an iterator from a node_base*, and a default constructor to -satisfy the forward traversal iterator requirements [2]. +satisfy the forward traversal iterator requirements2. Our node_iterator then becomes:

 # include "node.hpp"
@@ -1337,20 +1055,20 @@ class node_iterator
 
-

 
 
[2]Technically, the C++ standard places almost no
+
[2]Technically, the C++ standard places almost no
 requirements on a default-constructed iterator, so if we were
 really concerned with efficiency, we could've written the
 default constructor to leave m_node uninitialized.
-
-

Implementing the Core Operations

-

The last step is to implement the core operations required by +

+

Implementing the Core Operations

+

The last step is to implement the core operations required by the concepts we want our iterator to model. Referring to the -table, we can see that the first three rows are applicable +table, we can see that the first three rows are applicable because node_iterator needs to satisfy the requirements for -readable iterator, single pass iterator, and incrementable +readable iterator, single pass iterator, and incrementable iterator.

We therefore need to supply dereference, equal, and increment members. We don't want these members @@ -1392,11 +1110,11 @@ class node_iterator };

Voilà; a complete and conforming readable, forward-traversal -iterator! For a working example of its use, see this program.

+iterator! For a working example of its use, see this program.

-
-

A constant node_iterator

+
+

A constant node_iterator

Constant and Mutable iterators

The term mutable iterator means an iterator through which @@ -1496,8 +1214,8 @@ typedef node_iter<node_base> node_iterator; typedef node_iter<node_base const> node_const_iterator;

-
-

Interoperability

+
+

Interoperability

Our const_node_iterator works perfectly well on its own, but taken together with node_iterator it doesn't quite meet expectations. For example, we'd like to be able to pass a @@ -1507,9 +1225,9 @@ just as you can with std::list< node_const_iterator into the same list, we should be able to compare them for equality.

This expected ability to use two different iterator types together -is known as interoperability. Achieving interoperability in +is known as interoperability. Achieving interoperability in our case is as simple as templatizing the equal function and -adding a templatized converting constructor [3] [4]:

+adding a templatized converting constructor34:

 template <class Value>
 class node_iter
@@ -1554,23 +1272,23 @@ typedef impl::node_iterator<node_base const> node_const_iterator;
 
-
+

 
 
[3]If you're using an older compiler and it can't handle
-this example, see the example code for workarounds.
[3]If you're using an older compiler and it can't handle
+this example, see the example code for workarounds.

 
 

 
-

 
 
[4]If node_iterator had been a random access
+
[4]If node_iterator had been a random access
 traversal iterator, we'd have had to templatize its
 distance_to function as well.

 
 

 
You can see an example program which exercises our interoperable
-iterators here.

+iterators here.
-
-

Telling the Truth

+
+

Telling the Truth

Now node_iterator and node_const_iterator behave exactly as you'd expect... almost. We can compare them and we can convert in one direction: from node_iterator to node_const_iterator. @@ -1579,15 +1297,15 @@ If we try to convert from node_co constructor tries to initialize node_iterator's m_node, a node* with a node const*. So what's the problem?

The problem is that -boost::is_convertible<node_const_iterator,node_iterator>::value -will be true, but it should be false. is_convertible +boost::is_convertible<node_const_iterator,node_iterator>::value +will be true, but it should be false. is_convertible lies because it can only see as far as the declaration of node_iter's converting constructor, but can't look inside at the definition to make sure it will compile. A perfect solution would make node_iter's converting constructor disappear when the m_node conversion would fail.

In fact, that sort of magic is possible using -boost::enable_if. By rewriting the converting constructor as +boost::enable_if. By rewriting the converting constructor as follows, we can remove it from the overload set when it's not appropriate:

@@ -1611,14 +1329,20 @@ public:
     : m_node(other.m_node) {}
-
-

Wrap Up

+
+

Wrap Up

This concludes our iterator_facade tutorial, but before you -stop reading we urge you to take a look at iterator_adaptor. +stop reading we urge you to take a look at iterator_adaptor. There's another way to approach writing these iterators which might even be superior.

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/iterator_traits.html b/doc/iterator_traits.html index 35c743b..7bd6119 100755 --- a/doc/iterator_traits.html +++ b/doc/iterator_traits.html @@ -3,295 +3,13 @@ - + Iterator Traits - + - +
@@ -303,11 +21,11 @@ ul.auto-toc { Author: David Abrahams Contact: -dave@boost-consulting.com +dave@boost-consulting.com Organization: -Boost Consulting +Boost Consulting Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams 2004. @@ -321,21 +39,21 @@ ul.auto-toc { abstract:Header <boost/iterator/iterator_traits.hpp> provides the ability to access an iterator's associated types using -MPL-compatible metafunctions. +MPL-compatible metafunctions. -
-

Overview

+
+

Overview

std::iterator_traits provides access to five associated types of any iterator: its value_type, reference, pointer, iterator_category, and difference_type. Unfortunately, such a "multi-valued" traits template can be difficult to use in a metaprogramming context. <boost/iterator/iterator_traits.hpp> -provides access to these types using a standard metafunctions.

+provides access to these types using a standard metafunctions.

-
-

Summary

+
+

Summary

Header <boost/iterator/iterator_traits.hpp>:

 template <class Iterator>
@@ -380,14 +98,14 @@ struct iterator_category
 };
-
-

Broken Compiler Notes

+
+

Broken Compiler Notes

Because of workarounds in Boost, you may find that these -metafunctions actually work better than the facilities provided by +metafunctions actually work better than the facilities provided by your compiler's standard library.

On compilers that don't support partial specialization, such as Microsoft Visual C++ 6.0 or 7.0, you may need to manually invoke -BOOST_BROKEN_COMPILER_TYPE_TRAITS_SPECIALIZATION on the +BOOST_BROKEN_COMPILER_TYPE_TRAITS_SPECIALIZATION on the value_type of pointers that are passed to these metafunctions.

Because of bugs in the implementation of GCC-2.9x, the name of iterator_category is changed to iterator_category_ on that @@ -395,6 +113,12 @@ compiler. A macro, BOOST_ITERATO either iterator_category or iterator_category_, as appropriate to the platform, is provided for portability.

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html index 5659163..51a4ee0 100755 --- a/doc/new-iter-concepts.html +++ b/doc/new-iter-concepts.html @@ -3,295 +3,13 @@ - + New Iterator Concepts - + - +
@@ -303,16 +21,16 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com Organization: -Boost Consulting, Indiana University Open Systems -Lab, Zephyr Associates, Inc. +Boost Consulting, Indiana University Open Systems +Lab, Zephyr Associates, Inc. Date: -2006-04-30 -Number:This is a revised version of n1550=03-0133, which was +2006-09-11 +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. +revision of paper n1297, n1477, and n1531. Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt @@ -336,49 +54,49 @@ 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 @@ -409,12 +127,12 @@ requirements in the iterator categories.

*i is convertible to T Forward Iterator -*i is T& (or const T& once issue 200 +*i is T& (or const T& once issue 200 is resolved) Random Access Iterator i[n] is convertible to T (also i[n] = t -is required for mutable iterators once issue 299 +is required for mutable iterators once issue 299 is resolved) @@ -423,7 +141,7 @@ is resolved) single hierarchy, many useful iterators can not be appropriately categorized. For example, vector<bool>::iterator is almost a random access iterator, but the return type is not bool& (see -issue 96 and Herb Sutter's paper J16/99-0008 = WG21 +issue 96 and Herb Sutter's paper J16/99-0008 = WG21 N1185). Therefore, the iterators of vector<bool> only meet the requirements of input iterator and output iterator. This is so nonintuitive that the C++ standard contradicts itself on this point. @@ -431,7 +149,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 @@ -439,13 +157,13 @@ iterators are required to return lvalues from int* with a transform iterator, you do not get a random access iterator as might be expected, but an input iterator.

A third example is found in the vertex and edge iterators of the -Boost Graph Library. These iterators return vertex and edge +Boost Graph Library. These iterators return vertex and edge descriptors, which are lightweight handles created on-the-fly. They must be returned by-value. As a result, their current standard iterator category is input_iterator_tag, which means that, strictly speaking, you could not use these iterators with algorithms like min_element(). As a temporary solution, the concept -Multi-Pass Input Iterator was introduced to describe the vertex and +Multi-Pass Input Iterator was introduced to describe the vertex and edge descriptors, but as the design notes for the concept suggest, a better solution is needed.

In short, there are many useful iterators that do not fit into the @@ -458,8 +176,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 @@ -474,13 +192,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 @@ -544,15 +262,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 @@ -560,8 +278,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:

    @@ -626,24 +344,24 @@ approach for specifying operator[ direction would mean that an iterator satisfying the old Random Access Iterator requirements would not necessarily be a model of Readable or Writable Lvalue Iterator. Instead we have chosen a design that -matches the preferred resolution of issue 299: operator[] is +matches the preferred resolution of issue 299: operator[] is only required to return something convertible to the value_type (for a Readable Iterator), and is required to support assignment 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 @@ -685,8 +403,8 @@ non-cv-qualified type

-
-

Writable Iterators [lib.writable.iterators]

+
+

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 @@ -715,8 +433,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.

@@ -742,12 +460,12 @@ exchanged -

[Note: An iterator that is a model of the Readable Iterator and -Writable Iterator concepts is also a model of Swappable +

[Note: An iterator that is a model of the Readable Iterator and +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.

@@ -776,20 +494,20 @@ dereferenceable. -

If X is a Writable Iterator then a == b if and only if -*a is the same object as *b. If X is a Readable +

If X is a Writable Iterator then a == b if and only if +*a is the same object as *b. If X is a Readable Iterator then a == b implies *a is the same object as *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 @@ -828,16 +546,16 @@ stated semantics.

-

If X is a Writable Iterator then X a(r++); is equivalent +

If X is a Writable Iterator then X a(r++); is equivalent to X a(r); ++r; and *r++ = o is equivalent to *r = o; ++r. -If X is a Readable Iterator then T z(*r++); is equivalent +If X is a Readable Iterator then T z(*r++); is equivalent to T z(*r); ++r;.

-
-

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.

@@ -849,7 +567,8 @@ semantics.

-Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality Comparable) +Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality +Comparable) Expression Return Type @@ -897,8 +616,8 @@ between iterators
-
-

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 @@ -939,8 +658,8 @@ dereferenceable implies

-
-

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 @@ -1002,8 +721,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 @@ -1074,13 +793,13 @@ value n of a[n] convertible to T *(a + n) -pre: a is a Readable +pre: a is a Readable Iterator a[n] = v convertible to T *(a + n) = v -pre: a is a Writable +pre: a is a Writable Iterator a < b @@ -1116,8 +835,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 @@ -1240,8 +959,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;
@@ -1254,10 +973,10 @@ 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.

+template satisfies 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 @@ -1286,9 +1005,9 @@ otherwise.

-
-

Footnotes

-

The UnaryTypeTrait concept is defined in n1519; the LWG is +

+

Footnotes

+

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

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/permutation_iterator.html b/doc/permutation_iterator.html index 160cf21..ce27429 100644 --- a/doc/permutation_iterator.html +++ b/doc/permutation_iterator.html @@ -3,295 +3,13 @@ - + Permutation Iterator - + - +
@@ -303,12 +21,12 @@ ul.auto-toc { Author: Toon Knapen, David Abrahams, Roland Richter, Jeremy Siek Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu +dave@boost-consulting.com, jsiek@osl.iu.edu Organization: -Boost Consulting, Indiana University Open Systems +Boost Consulting, Indiana University Open Systems Lab Date: -2004-11-01 +2006-09-11 Copyright: Copyright Toon Knapen, David Abrahams, Roland Richter, and Jeremy Siek 2003. @@ -329,21 +47,21 @@ in a potentially different order. -
-

Table of Contents

+ -
-

Introduction

+
+

Introduction

@@ -365,8 +83,8 @@ to be unique. In this same context, it must be noted that the past the end permutation iterator is completely defined by means of the past-the-end iterator to the indices.

-
-

Reference

+
+

Reference

@@ -401,15 +119,15 @@ template <class ElementIterator, class IndexIterator> permutation_iterator<ElementIterator, IndexIterator> make_permutation_iterator( ElementIterator e, IndexIterator i); -
-

permutation_iterator requirements

+
+

permutation_iterator requirements

ElementIterator shall model Random Access Traversal Iterator. IndexIterator shall model Readable Iterator. The value type of the IndexIterator must be convertible to the difference type of ElementIterator.

-
-

permutation_iterator models

+
+

permutation_iterator models

permutation_iterator models the same iterator traversal concepts as IndexIterator and the same iterator access concepts as ElementIterator.

@@ -430,8 +148,8 @@ with permutation_iterator<E2,< X is interoperable with Y and E1 is convertible to E2.

-
-

permutation_iterator operations

+
+

permutation_iterator operations

In addition to those operations required by the concepts that permutation_iterator models, permutation_iterator provides the following operations.

@@ -514,8 +232,8 @@ make_permutation_iterator(ElementIterator e, IndexIterator i);
-
-

Example

+
+

Example

@@ -580,8 +298,14 @@ Elements at even indices in the permutation : 9 7 Permutation backwards : 6 7 8 9 Iterate backward with stride 2 : 6 8 -

The source code for this example can be found here.

+

The source code for this example can be found here.

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/pointee.html b/doc/pointee.html index d7ca6e3..1ce5d16 100755 --- a/doc/pointee.html +++ b/doc/pointee.html @@ -3,295 +3,13 @@ - + pointee and indirect_reference - + - +
@@ -303,11 +21,11 @@ ul.auto-toc { Author: David Abrahams Contact: -dave@boost-consulting.com +dave@boost-consulting.com Organization: -Boost Consulting +Boost Consulting Date: -2005-02-27 +2006-09-11 Copyright: Copyright David Abrahams 2004. @@ -324,8 +42,8 @@ pointers, smart pointers and iterators in generic code. -
-

Overview

+
+

Overview

Have you ever wanted to write a generic function that can operate on any kind of dereferenceable object? If you have, you've probably run into the problem of how to determine the type that the @@ -338,8 +56,8 @@ void f(Dereferenceable p) ... } -

-

pointee

+
+

pointee

It turns out to be impossible to come up with a fully-general algorithm to do determine what-goes-here directly, but it is possible to require that pointee<Dereferenceable>::type is @@ -360,8 +78,8 @@ namespace boost }

-
-

indirect_reference

+
+

indirect_reference

indirect_reference<T>::type is rather more specialized than pointee, and is meant to be used to forward the result of dereferencing an object of its argument type. Most dereferenceable @@ -369,13 +87,13 @@ types just return a reference to their pointee, but some return proxy references or return the pointee by value. When that information is needed, call on indirect_reference.

Both of these templates are essential to the correct functioning of -indirect_iterator.

+indirect_iterator.

-
-

Reference

-
-

pointee

+
+

Reference

+
+

pointee

@@ -418,8 +136,8 @@ else }
-
-

indirect_reference

+
+

indirect_reference

@@ -454,6 +172,12 @@ else
+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/reverse_iterator.html b/doc/reverse_iterator.html index aab1215..f635c1d 100644 --- a/doc/reverse_iterator.html +++ b/doc/reverse_iterator.html @@ -3,295 +3,13 @@ - + Reverse Iterator - + - +
@@ -303,13 +21,13 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de Organization: -Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport +Boost Consulting, Indiana University Open Systems +Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. @@ -329,18 +47,18 @@ range in the opposite direction. -
-

Table of Contents

+ -
-

reverse_iterator synopsis

+
+

reverse_iterator synopsis

@@ -379,14 +97,14 @@ Lvalue Iterator, then iterator_ca bidirectional_iterator_tag. Otherwise, iterator_category is convertible to input_iterator_tag.

-
-

reverse_iterator requirements

+
+

reverse_iterator requirements

Iterator must be a model of Bidirectional Traversal Iterator. The type iterator_traits<Iterator>::reference must be the type of *i, where i is an object of type Iterator.

-
-

reverse_iterator models

+
+

reverse_iterator models

A specialization of reverse_iterator models the same iterator traversal and iterator access concepts modeled by its Iterator argument. In addition, it may model old iterator concepts @@ -424,8 +142,8 @@ Random Access Traversal Iterator reverse_iterator<Y> if and only if X is interoperable with Y.

-
-

reverse_iterator operations

+
+

reverse_iterator operations

In addition to the operations required by the concepts modeled by reverse_iterator, reverse_iterator provides the following operations.

@@ -534,8 +252,8 @@ with a current constr
-
-

Example

+
+

Example

The following example prints an array of characters in reverse order using reverse_iterator.

@@ -566,8 +284,14 @@ original sequence of letters:                   hello world!
 sequence in reverse order:                      !dlrow olleh
 sequence in double-reversed (normal) order:     hello world!
-

The source code for this example can be found here.

+

The source code for this example can be found here.

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/rst2html b/doc/rst2html index 82a7f1e..9b5f63f 100755 --- a/doc/rst2html +++ b/doc/rst2html @@ -4,7 +4,7 @@ # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) PYTHONPATH="c:/src/docutils;c:/src/docutils/extras" export PYTHONPATH -python rst2html.py -gs $1 `echo $1 | sed 's/\(.*\)\..*/\1.html/'` +rst2html.py -gs --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript --stylesheet=../../../rst.css $1 `echo $1 | sed 's/\(.*\)\..*/\1.html/'` diff --git a/doc/transform_iterator.html b/doc/transform_iterator.html index 7b8ceb1..ed69c45 100644 --- a/doc/transform_iterator.html +++ b/doc/transform_iterator.html @@ -3,295 +3,13 @@ - + Transform Iterator - + - +
@@ -303,13 +21,13 @@ ul.auto-toc { Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de Organization: -Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport +Boost Consulting, Indiana University Open Systems +Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. @@ -330,18 +48,18 @@ dereferencing the iterator and returning the result. -
-

Table of Contents

+ -
-

transform_iterator synopsis

+
+

transform_iterator synopsis

@@ -396,8 +114,8 @@ convertible to forward_iterator_t model Readable Lvalue Iterator then iterator_category is convertible to input_iterator_tag.

-
-

transform_iterator requirements

+
+

transform_iterator requirements

The type UnaryFunction must be Assignable, Copy Constructible, and the expression f(*i) must be valid where f is an object of type UnaryFunction, i is an object of type Iterator, and @@ -405,8 +123,8 @@ where the type of f(*i)result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type.

The argument Iterator shall model Readable Iterator.

-
-

transform_iterator models

+
+

transform_iterator models

The resulting transform_iterator models the most refined of the following that is also modeled by Iterator.

@@ -452,8 +170,8 @@ mutable iterator (as defined in the old iterator requirements).

transform_iterator<F2, Y, R2, V2> if and only if X is interoperable with Y.

-
-

transform_iterator operations

+
+

transform_iterator operations

In addition to the operations required by the concepts modeled by transform_iterator, transform_iterator provides the following operations.

@@ -581,8 +299,8 @@ default constructed and m_iterato
-
-

Example

+
+

Example

This is a simple example of using the transform_iterators class to generate iterators that multiply (or add to) the value returned by dereferencing the iterator. It would be cooler to use lambda library @@ -615,8 +333,14 @@ multiplying the array by 2: adding 4 to each element in the array: 5 6 7 8 9 10 11 12 -

The source code for this example can be found here.

+

The source code for this example can be found here.

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/zip_iterator.html b/doc/zip_iterator.html index 559f262..a85ba13 100755 --- a/doc/zip_iterator.html +++ b/doc/zip_iterator.html @@ -3,295 +3,13 @@ - + Zip Iterator - + - +
@@ -303,11 +21,11 @@ ul.auto-toc { Author: David Abrahams, Thomas Becker Contact: -dave@boost-consulting.com, thomas@styleadvisor.com +dave@boost-consulting.com, thomas@styleadvisor.com Organization: -Boost Consulting, Zephyr Associates, Inc. +Boost Consulting, Zephyr Associates, Inc. Date: -2004-11-01 +2006-09-11 Copyright: Copyright David Abrahams and Thomas Becker 2003. @@ -331,18 +49,18 @@ the results of dereferencing the individual iterators. -
-

Table of Contents

+ -
-

zip_iterator synopsis

+
+

zip_iterator synopsis

@@ -392,12 +110,12 @@ iterators, then iterator_category iterator_category will be convertible to boost::bidirectional_traversal_tag, but no longer to boost::random_access_traversal_tag.

-
-

zip_iterator requirements

+
+

zip_iterator requirements

All iterator types in the argument IteratorTuple shall model Readable Iterator.

-
-

zip_iterator models

+
+

zip_iterator models

The resulting zip_iterator models Readable Iterator.

The fact that the zip_iterator models only Readable Iterator does not prevent you from modifying the values that the individual iterators point @@ -418,8 +136,8 @@ models the least refined standard traversal concept in this set.

zip_iterator<IteratorTuple2> if and only if IteratorTuple1 is interoperable with IteratorTuple2.

-
-

zip_iterator operations

+
+

zip_iterator operations

In addition to the operations required by the concepts modeled by zip_iterator, zip_iterator provides the following operations.

@@ -538,8 +256,8 @@ initialized to t.
-
-

Examples

+
+

Examples

There are two main types of applications of the zip_iterator. The first one concerns runtime efficiency: If one has several controlled sequences of the same length that must be somehow processed, e.g., with the @@ -638,6 +356,12 @@ the_transform_iterator it_end( );

+
+
+
+View document source. +Generated by Docutils from reStructuredText source. +
diff --git a/example/Jamfile b/example/Jamfile deleted file mode 100644 index f6f7f66..0000000 --- a/example/Jamfile +++ /dev/null @@ -1,17 +0,0 @@ -# Copyright David Abrahams 2006. Distributed under the Boost -# Software License, Version 1.0. (See accompanying -# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - -test-suite iterator_examples - : [ run reverse_iterator.cpp ] - [ run node_iterator1.cpp ] - [ run node_iterator2.cpp ] - [ run node_iterator3.cpp ] - [ run counting_iterator_example.cpp ] - [ run filter_iterator_example.cpp ] - [ run func_output_iter_example.cpp ] - [ run indirect_iterator_example.cpp ] - [ run permutation_iter_example.cpp ] - [ run reverse_iterator_example.cpp ] - [ run transform_iterator_example.cpp ] - ;