Filter iterator
+Filter iterator
+ + +The filter iterator adaptor creates a view of an iterator range in which some elements of the range are skipped. A predicate function object controls which elements are skipped. When the predicate is @@ -2119,12 +2459,12 @@ 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
- +template <class Predicate, class Iterator> class filter_iterator @@ -2157,15 +2497,15 @@ private:
If Iterator models Readable Lvalue Iterator and Bidirectional Traversal Iterator then iterator_category is convertible to -std::bidirectional_iterator_tag. +std::bidirectional_iterator_tag. Otherwise, if Iterator models Readable Lvalue Iterator and Forward Traversal Iterator then iterator_category is convertible to -std::forward_iterator_tag. +std::forward_iterator_tag. Otherwise iterator_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.
@@ -2175,8 +2515,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.
@@ -2186,8 +2526,8 @@ following tables.filter_iterator<P1, X> is interoperable with filter_iterator<P2, Y> +
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.
@@ -2264,7 +2604,7 @@ operations.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
+ + +
template <
class Incrementable
@@ -2409,7 +2755,7 @@ else if (numeric_limits<Incrementable>::is_specialized)
random_access_traversal_tag, Incrementable, const Incrementable&)
else
return iterator-category(
- iterator_traversal<Incrementable>::type,
+ iterator_traversal<Incrementable>::type,
Incrementable, const Incrementable&)
-
@@ -2419,8 +2765,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:
@@ -2445,8 +2791,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. @@ -2461,8 +2807,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.
@@ -2537,8 +2883,11 @@ operations.Function output iterator
+Function output iterator
+ + +The function output iterator adaptor makes it easier to create custom output iterators. The adaptor takes a unary function and creates a model of Output Iterator. Each item assigned to the output iterator is @@ -2546,11 +2895,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
+Header
#include <boost/function_output_iterator.hpp>@@ -2576,23 +2928,23 @@ private: };
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());
| Effects: | Constructs an instance of function_output_iterator + | ||
|---|---|---|---|
| Effects: | Constructs an instance of function_output_iterator with m_f constructed from f. |
| Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. |
| abstract: | The filter iterator adaptor creates a view of an iterator range in + |
|---|---|
| abstract: | + + +The filter iterator adaptor creates a view of an iterator range in which some elements of the range are skipped. A predicate function object controls which elements are skipped. When the predicate is -applied to an element, if it returns true then the element is -retained and if it returns false then the element is skipped +applied to an element, if it returns true then the element is +retained and if it returns false then the element is skipped over. When skipping over elements, it is necessary for the filter 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 @@ -49,22 +337,22 @@ sequence to be traversed. |
filter_iterator synopsis
+filter_iterator synopsis
- +
template <class Predicate, class Iterator>
class filter_iterator
@@ -95,39 +383,39 @@ private:
Iterator m_end; // exposition only
};
-If Iterator models Readable Lvalue Iterator and Bidirectional Traversal -Iterator then iterator_category is convertible to -std::bidirectional_iterator_tag. -Otherwise, if Iterator models Readable Lvalue Iterator and Forward Traversal -Iterator then iterator_category is convertible to -std::forward_iterator_tag. -Otherwise iterator_category is -convertible to std::input_iterator_tag.
+If Iterator models Readable Lvalue Iterator and Bidirectional Traversal +Iterator then iterator_category is convertible to +std::bidirectional_iterator_tag. +Otherwise, if Iterator models Readable Lvalue Iterator and Forward Traversal +Iterator then iterator_category is convertible to +std::forward_iterator_tag. +Otherwise iterator_category is +convertible to std::input_iterator_tag.
filter_iterator requirements
-The Iterator argument shall meet the requirements of Readable +
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.
-The Predicate argument must be Assignable, Copy Constructible, and -the expression p(x) must be valid where p is an object of type -Predicate, x is an object of type -iterator_traits<Iterator>::value_type, and where the type of -p(x) must be convertible to bool.
+The Predicate argument must be Assignable, Copy Constructible, and +the expression p(x) must be valid where p is an object of type +Predicate, x is an object of type +iterator_traits<Iterator>::value_type, and where the type of +p(x) must be convertible to bool.
filter_iterator models
-The concepts that filter_iterator models are dependent on which -concepts the Iterator argument models, as specified in the +
filter_iterator models
+The concepts that filter_iterator models are dependent on which +concepts the Iterator argument models, as specified in the following tables.
-| If Iterator models | -then filter_iterator models | +
|---|---|
| If Iterator models | +then filter_iterator models |
| If Iterator models | -then filter_iterator models | +
|---|---|
| If Iterator models | +then filter_iterator models |
| If Iterator models | -then filter_iterator models | +
|---|---|
| If Iterator models | +then filter_iterator models |
filter_iterator<P1, X> is interoperable with filter_iterator<P2, Y> -if and only if X is interoperable with Y.
+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 +filter_iterator models, filter_iterator provides the following operations.
-filter_iterator();
-| Requires: | Predicate and Iterator must be Default Constructible. | +
|---|---|
| Requires: | Predicate and Iterator must be Default Constructible. |
| Effects: | Constructs a filter_iterator whose``m_pred``, m_iter, and m_end + |
| Effects: | Constructs a filter_iterator whose``m_pred``, m_iter, and m_end members are a default constructed. |
filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
-| Effects: | Constructs a filter_iterator where m_iter is either -the first position in the range [x,end) such that f(*m_iter) == true -or else``m_iter == end``. The member m_pred is constructed from -f and m_end from end. | +
|---|---|
| Effects: | Constructs a filter_iterator where m_iter is either +the first position in the range [x,end) such that f(*m_iter) == true +or else``m_iter == end``. The member m_pred is constructed from +f and m_end from end. |
filter_iterator(Iterator x, Iterator end = Iterator());
-| Requires: | Predicate must be Default Constructible and -Predicate is a class type (not a function pointer). | +
|---|---|
| Requires: | Predicate must be Default Constructible and +Predicate is a class type (not a function pointer). |
| Effects: | Constructs a filter_iterator where m_iter is either -the first position in the range [x,end) such that m_pred(*m_iter) == true -or else``m_iter == end``. The member m_pred is default constructed. | +
| Effects: | Constructs a filter_iterator where m_iter is either +the first position in the range [x,end) such that m_pred(*m_iter) == true +or else``m_iter == end``. The member m_pred is default constructed. |
| Requires: | OtherIterator is implicitly convertible to Iterator. | +
|---|---|
| Requires: | OtherIterator is implicitly convertible to Iterator. |
| Effects: | Constructs a filter iterator whose members are copied from t. | +
| Effects: | Constructs a filter iterator whose members are copied from t. |
Predicate predicate() const;
-| Returns: | m_pred | +
|---|---|
| Returns: | m_pred |
Iterator end() const;
-| Returns: | m_end | +
|---|---|
| Returns: | m_end |
Iterator const& base() const;
-| Returns: | m_iterator | +
|---|---|
| Returns: | m_iterator |
reference operator*() const;
-| Returns: | *m_iter | +
|---|---|
| Returns: | *m_iter |
filter_iterator& operator++();
-| Effects: | Increments m_iter and then continues to -increment m_iter until either m_iter == m_end -or m_pred(*m_iter) == true. | +
|---|---|
| Effects: | Increments m_iter and then continues to +increment m_iter until either m_iter == m_end +or m_pred(*m_iter) == true. |
| Returns: | *this | +
| Returns: | *this |
template <class Predicate, class Iterator> filter_iterator<Predicate,Iterator> make_filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());-
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 -the integers greater than -2.
+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 +the integers greater than -2.
struct is_positive_number {
bool operator()(int x) { return 0 < x; }
@@ -384,17 +678,12 @@ int main()
The output is:
-4 5 8 -4 5 8 -0 -1 4 5 8 +4 5 8 +4 5 8 +0 -1 4 5 8
The source code for this example can be found here.
- diff --git a/doc/filter_iterator.rst b/doc/filter_iterator.rst index 2b1ebc3..cfa8642 100644 --- a/doc/filter_iterator.rst +++ b/doc/filter_iterator.rst @@ -1,3 +1,7 @@ +.. 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) + +++++++++++++++++ Filter Iterator +++++++++++++++++ diff --git a/doc/filter_iterator_abstract.rst b/doc/filter_iterator_abstract.rst index 4695478..9524efa 100644 --- a/doc/filter_iterator_abstract.rst +++ b/doc/filter_iterator_abstract.rst @@ -1,3 +1,7 @@ +.. 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) + The filter iterator adaptor creates a view of an iterator range in which some elements of the range are skipped. A predicate function object controls which elements are skipped. When the predicate is diff --git a/doc/filter_iterator_eg.rst b/doc/filter_iterator_eg.rst index 36448fe..dc2770e 100644 --- a/doc/filter_iterator_eg.rst +++ b/doc/filter_iterator_eg.rst @@ -1,3 +1,6 @@ +.. 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) Example ....... diff --git a/doc/func_output_iter_abstract.rst b/doc/func_output_iter_abstract.rst index 11fb4f1..d4a700f 100644 --- a/doc/func_output_iter_abstract.rst +++ b/doc/func_output_iter_abstract.rst @@ -1,3 +1,7 @@ +.. 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) + The function output iterator adaptor makes it easier to create custom output iterators. The adaptor takes a unary function and creates a model of Output Iterator. Each item assigned to the output iterator is diff --git a/doc/func_output_iter_ref.rst b/doc/func_output_iter_ref.rst index 97e2e17..e00eab7 100644 --- a/doc/func_output_iter_ref.rst +++ b/doc/func_output_iter_ref.rst @@ -1,3 +1,7 @@ +.. 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) + Header ...... diff --git a/doc/function_output_iterator.html b/doc/function_output_iterator.html index 94a5840..bea15ba 100644 --- a/doc/function_output_iterator.html +++ b/doc/function_output_iterator.html @@ -3,13 +3,295 @@ - +
| abstract: | The function output iterator adaptor makes it easier to create custom + |
|---|---|
| abstract: | + + +The function output iterator adaptor makes it easier to create custom output iterators. The adaptor takes a unary function and creates a model of Output Iterator. Each item assigned to the output iterator is passed as an argument to the unary function. The motivation for this @@ -46,8 +334,8 @@ proxy object. |
- Header
- function_output_iterator requirements @@ -56,8 +344,11 @@ proxy object.
- Example
Header
+ + + +Header
#include <boost/function_output_iterator.hpp>@@ -83,23 +374,23 @@ private: };
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());
| Effects: | Constructs an instance of function_output_iterator + |
|---|---|
| Effects: | Constructs an instance of function_output_iterator with m_f constructed from f. |
Example
+Example
struct string_appender
{
@@ -159,7 +453,7 @@ int main(int, char*[])
x.push_back("!");
std::string s = "";
- std::copy(x.begin(), x.end(),
+ std::copy(x.begin(), x.end(),
boost::make_function_output_iterator(string_appender(s)));
std::cout << s << std::endl;
@@ -169,10 +463,5 @@ int main(int, char*[])
- diff --git a/doc/function_output_iterator.rst b/doc/function_output_iterator.rst index a78c950..8018af5 100644 --- a/doc/function_output_iterator.rst +++ b/doc/function_output_iterator.rst @@ -1,3 +1,7 @@ +.. 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) + ++++++++++++++++++++++++++ Function Output Iterator ++++++++++++++++++++++++++ diff --git a/doc/function_output_iterator_eg.rst b/doc/function_output_iterator_eg.rst index eb635df..ab09f2d 100644 --- a/doc/function_output_iterator_eg.rst +++ b/doc/function_output_iterator_eg.rst @@ -1,3 +1,7 @@ +.. 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) + Example ....... diff --git a/doc/index.html b/doc/index.html index 0868477..eef53b1 100755 --- a/doc/index.html +++ b/doc/index.html @@ -3,13 +3,298 @@ - +
The Boost.Iterator Library 
+
+
+
- New-Style Iterators
- Iterator Facade and Adaptor @@ -66,8 +351,8 @@ older Boost Iterator Adaptor Library.
-
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 @@ -85,8 +370,8 @@ concepts, see our
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, @@ -112,8 +397,8 @@ and accepted into the first C++ technical report; see our
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.
-
@@ -141,10 +426,10 @@ underlying sequence. This component also replaces the old
positions of heterogeneous underlying iterators.
Iterator Utilities
-Traits
+Iterator Utilities
+Traits
- pointee.hpp (PDF): Provides the capability to deduce the referent types of pointers, smart pointers and iterators in generic code. Used @@ -157,17 +442,17 @@ of broken implementations of std: testing iterator interoperability -->
Testing and Concept Checking
+Testing and Concept Checking
- iterator_concepts.hpp (PDF): Concept checking classes for the new iterator concepts.
- iterator_archetypes.hpp (PDF): Concept archetype classes for the new iterators concepts.
Upgrading from the old Boost Iterator Adaptor Library
-If you have been using the old Boost Iterator Adaptor library to +
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 @@ -190,8 +475,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 @@ -232,10 +517,5 @@ LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct LocalWords: TraversalTag typename lvalues DWA Hmm JGS -->
- diff --git a/doc/index.rst b/doc/index.rst index 8f3a947..32db09a 100755 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,3 +1,7 @@ +.. 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) + +++++++++++++++++++++++++++++++++++++++++++++++++ The Boost.Iterator Library |(logo)|__ +++++++++++++++++++++++++++++++++++++++++++++++++ diff --git a/doc/indirect_iterator.html b/doc/indirect_iterator.html index 9e80b9b..11ea71f 100644 --- a/doc/indirect_iterator.html +++ b/doc/indirect_iterator.html @@ -3,13 +3,295 @@ - +
| abstract: | indirect_iterator adapts an iterator by applying an + |
|---|---|
| abstract: | + + +indirect_iterator adapts an iterator by applying an extra dereference inside of operator*(). For example, this iterator adaptor makes it possible to view a container of pointers (e.g. list<foo*>) as if it were a container of the pointed-to type @@ -47,8 +335,8 @@ not an iterator. |
- indirect_iterator synopsis
- indirect_iterator requirements @@ -57,8 +345,11 @@ not an iterator.
- Example
indirect_iterator synopsis
+indirect_iterator synopsis
+ + +
template <
class Iterator
@@ -115,9 +406,9 @@ if (Reference is use_default) then
else
typedef Reference reference;
-if (Value is use_default) then
+if (Value is use_default) then
typedef pointee<V>::type* pointer;
-else
+else
typedef Value* pointer;
if (Difference is use_default)
@@ -135,8 +426,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 @@ -149,8 +440,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 @@ -170,8 +461,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.
@@ -182,7 +473,7 @@ following operations.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 @@ -309,7 +603,7 @@ std::cout << std::endl; // Example of using make_indirect_iterator() -std::copy(boost::make_indirect_iterator(pointers_to_chars), +std::copy(boost::make_indirect_iterator(pointers_to_chars), boost::make_indirect_iterator(pointers_to_chars + N), std::ostream_iterator<char>(std::cout, ",")); std::cout << std::endl; @@ -323,10 +617,5 @@ a,b,c,d,e,f,g,
The source code for this example can be found here.
- diff --git a/doc/indirect_iterator.rst b/doc/indirect_iterator.rst index c197251..91328e0 100644 --- a/doc/indirect_iterator.rst +++ b/doc/indirect_iterator.rst @@ -1,3 +1,7 @@ +.. 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) + +++++++++++++++++++ Indirect Iterator +++++++++++++++++++ diff --git a/doc/indirect_iterator_abstract.rst b/doc/indirect_iterator_abstract.rst index 448b734..61fe016 100644 --- a/doc/indirect_iterator_abstract.rst +++ b/doc/indirect_iterator_abstract.rst @@ -1,3 +1,7 @@ +.. 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) + ``indirect_iterator`` adapts an iterator by applying an *extra* dereference inside of ``operator*()``. For example, this iterator adaptor makes it possible to view a container of pointers diff --git a/doc/indirect_iterator_eg.rst b/doc/indirect_iterator_eg.rst index 356a2dd..1cb00c0 100644 --- a/doc/indirect_iterator_eg.rst +++ b/doc/indirect_iterator_eg.rst @@ -1,3 +1,7 @@ +.. 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) + Example ....... diff --git a/doc/indirect_iterator_ref.html b/doc/indirect_iterator_ref.html index d69a8bc..54ff70c 100755 --- a/doc/indirect_iterator_ref.html +++ b/doc/indirect_iterator_ref.html @@ -3,12 +3,297 @@ - +
template <
class Iterator
@@ -48,9 +333,9 @@ private:
Iterator m_iterator; // exposition
};
-The member types of indirect_iterator are defined according to -the following pseudo-code, where V is -iterator_traits<Iterator>::value_type
+The member types of indirect_iterator are defined according to +the following pseudo-code, where V is +iterator_traits<Iterator>::value_type
if (Value is use_default) then
typedef remove_const<pointee<V>::type>::type value_type;
@@ -65,9 +350,9 @@ if (Reference is use_default) then
else
typedef Reference reference;
-if (Value is use_default) then
+if (Value is use_default) then
typedef pointee<V>::type* pointer;
-else
+else
typedef Value* pointer;
if (Difference is use_default)
@@ -84,65 +369,65 @@ else
CategoryOrTraversal,``reference``,``value_type``
) iterator_category;
-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 -model the traversal concept indicated by iterator_category. -Value, Reference, and Difference shall be chosen so -that value_type, reference, and difference_type meet -the requirements indicated by iterator_category.
+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 +model the traversal concept indicated by iterator_category. +Value, Reference, and Difference shall be chosen so +that value_type, reference, and difference_type meet +the requirements indicated by iterator_category.
[Note: there are further requirements on the -iterator_traits<Iterator>::value_type if the Value -parameter is not use_default, as implied by the algorithm for -deducing the default for the value_type member.]
+iterator_traits<Iterator>::value_type if the Value +parameter is not use_default, as implied by the algorithm for +deducing the default for the value_type member.]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 -concepts, Where v is an object of -iterator_traits<Iterator>::value_type:
+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 +concepts, Where v is an object of +iterator_traits<Iterator>::value_type:
--
- Readable Iterator if reference(*v) is convertible to -value_type.
-- Writable Iterator if reference(*v) = t is a valid -expression (where t is an object of type -indirect_iterator::value_type)
-- Lvalue Iterator if reference is a reference type.
+- Readable Iterator if reference(*v) is convertible to +value_type.
+- Writable Iterator if reference(*v) = t is a valid +expression (where t is an object of type +indirect_iterator::value_type)
+- Lvalue Iterator if reference is a reference type.
indirect_iterator<X,V1,C1,R1,D1> is interoperable with -indirect_iterator<Y,V2,C2,R2,D2> if and only if X is -interoperable with Y.
+indirect_iterator<X,V1,C1,R1,D1> is interoperable with +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 +above, specializations of indirect_iterator provide the following operations.
-indirect_iterator();
-| Requires: | Iterator must be Default Constructible. | +
|---|---|
| Requires: | Iterator must be Default Constructible. |
| Effects: | Constructs an instance of indirect_iterator with -a default-constructed m_iterator. | +
| Effects: | Constructs an instance of indirect_iterator with +a default-constructed m_iterator. |
indirect_iterator(Iterator x);
-| Effects: | Constructs an instance of indirect_iterator with -m_iterator copy constructed from x. | +
|---|---|
| Effects: | Constructs an instance of indirect_iterator with +m_iterator copy constructed from x. |
| Requires: | Iterator2 is implicitly convertible to Iterator. | +
|---|---|
| Requires: | Iterator2 is implicitly convertible to Iterator. |
| Effects: | Constructs an instance of indirect_iterator whose -m_iterator subobject is constructed from y.base(). | +
| Effects: | Constructs an instance of indirect_iterator whose +m_iterator subobject is constructed from y.base(). |
Iterator const& base() const;
-| Returns: | m_iterator | +
|---|---|
| Returns: | m_iterator |
reference operator*() const;
-| Returns: | **m_iterator | +
|---|---|
| Returns: | **m_iterator |
indirect_iterator& operator++();
-| Effects: | ++m_iterator | +
|---|---|
| Effects: | ++m_iterator |
| Returns: | *this | +
| Returns: | *this |
indirect_iterator& operator--();
-| Effects: | --m_iterator | +
|---|---|
| Effects: | --m_iterator |
| Returns: | *this | +
| Returns: | *this |
- diff --git a/doc/indirect_iterator_ref.rst b/doc/indirect_iterator_ref.rst index 1065659..d1430e1 100644 --- a/doc/indirect_iterator_ref.rst +++ b/doc/indirect_iterator_ref.rst @@ -1,3 +1,7 @@ +.. 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) + :: template < diff --git a/doc/issues.html b/doc/issues.html index 122a9c3..f8ab29c 100755 --- a/doc/issues.html +++ b/doc/issues.html @@ -3,68 +3,354 @@ - +
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: | $Date$ | -
| Copyright: | Copyright David Abrahams, Jeremy Siek 2003. Use, modification and + |
| 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) | -
Introduction
-The is_writable and is_swappable traits classes in N1550 +
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 +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 +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 +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 +
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
+ 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 +
Suppose the value_type of the iterator It has a private assignment operator:
class B {
@@ -74,31 +360,31 @@ 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.
+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
+Proposed Resolution
-
-
Remove the is_writable and is_swappable traits, and remove the +
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.
-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 +
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 +
Remove the requirement for support of the is_readable trait from the Readable Iterator concept.
-Remove the iterator_tag class.
+Remove the iterator_tag class.
-Change the specification of traversal_category to:
+Change the specification of traversal_category to:
traversal-category(Iterator) = let cat = iterator_traits<Iterator>::iterator_category @@ -120,14 +406,14 @@ traversal-category(Iterator) =
Rationale
+Rationale
-
-
- There are two reasons for removing is_writable -and is_swappable. The first is that we do not know of +
- 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 +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. @@ -137,34 +423,29 @@ 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. -
- 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 +
- 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. -
- The purpose of the iterator_tag class was to +is_readable so that it works for any iterator type. +
- 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, +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 +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 +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 +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. -
- The changes to the specification of traversal_category are a -direct result of the removal of iterator_tag. +for the iterator_category. +
- The changes to the specification of traversal_category are a +direct result of the removal of iterator_tag.
- diff --git a/doc/iterator_adaptor.html b/doc/iterator_adaptor.html index 5e5934f..1a559d7 100644 --- a/doc/iterator_adaptor.html +++ b/doc/iterator_adaptor.html @@ -3,13 +3,295 @@ - +
Each specialization of the iterator_adaptor class template is derived from a specialization of iterator_facade. The core interface functions expected by iterator_facade are implemented in terms of the @@ -53,8 +341,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.
-- Overview
- Reference
-
@@ -68,11 +356,14 @@ core interface functions of itera
- Tutorial Example
Overview
+Overview
+ + + - +The iterator_adaptor class template adapts some Base [1] type to create a new iterator. Instantiations of iterator_adaptor are derived from a corresponding instantiation of iterator_facade @@ -109,11 +400,14 @@ 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
+ + + - +
template <
class Derived
@@ -123,7 +417,7 @@ template <
, class Reference = use_default
, class Difference = use_default
>
-class iterator_adaptor
+class iterator_adaptor
: public iterator_facade<Derived, V', C', R', D'> // see details
{
friend class iterator_core_access;
@@ -136,12 +430,12 @@ class iterator_adaptor
typedef iterator_adaptor iterator_adaptor_;
Base const& base_reference() const;
Base& base_reference();
- private: // Core iterator interface for iterator_facade.
+ private: // Core iterator interface for iterator_facade.
typename iterator_adaptor::reference dereference() const;
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
- >
+ >
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
void advance(typename iterator_adaptor::difference_type n);
@@ -150,7 +444,7 @@ class iterator_adaptor
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
- >
+ >
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
@@ -158,13 +452,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
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:
@@ -204,8 +498,8 @@ expression involving ``Derived`` in those concepts' requirements. -->iterator_adaptor public operations
+iterator_adaptor public operations
iterator_adaptor();
| Requires: | The Base type must be Default Constructible. |
|---|---|
| Returns: | An instance of iterator_adaptor with + |
| Returns: | An instance of iterator_adaptor with m_iterator default constructed. |
iterator_adaptor protected member functions
+iterator_adaptor protected member functions
Base const& base_reference() const;
iterator_adaptor private member functions
+iterator_adaptor private member functions
typename iterator_adaptor::reference dereference() const;
Tutorial Example
+Tutorial Example
@@ -439,10 +733,5 @@ adaptor, and also iterator_adaptor's Base type needn't be an iterator.- diff --git a/doc/iterator_adaptor.rst b/doc/iterator_adaptor.rst index 81c34dc..4f8ca01 100644 --- a/doc/iterator_adaptor.rst +++ b/doc/iterator_adaptor.rst @@ -1,3 +1,7 @@ +.. 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) + +++++++++++++++++ Iterator Adaptor +++++++++++++++++ diff --git a/doc/iterator_adaptor_abstract.rst b/doc/iterator_adaptor_abstract.rst index fc4de4c..fa887f2 100644 --- a/doc/iterator_adaptor_abstract.rst +++ b/doc/iterator_adaptor_abstract.rst @@ -1,3 +1,7 @@ +.. 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) + .. Version 1.1 of this ReStructuredText document corresponds to n1530_, the paper accepted by the LWG. diff --git a/doc/iterator_adaptor_body.rst b/doc/iterator_adaptor_body.rst index 1c27118..ddd7f7b 100644 --- a/doc/iterator_adaptor_body.rst +++ b/doc/iterator_adaptor_body.rst @@ -1,3 +1,7 @@ +.. 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) + .. Version 1.2 of this ReStructuredText document corresponds to n1530_, the paper accepted by the LWG for TR1. diff --git a/doc/iterator_adaptor_ref.html b/doc/iterator_adaptor_ref.html index c3090db..b6c6a27 100755 --- a/doc/iterator_adaptor_ref.html +++ b/doc/iterator_adaptor_ref.html @@ -3,15 +3,300 @@ - +
template <
class Derived
@@ -21,7 +306,7 @@ template <
, class Reference = use_default
, class Difference = use_default
>
-class iterator_adaptor
+class iterator_adaptor
: public iterator_facade<Derived, V', C', R', D'> // see details
{
friend class iterator_core_access;
@@ -34,12 +319,12 @@ class iterator_adaptor
typedef iterator_adaptor iterator_adaptor_;
Base const& base_reference() const;
Base& base_reference();
- private: // Core iterator interface for iterator_facade.
+ private: // Core iterator interface for iterator_facade.
typename iterator_adaptor::reference dereference() const;
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
- >
+ >
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
void advance(typename iterator_adaptor::difference_type n);
@@ -48,7 +333,7 @@ class iterator_adaptor
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
- >
+ >
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
@@ -56,13 +341,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:
@@ -102,8 +387,8 @@ expression involving ``Derived`` in those concepts' requirements. -->iterator_adaptor public operations
+iterator_adaptor public operations
iterator_adaptor();
| Requires: | The Base type must be Default Constructible. |
|---|---|
| Returns: | An instance of iterator_adaptor with + |
| Returns: | An instance of iterator_adaptor with m_iterator default constructed. |
iterator_adaptor protected member functions
+iterator_adaptor protected member functions
Base const& base_reference() const;
iterator_adaptor private member functions
+iterator_adaptor private member functions
typename iterator_adaptor::reference dereference() const;
- diff --git a/doc/iterator_adaptor_ref.rst b/doc/iterator_adaptor_ref.rst index 1d13a9c..50c00fc 100644 --- a/doc/iterator_adaptor_ref.rst +++ b/doc/iterator_adaptor_ref.rst @@ -1,3 +1,7 @@ +.. 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) + .. Version 1.4 of this ReStructuredText document corresponds to n1530_, the paper accepted by the LWG for TR1. diff --git a/doc/iterator_archetypes.html b/doc/iterator_archetypes.html index c6bf7d7..323a214 100755 --- a/doc/iterator_archetypes.html +++ b/doc/iterator_archetypes.html @@ -3,13 +3,295 @@ - +
- Reference
- iterator_archetype Synopsis @@ -56,10 +341,10 @@ For further information see the documentation for the
Reference
-iterator_archetype Synopsis
+Reference
+iterator_archetype Synopsis
namespace iterator_archetypes
{
@@ -88,8 +373,8 @@ class iterator_archetype
};
Access Category Tags
+Access Category Tags
The access category types provided correspond to the following standard iterator access concept combinations:
@@ -114,27 +399,27 @@ 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)
-
+
value_type = Value
reference = Value
pointer = Value*
@@ -152,7 +437,7 @@ else if (AccessCategory == readable_writable_iterator_t)
reference :=
A type X that is convertible to Value for which the following
- expression is valid. Given an object x of type X and v of type
+ expression is valid. Given an object x of type X and v of type
Value.
x = v
@@ -160,13 +445,13 @@ else if (AccessCategory == readable_writable_iterator_t)
pointer = Value*
else if (AccessCategory == readable_lvalue_iterator_t)
-
+
value_type = Value
reference = Value const&
pointer = Value const*
else if (AccessCategory == writable_lvalue_iterator_t)
-
+
value_type = Value
reference = Value&
pointer = Value*
@@ -180,7 +465,7 @@ else
difference_type := unspecified type
-iterator_category :=
+iterator_category :=
A type X satisfying the following two constraints:
@@ -211,10 +496,5 @@ iterator_category :=
- diff --git a/doc/iterator_archetypes.rst b/doc/iterator_archetypes.rst index e26fde8..827723b 100755 --- a/doc/iterator_archetypes.rst +++ b/doc/iterator_archetypes.rst @@ -1,3 +1,7 @@ +.. 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) + ++++++++++++++++++++ Iterator Archetype ++++++++++++++++++++ diff --git a/doc/iterator_concepts.html b/doc/iterator_concepts.html index af23cdc..2bcb2e7 100644 --- a/doc/iterator_concepts.html +++ b/doc/iterator_concepts.html @@ -3,13 +3,295 @@ - +
For an introduction to using concept checking classes, see the documentation for the boost::concept_check library.
-Reference
-Iterator Access Concepts
+Reference
+Iterator Access Concepts
- Readable Iterator
- Writable Iterator @@ -55,8 +340,8 @@ the documentation for the Lvalue Iterator
Iterator Traversal Concepts
+Iterator Traversal Concepts
- Incrementable Iterator
- Single Pass Iterator @@ -65,8 +350,8 @@ the documentation for the Random Access Traversal
iterator_concepts.hpp Synopsis
+iterator_concepts.hpp Synopsis
namespace boost_concepts {
@@ -114,10 +399,5 @@ namespace boost_concepts {
- diff --git a/doc/iterator_concepts.rst b/doc/iterator_concepts.rst index 1653d22..77242a4 100755 --- a/doc/iterator_concepts.rst +++ b/doc/iterator_concepts.rst @@ -1,4 +1,6 @@ - +.. 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) ++++++++++++++++++ Iterator Concepts diff --git a/doc/iterator_facade.html b/doc/iterator_facade.html index de8459c..10fdc34 100644 --- a/doc/iterator_facade.html +++ b/doc/iterator_facade.html @@ -3,13 +3,295 @@ - +
| abstract: | iterator_facade is a base class template that implements the + |
|---|---|
| abstract: | + + +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. |
Overview
+Overview
+ + + - +While the iterator interface is rich, there is a core subset of the interface that is necessary for all the functionality. We have identified the following core behaviors for iterators:
@@ -124,8 +415,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. @@ -148,8 +439,8 @@ requirements.
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 @@ -212,7 +503,7 @@ provided, a class that acts as a gateway to the core member functions in the derived iterator class. The author of the derived class only needs to grant friendship to iterator_core_access to make his core member functions available to the library.
- +iterator_core_access will be typically implemented as an empty class containing only private static member functions which invoke the @@ -222,8 +513,8 @@ 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. @@ -245,8 +536,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 @@ -267,11 +558,14 @@ Patterns, C++ Report, February 1995, pp. 24-27.
Reference
+Reference
+ + + - +
template <
class Derived
@@ -355,12 +649,12 @@ template <class Dr, class V, class TC, class R, class D>
Derived operator+ (typename Derived::difference_type n,
iterator_facade<Dr,V,TC,R,D> const&);
-The iterator_category member of iterator_facade is
+The iterator_category member of iterator_facade is
iterator-category(CategoryOrTraversal, value_type, reference)
where iterator-category is defined as follows:
-
+
iterator-category(C,R,V) :=
if (C is convertible to std::input_iterator_tag
|| C is convertible to std::output_iterator_tag
@@ -407,10 +701,10 @@ traversal tags would add no information]
The enable_if_interoperable template used above is for exposition
purposes. The member operators should only be in an overload set
-provided the derived types Dr1 and Dr2 are interoperable,
+provided the derived types Dr1 and Dr2 are interoperable,
meaning that at least one of the types is convertible to the other. The
enable_if_interoperable approach uses SFINAE to take the operators
-out of the overload set when the types are not interoperable.
+out of the overload set when the types are not interoperable.
The operators should behave as-if enable_if_interoperable
were defined to be:
@@ -428,8 +722,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
@@ -442,8 +736,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
-Expression
-Return Type
-Assertion/Note
-Used to implement Iterator
+ Expression
+Return Type
+Assertion/Note
+Used to implement Iterator
Concept(s)
-
-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
@@ -527,14 +821,14 @@ of type pointer equal
&static_cast<Derived const*>(this)->dereference()
-Otherwise returns an object of unspecified type such that,
+
Otherwise returns an object of unspecified type such that,
(*static_cast<Derived const*>(this))->m is equivalent to (w = **static_cast<Derived const*>(this),
w.m) for some temporary object w of type value_type.
unspecified operator[](difference_type n) const;
+unspecified operator[](difference_type n) const;
| Returns: | if is_convertible<Dr2,Dr1>::value
|
|---|---|
| Returns: | if is_convertible<Dr2,Dr1>::value
|
| Returns: | if is_convertible<Dr2,Dr1>::value
|
| Returns: | if is_convertible<Dr2,Dr1>::value
|
| Returns: | if is_convertible<Dr2,Dr1>::value
|
| Returns: | if is_convertible<Dr2,Dr1>::value
|
+
template <class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2>
typename enable_if_interoperable<Dr1,Dr2,difference>::type
@@ -806,23 +1112,27 @@ operator -(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
Return Type: if is_convertible<Dr2,Dr1>::value
-
+
-- then
-- difference shall be
-iterator_traits<Dr1>::difference_type.
-- Otherwise
-- difference shall be iterator_traits<Dr2>::difference_type
+- then
+difference shall be
+iterator_traits<Dr1>::difference_type.
+- Otherwise
+difference shall be iterator_traits<Dr2>::difference_type
+
Returns: if is_convertible<Dr2,Dr1>::value
-- then
-- -((Dr1 const&)lhs).distance_to((Dr2 const&)rhs).
-- Otherwise,
-- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs).
+- then
+-((Dr1 const&)lhs).distance_to((Dr2 const&)rhs).
+- Otherwise,
+((Dr2 const&)rhs).distance_to((Dr1 const&)lhs).
+
Tutorial Example
+Tutorial Example
@@ -840,8 +1150,8 @@ iterators using iterator_facadeposting 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>
@@ -858,16 +1168,16 @@ struct node_base
// print to the stream
virtual void print(std::ostream& s) const = 0;
-
+
// double the value
virtual void double_me() = 0;
void append(node_base* p)
{
- if (m_next)
- m_next->append(p);
+ if (m_next)
+ m_next->append(p);
else
- m_next = p;
+ m_next = p;
}
private:
@@ -902,8 +1212,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.
@@ -916,25 +1226,25 @@ 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, 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
+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 @@ -953,8 +1263,8 @@ end up being std::forward_iterato
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 @@ -962,8 +1272,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. @@ -989,8 +1299,8 @@ 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 @@ -1034,8 +1344,8 @@ default constructor to leave m_no
Implementing the Core Operations
+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 @@ -1085,8 +1395,8 @@ class node_iterator iterator! For a working example of its use, see this program.
A constant node_iterator
+A constant node_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 @@ -1226,7 +1536,7 @@ class node_iter template <class OtherValue> bool equal(node_iter<OtherValue> const& other) const - { + { return this->m_node == other.m_node; } @@ -1259,8 +1569,8 @@ traversal iterator, we'd have had to templatize its
You can see an example program which exercises our interoperable 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. @@ -1286,7 +1596,7 @@ appropriate:
... -private: +private: struct enabler {}; public: @@ -1301,8 +1611,8 @@ 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. There's another way to approach writing these iterators which might @@ -1310,10 +1620,5 @@ even be superior.
- diff --git a/doc/iterator_facade.rst b/doc/iterator_facade.rst index a76da74..4cbafe6 100644 --- a/doc/iterator_facade.rst +++ b/doc/iterator_facade.rst @@ -1,3 +1,7 @@ +.. 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) + ++++++++++++++++ Iterator Facade ++++++++++++++++ diff --git a/doc/iterator_facade_abstract.rst b/doc/iterator_facade_abstract.rst index f024b9b..519cda7 100644 --- a/doc/iterator_facade_abstract.rst +++ b/doc/iterator_facade_abstract.rst @@ -1,3 +1,7 @@ +.. 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) + ``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. diff --git a/doc/iterator_facade_body.rst b/doc/iterator_facade_body.rst index 38b827a..4b3059d 100644 --- a/doc/iterator_facade_body.rst +++ b/doc/iterator_facade_body.rst @@ -1,3 +1,7 @@ +.. 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) + .. Version 1.1 of this ReStructuredText document corresponds to n1530_, the paper accepted by the LWG for TR1. diff --git a/doc/iterator_facade_ref.rst b/doc/iterator_facade_ref.rst index 695d2d4..c1baf9b 100644 --- a/doc/iterator_facade_ref.rst +++ b/doc/iterator_facade_ref.rst @@ -1,3 +1,7 @@ +.. 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) + .. Version 1.3 of this ReStructuredText document corresponds to n1530_, the paper accepted by the LWG for TR1. diff --git a/doc/iterator_traits.html b/doc/iterator_traits.html index d00d7be..35c743b 100755 --- a/doc/iterator_traits.html +++ b/doc/iterator_traits.html @@ -3,13 +3,295 @@ - +
| 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>
struct iterator_value
{
- typedef typename
- std::iterator_traits<Iterator>::value_type
+ typedef typename
+ std::iterator_traits<Iterator>::value_type
type;
};
template <class Iterator>
struct iterator_reference
{
- typedef typename
+ typedef typename
std::iterator_traits<Iterator>::reference
type;
};
@@ -73,8 +358,8 @@ struct iterator_reference
template <class Iterator>
struct iterator_pointer
{
- typedef typename
- std::iterator_traits<Iterator>::pointer
+ typedef typename
+ std::iterator_traits<Iterator>::pointer
type;
};
@@ -95,14 +380,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 @@ -111,10 +396,5 @@ either iterator_category
- diff --git a/doc/iterator_traits.rst b/doc/iterator_traits.rst index a6d76dd..2000d47 100755 --- a/doc/iterator_traits.rst +++ b/doc/iterator_traits.rst @@ -1,3 +1,7 @@ +.. 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) + +++++++++++++++++ Iterator Traits +++++++++++++++++ diff --git a/doc/make_counting_iterator.rst b/doc/make_counting_iterator.rst index f1c9ae9..8477093 100755 --- a/doc/make_counting_iterator.rst +++ b/doc/make_counting_iterator.rst @@ -1,3 +1,6 @@ +.. 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) :: diff --git a/doc/make_filter_iterator.html b/doc/make_filter_iterator.html index c138f02..56a26eb 100755 --- a/doc/make_filter_iterator.html +++ b/doc/make_filter_iterator.html @@ -3,18 +3,303 @@ - +
template <class Predicate, class Iterator> filter_iterator<Predicate,Iterator> make_filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());-
- diff --git a/doc/make_filter_iterator.rst b/doc/make_filter_iterator.rst index e4cd877..4374b60 100755 --- a/doc/make_filter_iterator.rst +++ b/doc/make_filter_iterator.rst @@ -1,3 +1,6 @@ +.. 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) :: diff --git a/doc/make_reverse_iterator.rst b/doc/make_reverse_iterator.rst index c3e20ed..dea1364 100644 --- a/doc/make_reverse_iterator.rst +++ b/doc/make_reverse_iterator.rst @@ -1,3 +1,7 @@ +.. 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) + :: template
- diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst index 389e52c..4648183 100644 --- a/doc/new-iter-concepts.rst +++ b/doc/new-iter-concepts.rst @@ -1,3 +1,7 @@ +.. 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) + ++++++++++++++++++++++ New Iterator Concepts ++++++++++++++++++++++ diff --git a/doc/permutation_iter_abstract.rst b/doc/permutation_iter_abstract.rst index 578b3ed..787c51a 100644 --- a/doc/permutation_iter_abstract.rst +++ b/doc/permutation_iter_abstract.rst @@ -1,3 +1,7 @@ +.. 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) + The permutation iterator adaptor provides a permuted view of a given range. That is, the view includes every element of the given range but in a potentially different order. diff --git a/doc/permutation_iterator.html b/doc/permutation_iterator.html index 667edfb..160cf21 100644 --- a/doc/permutation_iterator.html +++ b/doc/permutation_iterator.html @@ -3,13 +3,295 @@ - +
| abstract: | The permutation iterator adaptor provides a permuted view of a given + |
|---|---|
| abstract: | + + +The permutation iterator adaptor provides a permuted view of a given range. That is, the view includes every element of the given range but in a potentially different order. |
- Introduction
- Reference
-
@@ -54,8 +342,11 @@ in a potentially different order.
- Example
Introduction
+Introduction
+ + +The adaptor takes two arguments:
@@ -74,8 +365,11 @@ 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
+ + +
template< class ElementIterator
, class IndexIterator
@@ -104,28 +398,28 @@ private:
};
template <class ElementIterator, class IndexIterator>
-permutation_iterator<ElementIterator, 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.
-If IndexIterator models Single Pass Iterator and +
If IndexIterator models Single Pass Iterator and ElementIterator models Readable Iterator then permutation_iterator models Input Iterator.
-If IndexIterator models Forward Traversal Iterator and +
If IndexIterator models Forward Traversal Iterator and ElementIterator models Readable Lvalue Iterator then permutation_iterator models Forward Iterator.
-If IndexIterator models Bidirectional Traversal Iterator and +
If IndexIterator models Bidirectional Traversal Iterator and ElementIterator models Readable Lvalue Iterator then permutation_iterator models Bidirectional Iterator.
If IndexIterator models Random Access Traversal Iterator and @@ -136,8 +430,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.
@@ -207,7 +501,7 @@ permutation_iterator(template <class ElementIterator, class IndexIterator> -permutation_iterator<ElementIterator, IndexIterator> +permutation_iterator<ElementIterator, IndexIterator> make_permutation_iterator(ElementIterator e, IndexIterator i);
Example
+Example
+ + +using namespace boost; int i = 0; @@ -237,7 +534,7 @@ for(element_range_type::iterator el_it = elements.begin() ; el_it != elements.en *el_it = std::distance(elements.begin(), el_it); index_type indices( index_size ); -for(index_type::iterator i_it = indices.begin() ; i_it != indices.end() ; ++i_it ) +for(index_type::iterator i_it = indices.begin() ; i_it != indices.end() ; ++i_it ) *i_it = element_range_size - index_size + std::distance(indices.begin(), i_it); std::reverse( indices.begin(), indices.end() ); @@ -276,20 +573,15 @@ std::cout << "\n";
The output is:
-The original range is : 0 1 2 3 4 5 6 7 8 9 -The reindexing scheme is : 9 8 7 6 -The permutated range is : 9 8 7 6 -Elements at even indices in the permutation : 9 7 -Permutation backwards : 6 7 8 9 -Iterate backward with stride 2 : 6 8 +The original range is : 0 1 2 3 4 5 6 7 8 9 +The reindexing scheme is : 9 8 7 6 +The permutated range is : 9 8 7 6 +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.
- diff --git a/doc/permutation_iterator.rst b/doc/permutation_iterator.rst index d2f0ee0..0c8070c 100644 --- a/doc/permutation_iterator.rst +++ b/doc/permutation_iterator.rst @@ -1,3 +1,7 @@ +.. 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) + ++++++++++++++++++++++ Permutation Iterator ++++++++++++++++++++++ diff --git a/doc/permutation_iterator_body.rst b/doc/permutation_iterator_body.rst index 0f838e7..8b1333c 100644 --- a/doc/permutation_iterator_body.rst +++ b/doc/permutation_iterator_body.rst @@ -1,3 +1,7 @@ +.. 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) + The adaptor takes two arguments: * an iterator to the range V on which the permutation diff --git a/doc/permutation_iterator_eg.rst b/doc/permutation_iterator_eg.rst index 8b79cb9..eddf0a1 100644 --- a/doc/permutation_iterator_eg.rst +++ b/doc/permutation_iterator_eg.rst @@ -1,3 +1,7 @@ +.. 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) + :: using namespace boost; diff --git a/doc/permutation_iterator_ref.rst b/doc/permutation_iterator_ref.rst index c29f285..d51864f 100644 --- a/doc/permutation_iterator_ref.rst +++ b/doc/permutation_iterator_ref.rst @@ -1,3 +1,7 @@ +.. 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) + .. parsed-literal:: template< class ElementIterator diff --git a/doc/pointee.html b/doc/pointee.html index 5766c54..d7ca6e3 100755 --- a/doc/pointee.html +++ b/doc/pointee.html @@ -3,13 +3,295 @@ - +
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 @@ -53,8 +338,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 @@ -75,8 +360,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 @@ -87,10 +372,10 @@ information is needed, call on in indirect_iterator.
Reference
-pointee
+Reference
+pointee
@@ -133,8 +418,8 @@ else }indirect_reference
+indirect_reference
@@ -170,10 +455,5 @@ else- diff --git a/doc/pointee.rst b/doc/pointee.rst index 9f47692..993c3d4 100755 --- a/doc/pointee.rst +++ b/doc/pointee.rst @@ -1,3 +1,7 @@ +.. 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) + ++++++++++++++++++++++++++++++++++++++++ ``pointee`` and ``indirect_reference`` ++++++++++++++++++++++++++++++++++++++++ diff --git a/doc/ref_problem.html b/doc/ref_problem.html index cdc6682..c15e49e 100755 --- a/doc/ref_problem.html +++ b/doc/ref_problem.html @@ -3,73 +3,354 @@ - +
Problem with reference and old/new iterator category correspondance
| Author: | David Abrahams and Jeremy Siek | -
|---|---|
| Contact: | dave@boost-consulting.com, jsiek@osl.iu.edu | -
| Organization: | Boost Consulting, Indiana University Bloomington | -
| date: | $Date$ | -
| Copyright: | Copyright David Abrahams, Jeremy Siek 2003. Use, modification and + |
| Author: | +David Abrahams and Jeremy Siek |
| Contact: | +dave@boost-consulting.com, jsiek@osl.iu.edu |
| Organization: | +Boost Consulting, Indiana University Bloomington |
| Date: | +2003-11-17 |
| 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) | -
Introduction
+Introduction
The new iterator categories are intended to correspond to the old iterator categories, as specified in a diagram in N1550. For example, an iterator categorized as a mutable Forward Iterator under the old scheme is now a Writable, Lvalue, and Foward Traversal iterator. However, there is a problem with this correspondance, the new iterator -categories place requirements on the iterator_traits<X>::reference +categories place requirements on the iterator_traits<X>::reference type whereas the standard iterator requirements say nothing about the -reference type . In particular, the new Readable Iterator -requirements say that the return type of *a must be -iterator_traits<X>::reference and the Lvalue Iterator requirements -says that iterator_traits<X>::reference must be T& or const +reference type . In particular, the new Readable Iterator +requirements say that the return type of *a must be +iterator_traits<X>::reference and the Lvalue Iterator requirements +says that iterator_traits<X>::reference must be T& or const T&.
Proposed Resolution
+Proposed Resolution
Change the standard requirements to match the requirements of the new iterators. (more details to come)
Rationale
-The lack of specification in the standard of the reference type is +
Rationale
+The lack of specification in the standard of the reference type is certainly a defect. Without specification, it is entirely useless in a generic function. The current practice in the community is generally -to assume there are requirements on the reference type, such as +to assume there are requirements on the reference type, such as those proposed in the new iterator categories.
There is some danger in adding requirements to existing concepts. This will mean that some existing iterator types will no longer meet the iterator requirements. However, we feel that the impact of this is small enough to warrant going ahead with this change.
An alternative solution would be to leave the standard requirements as -is, and to remove the requirements for the reference type in the +is, and to remove the requirements for the reference type in the new iterator concepts. We are not in favor of this approach because it extends what we see as a defect further into the future.
- diff --git a/doc/reverse_iterator.html b/doc/reverse_iterator.html index fb6c759..aab1215 100644 --- a/doc/reverse_iterator.html +++ b/doc/reverse_iterator.html @@ -3,13 +3,295 @@ - +
| abstract: | The reverse iterator adaptor iterates through the adapted iterator + |
|---|---|
| abstract: | + + +The reverse iterator adaptor iterates through the adapted iterator range in the opposite direction. |
- reverse_iterator synopsis
- reverse_iterator requirements @@ -51,8 +339,11 @@ range in the opposite direction.
- Example
reverse_iterator synopsis
+reverse_iterator synopsis
+ + +
template <class Iterator>
class reverse_iterator
@@ -88,14 +379,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 @@ -106,8 +397,8 @@ specified in the following table:
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.
@@ -145,7 +436,7 @@ operations.
template <class BidirectionalIterator>
reverse_iterator<BidirectionalIterator>n
@@ -236,9 +530,12 @@ with a current constr
Example
+- diff --git a/doc/reverse_iterator.rst b/doc/reverse_iterator.rst index b33687b..e6034b6 100644 --- a/doc/reverse_iterator.rst +++ b/doc/reverse_iterator.rst @@ -1,3 +1,7 @@ +.. 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) + ++++++++++++++++++ Reverse Iterator ++++++++++++++++++ diff --git a/doc/reverse_iterator_abstract.rst b/doc/reverse_iterator_abstract.rst index a4caee5..911257f 100644 --- a/doc/reverse_iterator_abstract.rst +++ b/doc/reverse_iterator_abstract.rst @@ -1,3 +1,6 @@ +.. 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) The reverse iterator adaptor iterates through the adapted iterator range in the opposite direction. diff --git a/doc/reverse_iterator_eg.rst b/doc/reverse_iterator_eg.rst index 7923f2f..b17347e 100644 --- a/doc/reverse_iterator_eg.rst +++ b/doc/reverse_iterator_eg.rst @@ -1,3 +1,6 @@ +.. 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) Example ....... diff --git a/doc/reverse_iterator_ref.rst b/doc/reverse_iterator_ref.rst index 36b93d6..b239b26 100644 --- a/doc/reverse_iterator_ref.rst +++ b/doc/reverse_iterator_ref.rst @@ -1,3 +1,7 @@ +.. 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) + :: template
| abstract: | The transform iterator adapts an iterator by modifying the + |
|---|---|
| abstract: | + + +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. |
- transform_iterator synopsis
- transform_iterator requirements @@ -52,13 +340,16 @@ dereferencing the iterator and returning the result.
- Example
transform_iterator synopsis
+transform_iterator synopsis
+ + +
template <class UnaryFunction,
- class Iterator,
- class Reference = use_default,
+ class Iterator,
+ class Reference = use_default,
class Value = use_default>
class transform_iterator
{
@@ -105,8 +396,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 @@ -114,8 +405,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.
@@ -136,8 +427,8 @@ the Iterator argument- If Iterator models -then transform_iterator models +@@ -161,8 +452,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. - If Iterator models +then transform_iterator models -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.
@@ -255,6 +546,9 @@ initialized to t.functor()
template <class UnaryFunction, class Iterator>
transform_iterator<UnaryFunction, Iterator>
@@ -283,9 +577,12 @@ 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 @@ -314,17 +611,12 @@ std::cout << std::endl;
The output is:
multiplying the array by 2: -2 4 6 8 10 12 14 16 +2 4 6 8 10 12 14 16 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.
- diff --git a/doc/transform_iterator.rst b/doc/transform_iterator.rst index dff6dd9..4f81cca 100644 --- a/doc/transform_iterator.rst +++ b/doc/transform_iterator.rst @@ -1,3 +1,7 @@ +.. 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) + ++++++++++++++++++++ Transform Iterator ++++++++++++++++++++ diff --git a/doc/transform_iterator_abstract.rst b/doc/transform_iterator_abstract.rst index 4d40536..5fdcf53 100644 --- a/doc/transform_iterator_abstract.rst +++ b/doc/transform_iterator_abstract.rst @@ -1,3 +1,7 @@ +.. 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) + 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. diff --git a/doc/transform_iterator_eg.rst b/doc/transform_iterator_eg.rst index a6629ca..1406d2b 100755 --- a/doc/transform_iterator_eg.rst +++ b/doc/transform_iterator_eg.rst @@ -1,3 +1,7 @@ +.. 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) + Example ....... diff --git a/doc/transform_iterator_ref.rst b/doc/transform_iterator_ref.rst index 58f6f26..74347a0 100644 --- a/doc/transform_iterator_ref.rst +++ b/doc/transform_iterator_ref.rst @@ -1,3 +1,7 @@ +.. 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) + .. Version 1.3 of this document was accepted for TR1 :: diff --git a/doc/zip_iterator.html b/doc/zip_iterator.html index 3021ed4..559f262 100755 --- a/doc/zip_iterator.html +++ b/doc/zip_iterator.html @@ -3,13 +3,295 @@ - +
| abstract: | The zip iterator provides the ability to parallel-iterate -over several controlled sequences simultaneously. A zip + |
|---|---|
| abstract: | + + +The zip iterator provides the ability to parallel-iterate +over several controlled sequences simultaneously. A zip iterator is constructed from a tuple of iterators. Moving the zip iterator moves all the iterators in parallel. Dereferencing the zip iterator returns a tuple that contains @@ -43,8 +331,8 @@ the results of dereferencing the individual iterators. |
- zip_iterator synopsis
- zip_iterator requirements @@ -53,12 +341,15 @@ the results of dereferencing the individual iterators.
- Examples
zip_iterator synopsis
+zip_iterator synopsis
+ + +
template<typename IteratorTuple>
class zip_iterator
-{
+{
public:
typedef /* see below */ reference;
@@ -84,8 +375,8 @@ private:
IteratorTuple m_iterator_tuple; // exposition only
};
-template<typename IteratorTuple>
-zip_iterator<IteratorTuple>
+template<typename IteratorTuple>
+zip_iterator<IteratorTuple>
make_zip_iterator(IteratorTuple t);
The reference member of zip_iterator is the type of the tuple @@ -96,22 +387,22 @@ of the first of the iterator types in the The iterator_category member of zip_iterator is convertible to the minimum of the traversal categories of the iterator types in the IteratorTuple argument. For example, if the zip_iterator holds only vector -iterators, then iterator_category is convertible to +iterators, then iterator_category is convertible to boost::random_access_traversal_tag. If you add a list iterator, then 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 +
The fact that the zip_iterator models only Readable Iterator does not prevent you from modifying the values that the individual iterators point -to. The tuple returned by the zip_iterator's operator* is a tuple -constructed from the reference types of the individual iterators, not +to. The tuple returned by the zip_iterator's operator* is a tuple +constructed from the reference types of the individual iterators, not their value types. For example, if zip_it is a zip_iterator whose first member iterator is an std::vector<double>::iterator, then the following line will modify the value which the first member iterator of @@ -121,14 +412,14 @@ zip_it->get<0>() = 42.0;
Consider the set of standard traversal concepts obtained by taking the most refined standard traversal concept modeled by each individual -iterator type in the IteratorTuple argument.The zip_iterator +iterator type in the IteratorTuple argument.The zip_iterator models the least refined standard traversal concept in this set.
zip_iterator<IteratorTuple1> is interoperable with 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.
@@ -213,8 +504,8 @@ zip_iterator(-template<typename IteratorTuple> -zip_iterator<IteratorTuple> +template<typename IteratorTuple> +zip_iterator<IteratorTuple> make_zip_iterator(IteratorTuple t);
-template<typename IteratorTuple> -zip_iterator<IteratorTuple> +template<typename IteratorTuple> +zip_iterator<IteratorTuple> make_zip_iterator(IteratorTuple 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 +of the same length that must be somehow processed, e.g., with the for_each algorithm, then it is more efficient to perform just -one parallel-iteration rather than several individual iterations. For an +one parallel-iteration rather than several individual iterations. For an example, assume that vect_of_doubles and vect_of_ints are two vectors of equal length containing doubles and ints, respectively, and consider the following two iterations:
@@ -274,7 +571,7 @@ std::for_each(A non-generic implementation of zip_func could look as follows:
-struct zip_func :
+struct zip_func :
public std::unary_function<const boost::tuple<const double&, const int&>&, void>
{
void operator()(const boost::tuple<const double&, const int&>& t) const
@@ -294,14 +591,14 @@ that parallel-iterates over several controlled sequences and, upon
dereferencing, returns the result of applying a functor to the values of the
sequences at the respective positions. This can now be achieved by using the
zip_iterator in conjunction with the transform_iterator.
-Suppose, for example, that you have two vectors of doubles, say
+
Suppose, for example, that you have two vectors of doubles, say
vect_1 and vect_2, and you need to expose to a client
-a controlled sequence containing the products of the elements of
+a controlled sequence containing the products of the elements of
vect_1 and vect_2. Rather than placing these products
in a third vector, you can use a combining iterator that calculates the
products on the fly. Let us assume that tuple_multiplies is a
functor that works like std::multiplies, except that it takes
-its two arguments packaged in a tuple. Then the two iterators
+its two arguments packaged in a tuple. Then the two iterators
it_begin and it_end defined below delimit a controlled
sequence containing the products of the elements of vect_1 and
vect_2:
@@ -342,10 +639,5 @@ the_transform_iterator it_end(
- diff --git a/doc/zip_iterator.rst b/doc/zip_iterator.rst index a853237..4e360c3 100755 --- a/doc/zip_iterator.rst +++ b/doc/zip_iterator.rst @@ -1,3 +1,7 @@ +.. 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) + +++++++++++++ Zip Iterator +++++++++++++ diff --git a/doc/zip_iterator_abstract.rst b/doc/zip_iterator_abstract.rst index 0d1cf11..2f4aecf 100755 --- a/doc/zip_iterator_abstract.rst +++ b/doc/zip_iterator_abstract.rst @@ -1,3 +1,7 @@ +.. 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) + The zip iterator provides the ability to parallel-iterate over several controlled sequences simultaneously. A zip iterator is constructed from a tuple of iterators. Moving diff --git a/doc/zip_iterator_eg.rst b/doc/zip_iterator_eg.rst index 9016708..e999f15 100755 --- a/doc/zip_iterator_eg.rst +++ b/doc/zip_iterator_eg.rst @@ -1,3 +1,7 @@ +.. 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) + Examples ........ diff --git a/doc/zip_iterator_ref.rst b/doc/zip_iterator_ref.rst index 340fdc8..f81ccd2 100755 --- a/doc/zip_iterator_ref.rst +++ b/doc/zip_iterator_ref.rst @@ -1,3 +1,6 @@ +.. 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) ::