Counting Iterator
| Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. |
| abstract: | How would you fill up a vector with the numbers zero -through one hundred using std::copy()? The only iterator +through one hundred using std::copy()? The only iterator operation missing from builtin integer types is an -operator*() that returns the current value of the integer. +operator*() that returns the current value of the integer. The counting iterator adaptor adds this crucial piece of functionality to whatever type it wraps. One can use the counting iterator adaptor not only with integer types, but with any incrementable type. -counting_iterator adapts an object by adding an operator* that + 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. |
@@ -54,15 +54,15 @@ are forwarded to the adapted object.
|---|
| Requires: | Incrementable is Default Constructible. | +
|---|---|
| Requires: | Incrementable is Default Constructible. |
| Effects: | Default construct the member m_inc. | +
| Effects: | Default construct the member m_inc. |
counting_iterator(counting_iterator const& rhs);
-| Effects: | Construct member m_inc from rhs.m_inc. | +
|---|---|
| Effects: | Construct member m_inc from rhs.m_inc. |
explicit counting_iterator(Incrementable x);
-| Effects: | Construct member m_inc from x. | +
|---|---|
| Effects: | Construct member m_inc from x. |
reference operator*() const;
-| Returns: | m_inc | +
|---|---|
| Returns: | m_inc |
counting_iterator& operator++();
-| Effects: | ++m_inc | +
|---|---|
| Effects: | ++m_inc |
| Returns: | *this | +
| Returns: | *this |
counting_iterator& operator--();
-| Effects: | --m_inc | +
|---|---|
| Effects: | --m_inc |
| Returns: | *this | +
| Returns: | *this |
Incrementable const& base() const;
-| Returns: | m_inc | +
|---|---|
| Returns: | m_inc |
| Returns: | An instance of counting_iterator<Incrementable> -with current constructed from x. | +
|---|---|
| Returns: | An instance of counting_iterator<Incrementable> +with current constructed from x. |
Example
This example fills an array with numbers and a second array with -pointers into the first array, using counting_iterator for both -tasks. Finally indirect_iterator is used to print out the numbers +pointers into the first array, using counting_iterator for both +tasks. Finally indirect_iterator is used to print out the numbers into the first array via indirection through the second array.
int N = 7; @@ -276,7 +276,7 @@ indirectly printing out the numbers from 0 to 7The source code for this example can be found here.
+
Iterator Facade and Adaptor
| [1] | We use the term concept to mean a set of requirements @@ -205,7 +205,7 @@ that a type must satisfy to be used with a particular template parameter. |
| [2] | The term mutable iterator refers to iterators over objects that @@ -215,12 +215,12 @@ modified. |
To fulfill the need for constructing adaptors, we propose the -iterator_adaptor class template. Instantiations of -iterator_adaptor serve as a base classes for new iterators, +iterator_adaptor class template. Instantiations of +iterator_adaptor serve as a base classes for new iterators, providing the default behavior of forwarding all operations to the underlying iterator. The user can selectively replace these features in the derived iterator class. This proposal also includes a number -of more specialized adaptors, such as the transform_iterator that +of more specialized adaptors, such as the transform_iterator that applies some user-specified function during the dereference of the iterator.
@@ -234,7 +234,7 @@ Iterator Concepts.Design
Iterator Concepts
-This proposal is formulated in terms of the new iterator concepts +
This proposal is formulated in terms of the new iterator concepts as proposed in n1550, since user-defined and especially adapted iterators suffer from the well known categorization problems that are inherent to the current iterator categories.
@@ -280,11 +280,11 @@ identified the following core behaviors for iterators:In addition to the behaviors listed above, the core interface elements include the associated types exposed through iterator traits: -value_type, reference, difference_type, and -iterator_category.
+value_type, reference, difference_type, and +iterator_category.Iterator facade uses the Curiously Recurring Template Pattern (CRTP) [Cop95] so that the user can specify the behavior -of iterator_facade in a derived class. Former designs used +of iterator_facade in a derived class. Former designs used policy objects to specify the behavior, but that approach was discarded for several reasons:
@@ -293,30 +293,30 @@ discarded for several reasons: overhead that can be avoided with the current approach.The policy object approach does not allow for custom constructors on the created iterator types, an essential feature if -iterator_facade should be used in other library +iterator_facade should be used in other library implementations. Without the use of CRTP, the standard requirement that an -iterator's operator++ returns the iterator type itself +iterator's operator++ returns the iterator type itself would mean that all iterators built with the library would -have to be specializations of iterator_facade<...>, rather +have to be specializations of iterator_facade<...>, rather than something more descriptive like -indirect_iterator<T*>. Cumbersome type generator +indirect_iterator<T*>. Cumbersome type generator metafunctions would be needed to build new parameterized -iterators, and a separate iterator_adaptor layer would be +iterators, and a separate iterator_adaptor layer would be impossible.
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. +
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. The order of the other template parameters have been carefully chosen to take advantage of useful defaults. For example, when defining a constant lvalue iterator, the user can pass a -const-qualified version of the iterator's value_type as -iterator_facade's Value parameter and omit the -Reference parameter which follows.
+const-qualified version of the iterator's value_type as +iterator_facade's Value parameter and omit the +Reference parameter which follows.The derived iterator class must define member functions implementing the iterator's core behaviors. The following table describes expressions which are required to be valid depending on the category @@ -324,7 +324,7 @@ of the derived iterator type. These member functions are described briefly below and in more detail in the iterator facade requirements.
-+
@@ -359,20 +359,20 @@ requirements.
- @@ -335,23 +335,23 @@ requirements. i.dereference() +- i.dereference() Access the value referred to i.equal(j) -Compare for equality with j +- i.equal(j) +Compare for equality with j i.increment() +- i.increment() Advance by one position i.decrement() +- i.decrement() Retreat by one position i.advance(n) -Advance by n positions +- i.advance(n) +Advance by n positions i.distance_to(j) -Measure the distance to j +i.distance_to(j) +Measure the distance to j In addition to implementing the core interface functions, an iterator -derived from iterator_facade typically defines several +derived from iterator_facade typically defines several constructors. To model any of the standard iterator concepts, the iterator must at least have a copy constructor. Also, if the iterator -type X is meant to be automatically interoperate with another -iterator type Y (as with constant and mutable iterators) then -there must be an implicit conversion from X to Y or from Y -to X (but not both), typically implemented as a conversion +type X is meant to be automatically interoperate with another +iterator type Y (as with constant and mutable iterators) then +there must be an implicit conversion from X to Y or from Y +to X (but not both), typically implemented as a conversion constructor. Finally, if the iterator is to model Forward Traversal Iterator or a more-refined iterator concept, a default constructor is required.
Iterator Core Access
-iterator_facade and the operator implementations need to be able +
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 the user. The design used here ensures that implementation details do @@ -383,64 +383,64 @@ use a member function of the iterator when a member of the value_type was intended. This has been an issue with smart pointer implementations in the past. The second and main advantage is that library implementers can freely exchange a hand-rolled iterator -implementation for one based on iterator_facade without fear of +implementation for one based on iterator_facade without fear of breaking code that was accessing the public core member functions directly.
In a naive implementation, keeping the derived class' core member functions private would require it to grant friendship to -iterator_facade and each of the seven operators. In order to -reduce the burden of limiting access, iterator_core_access is +iterator_facade and each of the seven operators. In order to +reduce the burden of limiting access, iterator_core_access is 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 +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 +
iterator_core_access will be typically implemented as an empty class containing only private static member functions which invoke the iterator core member functions. There is, however, no need to standardize the gateway protocol. Note that even if -iterator_core_access used public member functions it would not +iterator_core_access used public member functions it would not 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. +challenges. A random access iterator's operator[] is only +required to return something convertible to its value_type. Requiring that it return an lvalue would rule out currently-legal random-access iterators which hold the referenced value in a data -member (e.g. counting_iterator), because *(p+n) is a reference -into the temporary iterator p+n, which is destroyed when -operator[] returns.
-Writable iterators built with iterator_facade implement the +member (e.g. counting_iterator), because *(p+n) is a reference +into the temporary iterator p+n, which is destroyed when +operator[] returns.
+Writable iterators built with iterator_facade implement the semantics required by the preferred resolution to issue 299 and -adopted by proposal n1550: the result of p[n] is an object -convertible to the iterator's value_type, and p[n] = x is -equivalent to *(p + n) = x (Note: This result object may be -implemented as a proxy containing a copy of p+n). This approach +adopted by proposal n1550: the result of p[n] is an object +convertible to the iterator's value_type, and p[n] = x is +equivalent to *(p + n) = x (Note: This result object may be +implemented as a proxy containing a copy of p+n). This approach will work properly for any random-access iterator regardless of the other details of its implementation. A user who knows more about the implementation of her iterator is free to implement an -operator[] that returns an lvalue in the derived iterator -class; it will hide the one supplied by iterator_facade from +operator[] that returns an lvalue in the derived iterator +class; it will hide the one supplied by iterator_facade from clients of her iterator.
-operator->
-The reference type of a readable iterator (and today's input +
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 +convertible to the iterator's value_type. When the value_type is a class, however, it must still be possible to access members -through operator->. Therefore, an iterator whose reference +through operator->. Therefore, an iterator whose reference type is not in fact a reference must return a proxy containing a copy -of the referenced value from its operator->.
-The return types for iterator_facade's operator-> and -operator[] are not explicitly specified. Instead, those types +of the referenced value from its operator->.
+The return types for iterator_facade's operator-> and +operator[] are not explicitly specified. Instead, those types are described in terms of a set of requirements, which must be -satisfied by the iterator_facade implementation.
-+satisfied by the iterator_facade implementation. +
- [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template @@ -454,64 +454,64 @@ Patterns, C++ Report, February 1995, pp. 24-27. The iterator_adaptor class template adapts some Base 3 -type to create a new iterator. Instantiations of iterator_adaptor -are derived from a corresponding instantiation of iterator_facade -and implement the core behaviors in terms of the Base type. In -essence, iterator_adaptor merely forwards all operations to an -instance of the Base type, which it stores as a member.
-+
The iterator_adaptor class template adapts some Base [3] +type to create a new iterator. Instantiations of iterator_adaptor +are derived from a corresponding instantiation of iterator_facade +and implement the core behaviors in terms of the Base type. In +essence, iterator_adaptor merely forwards all operations to an +instance of the Base type, which it stores as a member.
+-
+the underlying iterator object of a reverse_iterator adaptor. [3] The term "Base" here does not refer to a base class and is not meant to imply the use of derivation. We have followed the lead of the standard library, which provides a base() function to access -the underlying iterator object of a reverse_iterator adaptor. The user of iterator_adaptor creates a class derived from an -instantiation of iterator_adaptor and then selectively +
The user of iterator_adaptor creates a class derived from an +instantiation of iterator_adaptor and then selectively redefines some of the core member functions described in the -iterator_facade core requirements table. The Base type need +iterator_facade core requirements table. The Base type need not meet the full requirements for an iterator; it need only support the operations used by the core interface functions of -iterator_adaptor that have not been redefined in the user's +iterator_adaptor that have not been redefined in the user's derived class.
-Several of the template parameters of iterator_adaptor default -to use_default. This allows the +
Several of the template parameters of iterator_adaptor default +to use_default. This allows the user to make use of a default parameter even when she wants to specify a parameter later in the parameter list. Also, the defaults for the corresponding associated types are somewhat complicated, so metaprogramming is required to compute them, and -use_default can help to simplify the implementation. Finally, -the identity of the use_default type is not left unspecified -because specification helps to highlight that the Reference +use_default can help to simplify the implementation. Finally, +the identity of the use_default type is not left unspecified +because specification helps to highlight that the Reference template parameter may not always be identical to the iterator's -reference type, and will keep users from making mistakes based on +reference type, and will keep users from making mistakes based on that assumption.
Specialized Adaptors
This proposal also contains several examples of specialized adaptors -which were easily implemented using iterator_adaptor:
+which were easily implemented using iterator_adaptor:-
- indirect_iterator, which iterates over iterators, pointers, +
- indirect_iterator, which iterates over iterators, pointers, or smart pointers and applies an extra level of dereferencing.
-- A new reverse_iterator, which inverts the direction of a Base +
- A new reverse_iterator, which inverts the direction of a Base iterator's motion, while allowing adapted constant and mutable iterators to interact in the expected ways (unlike those in most implementations of C++98).
-- transform_iterator, which applies a user-defined function object +
- transform_iterator, which applies a user-defined function object to the underlying values when dereferenced.
-- filter_iterator, which provides a view of an iterator range in +
- filter_iterator, which provides a view of an iterator range in which some elements of the underlying range are skipped.
-
- counting_iterator, which adapts any incrementable type +
- counting_iterator, which adapts any incrementable type (e.g. integers, iterators) so that incrementing/decrementing the adapted iterator and dereferencing it produces successive values of the Base type.
-- function_output_iterator, which makes it easier to create custom +
- function_output_iterator, which makes it easier to create custom output iterators.
Based on examples in the Boost library, users have generated many new @@ -527,7 +527,7 @@ Standard compliant iterators).
Proposed Text
-Header <iterator_helper> synopsis [lib.iterator.helper.synopsis]
+Header <iterator_helper> synopsis [lib.iterator.helper.synopsis]
struct use_default; @@ -594,11 +594,11 @@ class function_output_iterator;Iterator facade [lib.iterator.facade]
-iterator_facade is a base class template that implements the +
iterator_facade is a base class template that implements the interface of standard iterators in terms of a few core functions and associated types, to be supplied by a derived iterator class.
-Class template iterator_facade
+Class template iterator_facade
@@ -685,7 +685,7 @@ 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)@@ -729,19 +729,19 @@ Derived operator+ (typename Derived::difference_type n, convertible, and not to any more-derived traversal tag type. -[Note: the intention is to allow iterator_category to be one of +
[Note: the intention is to allow iterator_category to be one of the five original category tags when convertibility to one of the traversal tags would add no information]
-The enable_if_interoperable template used above is for exposition +
The enable_if_interoperable template used above is for exposition purposes. The member operators should 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 +enable_if_interoperable approach uses SFINAE to take the operators out of the overload set when the types are not interoperable. -The operators should behave as-if enable_if_interoperable +The operators should behave as-if enable_if_interoperable were defined to be:
template <bool, typename> enable_if_interoperable_impl @@ -760,22 +760,22 @@ 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_facade's Derived parameter, depending on the iterator concept(s) it will model. The operations in the first column must be made accessible to member functions of class -iterator_core_access. In addition, -static_cast<Derived*>(iterator_facade*) shall be well-formed.
-In the table below, F is iterator_facade<X,V,C,R,D>, a is an -object of type X, b and c are objects of type const X, -n is an object of F::difference_type, y is a constant -object of a single pass iterator type interoperable with X, and z +iterator_core_access. In addition, +static_cast<Derived*>(iterator_facade*) shall be well-formed.
+In the table below, F is iterator_facade<X,V,C,R,D>, a is an +object of type X, b and c are objects of type const X, +n is an object of F::difference_type, y is a constant +object of a single pass iterator type interoperable with X, and z is a constant object of a random access traversal iterator type -interoperable with X.
+interoperable with X.-iterator_facade Core Operations
-+
iterator_facade Core Operations
+
- @@ -791,41 +791,41 @@ Concept(s) c.dereference() -F::reference +- c.dereference() +F::reference Readable Iterator, Writable Iterator c.equal(y) +- c.equal(y) convertible to bool -true iff c and y + true iff c and y refer to the same position. Single Pass Iterator a.increment() +- a.increment() unused Incrementable Iterator a.decrement() +- a.decrement() unused Bidirectional Traversal Iterator a.advance(n) +- a.advance(n) unused Random Access Traversal Iterator c.distance_to(z) +@@ -834,53 +834,53 @@ Iterator c.distance_to(z) convertible to -F::difference_type +F::difference_typeequivalent to -distance(c, X(z)). +distance(c, X(z)).Random Access Traversal Iterator -iterator_facade operations
+iterator_facade operations
The operations in this section are described in terms of operations on -the core interface of Derived which may be inaccessible +the core interface of Derived which may be inaccessible (i.e. private). The implementation should access these operations -through member functions of class iterator_core_access.
-reference operator*() const;
-+through member functions of class iterator_core_access. +
reference operator*() const;
+-
- Returns: static_cast<Derived const*>(this)->dereference() +Returns: static_cast<Derived const*>(this)->dereference() operator->() const; (see below)
-+
operator->() const; (see below)
+-
- Returns: If reference is a reference type, an object -of type pointer equal to:
+Returns: If reference is a reference type, an object +of type pointer equal to:
&static_cast<Derived const*>(this)->dereference()Otherwise returns an object of unspecified type such that, -(*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.
+(*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: an object convertible to value_type. For constant -objects v of type value_type, and n of type -difference_type, (*this)[n] = v is equivalent to -*(*this + n) = v, and static_cast<value_type + Returns: an object convertible to value_type. For constant +objects v of type value_type, and n of type +difference_type, (*this)[n] = v is equivalent to +*(*this + n) = v, and static_cast<value_type const&>((*this)[n]) is equivalent to -static_cast<value_type const&>(*(*this + n)) +static_cast<value_type const&>(*(*this + n))Derived& operator++();
-+
Derived& operator++();
+-
@@ -892,8 +892,8 @@ return *static_cast<Derived*>(this); Derived operator++(int);
-+
Derived operator++(int);
+-
@@ -906,8 +906,8 @@ return tmp; Derived& operator--();
-+
Derived& operator--();
+-
@@ -919,8 +919,8 @@ return *static_cast<Derived*>(this); Derived operator--(int);
-+
Derived operator--(int);
+-
@@ -933,8 +933,8 @@ return tmp; Derived& operator+=(difference_type n);
-+
Derived& operator+=(difference_type n);
+-
@@ -946,8 +946,8 @@ return *static_cast<Derived*>(this); Derived& operator-=(difference_type n);
-+
Derived& operator-=(difference_type n);
+-
@@ -959,8 +959,8 @@ return *static_cast<Derived*>(this); Derived operator-(difference_type n) const;
-+
Derived operator-(difference_type n) const;
+
@@ -981,7 +981,7 @@ 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&); - +
@@ -1000,16 +1000,16 @@ typename enable_if_interoperable<Dr1,Dr2,bool>::type operator ==(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs); - +
- Returns: if is_convertible<Dr2,Dr1>::value
-+
@@ -1022,16 +1022,16 @@ typename enable_if_interoperable<Dr1,Dr2,bool>::type operator !=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs); - Returns: if is_convertible<Dr2,Dr1>::value
+
- then
-- ((Dr1 const&)lhs).equal((Dr2 const&)rhs).
+- ((Dr1 const&)lhs).equal((Dr2 const&)rhs).
- Otherwise,
-- ((Dr2 const&)rhs).equal((Dr1 const&)lhs).
+- ((Dr2 const&)rhs).equal((Dr1 const&)lhs).
+
- Returns: if is_convertible<Dr2,Dr1>::value
-+
@@ -1044,16 +1044,16 @@ typename enable_if_interoperable<Dr1,Dr2,bool>::type operator <(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs); - Returns: if is_convertible<Dr2,Dr1>::value
+
- then
-- !((Dr1 const&)lhs).equal((Dr2 const&)rhs).
+- !((Dr1 const&)lhs).equal((Dr2 const&)rhs).
- Otherwise,
-- !((Dr2 const&)rhs).equal((Dr1 const&)lhs).
+- !((Dr2 const&)rhs).equal((Dr1 const&)lhs).
+
- Returns: if is_convertible<Dr2,Dr1>::value
-+
@@ -1066,16 +1066,16 @@ typename enable_if_interoperable<Dr1,Dr2,bool>::type operator <=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs); - Returns: if is_convertible<Dr2,Dr1>::value
+
- then
-- ((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) < 0.
+- ((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) < 0.
- Otherwise,
-- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) > 0.
+- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) > 0.
+
- Returns: if is_convertible<Dr2,Dr1>::value
-+
@@ -1088,16 +1088,16 @@ typename enable_if_interoperable<Dr1,Dr2,bool>::type operator >(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs); - Returns: if is_convertible<Dr2,Dr1>::value
+
- then
-- ((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) <= 0.
+- ((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) <= 0.
- Otherwise,
-- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) >= 0.
+- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) >= 0.
+
- Returns: if is_convertible<Dr2,Dr1>::value
-+
@@ -1110,16 +1110,16 @@ typename enable_if_interoperable<Dr1,Dr2,bool>::type operator >=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs); - Returns: if is_convertible<Dr2,Dr1>::value
+
- then
-- ((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) > 0.
+- ((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) > 0.
- Otherwise,
-- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) < 0.
+- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) < 0.
+
- Returns: if is_convertible<Dr2,Dr1>::value
-+
@@ -1132,28 +1132,28 @@ typename enable_if_interoperable<Dr1,Dr2,difference>::type operator -(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs); - Returns: if is_convertible<Dr2,Dr1>::value
+
- then
-- ((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) >= 0.
+- ((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) >= 0.
- Otherwise,
-- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) <= 0.
+- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) <= 0.
+
- Return Type: if is_convertible<Dr2,Dr1>::value
+- Return Type: if is_convertible<Dr2,Dr1>::value
-+
- then
-- difference shall be -iterator_traits<Dr1>::difference_type.
+- difference shall be +iterator_traits<Dr1>::difference_type.
- Otherwise
-- difference shall be iterator_traits<Dr2>::difference_type
+- difference shall be iterator_traits<Dr2>::difference_type
Returns: if is_convertible<Dr2,Dr1>::value
-+
@@ -1166,18 +1166,18 @@ operator -(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs, - Returns: if is_convertible<Dr2,Dr1>::value
+
- then
-- -((Dr1 const&)lhs).distance_to((Dr2 const&)rhs).
+- -((Dr1 const&)lhs).distance_to((Dr2 const&)rhs).
- Otherwise,
-- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs).
+- ((Dr2 const&)rhs).distance_to((Dr1 const&)lhs).
Each specialization of the iterator_adaptor class template is derived from -a specialization of iterator_facade. The core interface functions -expected by iterator_facade are implemented in terms of the -iterator_adaptor's Base template parameter. A class derived -from iterator_adaptor typically redefines some of the core -interface functions to adapt the behavior of the Base type. +
Each specialization of the iterator_adaptor class template is derived from +a specialization of iterator_facade. The core interface functions +expected by iterator_facade are implemented in terms of the +iterator_adaptor's Base template parameter. A class derived +from iterator_adaptor typically redefines some of the core +interface functions to adapt the behavior of the Base type. 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.
+depends on the operations supported by the Base type and which +core interface functions of iterator_facade are redefined in the +Derived class.-Class template iterator_adaptor
+Class template iterator_adaptor
@@ -1196,7 +1196,8 @@ class iterator_adaptor friend class iterator_core_access; public: iterator_adaptor(); - explicit iterator_adaptor(Base iter); + explicit iterator_adaptor(Base const& iter); + typedef Base base_type; Base const& base() const; protected: typedef iterator_adaptor iterator_adaptor_; @@ -1226,14 +1227,14 @@ class iterator_adaptor-iterator_adaptor requirements
-static_cast<Derived*>(iterator_adaptor*) shall be well-formed. -The Base argument shall be Assignable and Copy Constructible.
+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 +
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:
V' = if (Value is use_default) @@ -1272,68 +1273,68 @@ expression involving ``Derived`` in those concepts' requirements. -->-iterator_adaptor public operations
-iterator_adaptor();
-+
iterator_adaptor public operations
+iterator_adaptor();
+-
- Requires: The Base type must be Default Constructible. +- Requires: The Base type must be Default Constructible. Returns: An instance of iterator_adaptor with -m_iterator default constructed. +Returns: An instance of iterator_adaptor with +m_iterator default constructed. explicit iterator_adaptor(Base iter);
-+
explicit iterator_adaptor(Base const& iter);
+-
- Returns: An instance of iterator_adaptor with -m_iterator copy constructed from iter. +Returns: An instance of iterator_adaptor with +m_iterator copy constructed from iter. Base const& base() const;
-+
Base const& base() const;
+
- Returns: m_iterator +Returns: m_iterator -iterator_adaptor protected member functions
-Base const& base_reference() const;
-+
iterator_adaptor protected member functions
+Base const& base_reference() const;
+-
- Returns: A const reference to m_iterator. +Returns: A const reference to m_iterator. Base& base_reference();
-+
Base& base_reference();
+
- Returns: A non-const reference to m_iterator. +Returns: A non-const reference to m_iterator. -iterator_adaptor private member functions
-typename iterator_adaptor::reference dereference() const;
-+
iterator_adaptor private member functions
+typename iterator_adaptor::reference dereference() const;
+@@ -1343,38 +1344,38 @@ 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; -
- Returns: *m_iterator +Returns: *m_iterator +
-
- Returns: m_iterator == x.base() +Returns: m_iterator == x.base() void advance(typename iterator_adaptor::difference_type n);
-+
void advance(typename iterator_adaptor::difference_type n);
+-
- Effects: m_iterator += n; +Effects: m_iterator += n; void increment();
-+
void increment();
+-
- Effects: ++m_iterator; +Effects: ++m_iterator; void decrement();
-+
void decrement();
+@@ -1385,11 +1386,11 @@ template < typename iterator_adaptor::difference_type distance_to( iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const; -
- Effects: --m_iterator; +Effects: --m_iterator; +
@@ -1397,13 +1398,13 @@ typename iterator_adaptor::difference_type distance_to(
- Returns: y.base() - m_iterator +Returns: y.base() - m_iterator Specialized adaptors [lib.iterator.special.adaptors]
-The enable_if_convertible<X,Y>::type expression used in +
The enable_if_convertible<X,Y>::type expression used in this section is for exposition purposes. The converting constructors for specialized adaptors should be only be in an overload set provided -that an object of type X is implicitly convertible to an object of -type Y. -The signatures involving enable_if_convertible should behave -as-if enable_if_convertible were defined to be:
+that an object of type X is implicitly convertible to an object of +type Y. +The signatures involving enable_if_convertible should behave +as-if enable_if_convertible were defined to be:template <bool> enable_if_convertible_impl {}; @@ -1418,24 +1419,24 @@ struct enable_if_convertibleIf an expression other than the default argument is used to supply the value of a function parameter whose type is written in terms -of enable_if_convertible, the program is ill-formed, no +of enable_if_convertible, the program is ill-formed, no diagnostic required.
-[Note: The enable_if_convertible approach uses SFINAE to +
[Note: The enable_if_convertible approach uses SFINAE to take the constructor out of the overload set when the types are not implicitly convertible. ]
Indirect iterator
-indirect_iterator adapts an iterator by applying an -extra dereference inside of operator*(). For example, this +
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 -(e.g. list<foo>). indirect_iterator depends on two -auxiliary traits, pointee and indirect_reference, to -provide support for underlying iterators whose value_type is +(e.g. list<foo*>) as if it were a container of the pointed-to type +(e.g. list<foo>). indirect_iterator depends on two +auxiliary traits, pointee and indirect_reference, to +provide support for underlying iterators whose value_type is not an iterator.
-Class template pointee
+Class template pointee
@@ -1446,22 +1447,22 @@ struct pointee typedef /* see below */ type; }; -+
-
- Requires: For an object x of type Dereferenceable, *x -is well-formed. If ++x is ill-formed it shall neither be + Requires: For an object x of type Dereferenceable, *x +is well-formed. If ++x is ill-formed it shall neither be ambiguous nor shall it violate access control, and -Dereferenceable::element_type shall be an accessible type. -Otherwise iterator_traits<Dereferenceable>::value_type shall +Dereferenceable::element_type shall be an accessible type. +Otherwise iterator_traits<Dereferenceable>::value_type shall be well formed. [Note: These requirements need not apply to -explicit or partial specializations of pointee] +explicit or partial specializations of pointee]type is determined according to the following algorithm, where -x is an object of type Dereferenceable:
+type is determined according to the following algorithm, where +x is an object of type Dereferenceable:
if ( ++x is ill-formed ) { @@ -1479,7 +1480,7 @@ else-Class template indirect_reference
+Class template indirect_reference
@@ -1490,22 +1491,22 @@ struct indirect_reference typedef /* see below */ type; }; -+
-
- Requires: For an object x of type Dereferenceable, *x -is well-formed. If ++x is ill-formed it shall neither be + Requires: For an object x of type Dereferenceable, *x +is well-formed. If ++x is ill-formed it shall neither be ambiguous nor shall it violate access control, and -pointee<Dereferenceable>::type& shall be well-formed. -Otherwise iterator_traits<Dereferenceable>::reference shall +pointee<Dereferenceable>::type& shall be well-formed. +Otherwise iterator_traits<Dereferenceable>::reference shall be well formed. [Note: These requirements need not apply to -explicit or partial specializations of indirect_reference] +explicit or partial specializations of indirect_reference]type is determined according to the following algorithm, where -x is an object of type Dereferenceable:
+type is determined according to the following algorithm, where +x is an object of type Dereferenceable:
if ( ++x is ill-formed ) return ``pointee<Dereferenceable>::type&`` @@ -1514,7 +1515,7 @@ else-Class template indirect_iterator
+Class template indirect_iterator
template < class Iterator @@ -1554,9 +1555,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; @@ -1592,64 +1593,64 @@ else-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();
-+
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);
-+
indirect_iterator(Iterator x);
+@@ -1665,54 +1666,54 @@ indirect_iterator( , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition ); -
- 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;
-+
Iterator const& base() const;
+-
- Returns: m_iterator +Returns: m_iterator reference operator*() const;
-+
reference operator*() const;
+-
- Returns: **m_iterator +Returns: **m_iterator indirect_iterator& operator++();
-+
indirect_iterator& operator++();
+-
- Effects: ++m_iterator +- Effects: ++m_iterator Returns: *this +Returns: *this indirect_iterator& operator--();
-+
indirect_iterator& operator--();
+@@ -1723,7 +1724,7 @@ indirect_iterator(
- Effects: --m_iterator +- Effects: --m_iterator Returns: *this +Returns: *this The reverse iterator adaptor iterates through the adapted iterator range in the opposite direction.
-Class template reverse_iterator
+Class template reverse_iterator
template <class Iterator> class reverse_iterator @@ -1751,34 +1752,34 @@ private: Iterator m_iterator; // exposition };-If Iterator models Random Access Traversal Iterator and Readable -Lvalue Iterator, then iterator_category is convertible to -random_access_iterator_tag. Otherwise, if -Iterator models Bidirectional Traversal Iterator and Readable -Lvalue Iterator, then iterator_category is convertible to -bidirectional_iterator_tag. Otherwise, iterator_category is -convertible to input_iterator_tag.
+If Iterator models Random Access Traversal Iterator and Readable +Lvalue Iterator, then iterator_category is convertible to +random_access_iterator_tag. Otherwise, if +Iterator models Bidirectional Traversal Iterator and Readable +Lvalue Iterator, then iterator_category is convertible to +bidirectional_iterator_tag. Otherwise, iterator_category is +convertible to input_iterator_tag.
-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 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
-A specialization of reverse_iterator models the same iterator -traversal and iterator access concepts modeled by its Iterator +
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 specified in the following table:
-+
-
- If I models -then reverse_iterator<I> models +@@ -1800,34 +1801,34 @@ Random Access Traversal Iterator If I models +then reverse_iterator<I> models reverse_iterator<X> is interoperable with -reverse_iterator<Y> if and only if X is interoperable with -Y.
+reverse_iterator<X> is interoperable with +reverse_iterator<Y> if and only if X is interoperable with +Y.
-reverse_iterator operations
+reverse_iterator operations
In addition to the operations required by the concepts modeled by -reverse_iterator, reverse_iterator provides the following +reverse_iterator, reverse_iterator provides the following operations.
-reverse_iterator();
-+
reverse_iterator();
+-
- Requires: Iterator must be Default Constructible. +- Requires: Iterator must be Default Constructible. Effects: Constructs an instance of reverse_iterator with m_iterator + Effects: Constructs an instance of reverse_iterator with m_iterator default constructed. explicit reverse_iterator(Iterator x);
-+
explicit reverse_iterator(Iterator x);
+@@ -1838,28 +1839,28 @@ reverse_iterator( , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition ); -
- Effects: Constructs an instance of reverse_iterator with -m_iterator copy constructed from x. +Effects: Constructs an instance of reverse_iterator with +m_iterator copy constructed from x. +
-
- Requires: OtherIterator is implicitly convertible to Iterator. +- Requires: OtherIterator is implicitly convertible to Iterator. Effects: Constructs instance of reverse_iterator whose -m_iterator subobject is constructed from y.base(). +Effects: Constructs instance of reverse_iterator whose +m_iterator subobject is constructed from y.base(). Iterator const& base() const;
-+
Iterator const& base() const;
+-
- Returns: m_iterator +Returns: m_iterator reference operator*() const;
-+
reference operator*() const;
+
@@ -1871,25 +1872,25 @@ reverse_iterator( Iterator tmp = m_iterator; return *--tmp; - reverse_iterator& operator++();
-+
reverse_iterator& operator++();
+-
- Effects: --m_iterator +- Effects: --m_iterator Returns: *this +Returns: *this reverse_iterator& operator--();
-+
reverse_iterator& operator--();
+@@ -1898,10 +1899,10 @@ return *--tmp;
- Effects: ++m_iterator +- Effects: ++m_iterator Returns: *this +Returns: *this Transform iterator
The transform iterator adapts an iterator by modifying the -operator* to apply a function object to the result of +operator* to apply a function object to the result of dereferencing the iterator and returning the result.
-Class template transform_iterator
+Class template transform_iterator
template <class UnaryFunction, @@ -1936,56 +1937,56 @@ private: UnaryFunction m_f; // exposition only };-If Reference is use_default then the reference member of -transform_iterator is -result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type. -Otherwise, reference is Reference.
-If Value is use_default then the value_type member is -remove_cv<remove_reference<reference> >::type. Otherwise, -value_type is Value.
-If Iterator models Readable Lvalue Iterator and if Iterator -models Random Access Traversal Iterator, then iterator_category is -convertible to random_access_iterator_tag. Otherwise, if -Iterator models Bidirectional Traversal Iterator, then -iterator_category is convertible to -bidirectional_iterator_tag. Otherwise iterator_category is -convertible to forward_iterator_tag. If Iterator does not -model Readable Lvalue Iterator then iterator_category is -convertible to input_iterator_tag.
+If Reference is use_default then the reference member of +transform_iterator is +result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type. +Otherwise, reference is Reference.
+If Value is use_default then the value_type member is +remove_cv<remove_reference<reference> >::type. Otherwise, +value_type is Value.
+If Iterator models Readable Lvalue Iterator and if Iterator +models Random Access Traversal Iterator, then iterator_category is +convertible to random_access_iterator_tag. Otherwise, if +Iterator models Bidirectional Traversal Iterator, then +iterator_category is convertible to +bidirectional_iterator_tag. Otherwise iterator_category is +convertible to forward_iterator_tag. If Iterator does not +model Readable Lvalue Iterator then iterator_category is +convertible to input_iterator_tag.
-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 -where the type of f(*i) must be -result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type.
-The argument Iterator shall model Readable Iterator.
+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 +where the type of f(*i) must be +result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type.
+The argument Iterator shall model Readable Iterator.
-transform_iterator models
-The resulting transform_iterator models the most refined of the -following that is also modeled by Iterator.
+transform_iterator models
+The resulting transform_iterator models the most refined of the +following that is also modeled by Iterator.
--
- Writable Lvalue Iterator if transform_iterator::reference is a non-const reference.
-- Readable Lvalue Iterator if transform_iterator::reference is a const reference.
+- Writable Lvalue Iterator if transform_iterator::reference is a non-const reference.
+- Readable Lvalue Iterator if transform_iterator::reference is a const reference.
- Readable Iterator otherwise.
The transform_iterator models the most refined standard traversal -concept that is modeled by the Iterator argument.
-If transform_iterator is a model of Readable Lvalue Iterator then +
The transform_iterator models the most refined standard traversal +concept that is modeled by the Iterator argument.
+If transform_iterator is a model of Readable Lvalue Iterator then it models the following original iterator concepts depending on what -the Iterator argument models.
-+the Iterator argument models. +
-
- If Iterator models -then transform_iterator models +@@ -2003,34 +2004,34 @@ the Iterator argument models.< If Iterator models +then transform_iterator models If transform_iterator models Writable Lvalue Iterator then it is a +
If transform_iterator models Writable Lvalue Iterator then it is a mutable iterator (as defined in the old iterator requirements).
-transform_iterator<F1, X, R1, V1> is interoperable with -transform_iterator<F2, Y, R2, V2> if and only if X is -interoperable with Y.
+transform_iterator<F1, X, R1, V1> is interoperable with +transform_iterator<F2, Y, R2, V2> if and only if X is +interoperable with Y.
-transform_iterator operations
+transform_iterator operations
In addition to the operations required by the concepts modeled by -transform_iterator, transform_iterator provides the following +transform_iterator, transform_iterator provides the following operations.
-transform_iterator();
-+
transform_iterator();
+-
- Returns: An instance of transform_iterator with m_f -and m_iterator default constructed. +Returns: An instance of transform_iterator with m_f +and m_iterator default constructed. transform_iterator(Iterator const& x, UnaryFunction f);
-+
transform_iterator(Iterator const& x, UnaryFunction f);
+@@ -2042,64 +2043,64 @@ transform_iterator( , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only ); -
- Returns: An instance of transform_iterator with m_f -initialized to f and m_iterator initialized to x. +Returns: An instance of transform_iterator with m_f +initialized to f and m_iterator initialized to x. +
-
- Returns: An instance of transform_iterator with m_f -initialized to t.functor() and m_iterator initialized to -t.base(). +- Returns: An instance of transform_iterator with m_f +initialized to t.functor() and m_iterator initialized to +t.base(). Requires: OtherIterator is implicitly convertible to Iterator. +Requires: OtherIterator is implicitly convertible to Iterator. UnaryFunction functor() const;
-+
UnaryFunction functor() const;
+-
- Returns: m_f +Returns: m_f Iterator const& base() const;
-+
Iterator const& base() const;
+-
- Returns: m_iterator +Returns: m_iterator reference operator*() const;
-+
reference operator*() const;
+-
- Returns: m_f(*m_iterator) +Returns: m_f(*m_iterator) transform_iterator& operator++();
-+
transform_iterator& operator++();
+-
- Effects: ++m_iterator +- Effects: ++m_iterator Returns: *this +Returns: *this transform_iterator& operator--();
-+
transform_iterator& operator--();
+@@ -2110,15 +2111,15 @@ initialized to t.functor() and
- Effects: --m_iterator +- Effects: --m_iterator Returns: *this +Returns: *this 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 of iterators indicating the range of elements in the unfiltered sequence to be traversed.
-Class template filter_iterator
+Class template filter_iterator
@@ -2153,35 +2154,39 @@ private: Iterator m_end; // exposition only }; -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 +@@ -2191,16 +2196,19 @@ following tables. If Iterator models +then filter_iterator models + Forward Traversal Iterator Forward Traversal Iterator Bidirectional Traversal Iterator +Bidirectional Traversal Iterator ++
-
- If Iterator models -then filter_iterator models +@@ -2215,14 +2223,14 @@ following tables. If Iterator models +then filter_iterator models +
-
- If Iterator models -then filter_iterator models +@@ -2235,51 +2243,54 @@ following tables. If Iterator models +then filter_iterator models + Writable Lvalue Iterator, Forward Traversal Iterator Mutable Forward Iterator Writable Lvalue Iterator, Bidirectional Iterator +Mutable Bidirectional Iterator +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();
-+
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());
-+
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());
-+
filter_iterator(Iterator x, Iterator end = Iterator());
+@@ -2290,62 +2301,62 @@ filter_iterator( , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition );`` -
- 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;
-+
Predicate predicate() const;
+-
- Returns: m_pred +Returns: m_pred Iterator end() const;
-+
Iterator end() const;
+-
- Returns: m_end +Returns: m_end Iterator const& base() const;
-+
Iterator const& base() const;
+-
- Returns: m_iterator +Returns: m_iterator reference operator*() const;
-+
reference operator*() const;
+-
- Returns: *m_iter +Returns: *m_iter filter_iterator& operator++();
-+
filter_iterator& operator++();
+@@ -2353,11 +2364,11 @@ or m_pred(*m_iter)
- 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 Counting iterator
-counting_iterator adapts an object by adding an operator* that +
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 @@ -2384,10 +2395,10 @@ private: Incrementable m_inc; // exposition };-If the Difference argument is use_default then -difference_type is an unspecified signed integral -type. Otherwise difference_type is Difference.
-iterator_category is determined according to the following +
If the Difference argument is use_default then +difference_type is an unspecified signed integral +type. Otherwise difference_type is Difference.
+iterator_category is determined according to the following algorithm:
if (CategoryOrTraversal is not use_default) @@ -2400,31 +2411,31 @@ else iterator_traversal<Incrementable>::type, Incrementable, const Incrementable&)-+
- [Note: implementers are encouraged to provide an implementation of
-- operator- and a difference_type that avoids overflows in -the cases where std::numeric_limits<Incrementable>::is_specialized +
- operator- and a difference_type that avoids overflows in +the cases where std::numeric_limits<Incrementable>::is_specialized is true.]
-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:
+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:
Incrementable i, j; ++i; // pre-increment i == j; // operator equal-If iterator_category is convertible to -bidirectional_iterator_tag or bidirectional_traversal_tag, +
If iterator_category is convertible to +bidirectional_iterator_tag or bidirectional_traversal_tag, the following expression must also be well-formed:
--i-If iterator_category is convertible to -random_access_iterator_tag or random_access_traversal_tag, +
If iterator_category is convertible to +random_access_iterator_tag or random_access_traversal_tag, the following must must also be valid:
counting_iterator::difference_type n; @@ -2434,92 +2445,92 @@ i < j;-counting_iterator models
-Specializations of counting_iterator model Readable Lvalue +
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. -Also, if CategoryOrTraversal is not use_default then -counting_iterator models the concept corresponding to the iterator -tag CategoryOrTraversal. Otherwise, if -numeric_limits<Incrementable>::is_specialized, then -counting_iterator models Random Access Traversal Iterator. -Otherwise, counting_iterator models the same iterator traversal -concepts modeled by Incrementable.
-counting_iterator<X,C1,D1> is interoperable with -counting_iterator<Y,C2,D2> if and only if X is -interoperable with Y.
+iterator tags to which their iterator_category is convertible. +Also, if CategoryOrTraversal is not use_default then +counting_iterator models the concept corresponding to the iterator +tag CategoryOrTraversal. Otherwise, if +numeric_limits<Incrementable>::is_specialized, then +counting_iterator models Random Access Traversal Iterator. +Otherwise, counting_iterator models the same iterator traversal +concepts modeled by Incrementable. +counting_iterator<X,C1,D1> is interoperable with +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 +counting_iterator, counting_iterator provides the following operations.
-counting_iterator();
-+
counting_iterator();
+-
- Requires: Incrementable is Default Constructible. +- Requires: Incrementable is Default Constructible. Effects: Default construct the member m_inc. +Effects: Default construct the member m_inc. counting_iterator(counting_iterator const& rhs);
-+
counting_iterator(counting_iterator const& rhs);
+-
- Effects: Construct member m_inc from rhs.m_inc. +Effects: Construct member m_inc from rhs.m_inc. explicit counting_iterator(Incrementable x);
-+
explicit counting_iterator(Incrementable x);
+-
- Effects: Construct member m_inc from x. +Effects: Construct member m_inc from x. reference operator*() const;
-+
reference operator*() const;
+-
- Returns: m_inc +Returns: m_inc counting_iterator& operator++();
-+
counting_iterator& operator++();
+-
- Effects: ++m_inc +- Effects: ++m_inc Returns: *this +Returns: *this counting_iterator& operator--();
-+
counting_iterator& operator--();
+-
- Effects: --m_inc +- Effects: --m_inc Returns: *this +Returns: *this Incrementable const& base() const;
-+
Incrementable const& base() const;
+@@ -2535,7 +2546,7 @@ iterator is that creating a conforming output iterator is non-trivial, particularly because the proper implementation usually requires a proxy object.
- Returns: m_inc +Returns: m_inc -Class template function_output_iterator
+Class template function_output_iterator
template <class UnaryFunction> class function_output_iterator { @@ -2559,51 +2570,51 @@ private:-function_output_iterator requirements
-UnaryFunction must be Assignable and Copy Constructible.
+function_output_iterator requirements
+UnaryFunction must be Assignable and Copy Constructible.
-function_output_iterator models
-function_output_iterator is a model of the Writable and +
function_output_iterator models
+function_output_iterator is a model of the Writable and Incrementable Iterator concepts.
-function_output_iterator operations
-explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
-+
function_output_iterator operations
+explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
+-
- Effects: Constructs an instance of function_output_iterator -with m_f constructed from f. +Effects: Constructs an instance of function_output_iterator +with m_f constructed from f. operator*();
-+
operator*();
+-
- Returns: An object r of unspecified type such that r = t -is equivalent to m_f(t) for all t. +Returns: An object r of unspecified type such that r = t +is equivalent to m_f(t) for all t. function_output_iterator& operator++();
-+
function_output_iterator& operator++();
+-
- Returns: *this +Returns: *this function_output_iterator& operator++(int);
-+
function_output_iterator& operator++(int);
+@@ -2618,7 +2629,7 @@ LocalWords: OtherIncrementable Coplien --> -
- Returns: *this +Returns: *this
+
View document source. Generated by Docutils from reStructuredText source. diff --git a/doc/facade-and-adaptor.pdf b/doc/facade-and-adaptor.pdf index e484a71..7bf3472 100755 Binary files a/doc/facade-and-adaptor.pdf and b/doc/facade-and-adaptor.pdf differ diff --git a/doc/function_output_iterator.html b/doc/function_output_iterator.html index be94d79..7c9486d 100644 --- a/doc/function_output_iterator.html +++ b/doc/function_output_iterator.html @@ -3,7 +3,7 @@ - +Function Output Iterator @@ -12,6 +12,7 @@ +Function Output Iterator
-
@@ -31,8 +32,7 @@ Railway Operation and Construction Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -+
@@ -49,9 +49,9 @@ proxy object. @@ -77,51 +77,51 @@ private: };-function_output_iterator requirements
-UnaryFunction must be Assignable and Copy Constructible.
+function_output_iterator requirements
+UnaryFunction must be Assignable and Copy Constructible.
-function_output_iterator models
-function_output_iterator is a model of the Writable and +
function_output_iterator models
+function_output_iterator is a model of the Writable and Incrementable Iterator concepts.
-function_output_iterator operations
-explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
-+
function_output_iterator operations
+explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
+-
- Effects: Constructs an instance of function_output_iterator -with m_f constructed from f. +Effects: Constructs an instance of function_output_iterator +with m_f constructed from f. operator*();
-+
operator*();
+-
- Returns: An object r of unspecified type such that r = t -is equivalent to m_f(t) for all t. +Returns: An object r of unspecified type such that r = t +is equivalent to m_f(t) for all t. function_output_iterator& operator++();
-+
function_output_iterator& operator++();
+-
- Returns: *this +Returns: *this function_output_iterator& operator++(int);
-+
function_output_iterator& operator++(int);
+@@ -162,7 +162,7 @@ int main(int, char*[]) -
- Returns: *this +Returns: *this
+
View document source. Generated by Docutils from reStructuredText source. diff --git a/doc/function_output_iterator.pdf b/doc/function_output_iterator.pdf index e14507b..c6538ea 100755 Binary files a/doc/function_output_iterator.pdf and b/doc/function_output_iterator.pdf differ diff --git a/doc/index.html b/doc/index.html index 2641959..0868477 100755 --- a/doc/index.html +++ b/doc/index.html @@ -3,15 +3,15 @@ - +The Boost.Iterator Library Boost -The Boost.Iterator Library
-
-+
The Boost.Iterator Library
+
+-
@@ -28,7 +28,7 @@ Lab, Zephyr Associat +
@@ -65,7 +65,7 @@ older Boost Iterator Adaptor Library. - History
-
+
@@ -146,12 +146,12 @@ positions of heterogeneous underlying iterators.New-Style Iterators
The iterator categories defined in C++98 are extremely limiting @@ -73,12 +73,12 @@ because they bind together two orthogonal concepts: traversal and element access. For example, because a random access iterator is required to return a reference (and not a proxy) when dereferenced, it is impossible to capture the capabilities of -vector<bool>::iterator using the C++98 categories. This is the -infamous "vector<bool> is not a container, and its iterators +vector<bool>::iterator using the C++98 categories. This is the +infamous "vector<bool> is not a container, and its iterators aren't random access iterators", debacle about which Herb Sutter wrote two papers for the standards comittee (n1185 and n1211), and a Guru of the Week. New-style iterators go well beyond -patching up vector<bool>, though: there are lots of other +patching up vector<bool>, though: there are lots of other iterators already in use which can't be adequately represented by the existing concepts. For details about the new iterator concepts, see our
@@ -89,23 +89,23 @@ concepts, see ourIterator 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, +the Boost.Iterator library provides the iterator_facade class template, which implements many useful defaults and compile-time checks designed to help the iterator author ensure that his iterator is correct.
It is also common to define a new iterator that is similar to some underlying iterator or iterator-like type, but that modifies some aspect of the underlying type's behavior. For that purpose, the -library supplies the iterator_adaptor class template, which is specially +library supplies the iterator_adaptor class template, which is specially designed to take advantage of as much of the underlying type's behavior as possible.
The documentation for these two classes can be found at the following web pages:
-
-- iterator_facade (PDF)
-- iterator_adaptor (PDF)
+- iterator_facade (PDF)
+- iterator_adaptor (PDF)
Both iterator_facade and iterator_adaptor as well as many of the specialized +
Both iterator_facade and iterator_adaptor as well as many of the specialized adaptors mentioned below have been proposed for standardization, and accepted into the first C++ technical report; see our
@@ -117,27 +117,27 @@ and accepted into the first C++ technical report; see ourThe iterator library supplies a useful suite of standard-conforming iterator templates based on the Boost iterator facade and adaptor.
-
- counting_iterator (PDF): an iterator over a sequence of consecutive values. +
- counting_iterator (PDF): an iterator over a sequence of consecutive values. Implements a "lazy sequence"
-- filter_iterator (PDF): an iterator over the subset of elements of some +
- filter_iterator (PDF): an iterator over the subset of elements of some sequence which satisfy a given predicate
-- function_output_iterator (PDF): an output iterator wrapping a unary function +
- function_output_iterator (PDF): an output iterator wrapping a unary function object; each time an element is written into the dereferenced iterator, it is passed as a parameter to the function object.
-- indirect_iterator (PDF): an iterator over the objects pointed-to by the +
- indirect_iterator (PDF): an iterator over the objects pointed-to by the elements of some sequence.
-- permutation_iterator (PDF): an iterator over the elements of some random-access +
- permutation_iterator (PDF): an iterator over the elements of some random-access sequence, rearranged according to some sequence of integer indices.
-- reverse_iterator (PDF): an iterator which traverses the elements of some +
- reverse_iterator (PDF): an iterator which traverses the elements of some bidirectional sequence in reverse. Corrects many of the -shortcomings of C++98's std::reverse_iterator.
-- shared_container_iterator: an iterator over elements of a container whose -lifetime is maintained by a shared_ptr stored in the iterator.
-- transform_iterator (PDF): an iterator over elements which are the result of +shortcomings of C++98's std::reverse_iterator.
+- shared_container_iterator: an iterator over elements of a container whose +lifetime is maintained by a shared_ptr stored in the iterator.
+- transform_iterator (PDF): an iterator over elements which are the result of applying some functional transformation to the elements of an underlying sequence. This component also replaces the old -projection_iterator_adaptor.
-- zip_iterator (PDF): an iterator over tuples of the elements at corresponding +projection_iterator_adaptor.
+- zip_iterator (PDF): an iterator over tuples of the elements at corresponding positions of heterogeneous underlying iterators.
Traits
-
@@ -160,35 +160,35 @@ testing iterator interoperability -->- pointee.hpp (PDF): Provides the capability to deduce the referent types +
- pointee.hpp (PDF): Provides the capability to deduce the referent types of pointers, smart pointers and iterators in generic code. Used -in indirect_iterator.
-- iterator_traits.hpp (PDF): Provides MPL-compatible metafunctions which +in indirect_iterator.
+- iterator_traits.hpp (PDF): Provides MPL-compatible metafunctions which retrieve an iterator's traits. Also corrects for the deficiencies -of broken implementations of std::iterator_traits.
+of broken implementations of std::iterator_traits.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.
+- 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 -implement iterators, you probably wrote a Policies class which +implement iterators, you probably wrote a Policies class which captures the core operations of your iterator. In the new library design, you'll move those same core operations into the body of the iterator class itself. If you were writing a family of iterators, you probably wrote a type generator to build the -iterator_adaptor specialization you needed; in the new library +iterator_adaptor specialization you needed; in the new library design you don't need a type generator (though may want to keep it around as a compatibility aid for older code) because, due to the use of the Curiously Recurring Template Pattern (CRTP) [Cop95], you can now define the iterator class yourself and acquire -functionality through inheritance from iterator_facade or -iterator_adaptor. As a result, you also get much finer control +functionality through inheritance from iterator_facade or +iterator_adaptor. As a result, you also get much finer control over how your iterator works: you can add additional constructors, or even override the iterator functionality provided by the library.
-If you're looking for the old projection_iterator component, -its functionality has been merged into transform_iterator: as -long as the function object's result_type (or the Reference +
If you're looking for the old projection_iterator component, +its functionality has been merged into transform_iterator: as +long as the function object's result_type (or the Reference template argument, if explicitly specified) is a true reference -type, transform_iterator will behave like -projection_iterator used to.
+type, transform_iterator will behave like +projection_iterator used to.History
@@ -212,11 +212,11 @@ policies into the iterator class itself. Thomas Witt expressed interest and became the voice of strict compile-time checking for the project, adding uses of the SFINAE technique to eliminate false converting constructors and operators from the overload set. He -also recognized the need for a separate iterator_facade, and -factored it out of iterator_adaptor. Finally, after a +also recognized the need for a separate iterator_facade, and +factored it out of iterator_adaptor. Finally, after a near-complete rewrite of the prototype, they came up with the library you see today. -+
[Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template @@ -232,7 +232,7 @@ LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct LocalWords: TraversalTag typename lvalues DWA Hmm JGS --> -
+
