diff --git a/doc/facade-and-adaptor.html b/doc/facade-and-adaptor.html index 49efb2e..a8f2a09 100755 --- a/doc/facade-and-adaptor.html +++ b/doc/facade-and-adaptor.html @@ -8,7 +8,6 @@ -
filter_iterator requirements
-The base Iterator parameter must be a model of Readable Iterator -and Single Pass Iterator. The resulting filter_iterator will be a -model of Forward Traversal Iterator if Iterator is, otherwise the -filter_iterator will be a model of Single Pass Iterator. The -access category of the filter_iterator will be the most refined -standard access category that is modeled by Iterator.
+The base Iterator parameter must be a model of Readable +Iterator and Single Pass Iterator. The resulting +filter_iterator will be a model of Forward Traversal Iterator +if Iterator is, otherwise the filter_iterator will be a +model of Single Pass Iterator. The access category of the +filter_iterator will be the same as the access category of +Iterator.
The Predicate must be Assignable, Copy Constructible, and the @@ -189,7 +381,7 @@ filter_iterator(
diff --git a/doc/function_output_iterator.html b/doc/function_output_iterator.html index 90e2d2f..8af8f32 100644 --- a/doc/function_output_iterator.html +++ b/doc/function_output_iterator.html @@ -9,7 +9,198 @@ - +
diff --git a/doc/index.html b/doc/index.html index 3dfe4a0..b3a3a14 100755 --- a/doc/index.html +++ b/doc/index.html @@ -4,12 +4,203 @@ -
The Boost Iterator Library 
+The Boost.Iterator Library
| Abstract: | The Boost Iterator Library contains two parts. The first is a system of concepts which extend the C++ standard -iterator requirements. The second is a framework -of components for building iterators based on these +iterator requirements. The second is a framework of +components for building iterators based on these extended concepts and includes several useful iterator -adaptors. The extended iterator concepts have -been carefully designed so that new-style iterators will be -compatible with old-style algorithms, though algorithms may -need to be updated if they want to take full advantage of -the new-style iterators. Several components of this -library have been proposed for the C++ standard technical -report. The components of the Boost Iterator Library -replace the older Boost Iterator Adaptor Library. | +adaptors. The extended iterator concepts have been +carefully designed so that so that old-style iterators +can fit in the new concepts and so that new-style +iterators will be compatible with old-style algorithms, +though algorithms may need to be updated if they want to +take full advantage of the new-style iterator +capabilities. Several components of this library have +been accepted into the C++ standard technical report. +The components of the Boost Iterator Library replace the +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,26 +278,26 @@ concepts, see our
Standard Proposal For New-Style IteratorsIterator Facade and Adaptor
-Writing standard-conforming iterators is tricky. In order to ease the -implementation of new iterators, the iterator library provides the -iterator_facade class template, which implements many useful -defaults and compile-time checks designed to help the author iterator -ensure that his iterator is correct. It is common to define a new -iterator which behaves like another iterator, but modifies some aspect -of its behavior. For that purpose, the library supplies the -iterator_adaptor class template, which is specially designed to -take advantage of as much of the underlying iterator's behavior as -possible.
-Both iterator_facade and iterator_adaptor as well as many of -the specialized adaptors mentioned below have been proposed for -standardization; see our
+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, +which implements many useful defaults and compile-time checks +designed to help the author iterator ensure that his iterator is +correct. It is common to define a new iterator which behaves like +another iterator, but which modifies some aspect of its behavior. +For that purpose, the library supplies the iterator_adaptor class +template, which is specially designed to take advantage of as much +of the underlying iterator's behavior as possible.
+Both iterator_facade and iterator_adaptor as well as many of the specialized +adaptors mentioned below have been proposed for standardization, +and accepted into the first C++ technical report; see our
Standard Proposal For Iterator Facade and Adaptor
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.
-
@@ -126,9 +319,9 @@ underlying sequence. This component also replaces the old
Iterator Utilities
+Iterator Utilities
Traits
+Traits
- iterator_traits.hpp: Provides MPL-compatible metafunctions which retrieve an iterator's traits. Also corrects for the deficiencies @@ -138,7 +331,7 @@ testing iterator interoperability
Testing and Concept Checking
+Testing and Concept Checking
- iterator_archetypes.hpp: Add summary here
- iterator_concepts.hpp: Add summary @@ -146,13 +339,32 @@ testing iterator interoperability
Upgrading from the old Boost Iterator Adaptor Library
-Turn your policy class into the body of the iterator
-Use transform_iterator with a true reference type for -projection_iterator.
+Upgrading from the old Boost Iterator Adaptor Library
+If you have been using the old Boost Iterator Adaptor library to +implement iterators, you probably wrote a Policies class which +captures the core operations of your iterator. In the new library +design, you'll move those same core operations into the body of the +iterator class itself. If you were writing a family of iterators, +you probably wrote a type generator to build the +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 +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 +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 @@ -165,10 +377,26 @@ library and they worked together to produce a "Boostified" version, which was reviewed and accepted into the library. They wrote a paper and made several important revisions of the code.
Eventually, several shortcomings of the older library began to make -the need for a rewrite apparent. Dave and Jeremy started working at -the Santa Cruz C++ committee meeting in 2002, and had quickly -generated a working prototype. Thomas Witt expressed interest and -became the voice of compile-time checking for the project...
+the need for a rewrite apparent. Dave and Jeremy started working +at the Santa Cruz C++ committee meeting in 2002, and had quickly +generated a working prototype. At the urging of Mat Marcus, they +decided to use the GenVoca/CRTP pattern approach, and moved the +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 +near-complete rewrite of the prototype, they came up with the +library you see today. +| [Cop95] | [Coplien, 1995] Coplien, J., Curiously Recurring Template +Patterns, C++ Report, February 1995, pp. 24-27. |
diff --git a/doc/index.rst b/doc/index.rst index 13da6f7..d25bad7 100755 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,5 +1,5 @@ +++++++++++++++++++++++++++++++++++++++++++++++++ - The Boost Iterator Library |(logo)|__ + The Boost.Iterator Library |(logo)|__ +++++++++++++++++++++++++++++++++++++++++++++++++ .. |(logo)| image:: ../../../c++boost.gif @@ -25,17 +25,19 @@ __ ../../../index.htm :Abstract: The Boost Iterator Library contains two parts. The first is a system of concepts_ which extend the C++ standard - iterator requirements. The second is a framework - of components for building iterators based on these + iterator requirements. The second is a framework of + components for building iterators based on these extended concepts and includes several useful iterator - adaptors. The extended iterator concepts have - been carefully designed so that new-style iterators will be - compatible with old-style algorithms, though algorithms may - need to be updated if they want to take full advantage of - the new-style iterators. Several components of this - library have been proposed for the C++ standard technical - report. The components of the Boost Iterator Library - replace the older Boost Iterator Adaptor Library. + adaptors. The extended iterator concepts have been + carefully designed so that so that old-style iterators + can fit in the new concepts and so that new-style + iterators will be compatible with old-style algorithms, + though algorithms may need to be updated if they want to + take full advantage of the new-style iterator + capabilities. Several components of this library have + been accepted into the C++ standard technical report. + The components of the Boost Iterator Library replace the + older Boost Iterator Adaptor Library. .. _concepts: ../../../more/generic_programming.html#concept @@ -77,25 +79,25 @@ __ new-iter-concepts.html Iterator Facade and Adaptor ============================= -Writing standard-conforming iterators is tricky. In order to ease the -implementation of new iterators, the iterator library provides the -|facade|_ class template, which implements many useful -defaults and compile-time checks designed to help the author iterator -ensure that his iterator is correct. It is common to define a new -iterator which behaves like another iterator, but modifies some aspect -of its behavior. For that purpose, the library supplies the -|adaptor|_ class template, which is specially designed to -take advantage of as much of the underlying iterator's behavior as -possible. +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 |facade|_ class template, +which implements many useful defaults and compile-time checks +designed to help the author iterator ensure that his iterator is +correct. It is common to define a new iterator which behaves like +another iterator, but which modifies some aspect of its behavior. +For that purpose, the library supplies the |adaptor|_ class +template, which is specially designed to take advantage of as much +of the underlying iterator's behavior as possible. .. |facade| replace:: ``iterator_facade`` .. _facade: iterator_facade.html .. |adaptor| replace:: ``iterator_adaptor`` .. _adaptor: iterator_adaptor.html -Both |facade|_ and |adaptor|_ as well as many of -the `specialized adaptors`_ mentioned below have been proposed for -standardization; see our +Both |facade|_ and |adaptor|_ as well as many of the `specialized +adaptors`_ mentioned below have been proposed for standardization, +and accepted into the first C++ technical report; see our `Standard Proposal For Iterator Facade and Adaptor`__ @@ -189,10 +191,33 @@ Testing and Concept Checking Upgrading from the old Boost Iterator Adaptor Library ======================================================= -Turn your policy class into the body of the iterator +.. _Upgrading: -Use transform_iterator with a true reference type for -projection_iterator. +If you have been using the old Boost Iterator Adaptor library to +implement iterators, you probably wrote a ``Policies`` class which +captures the core operations of your iterator. In the new library +design, you'll move those same core operations into the body of the +iterator class itself. If you were writing a family of iterators, +you probably wrote a `type generator`_ to build the +``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 +over how your iterator works: you can add additional constructors, +or even override the iterator functionality provided by the +library. + +.. _`type generator`: ../../../more/generic_programming.html#type_generator + +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. ========= History @@ -211,10 +236,21 @@ which was reviewed and accepted into the library. They wrote a paper and made several important revisions of the code. Eventually, several shortcomings of the older library began to make -the need for a rewrite apparent. Dave and Jeremy started working at -the Santa Cruz C++ committee meeting in 2002, and had quickly -generated a working prototype. Thomas Witt expressed interest and -became the voice of compile-time checking for the project... +the need for a rewrite apparent. Dave and Jeremy started working +at the Santa Cruz C++ committee meeting in 2002, and had quickly +generated a working prototype. At the urging of Mat Marcus, they +decided to use the GenVoca/CRTP pattern approach, and moved the +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 +near-complete rewrite of the prototype, they came up with the +library you see today. + +.. [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template + Patterns, C++ Report, February 1995, pp. 24-27. .. LocalWords: Abrahams Siek Witt const bool Sutter's WG int UL LI href Lvalue diff --git a/doc/indirect_iterator.html b/doc/indirect_iterator.html index fafefb5..7365fc8 100644 --- a/doc/indirect_iterator.html +++ b/doc/indirect_iterator.html @@ -9,7 +9,198 @@ - +
The Reference parameter will be the reference type of the indirect_iterator. The default is Value&.
-The Category parameter is the iterator_category type for the -indirect_iterator. The default is -iterator_traits<Iterator>::iterator_category.
+The Access and Traversal parameters are passed unchanged to +the corresponding parameters of the iterator_adaptor base +class, and the Iterator parameter is passed unchanged as the +Base parameter to the iterator_adaptor base class.
The indirect iterator will model the most refined standard traversal concept that is modeled by the Iterator type. The indirect iterator will model the most refined standard access concept that is @@ -137,12 +330,12 @@ the iterator_adaptor subobject
template <
- class Iterator2, class Value2, class Category2
+ class Iterator2, class Value2, unsigned Access, class Traversal
, class Reference2, class Difference2
>
indirect_iterator(
indirect_iterator<
- Iterator2, Value2, Category2, Reference2, Difference2
+ Iterator2, Value2, Access, Traversal, Reference2, Difference2
> const& y
, typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
);
@@ -162,7 +355,7 @@ indirect_iterator(
diff --git a/doc/iterator_adaptor.html b/doc/iterator_adaptor.html
index ec328a9..4d39ff1 100644
--- a/doc/iterator_adaptor.html
+++ b/doc/iterator_adaptor.html
@@ -9,7 +9,198 @@
-
+
@@ -40,8 +231,12 @@ Railway Operation and Construction
-The iterator_adaptor is a base class template derived from an
-instantiation of iterator_facade. The core interface functions
+
+
+
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
@@ -55,16 +250,21 @@ core interface functions of iterator_facad
- Introduction
- Reference
-- iterator_adaptor requirements
-- iterator_adaptor public operations
-- iterator_adaptor protected member functions
-- iterator_adaptor private member functions
+- iterator_adaptor base class parameters
+- iterator_adaptor usage
+- iterator_adaptor public operations
+- iterator_adaptor protected member functions
+- iterator_adaptor private member functions
Introduction
+
+
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
@@ -87,31 +287,36 @@ above. The Base type need not
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 derived class.
-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 the user wants to specify a parameter later in the
-parameter list. Also, the defaults for the corresponding associated
-types are fairly complicated, so metaprogramming is required to
-compute them, and use_default can help to simplify the
-implementation. Finally, use_default is not left unspecified
+
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
template parameter may not always be identical to the iterator's
-reference type, and will keep users making mistakes based on that
-assumption.
+reference type, and will keep users from making mistakes based on
+that assumption.
Reference
+
+
template <
class Derived
, class Base
- , class Value = use_default
- , class Category = use_default
+ , class Value = use_default
+ , class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
class iterator_adaptor
- : public iterator_facade<Derived, /* see details ...*/>
+ : public iterator_facade<Derived, V, C, R, D> // see details
{
friend class iterator_core_access;
public:
@@ -140,68 +345,53 @@ class iterator_adaptor
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
private:
- Base m_iterator;
+ Base m_iterator; // exposition only
};
-
-iterator_adaptor requirements
-The Derived template parameter must be a derived class of
-iterator_adaptor. The Base type must implement the
-expressions involving m_iterator in the specifications of those
-private member functions of iterator_adaptor that are not
-redefined by the Derived class and that are needed to model the
-concept corresponding to the iterator_adaptor's category
-typedef according to the requirements of iterator_facade. The
-rest of the template parameters specify the types for the member
-typedefs in iterator_facade. The following pseudo-code
-specifies the traits types for 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:
-if (Value == use_default)
- value_type = iterator_traits<Base>::value_type;
-else
- value_type = remove_cv<Value>::type;
+V = if (Value is use_default)
+ return iterator_traits<Base>::value_type
+ else
+ return Value
-if (Reference == use_default) {
- if (Value == use_default)
- reference = iterator_traits<Base>::reference;
- else
- reference = Value&;
-} else
- reference = Reference;
+C = if (CategoryOrTraversal is use_default)
+ return iterator_traversal<Base>::type
+ else
+ return CategoryOrTraversal
-if (Distance == use_default)
- difference_type = iterator_traits<Base>::difference_type;
-else
- difference_type = Distance;
+R = if (Reference is use_default)
+ if (Value is use_default)
+ return iterator_traits<Base>::reference
+ else
+ return Value&
+ else
+ return Reference
-if (Category == use_default)
- iterator_category = iterator_tag<
- access_category< Base >,
- traversal_category< Base >
- >
-else if (Category is an access tag)
- iterator_category = iterator_tag<
- Category
- ...
-
-else if (Category is a traversal tag)
- ...
-else
- iterator_category = Category;
- // Actually the above is wrong. See the use of
- // access_category_tag and
- // new_category_to_access/iter_category_to_access.
+D = if (Difference is use_default)
+ return iterator_traits<Base>::difference_type
+ else
+ return Difference
-
+
+
+iterator_adaptor usage
+The Derived template parameter must be a publicly derived from
+iterator_adaptor. In order for Derived to model the
+iterator concepts corresponding to
+iterator_traits<Derived>::iterator_category, the expressions
+involving m_iterator in the specifications of those private
+member functions of iterator_adaptor that may be called by
+iterator_facade<Derived, ``\ *V*\, \ *C*\, \ *R*\, \
+*D*\>`` in evaluating any valid expression involving Derived
+in those concepts' requirements.
-iterator_adaptor public operations
+iterator_adaptor public operations
iterator_adaptor();
-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_abstract.rst b/doc/iterator_adaptor_abstract.rst
index ee75455..c20ac7b 100644
--- a/doc/iterator_adaptor_abstract.rst
+++ b/doc/iterator_adaptor_abstract.rst
@@ -1,5 +1,11 @@
-The ``iterator_adaptor`` is a base class template derived from an
-instantiation of ``iterator_facade``. The core interface functions
+.. Version 1.1 of this ReStructuredText document corresponds to
+ n1530_, the paper accepted by the LWG.
+
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
+ rights reserved
+
+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
diff --git a/doc/iterator_adaptor_body.rst b/doc/iterator_adaptor_body.rst
index 942c2f6..59b8cef 100644
--- a/doc/iterator_adaptor_body.rst
+++ b/doc/iterator_adaptor_body.rst
@@ -1,3 +1,9 @@
+.. Version 1.2 of this ReStructuredText document corresponds to
+ n1530_, the paper accepted by the LWG for TR1.
+
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
+ rights reserved
+
The ``iterator_adaptor`` class template adapts some ``Base`` [#base]_
type to create a new iterator. Instantiations of ``iterator_adaptor``
are derived from a corresponding instantiation of ``iterator_facade``
@@ -19,7 +25,7 @@ interface functions of ``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`` (or ``use_default_access``). This allows the
+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
@@ -28,6 +34,6 @@ complicated, so metaprogramming is required to compute them, and
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 making mistakes based on
+``reference`` type, and will keep users from making mistakes based on
that assumption.
diff --git a/doc/iterator_adaptor_ref.rst b/doc/iterator_adaptor_ref.rst
index a51e2e9..d1f0100 100644
--- a/doc/iterator_adaptor_ref.rst
+++ b/doc/iterator_adaptor_ref.rst
@@ -1,17 +1,21 @@
+.. Version 1.4 of this ReStructuredText document corresponds to
+ n1530_, the paper accepted by the LWG for TR1.
+
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
+ rights reserved.
+
.. parsed-literal::
- bool
template <
class Derived
, class Base
- , class Value = use_default
- , unsigned Access = use_default_access
- , class Traversal = use_default
+ , class Value = use_default
+ , class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
class iterator_adaptor
- : public iterator_facade // see details__
{
friend class iterator_core_access;
public:
@@ -40,69 +44,55 @@
iterator_adaptor const& y) const;
private:
- Base m_iterator;
+ Base m_iterator; // exposition only
};
-__ : THE LINK HERE IS MISSING!
+__ :
-``iterator_adaptor`` requirements
----------------------------------
+``iterator_adaptor`` base class parameters
+------------------------------------------
-The ``Derived`` template parameter must be a derived class of
-``iterator_adaptor``. The ``Base`` type must implement the
-expressions involving ``m_iterator`` in the specifications of those
-private member functions of ``iterator_adaptor`` that are not
-redefined by the ``Derived`` class and that are needed to model the
-concept corresponding to
-``iterator_traits::iterator_category`` according to the
-requirements of ``iterator_facade``. The rest of the template
-parameters specify the types for the member typedefs in
-``iterator_facade``. The following pseudo-code specifies the
-traits types for ``iterator_adaptor``.
+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:
-::
+.. parsed-literal::
- if (Value != use_default)
- value_type = remove_cv::type;
- else
- value_type = iterator_traits)
- access_category &= ~writable_iterator;
- }
-
- iterator_category = iterator_tag<
- access_category
- , traversal_category
- >
-
- if (Reference != use_default)
- reference = Reference
- else if (Value != use_default)
- reference = Value&
- else
- reference = iterator_traits::iterator_category``, the expressions
+involving ``m_iterator`` in the specifications of those private
+member functions of ``iterator_adaptor`` that may be called by
+``iterator_facade`` in evaluating any valid expression involving ``Derived``
+in those concepts' requirements.
``iterator_adaptor`` public operations
--------------------------------------
diff --git a/doc/iterator_facade.html b/doc/iterator_facade.html
index af5d672..71d630b 100644
--- a/doc/iterator_facade.html
+++ b/doc/iterator_facade.html
@@ -9,7 +9,198 @@
-
+
@@ -46,20 +237,25 @@ and associated types, to be supplied by a derived iterator class.
-Motivation
+Motivation
+
+
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:
@@ -91,7 +287,7 @@ implementations.
Without the use of CRTP, the standard requirement that an
iterator's operator++ returns the iterator type itself means
that all iterators generated by iterator_facade would be
-instantiations of iterator_facade. Cumbersome type generator
+specializations of iterator_facade. Cumbersome type generator
metafunctions would be needed to build new parameterized
iterators, and a separate iterator_adaptor layer would be
impossible.
@@ -99,9 +295,9 @@ impossible.
-Usage
+Usage
The user of iterator_facade derives his iterator class from an
-instantiation of iterator_facade which takes the derived iterator
+specialization of iterator_facade which takes the derived iterator
class as the first template parameter. The order of the other
template parameters to iterator_facade have been carefully chosen
to take advantage of useful defaults. For example, when defining a
@@ -162,7 +358,7 @@ Iterator or a more-refined iterator concept, a default constructor is
required.
-Iterator Core Access
+Iterator Core Access
iterator_facade and the operator implementations need to be able
to access the core member functions in the derived class. Making the
core member functions public would expose an implementation detail to
@@ -196,18 +392,18 @@ open a safety loophole, as every core member function preserves the
invariants of the iterator.
-operator[]
+operator[]
The indexing operator for a generalized iterator presents special
challenges. A random access iterator's operator[] is only
required to return something convertible to its value_type.
Requiring that it return an lvalue would rule out currently-legal
random-access iterators which hold the referenced value in a data
-member (e.g. counting_iterator), because *(p+n) is a reference
+member (e.g. counting_iterator), because *(p+n) is a reference
into the temporary iterator p+n, which is destroyed when
operator[] returns.
Writable iterators built with iterator_facade implement the
semantics required by the preferred resolution to issue 299 and
-adopted by proposal n1477: the result of p[n] is a proxy object
+adopted by proposal n1550: the result of p[n] is a proxy object
containing a copy of p+n, and p[n] = x is equivalent to *(p
+ n) = x. This approach will work properly for any random-access
iterator regardless of the other details of its implementation. A
@@ -216,8 +412,8 @@ to implement an operator[] whi
iterator 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
@@ -227,7 +423,7 @@ type is not in fact a reference must return a proxy containing a copy
of the referenced value from its operator->.
The return type for operator-> and operator[] is not
explicitly specified. Instead it requires each iterator_facade
-instantiation to meet the requirements of its iterator_category.
+specialization to meet the requirements of its iterator_category.
-Reference
+Reference
+
+
template <
class Derived
, class Value
- , class AccessCategory
- , class TraversalCategory
- , class Reference = /* see below */
+ , class CategoryOrTraversal
+ , class Reference = Value&
, class Difference = ptrdiff_t
>
class iterator_facade {
public:
- typedef remove_cv<Value>::type value_type;
+ typedef remove_const<Value>::type value_type;
typedef Reference reference;
- typedef /* see description of operator-> */ pointer;
+ typedef Value* pointer;
typedef Difference difference_type;
- typedef iterator_tag<AccessCategory, TraversalCategory> iterator_category;
+ typedef /* see below */ iterator_category;
reference operator*() const;
/* see below */ operator->() const;
@@ -269,104 +468,114 @@ public:
};
// Comparison operators
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
- class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+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, bool>::type // exposition
-operator ==(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
- iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+operator ==(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
+ iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
- class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+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, bool>::type
-operator !=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
- iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+operator !=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
+ iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
- class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+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, bool>::type
-operator <(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
- iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+operator <(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
+ iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
- class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+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, bool>::type
-operator <=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
- iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+operator <=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
+ iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
- class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+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, bool>::type
-operator >(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
- iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+operator >(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
+ iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
- class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+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, bool>::type
-operator >=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
- iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+operator >=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
+ iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
- class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+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, bool>::type
-operator >=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
- iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+operator >=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
+ iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
// Iterator difference
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
- class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+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, bool>::type
-operator -(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
- iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+operator -(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
+ iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
// Iterator addition
-template <class Derived, class V, class AC, class TC, class R, class D>
-Derived operator+ (iterator_facade<Derived, V, AC, TC, R, D> const&,
+template <class Derived, class V, class TC, class R, class D>
+Derived operator+ (iterator_facade<Derived, V, TC, R, D> const&,
typename Derived::difference_type n)
-[Note: The enable_if_interoperable template used above is for exposition
-purposes. The member operators should be only be in an overload set
-provided the derived types Dr1 and Dr2 are interoperable, by
-which we mean they are convertible to each other. The
+
The enable_if_interoperable template used above is for exposition
+purposes. The member operators should be only be in an overload set
+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.]
-
-
-iterator_facade requirements
-The Derived template parameter must be a class derived from
-iterator_facade.
-The default for the Reference parameter is Value& if the
-access category for iterator_facade is implicitly convertible to
-writable_iterator_tag, and const Value& otherwise.
-The following table describes the other requirements on the
-Derived parameter. Depending on the resulting iterator's
-iterator_category, a subset of the expressions listed in the table
-are required to be valid. The operations in the first column must be
-accessible to member functions of class iterator_core_access.
-In the table below, X is the derived iterator type, a is an
+out of the overload set when the types are not interoperable.
+The operators should behave as-if enable_if_interoperable
+were defined to be:
+
+template <bool, typename> enable_if_interoperable_impl
+{};
+
+template <typename T> enable_if_interoperable_impl<true,T>
+{ typedef T type; };
+
+template<typename Dr1, typename Dr2, typename T>
+struct enable_if_interoperable
+ : enable_if_interoperable_impl<
+ is_convertible<Dr1,Dr2>::value || is_convertible<Dr2,Dr1>::value
+ , T
+ >
+{};
+
+
+iterator_facade usage
+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
+column must be made accessible to member functions of class
+iterator_core_access.
+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 X::difference_type, y is a constant
-object of a single pass iterator type interoperable with X, and z
+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.
Expression
Return Type
Assertion/Note
-Required to implement
-Iterator Concept(s)
+Used to implement Iterator
+Concept(s)
c.dereference()
-X::reference
+F::reference
Readable Iterator, Writable
Iterator
@@ -403,14 +612,14 @@ Iterator
c.distance_to(b)
convertible to
-X::difference_type
+F::difference_type
equivalent to distance(c, b)
Random Access Traversal
Iterator
c.distance_to(z)
convertible to
-X::difference_type
+F::difference_type
equivalent to distance(c, z).
Implements c - z, c < z, c
<= z, c > z, and c >= c.
@@ -419,12 +628,62 @@ Iterator
-
+
+
+iterator_facade iterator category
+The iterator_category member of iterator_facade<X,V,R,C,D>
+is a type which satisfies the following conditions:
+
+
+if C is convertible to std::input_iterator_tag or
+C is convertible to std::output_iterator_tag,
+iterator_category is the same as C.
+Otherwise, if C is not convertible to
+incrementable_traversal_tag, the program is ill-formed
+Otherwise:
+
+iterator_category is convertible to the iterator
+category tag or tags given by the following algorithm, and
+not to any more-derived iterator category tag or tags:
+
+if (R is a reference type
+ && C is convertible to forward_traversal_tag)
+{
+ if (C is convertible to random_access_traversal_tag)
+ return random_access_iterator_tag
+ else if (C is convertible to bidirectional_traversal_tag)
+ return bidirectional_iterator_tag
+ else
+ return forward_traversal_tag
+}
+else
+{
+ if (C is convertible to single_pass_traversal_tag
+ && R is convertible to V)
+ {
+ if (V is const)
+ return input_iterator_tag
+ else
+ return input_iterator_tag and output_iterator_tag
+ }
+ else
+ return output_iterator_tag
+}
+
+iterator_traversal<X>::type is convertible to the most
+derived traversal tag type to which C is also
+convertible, and not to any more-derived traversal tag type.
+
+
+
-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
@@ -443,17 +702,14 @@ through member functions of class iterator
Returns: If X::reference is a reference type, returns an object
-of type X::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, given an
-object a of type X, a->m is equivalent to (w = *a,
-w.m) for some temporary object w of type X::value_type.
-The type X::pointer is Value* if the access category for
-X is implicitly convertible to writable_iterator_tag, and
-Value const* otherwise.
+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.
Returns: an object convertible to X::reference and holding a copy
-p of a+n such that, for a constant object v of type
-X::value_type, X::reference(a[n] = v) is equivalent
+ Returns: an object convertible to reference and holding a copy
+p of *static_cast<Derived const*>(this) + n such that, for a constant object v of type
+value_type, (*static_cast<Derived const*>(this))[n] = v is equivalent
to p = v.
Effects:
static_cast<Derived*>(this)->increment();
-return *this;
+return *static_cast<Derived*>(this);
-
Derived operator++(int);
Effects:
static_cast<Derived*>(this)->decrement();
-return *this;
+return static_cast<Derived*>(this);
Effects:
static_cast<Derived*>(this)->advance(n);
-return *this;
+return static_cast<Derived*>(this);
Effects:
static_cast<Derived*>(this)->advance(-n);
-return *this;
+return static_cast<Derived*>(this);
Effects: Derived tmp(static_cast<Derived const*>(this));
-return tmp -= n;
-Returns: static_cast<Derived const*>(this)->advance(-n);
+Effects:
+Derived tmp(static_cast<Derived const*>(this));
+return tmp -= n;
+
+
@@ -573,7 +825,7 @@ return tmp -= n;
diff --git a/doc/iterator_facade.rst b/doc/iterator_facade.rst
index 473d095..d258dce 100644
--- a/doc/iterator_facade.rst
+++ b/doc/iterator_facade.rst
@@ -31,3 +31,5 @@ Reference
---------
.. include:: iterator_facade_ref.rst
+
+.. _counting: counting_iterator.html
diff --git a/doc/iterator_facade_body.rst b/doc/iterator_facade_body.rst
index ee6fb9c..a407b16 100644
--- a/doc/iterator_facade_body.rst
+++ b/doc/iterator_facade_body.rst
@@ -1,3 +1,10 @@
+.. Version 1.1 of this ReStructuredText document corresponds to
+ n1530_, the paper accepted by the LWG for TR1.
+
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
+ rights reserved
+
+
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:
@@ -31,7 +38,7 @@ objects for several reasons:
3. Without the use of CRTP, the standard requirement that an
iterator's ``operator++`` returns the iterator type itself means
that all iterators generated by ``iterator_facade`` would be
- instantiations of ``iterator_facade``. Cumbersome type generator
+ specializations of ``iterator_facade``. Cumbersome type generator
metafunctions would be needed to build new parameterized
iterators, and a separate ``iterator_adaptor`` layer would be
impossible.
@@ -40,7 +47,7 @@ Usage
-----
The user of ``iterator_facade`` derives his iterator class from an
-instantiation of ``iterator_facade`` which takes the derived iterator
+specialization of ``iterator_facade`` which takes the derived iterator
class as the first template parameter. The order of the other
template parameters to ``iterator_facade`` have been carefully chosen
to take advantage of useful defaults. For example, when defining a
@@ -135,15 +142,15 @@ challenges. A random access iterator's ``operator[]`` is only
required to return something convertible to its ``value_type``.
Requiring that it return an lvalue would rule out currently-legal
random-access iterators which hold the referenced value in a data
-member (e.g. `counting_iterator`__), because ``*(p+n)`` is a reference
+member (e.g. |counting|_), because ``*(p+n)`` is a reference
into the temporary iterator ``p+n``, which is destroyed when
``operator[]`` returns.
-__ counting_iterator.html
+.. |counting| replace:: ``counting_iterator``
Writable iterators built with ``iterator_facade`` implement the
semantics required by the preferred resolution to `issue 299`_ and
-adopted by proposal `n1477`_: the result of ``p[n]`` is a proxy object
+adopted by proposal n1550_: the result of ``p[n]`` is a proxy object
containing a copy of ``p+n``, and ``p[n] = x`` is equivalent to ``*(p
+ n) = x``. This approach will work properly for any random-access
iterator regardless of the other details of its implementation. A
@@ -152,9 +159,9 @@ to implement an ``operator[]`` which returns an lvalue in the derived
iterator class; it will hide the one supplied by ``iterator_facade``
from clients of her iterator.
-.. _`n1477`: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html
+.. _n1550: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1550.html
-.. _issue 299: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299
+.. _`issue 299`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299
.. _`operator arrow`:
@@ -172,7 +179,7 @@ of the referenced value from its ``operator->``.
The return type for ``operator->`` and ``operator[]`` is not
explicitly specified. Instead it requires each ``iterator_facade``
-instantiation to meet the requirements of its ``iterator_category``.
+specialization to meet the requirements of its ``iterator_category``.
.. [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template
diff --git a/doc/iterator_facade_ref.rst b/doc/iterator_facade_ref.rst
index bba0dd2..dbec7d1 100644
--- a/doc/iterator_facade_ref.rst
+++ b/doc/iterator_facade_ref.rst
@@ -1,20 +1,26 @@
+.. Version 1.3 of this ReStructuredText document corresponds to
+ n1530_, the paper accepted by the LWG for TR1.
+
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
+ rights reserved
+
+
.. parsed-literal::
template <
class Derived
, class Value
- , unsigned AccessCategory
- , class TraversalCategory
- , class Reference = /* see below__ \*/
+ , class CategoryOrTraversal
+ , class Reference = Value&
, class Difference = ptrdiff_t
>
class iterator_facade {
public:
- typedef remove_cv::type value_type;
+ typedef remove_const::type value_type;
typedef Reference reference;
- typedef /* see `description of operator->`__ \*/ pointer;
+ typedef Value* pointer;
typedef Difference difference_type;
- typedef iterator_tag iterator_category;
+ typedef /* see below__ \*/ iterator_category;
reference operator\*() const;
/* see below__ \*/ operator->() const;
@@ -29,151 +35,185 @@
};
// Comparison operators
- template
+ template
typename enable_if_interoperable::type // exposition
- operator ==(iterator_facade const& lhs,
- iterator_facade const& rhs);
+ operator ==(iterator_facade const& lhs,
+ iterator_facade const& rhs);
- template
+ template
typename enable_if_interoperable::type
- operator !=(iterator_facade const& lhs,
- iterator_facade const& rhs);
+ operator !=(iterator_facade const& lhs,
+ iterator_facade const& rhs);
- template
+ template
typename enable_if_interoperable::type
- operator <(iterator_facade const& lhs,
- iterator_facade const& rhs);
+ operator <(iterator_facade const& lhs,
+ iterator_facade const& rhs);
- template
+ template
typename enable_if_interoperable::type
- operator <=(iterator_facade const& lhs,
- iterator_facade const& rhs);
+ operator <=(iterator_facade const& lhs,
+ iterator_facade const& rhs);
- template
+ template
typename enable_if_interoperable::type
- operator >(iterator_facade const& lhs,
- iterator_facade const& rhs);
+ operator >(iterator_facade const& lhs,
+ iterator_facade const& rhs);
- template
+ template
typename enable_if_interoperable::type
- operator >=(iterator_facade const& lhs,
- iterator_facade const& rhs);
+ operator >=(iterator_facade const& lhs,
+ iterator_facade const& rhs);
- template
+ template
typename enable_if_interoperable::type
- operator >=(iterator_facade const& lhs,
- iterator_facade const& rhs);
+ operator >=(iterator_facade const& lhs,
+ iterator_facade const& rhs);
// Iterator difference
- template
+ template
typename enable_if_interoperable::type
- operator -(iterator_facade const& lhs,
- iterator_facade const& rhs);
+ operator -(iterator_facade const& lhs,
+ iterator_facade const& rhs);
// Iterator addition
- template
- Derived operator+ (iterator_facade const&,
+ template
+ Derived operator+ (iterator_facade const&,
typename Derived::difference_type n)
-__ `iterator facade requirements`_
-
-__ `operator arrow`_
+__ `facade iterator category`_
__ `operator arrow`_
__ brackets_
-[*Note:* The ``enable_if_interoperable`` template used above is for exposition
-purposes. The member operators should be only be in an overload set
-provided the derived types ``Dr1`` and ``Dr2`` are interoperable, by
-which we mean they are convertible to each other. The
+The ``enable_if_interoperable`` template used above is for exposition
+purposes. The member operators should be only be in an overload set
+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::
+
+ template enable_if_interoperable_impl
+ {};
+
+ template enable_if_interoperable_impl
+ { typedef T type; };
+
+ template
+ struct enable_if_interoperable
+ : enable_if_interoperable_impl<
+ is_convertible::value || is_convertible::value
+ , T
+ >
+ {};
-.. we need a new label here because the presence of markup in the
- title prevents an automatic link from being generated
+``iterator_facade`` usage
+.........................
-.. _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
+column must be made accessible to member functions of class
+``iterator_core_access``.
-``iterator_facade`` requirements
-................................
-
-Some of the constraints on template parameters to
-``iterator_facade`` are expressed in terms of resulting nested
-types and should be viewed in the context of their impact on
-``iterator_traits``.
-
-The ``Derived`` template parameter must be a class derived from
-``iterator_facade``.
-
-The nested ``::value_type`` type will be the same as
-``remove_cv::type``, so the ``Value`` parameter must be
-an (optionally ``const``\ -qualified) non-reference type.
-
-``AccessCategory`` must be an unsigned value which uses no more
-bits than the greatest value of ``iterator_access``.
-
-The nested ``::reference`` will be the same as the ``Reference``
-parameter; it must be a suitable reference type for the resulting
-iterator. The default for the ``Reference`` parameter is
-``Value&``.
-
-The following table describes the other requirements on the
-``Derived`` parameter. Depending on the resulting iterator's
-``iterator_category``, a subset of the expressions listed in the table
-are required to be valid. The operations in the first column must be
-accessible to member functions of class ``iterator_core_access``.
-
-In the table below, ``X`` is the derived iterator type, ``a`` is an
+In the table below, ``F`` is ``iterator_facade``, ``a`` is an
object of type ``X``, ``b`` and ``c`` are objects of type ``const X``,
-``n`` is an object of ``X::difference_type``, ``y`` is a constant
-object of a single pass iterator type interoperable with X, and ``z``
+``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``.
-+--------------------+-------------------+-------------------------------------+---------------------------+
-|Expression |Return Type |Assertion/Note |Required to implement |
-| | | |Iterator Concept(s) |
-+====================+===================+=====================================+===========================+
-|``c.dereference()`` |``X::reference`` | |Readable Iterator, Writable|
-| | | |Iterator |
-+--------------------+-------------------+-------------------------------------+---------------------------+
-|``c.equal(b)`` |convertible to bool|true iff ``b`` and ``c`` are |Single Pass Iterator |
-| | |equivalent. | |
-+--------------------+-------------------+-------------------------------------+---------------------------+
-|``c.equal(y)`` |convertible to bool|true iff ``c`` and ``y`` refer to the|Single Pass Iterator |
-| | |same position. Implements ``c == y``| |
-| | |and ``c != y``. | |
-+--------------------+-------------------+-------------------------------------+---------------------------+
-|``a.advance(n)`` |unused | |Random Access Traversal |
-| | | |Iterator |
-+--------------------+-------------------+-------------------------------------+---------------------------+
-|``a.increment()`` |unused | |Incrementable Iterator |
-+--------------------+-------------------+-------------------------------------+---------------------------+
-|``a.decrement()`` |unused | |Bidirectional Traversal |
-| | | |Iterator |
-+--------------------+-------------------+-------------------------------------+---------------------------+
-|``c.distance_to(b)``|convertible to |equivalent to ``distance(c, b)`` |Random Access Traversal |
-| |X::difference_type | |Iterator |
-+--------------------+-------------------+-------------------------------------+---------------------------+
-|``c.distance_to(z)``|convertible to |equivalent to ``distance(c, z)``. |Random Access Traversal |
-| |X::difference_type |Implements ``c - z``, ``c < z``, ``c |Iterator |
-| | |<= z``, ``c > z``, and ``c >= c``. | |
-+--------------------+-------------------+-------------------------------------+---------------------------+
++--------------------+----------------------+-------------------------------------+---------------------------+
+|Expression |Return Type |Assertion/Note |Used to implement Iterator |
+| | | |Concept(s) |
++====================+======================+=====================================+===========================+
+|``c.dereference()`` |``F::reference`` | |Readable Iterator, Writable|
+| | | |Iterator |
++--------------------+----------------------+-------------------------------------+---------------------------+
+|``c.equal(b)`` |convertible to bool |true iff ``b`` and ``c`` are |Single Pass Iterator |
+| | |equivalent. | |
++--------------------+----------------------+-------------------------------------+---------------------------+
+|``c.equal(y)`` |convertible to bool |true iff ``c`` and ``y`` refer to the|Single Pass Iterator |
+| | |same position. Implements ``c == y``| |
+| | |and ``c != y``. | |
++--------------------+----------------------+-------------------------------------+---------------------------+
+|``a.advance(n)`` |unused | |Random Access Traversal |
+| | | |Iterator |
++--------------------+----------------------+-------------------------------------+---------------------------+
+|``a.increment()`` |unused | |Incrementable Iterator |
++--------------------+----------------------+-------------------------------------+---------------------------+
+|``a.decrement()`` |unused | |Bidirectional Traversal |
+| | | |Iterator |
++--------------------+----------------------+-------------------------------------+---------------------------+
+|``c.distance_to(b)``|convertible to |equivalent to ``distance(c, b)`` |Random Access Traversal |
+| |``F::difference_type``| |Iterator |
++--------------------+----------------------+-------------------------------------+---------------------------+
+|``c.distance_to(z)``|convertible to |equivalent to ``distance(c, z)``. |Random Access Traversal |
+| |``F::difference_type``|Implements ``c - z``, ``c < z``, ``c |Iterator |
+| | |<= z``, ``c > z``, and ``c >= c``. | |
++--------------------+----------------------+-------------------------------------+---------------------------+
-.. We should explain more about how the
- functions in the interface of iterator_facade
- are there conditionally. -JGS
+.. _facade iterator category:
+
+``iterator_facade`` iterator category
+.....................................
+
+The ``iterator_category`` member of ``iterator_facade``
+is a type which satisfies the following conditions:
+
+ * if ``C`` is convertible to ``std::input_iterator_tag`` or
+ ``C`` is convertible to ``std::output_iterator_tag``,
+ ``iterator_category`` is the same as ``C``.
+
+ * Otherwise, if ``C`` is not convertible to
+ ``incrementable_traversal_tag``, the program is ill-formed
+
+ * Otherwise:
+
+ - ``iterator_category`` is convertible to the iterator
+ category tag or tags given by the following algorithm, and
+ not to any more-derived iterator category tag or tags::
+
+ if (R is a reference type
+ && C is convertible to forward_traversal_tag)
+ {
+ if (C is convertible to random_access_traversal_tag)
+ return random_access_iterator_tag
+ else if (C is convertible to bidirectional_traversal_tag)
+ return bidirectional_iterator_tag
+ else
+ return forward_traversal_tag
+ }
+ else
+ {
+ if (C is convertible to single_pass_traversal_tag
+ && R is convertible to V)
+ {
+ if (V is const)
+ return input_iterator_tag
+ else
+ return input_iterator_tag and output_iterator_tag
+ }
+ else
+ return output_iterator_tag
+ }
+
+ - ``iterator_traversal::type`` is convertible to the most
+ derived traversal tag type to which ``C`` is also
+ convertible, and not to any more-derived traversal tag type.
``iterator_facade`` operations
@@ -192,27 +232,22 @@ through member functions of class ``iterator_core_access``.
__ `operator arrow`_
-:Returns: If ``X::reference`` is a reference type, returns an object
- of type ``X::pointer`` equal to::
+:Returns: If ``reference`` is a reference type, an object
+ of type ``pointer`` equal to::
&static_cast(this)->dereference()
- Otherwise returns an object of unspecified type such that, given an
- object ``a`` of type ``X``, ``a->m`` is equivalent to ``(w = *a,
- w.m)`` for some temporary object ``w`` of type ``X::value_type``.
-
- The type ``X::pointer`` is ``Value*`` if
- ``is_writable_iterator::value`` is ``true``, and
- ``Value const*`` otherwise.
-
+ Otherwise returns an object of unspecified type such that,
+ ``(*static_cast(this))->m`` is equivalent to ``(w = **static_cast(this),
+ w.m)`` for some temporary object ``w`` of type ``value_type``.
.. _brackets:
*unspecified* ``operator[](difference_type n) const;``
-:Returns: an object convertible to ``X::reference`` and holding a copy
- *p* of ``a+n`` such that, for a constant object ``v`` of type
- ``X::value_type``, ``X::reference(a[n] = v)`` is equivalent
+:Returns: an object convertible to ``reference`` and holding a copy
+ *p* of ``*static_cast(this) + n`` such that, for a constant object ``v`` of type
+ ``value_type``, ``(*static_cast(this))[n] = v`` is equivalent
to ``p = v``.
@@ -224,14 +259,7 @@ __ `operator arrow`_
::
static_cast(this)->increment();
- return *this;
-
-.. I realize that the committee is moving away from specifying things
- like this in terms of code, but I worried about the imprecision of
- saying that a core interface function is invoked without describing
- the downcast. An alternative to what I did would be to mention it
- above where we talk about accessibility.
-
+ return *static_cast(this);
``Derived operator++(int);``
@@ -251,7 +279,7 @@ __ `operator arrow`_
::
static_cast(this)->decrement();
- return *this;
+ return static_cast(this);
``Derived operator--(int);``
@@ -272,26 +300,27 @@ __ `operator arrow`_
::
static_cast(this)->advance(n);
- return *this;
+ return static_cast(this);
``Derived& operator-=(difference_type n);``
:Effects:
-
- ::
+
+ ::
static_cast(this)->advance(-n);
- return *this;
+ return static_cast(this);
``Derived operator-(difference_type n) const;``
-:Effects:
+:Effects:
+
+ ::
Derived tmp(static_cast(this));
return tmp -= n;
-:Returns: ``static_cast(this)->advance(-n);``
diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html
index cc69a33..12cabb2 100755
--- a/doc/new-iter-concepts.html
+++ b/doc/new-iter-concepts.html
@@ -7,7 +7,7 @@
New Iterator Concepts
-
+
@@ -79,7 +270,8 @@ past-the-end iterator to the indices.
template< class ElementIterator
, class IndexIterator
, class ValueT = use_default
- , class CategoryT = use_default
+ , unsigned access = use_default_access
+ , class Traversal = use_default
, class ReferenceT = use_default
, class DifferenceT = use_default >
class permutation_iterator
@@ -121,7 +313,7 @@ ForwardIterator instead of amortized constant time.
diff --git a/doc/style.tex b/doc/style.tex
index 4b2407e..a4fe2f9 100755
--- a/doc/style.tex
+++ b/doc/style.tex
@@ -1,60 +1,3 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%%%%%%%%%%%%% docutils.sty: A style for docutils latex output %%%%%%%%%%%%%%%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%
-%% o author: Alexander Schmolck (a.schmolck@gmx.net)
-%% o created: 2002-07-07 10:50:31+00:40
-%% o last modified: $Date: 2003/09/22 19:55:01 $
-%% o keywords:
-%% o license:
-%XXX titlesec
-%% XXX geometry
-\usepackage{graphicx}
-\usepackage{latexsym} % extra symbols
-\usepackage{url} % !!!: pay attention when using in other commands!!!
-\usepackage{verbatim} % normal verbatim has lenght-limit
-\usepackage{enumerate} % easy style choice with e.g: ``\begin{enumerate}[Ex i.]``
-\usepackage{hyperref} %href, htarget and hlink XXX: pdfauthor, pdfcreator etc.
-\usepackage{xr} %XXX do we need this?
-% need this to have ``fboxes`` in ``enviroments``, as well as ``verbatim``s
-\usepackage{fancybox}
-\usepackage{mdwtab} % better tables and arrays (fixes spacing and adds
- % vertical align and multirows (m))
-\usepackage{ltxtable} % long and autoscaling tables (use X for autoscaled
- % columns)
-\newcommand{\transition}{\vspace{2em}\par\hrule{}\par\vspace{2em}}
-\newcommand{\classifier}[1]{(\textit{#1})}
-\newenvironment{topic}[1]%
-{\begin{Sbox}%
- \begin{minipage}{.8\textwidth}%
- \protect{\large{\textbf{#1}}}\par\vspace{.5em}}%
-{\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}}
-%XXX shadow box for warnings?
-\newenvironment{admonition}[1]%
-{\begin{center}%
- \begin{Sbox}%
- \begin{minipage}{.9\textwidth}%
- \protect{\textsc{#1}}\par\vspace{.2em}}%
-{\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}\end{center}}
-
-\newenvironment{doctest}%
-{\VerbatimEnvironment
- \begin{Verbatim}}%
-{\end{Verbatim}}
-% {%
-% \begin{Sbox}%
-% \begin{minipage}{.8\textwidth}%
-% \protect{\large{\textsc{#1}}\par\vspace{.5em}}}%
-% {\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}}
-%{\end{minipage}\end{Sbox}\fbox{\TheSbox}}
-
-
-%% just a piece of example code
-% \newcommand{\vitem}%
-% {\SaveVerb[{\item[\UseVerb{\MyTemp}]}]{\MyTemp}}
-
-%%%%%%%%%%%%%%%%%%% Added by DWA %%%%%%%%%%%%%%%%%%%%%%%%%
-
% donot indent first line.
\setlength{\parindent}{0pt}
\setlength{\parskip}{5pt plus 2pt minus 1pt}
@@ -75,4 +18,24 @@
\usepackage{pslatex}
% pagestyle
+% \usepackage{fancyhdr}
\pagestyle{headings}
+\setlength{\paperwidth}{7.375in}
+\setlength{\paperheight}{9.25in}
+
+\setlength{\oddsidemargin}{0.375in}
+\setlength{\evensidemargin}{0.375in}
+\setlength{\textwidth}{5in}
+\setlength{\textheight}{7.125in}
+
+\setlength{\topmargin}{-0.375in}
+\setlength{\headheight}{0.25in}
+\setlength{\headsep}{0.25in}
+\setlength{\footskip}{0.25in}
+
+\setlength{\admonitionwidth}{0.9\textwidth}
+\setlength{\docinfowidth}{0.9\textwidth}
+
+
+
+