diff --git a/doc/counting_iterator.rst b/doc/counting_iterator.rst new file mode 100644 index 0000000..d6aedf7 --- /dev/null +++ b/doc/counting_iterator.rst @@ -0,0 +1,23 @@ ++++++++++++++++++++ + Counting Iterator ++++++++++++++++++++ + +:Author: David Abrahams, Jeremy Siek, Thomas Witt +:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +:organization: `Boost Consulting`_, Indiana University `Open Systems + Lab`_, University of Hanover `Institute for Transport + Railway Operation and Construction`_ +:date: $Date$ +:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved + +.. _`Boost Consulting`: http://www.boost-consulting.com +.. _`Open Systems Lab`: http://www.osl.iu.edu +.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de + +:abstract: + +.. include:: counting_iterator_abstract.rst + +.. contents:: Table of Contents + +.. include:: counting_iterator_ref.rst diff --git a/doc/counting_iterator_abstract.rst b/doc/counting_iterator_abstract.rst new file mode 100644 index 0000000..2ac2233 --- /dev/null +++ b/doc/counting_iterator_abstract.rst @@ -0,0 +1,5 @@ +The counting iterator adaptor implements dereference by returning a +reference to the base object. The other operations are implemented by +the base ``m_iterator``, as per the inheritance from +``iterator_adaptor``. + diff --git a/doc/counting_iterator_ref.rst b/doc/counting_iterator_ref.rst new file mode 100644 index 0000000..fc01011 --- /dev/null +++ b/doc/counting_iterator_ref.rst @@ -0,0 +1,85 @@ +:: + + template + class counting_iterator + : public iterator_adaptor< + counting_iterator + , Incrementable + , Incrementable + , /* see details for category */ + , Incrementable const& + , Incrementable const* + , /* distance = Difference or a signed integral type */> + { + friend class iterator_core_access; + public: + counting_iterator(); + counting_iterator(counting_iterator const& rhs); + counting_iterator(Incrementable x); + private: + typename counting_iterator::reference dereference() const + { + return this->base_reference(); + } + }; + + +[*Note:* implementers are encouraged to provide an implementation of + ``distance_to`` and a ``difference_type`` that avoids overflows in + the cases when the ``Incrementable`` type is a numeric type.] + +``counting_iterator`` requirements +---------------------------------- + +The ``Incrementable`` type must be Default Constructible, Copy +Constructible, and Assignable. The default distance is +an implementation defined signed integegral type. + +The resulting ``counting_iterator`` models Readable Lvalue Iterator. + +Furthermore, if you wish to create a counting iterator that is a Forward +Traversal Iterator, then the following expressions must be valid: +:: + + Incrementable i, j; + ++i // pre-increment + i == j // operator equal + +If you wish to create a counting iterator that is a +Bidirectional Traversal Iterator, then pre-decrement is also required: +:: + + --i + +If you wish to create a counting iterator that is a Random Access +Traversal Iterator, then these additional expressions are also +required: +:: + + counting_iterator::difference_type n; + i += n + n = i - j + i < j + + + + +``counting_iterator`` operations +-------------------------------- + +``counting_iterator();`` + +:Returns: A default constructed instance of ``counting_iterator``. + + +``counting_iterator(counting_iterator const& rhs);`` + +:Returns: An instance of ``counting_iterator`` that is a copy of ``rhs``. + + + +``counting_iterator(Incrementable x);`` + +:Returns: An instance of ``counting_iterator`` with its base + object copy constructed from ``x``. + diff --git a/doc/facade-and-adaptor.rst b/doc/facade-and-adaptor.rst index 3c6a788..a2d0493 100644 --- a/doc/facade-and-adaptor.rst +++ b/doc/facade-and-adaptor.rst @@ -324,626 +324,68 @@ implicitly convertible.] Indirect iterator ----------------- -The 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``) as if it were a container of the pointed-to type -(e.g. ``list``) . - -.. At some point we should add the capability to handle - iterators over smart pointers, which the impl handles. -JGS - +.. include:: indirect_iterator_abstract.rst Class template ``indirect_iterator`` .................................... -:: - - template < - class Iterator - , class Value = use_default - , class Category = use_default - , class Reference = use_default - , class Difference = use_default - > - class indirect_iterator - : public iterator_adaptor - { - friend class iterator_core_access; - public: - indirect_iterator(); - indirect_iterator(Iterator x); - template < - class Iterator2, class Value2, class Category2 - , class Reference2, class Difference2 - > - indirect_iterator( - indirect_iterator< - Iterator2, Value2, Category2, Reference2, Difference2 - > const& y - , typename enable_if_convertible::type* = 0 // exposition - ); - private: // as-if specification - typename indirect_iterator::reference dereference() const - { - return **this->base(); - } - }; - -``indirect_iterator`` requirements -.................................. - -The ``value_type`` of the ``Iterator`` template parameter should -itself be dereferenceable. The return type of the ``operator*`` for -the ``value_type`` must be the same type as the ``Reference`` template -parameter. The ``Value`` template parameter will be the ``value_type`` -for the ``indirect_iterator``, unless ``Value`` is const. If ``Value`` -is ``const X``, then ``value_type`` will be *non-* ``const X``. The -default for ``Value`` is - -:: - - iterator_traits< iterator_traits::value_type >::value_type - -If the default is used for ``Value``, then there must be a valid -specialization of ``iterator_traits`` for the value type of the base -iterator. - -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_category``. - -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 -modeled by the value type of ``Iterator``. - - -``indirect_iterator`` operations -................................ - -``indirect_iterator();`` - -:Requires: ``Iterator`` must be Default Constructible. -:Returns: An instance of ``indirect_iterator`` with - a default constructed base object. - - -``indirect_iterator(Iterator x);`` - -:Returns: An instance of ``indirect_iterator`` with - the ``iterator_adaptor`` subobject copy constructed from ``x``. - -:: - - template < - class Iterator2, class Value2, class Category2 - , class Reference2, class Difference2 - > - indirect_iterator( - indirect_iterator< - Iterator2, Value2, Category2, Reference2, Difference2 - > const& y - , typename enable_if_convertible::type* = 0 // exposition - ); - -:Requires: ``Iterator2`` is implicitly convertible to ``Iterator``. -:Returns: An instance of ``indirect_iterator`` that is a copy of ``y``. +.. include:: indirect_iterator_ref.rst Reverse iterator ---------------- -.. I think we'd better strike the old reverse_iterator text from the standard, eh? - -The reverse iterator adaptor flips the direction of a base iterator's -motion. Invoking ``operator++()`` moves the base iterator backward and -invoking ``operator--()`` moves the base iterator forward. +.. include:: reverse_iterator_abstract.rst Class template ``reverse_iterator`` ................................... -:: - - template - class reverse_iterator : - public iterator_adaptor< reverse_iterator, Iterator > - { - friend class iterator_core_access; - public: - reverse_iterator() {} - explicit reverse_iterator(Iterator x) ; - - template - reverse_iterator( - reverse_iterator const& r - , typename enable_if_convertible::type* = 0 // exposition - ); - - private: // as-if specification - typename reverse_iterator::reference dereference() const { return *prior(this->base()); } - - void increment() { --this->base_reference(); } - void decrement() { ++this->base_reference(); } - - void advance(typename reverse_iterator::difference_type n) - { - this->base_reference() += -n; - } - - template - typename reverse_iterator::difference_type - distance_to(reverse_iterator const& y) const - { - return this->base_reference() - y.base(); - } - - }; - - -``reverse_iterator`` requirements -................................. - -The base ``Iterator`` must be a model of Bidirectional Traversal -Iterator. The resulting ``reverse_iterator`` will be a model of the -most refined standard traversal and access concepts that are modeled -by ``Iterator``. - - -``reverse_iterator();`` - -:Requires: ``Iterator`` must be Default Constructible. -:Returns: An instance of ``reverse_iterator`` with a - default constructed base object. - -``explicit reverse_iterator(Iterator x);`` - -:Returns: An instance of ``reverse_iterator`` with a - base object copy constructed from ``x``. - - -:: - - template - reverse_iterator( - reverse_iterator const& r - , typename enable_if_convertible::type* = 0 // exposition - ); - -:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``. -:Returns: An instance of ``reverse_iterator`` that is a copy of ``r``. +.. include:: reverse_iterator_ref.rst Transform iterator ------------------ -The transform iterator adapts an iterator by applying some function -object to the result of dereferencing the iterator. In other words, -the ``operator*`` of the transform iterator first dereferences the -base iterator, passes the result of this to the function object, and -then returns the result. - +.. include:: transform_iterator_abstract.rst Class template ``transform_iterator`` ..................................... -:: - - template - class transform_iterator - : public iterator_adaptor - { - friend class iterator_core_access; - public: - transform_iterator(); - transform_iterator(Iterator const& x, AdaptableUnaryFunction f); - - template - transform_iterator( - transform_iterator const& t - , typename enable_if_convertible::type* = 0 // exposition - ); - - AdaptableUnaryFunction functor() const; - private: - typename transform_iterator::value_type dereference() const; - AdaptableUnaryFunction m_f; - }; - - -``transform_iterator`` requirements -................................... - -The type ``AdaptableUnaryFunction`` must be Assignable, Copy -Constructible, and the expression ``f(x)`` must be valid where ``f`` -is an object of type ``AdaptableUnaryFunction``, ``x`` is an object of -type ``AdaptableUnaryFunction::argument_type``, and where the type of -``f(x)`` must be ``AdaptableUnaryFunction::result_type``. - -The type ``Iterator`` must at least model Readable Iterator. The -resulting ``transform_iterator`` models the most refined of the -following options that is also modeled by ``Iterator``. - - * Writable Lvalue Iterator if the ``result_type`` of the - ``AdaptableUnaryFunction`` is a non-const reference. - - * Readable Lvalue Iterator if the ``result_type`` is a const - reference. - - * Readable Iterator otherwise. - - -The ``transform_iterator`` models the most refined standard traversal -concept that is modeled by ``Iterator``. - -The ``value_type`` of ``transform_iterator`` is -``remove_reference::type``. The ``reference`` type is -``result_type``. - - -``transform_iterator`` public operations -........................................ - - -``transform_iterator();`` - -:Returns: An instance of ``transform_iterator`` with ``m_f`` - and ``m_iterator`` default constructed. - - -``transform_iterator(Iterator const& x, AdaptableUnaryFunction f);`` - -:Returns: An instance of ``transform_iterator`` with ``m_f`` - initialized to ``f`` and ``m_iterator`` initialized to ``x``. - - -:: - - template - transform_iterator( - transform_iterator const& t - , typename enable_if_convertible::type* = 0 // exposition - ); - -:Returns: An instance of ``transform_iterator`` that is a copy of ``t``. -:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``. - -``AdaptableUnaryFunction functor() const;`` - -:Returns: ``m_f`` - -``transform_iterator`` private operations -......................................... - -``typename transform_iterator::value_type dereference() const;`` - -:Returns: ``m_f(transform_iterator::dereference());`` - +.. include:: transform_iterator_ref.rst Filter iterator --------------- -The filter iterator adaptor creates a view of an iterator range in -which some elements of the range are skipped over. 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 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. Therefore the constructor of the filter -iterator takes two iterator parameters: the position for the filtered -iterator and the end of the range. - +.. include:: filter_iterator_abstract.rst Class template ``filter_iterator`` .................................. -:: - - template - class filter_iterator - : public iterator_adaptor< - filter_iterator, Iterator - , use_default - , /* see details */ - > - { - public: - filter_iterator(); - filter_iterator(Predicate f, Iterator x, Iterator end = Iterator()); - filter_iterator(Iterator x, Iterator end = Iterator()); - template - filter_iterator( - filter_iterator const& t - , typename enable_if_convertible::type* = 0 // exposition - ); - Predicate predicate() const; - Iterator end() const; - - private: // as-if specification - void increment() - { - ++(this->base_reference()); - satisfy_predicate(); - } - - void satisfy_predicate() - { - while (this->base() != this->m_end && !this->m_predicate(*this->base())) - ++(this->base_reference()); - } - - Predicate m_predicate; - Iterator m_end; - }; - - -``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``. - -.. Thomas is going to try implementing filter_iterator so that - it will be bidirectional if the underlying iterator is. -JGS - - -The ``Predicate`` 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::value_type``, and where the type of -``p(x)`` must be convertible to ``bool``. - - - -``filter_iterator`` operations ------------------------------- - -``filter_iterator();`` - -:Requires: ``Predicate`` and ``Iterator`` must be Default Constructible. -:Returns: a ``filter_iterator`` whose - predicate is a default constructed ``Predicate`` and - whose ``end`` is a default constructed ``Iterator``. - - -``filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());`` - -:Returns: A ``filter_iterator`` at position ``x`` that filters according - to predicate ``f`` and that will not increment past ``end``. - - -``filter_iterator(Iterator x, Iterator end = Iterator());`` - -:Requires: ``Predicate`` must be Default Constructible. -:Returns: A ``filter_iterator`` at position ``x`` that filters - according to a default constructed ``Predicate`` - and that will not increment past ``end``. - - -:: - - template - filter_iterator( - filter_iterator const& t - , typename enable_if_convertible::type* = 0 // exposition - );`` - -:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``. -:Returns: A copy of iterator ``t``. - - -``Predicate predicate() const;`` - -:Returns: A copy of the predicate object used to construct ``*this``. - - -``Iterator end() const;`` - -:Returns: The object ``end`` used to construct ``*this``. +.. include:: filter_iterator_ref.rst Counting iterator ----------------- -The counting iterator adaptor implements dereference by returning a -reference to the base object. The other operations are implemented by -the base ``m_iterator``, as per the inheritance from -``iterator_adaptor``. - +.. include:: counting_iterator_abstract.rst Class template ``counting_iterator`` .................................... -:: - - template - class counting_iterator - : public iterator_adaptor< - counting_iterator - , Incrementable - , Incrementable - , /* see details for category */ - , Incrementable const& - , Incrementable const* - , /* distance = Difference or a signed integral type */> - { - friend class iterator_core_access; - public: - counting_iterator(); - counting_iterator(counting_iterator const& rhs); - counting_iterator(Incrementable x); - private: - typename counting_iterator::reference dereference() const - { - return this->base_reference(); - } - }; - - -[*Note:* implementers are encouraged to provide an implementation of - ``distance_to`` and a ``difference_type`` that avoids overflows in - the cases when the ``Incrementable`` type is a numeric type.] - -``counting_iterator`` requirements ----------------------------------- - -The ``Incrementable`` type must be Default Constructible, Copy -Constructible, and Assignable. The default distance is -an implementation defined signed integegral type. - -The resulting ``counting_iterator`` models Readable Lvalue Iterator. - -Furthermore, if you wish to create a counting iterator that is a Forward -Traversal Iterator, then the following expressions must be valid: -:: - - Incrementable i, j; - ++i // pre-increment - i == j // operator equal - -If you wish to create a counting iterator that is a -Bidirectional Traversal Iterator, then pre-decrement is also required: -:: - - --i - -If you wish to create a counting iterator that is a Random Access -Traversal Iterator, then these additional expressions are also -required: -:: - - counting_iterator::difference_type n; - i += n - n = i - j - i < j - - - - -``counting_iterator`` operations --------------------------------- - -``counting_iterator();`` - -:Returns: A default constructed instance of ``counting_iterator``. - - -``counting_iterator(counting_iterator const& rhs);`` - -:Returns: An instance of ``counting_iterator`` that is a copy of ``rhs``. - - - -``counting_iterator(Incrementable x);`` - -:Returns: An instance of ``counting_iterator`` with its base - object copy constructed from ``x``. +.. include:: counting_iterator_ref.rst Function output iterator ------------------------ -The function output iterator adaptor makes it easier to create custom -output iterators. The adaptor takes a unary function and creates a -model of Output Iterator. Each item assigned to the output iterator is -passed as an argument to the unary function. The motivation for this -iterator is that creating a conforming output iterator is non-trivial, -particularly because the proper implementation usually requires a -proxy object. - +.. include:: function_output_iterator_abstract.rst Class template ``function_output_iterator`` ........................................... -:: +.. include:: function_output_iterator_ref.rst - template - class function_output_iterator { - public: - typedef iterator_tag< - writable_iterator_tag - , incrementable_traversal_tag - > iterator_category; - typedef void value_type; - typedef void difference_type; - typedef void pointer; - typedef void reference; - - explicit function_output_iterator(const UnaryFunction& f = UnaryFunction()); - - struct output_proxy { - output_proxy(UnaryFunction& f); - template output_proxy& operator=(const T& value); - }; - output_proxy operator*(); - function_output_iterator& operator++(); - function_output_iterator& operator++(int); - }; - - -``function_output_iterator`` requirements ------------------------------------------ - -The ``UnaryFunction`` must be Assignable, Copy Constructible, and the -expression ``f(x)`` must be valid, where ``f`` is an object of type -``UnaryFunction`` and ``x`` is an object of a type accepted by ``f``. -The resulting ``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());`` - -:Returns: An instance of ``function_output_iterator`` with - ``f`` stored as a data member. - - -``output_proxy operator*();`` - -:Returns: An instance of ``output_proxy`` constructed with - a copy of the unary function ``f``. - - -``function_output_iterator& operator++();`` - -:Returns: ``*this`` - - -``function_output_iterator& operator++(int);`` - -:Returns: ``*this`` - - -``function_output_iterator::output_proxy`` operations ------------------------------------------------------ - -``output_proxy(UnaryFunction& f);`` - -:Returns: An instance of ``output_proxy`` with ``f`` stored as - a data member. - - -``template output_proxy& operator=(const T& value);`` - -:Effects: - :: - - m_f(value); - return *this; diff --git a/doc/filter_iterator.rst b/doc/filter_iterator.rst new file mode 100644 index 0000000..06a7c5f --- /dev/null +++ b/doc/filter_iterator.rst @@ -0,0 +1,23 @@ ++++++++++++++++++ + Filter Iterator ++++++++++++++++++ + +:Author: David Abrahams, Jeremy Siek, Thomas Witt +:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +:organization: `Boost Consulting`_, Indiana University `Open Systems + Lab`_, University of Hanover `Institute for Transport + Railway Operation and Construction`_ +:date: $Date$ +:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved + +.. _`Boost Consulting`: http://www.boost-consulting.com +.. _`Open Systems Lab`: http://www.osl.iu.edu +.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de + +:abstract: + +.. include:: filter_iterator_abstract.rst + +.. contents:: Table of Contents + +.. include:: filter_iterator_ref.rst diff --git a/doc/filter_iterator_abstract.rst b/doc/filter_iterator_abstract.rst new file mode 100644 index 0000000..9517b23 --- /dev/null +++ b/doc/filter_iterator_abstract.rst @@ -0,0 +1,10 @@ +The filter iterator adaptor creates a view of an iterator range in +which some elements of the range are skipped over. 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 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. Therefore the constructor of the filter +iterator takes two iterator parameters: the position for the filtered +iterator and the end of the range. diff --git a/doc/filter_iterator_ref.rst b/doc/filter_iterator_ref.rst new file mode 100644 index 0000000..29bc166 --- /dev/null +++ b/doc/filter_iterator_ref.rst @@ -0,0 +1,108 @@ +:: + + template + class filter_iterator + : public iterator_adaptor< + filter_iterator, Iterator + , use_default + , /* see details */ + > + { + public: + filter_iterator(); + filter_iterator(Predicate f, Iterator x, Iterator end = Iterator()); + filter_iterator(Iterator x, Iterator end = Iterator()); + template + filter_iterator( + filter_iterator const& t + , typename enable_if_convertible::type* = 0 // exposition + ); + Predicate predicate() const; + Iterator end() const; + + private: // as-if specification + void increment() + { + ++(this->base_reference()); + satisfy_predicate(); + } + + void satisfy_predicate() + { + while (this->base() != this->m_end && !this->m_predicate(*this->base())) + ++(this->base_reference()); + } + + Predicate m_predicate; + Iterator m_end; + }; + + +``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``. + +.. Thomas is going to try implementing filter_iterator so that + it will be bidirectional if the underlying iterator is. -JGS + + +The ``Predicate`` 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::value_type``, and where the type of +``p(x)`` must be convertible to ``bool``. + + + +``filter_iterator`` operations +------------------------------ + +``filter_iterator();`` + +:Requires: ``Predicate`` and ``Iterator`` must be Default Constructible. +:Returns: a ``filter_iterator`` whose + predicate is a default constructed ``Predicate`` and + whose ``end`` is a default constructed ``Iterator``. + + +``filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());`` + +:Returns: A ``filter_iterator`` at position ``x`` that filters according + to predicate ``f`` and that will not increment past ``end``. + + +``filter_iterator(Iterator x, Iterator end = Iterator());`` + +:Requires: ``Predicate`` must be Default Constructible. +:Returns: A ``filter_iterator`` at position ``x`` that filters + according to a default constructed ``Predicate`` + and that will not increment past ``end``. + + +:: + + template + filter_iterator( + filter_iterator const& t + , typename enable_if_convertible::type* = 0 // exposition + );`` + +:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``. +:Returns: A copy of iterator ``t``. + + +``Predicate predicate() const;`` + +:Returns: A copy of the predicate object used to construct ``*this``. + + +``Iterator end() const;`` + +:Returns: The object ``end`` used to construct ``*this``. + diff --git a/doc/function_output_iterator.rst b/doc/function_output_iterator.rst new file mode 100644 index 0000000..33ea80e --- /dev/null +++ b/doc/function_output_iterator.rst @@ -0,0 +1,23 @@ +++++++++++++++++++++++++++ + Function Output Iterator +++++++++++++++++++++++++++ + +:Author: David Abrahams, Jeremy Siek, Thomas Witt +:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +:organization: `Boost Consulting`_, Indiana University `Open Systems + Lab`_, University of Hanover `Institute for Transport + Railway Operation and Construction`_ +:date: $Date$ +:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved + +.. _`Boost Consulting`: http://www.boost-consulting.com +.. _`Open Systems Lab`: http://www.osl.iu.edu +.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de + +:abstract: + +.. include:: function_output_iterator_abstract.rst + +.. contents:: Table of Contents + +.. include:: function_output_iterator_ref.rst diff --git a/doc/function_output_iterator_abstract.rst b/doc/function_output_iterator_abstract.rst new file mode 100644 index 0000000..11fb4f1 --- /dev/null +++ b/doc/function_output_iterator_abstract.rst @@ -0,0 +1,8 @@ +The function output iterator adaptor makes it easier to create custom +output iterators. The adaptor takes a unary function and creates a +model of Output Iterator. Each item assigned to the output iterator is +passed as an argument to the unary function. The motivation for this +iterator is that creating a conforming output iterator is non-trivial, +particularly because the proper implementation usually requires a +proxy object. + diff --git a/doc/function_output_iterator_ref.rst b/doc/function_output_iterator_ref.rst new file mode 100644 index 0000000..4bb5cf1 --- /dev/null +++ b/doc/function_output_iterator_ref.rst @@ -0,0 +1,77 @@ +:: + + template + class function_output_iterator { + public: + typedef iterator_tag< + writable_iterator_tag + , incrementable_traversal_tag + > iterator_category; + typedef void value_type; + typedef void difference_type; + typedef void pointer; + typedef void reference; + + explicit function_output_iterator(const UnaryFunction& f = UnaryFunction()); + + struct output_proxy { + output_proxy(UnaryFunction& f); + template output_proxy& operator=(const T& value); + }; + output_proxy operator*(); + function_output_iterator& operator++(); + function_output_iterator& operator++(int); + }; + + +``function_output_iterator`` requirements +----------------------------------------- + +The ``UnaryFunction`` must be Assignable, Copy Constructible, and the +expression ``f(x)`` must be valid, where ``f`` is an object of type +``UnaryFunction`` and ``x`` is an object of a type accepted by ``f``. +The resulting ``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());`` + +:Returns: An instance of ``function_output_iterator`` with + ``f`` stored as a data member. + + +``output_proxy operator*();`` + +:Returns: An instance of ``output_proxy`` constructed with + a copy of the unary function ``f``. + + +``function_output_iterator& operator++();`` + +:Returns: ``*this`` + + +``function_output_iterator& operator++(int);`` + +:Returns: ``*this`` + + +``function_output_iterator::output_proxy`` operations +----------------------------------------------------- + +``output_proxy(UnaryFunction& f);`` + +:Returns: An instance of ``output_proxy`` with ``f`` stored as + a data member. + + +``template output_proxy& operator=(const T& value);`` + +:Effects: + :: + + m_f(value); + return *this; diff --git a/doc/indirect_iterator.rst b/doc/indirect_iterator.rst new file mode 100644 index 0000000..7d19ba2 --- /dev/null +++ b/doc/indirect_iterator.rst @@ -0,0 +1,23 @@ ++++++++++++++++++++ + Indirect Iterator ++++++++++++++++++++ + +:Author: David Abrahams, Jeremy Siek, Thomas Witt +:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +:organization: `Boost Consulting`_, Indiana University `Open Systems + Lab`_, University of Hanover `Institute for Transport + Railway Operation and Construction`_ +:date: $Date$ +:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved + +.. _`Boost Consulting`: http://www.boost-consulting.com +.. _`Open Systems Lab`: http://www.osl.iu.edu +.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de + +:abstract: + +.. include:: indirect_iterator_abstract.rst + +.. contents:: Table of Contents + +.. include:: indirect_iterator_ref.rst diff --git a/doc/indirect_iterator_abstract.rst b/doc/indirect_iterator_abstract.rst new file mode 100644 index 0000000..3b6c2a6 --- /dev/null +++ b/doc/indirect_iterator_abstract.rst @@ -0,0 +1,8 @@ +The 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``) as if it were a container of the pointed-to type +(e.g. ``list``) . + +.. At some point we should add the capability to handle + iterators over smart pointers, which the impl handles. -JGS diff --git a/doc/indirect_iterator_ref.rst b/doc/indirect_iterator_ref.rst new file mode 100644 index 0000000..ebbe2ff --- /dev/null +++ b/doc/indirect_iterator_ref.rst @@ -0,0 +1,96 @@ +:: + + template < + class Iterator + , class Value = use_default + , class Category = use_default + , class Reference = use_default + , class Difference = use_default + > + class indirect_iterator + : public iterator_adaptor + { + friend class iterator_core_access; + public: + indirect_iterator(); + indirect_iterator(Iterator x); + template < + class Iterator2, class Value2, class Category2 + , class Reference2, class Difference2 + > + indirect_iterator( + indirect_iterator< + Iterator2, Value2, Category2, Reference2, Difference2 + > const& y + , typename enable_if_convertible::type* = 0 // exposition + ); + private: // as-if specification + typename indirect_iterator::reference dereference() const + { + return **this->base(); + } + }; + +``indirect_iterator`` requirements +.................................. + +The ``value_type`` of the ``Iterator`` template parameter should +itself be dereferenceable. The return type of the ``operator*`` for +the ``value_type`` must be the same type as the ``Reference`` template +parameter. The ``Value`` template parameter will be the ``value_type`` +for the ``indirect_iterator``, unless ``Value`` is const. If ``Value`` +is ``const X``, then ``value_type`` will be *non-* ``const X``. The +default for ``Value`` is + +:: + + iterator_traits< iterator_traits::value_type >::value_type + +If the default is used for ``Value``, then there must be a valid +specialization of ``iterator_traits`` for the value type of the base +iterator. + +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_category``. + +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 +modeled by the value type of ``Iterator``. + + +``indirect_iterator`` operations +................................ + +``indirect_iterator();`` + +:Requires: ``Iterator`` must be Default Constructible. +:Returns: An instance of ``indirect_iterator`` with + a default constructed base object. + + +``indirect_iterator(Iterator x);`` + +:Returns: An instance of ``indirect_iterator`` with + the ``iterator_adaptor`` subobject copy constructed from ``x``. + +:: + + template < + class Iterator2, class Value2, class Category2 + , class Reference2, class Difference2 + > + indirect_iterator( + indirect_iterator< + Iterator2, Value2, Category2, Reference2, Difference2 + > const& y + , typename enable_if_convertible::type* = 0 // exposition + ); + +:Requires: ``Iterator2`` is implicitly convertible to ``Iterator``. +:Returns: An instance of ``indirect_iterator`` that is a copy of ``y``. + diff --git a/doc/permutation_iterator.rst b/doc/permutation_iterator.rst new file mode 100644 index 0000000..3d75608 --- /dev/null +++ b/doc/permutation_iterator.rst @@ -0,0 +1,31 @@ +++++++++++++++++++++++ + Permutation Iterator +++++++++++++++++++++++ + +:Author: Toon Knapen, David Abrahams, Roland Richter, Jeremy Siek +:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu +:organization: `Boost Consulting`_, Indiana University `Open Systems + Lab`_ +:date: $Date$ +:copyright: Copyright Toon Knapen, Dave Abrahams, Roland Richter, and Jeremy Siek 2003. All rights reserved + +.. _`Boost Consulting`: http://www.boost-consulting.com +.. _`Open Systems Lab`: http://www.osl.iu.edu + +:abstract: + +.. include:: permutation_iterator_abstract.rst + +.. contents:: Table of Contents + + +Introduction +============ + +.. include:: permutation_iterator_body.rst + + +Reference +========= + +.. include:: permutation_iterator_ref.rst diff --git a/doc/permutation_iterator_abstract.rst b/doc/permutation_iterator_abstract.rst new file mode 100644 index 0000000..578b3ed --- /dev/null +++ b/doc/permutation_iterator_abstract.rst @@ -0,0 +1,4 @@ +The permutation iterator adaptor provides a permuted view of a given +range. That is, the view includes every element of the given range but +in a potentially different order. + diff --git a/doc/permutation_iterator_body.rst b/doc/permutation_iterator_body.rst new file mode 100644 index 0000000..0f838e7 --- /dev/null +++ b/doc/permutation_iterator_body.rst @@ -0,0 +1,15 @@ +The adaptor takes two arguments: + + * an iterator to the range V on which the permutation + will be applied + * the reindexing scheme that defines how the + elements of V will be permuted. + +Note that the permutation iterator is not limited to strict +permutations of the given range V. The distance between begin and end +of the reindexing iterators is allowed to be smaller compared to the +size of the range V, in which case the permutation iterator only +provides a permutation of a subrange of V. The indexes neither need +to be unique. In this same context, it must be noted that the past the +end permutation iterator is completely defined by means of the +past-the-end iterator to the indices. diff --git a/doc/permutation_iterator_ref.rst b/doc/permutation_iterator_ref.rst new file mode 100644 index 0000000..ef84045 --- /dev/null +++ b/doc/permutation_iterator_ref.rst @@ -0,0 +1,54 @@ +.. parsed-literal:: + + template< class ElementIterator + , class IndexIterator + , class ValueT = use_default + , class CategoryT = use_default + , class ReferenceT = use_default + , class DifferenceT = use_default > + class permutation_iterator + : public iterator_adaptor<...> + { + typedef iterator_adaptor<...> + friend class iterator_core_access; + public: + permutation_iterator(); + explicit permutation_iterator(ElementIterator x, IndexIterator y); + + template< class OEIter, class OIIter, class V, class C, class R, class D > + permutation_iterator( + permutation_iterator const& r + , typename enable_if_convertible::type* = 0 + , typename enable_if_convertible::type* = 0 + ); + }; + + + +``permutation_iterator`` requirements +------------------------------------- + +``ElementIterator`` must be a model of RandomAccessIterator__. +``IndexIterator`` must at least be a model ForwardIterator__. The +value type of the ``IndexIterator`` must be convertible to the +difference type of ``ElementIterator``. + +__ http://www.sgi.com/tech/stl/RandomAccessIterator.html + +__ http://www.sgi.com/tech/stl/ForwardIterator.html + + + + +``permutation_iterator`` operations +----------------------------------- + +The permutation iterator implements the member functions and operators +required for the `Random Access Iterator`__ concept. However, the +permutation iterator can only meet the complexity guarantees of the +same concept as the IndexIterator. Thus for instance, although the +permutation iterator provides ``operator+=(distance)``, this operation +will take linear time in case the IndexIterator is a model of +ForwardIterator instead of amortized constant time. + +__ http://www.sgi.com/tech/stl/RandomAccessIterator.html diff --git a/doc/reverse_iterator.rst b/doc/reverse_iterator.rst new file mode 100644 index 0000000..44b9101 --- /dev/null +++ b/doc/reverse_iterator.rst @@ -0,0 +1,23 @@ +++++++++++++++++++ + Reverse Iterator +++++++++++++++++++ + +:Author: David Abrahams, Jeremy Siek, Thomas Witt +:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +:organization: `Boost Consulting`_, Indiana University `Open Systems + Lab`_, University of Hanover `Institute for Transport + Railway Operation and Construction`_ +:date: $Date$ +:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved + +.. _`Boost Consulting`: http://www.boost-consulting.com +.. _`Open Systems Lab`: http://www.osl.iu.edu +.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de + +:abstract: + +.. include:: reverse_iterator_abstract.rst + +.. contents:: Table of Contents + +.. include:: reverse_iterator_ref.rst diff --git a/doc/reverse_iterator_abstract.rst b/doc/reverse_iterator_abstract.rst new file mode 100644 index 0000000..0574988 --- /dev/null +++ b/doc/reverse_iterator_abstract.rst @@ -0,0 +1,6 @@ +.. I think we'd better strike the old reverse_iterator text from the standard, eh? + +The reverse iterator adaptor flips the direction of a base iterator's +motion. Invoking ``operator++()`` moves the base iterator backward and +invoking ``operator--()`` moves the base iterator forward. + diff --git a/doc/reverse_iterator_ref.rst b/doc/reverse_iterator_ref.rst new file mode 100644 index 0000000..c0acc2b --- /dev/null +++ b/doc/reverse_iterator_ref.rst @@ -0,0 +1,69 @@ +:: + + template + class reverse_iterator : + public iterator_adaptor< reverse_iterator, Iterator > + { + friend class iterator_core_access; + public: + reverse_iterator() {} + explicit reverse_iterator(Iterator x) ; + + template + reverse_iterator( + reverse_iterator const& r + , typename enable_if_convertible::type* = 0 // exposition + ); + + private: // as-if specification + typename reverse_iterator::reference dereference() const { return *prior(this->base()); } + + void increment() { --this->base_reference(); } + void decrement() { ++this->base_reference(); } + + void advance(typename reverse_iterator::difference_type n) + { + this->base_reference() += -n; + } + + template + typename reverse_iterator::difference_type + distance_to(reverse_iterator const& y) const + { + return this->base_reference() - y.base(); + } + + }; + + +``reverse_iterator`` requirements +................................. + +The base ``Iterator`` must be a model of Bidirectional Traversal +Iterator. The resulting ``reverse_iterator`` will be a model of the +most refined standard traversal and access concepts that are modeled +by ``Iterator``. + + +``reverse_iterator();`` + +:Requires: ``Iterator`` must be Default Constructible. +:Returns: An instance of ``reverse_iterator`` with a + default constructed base object. + +``explicit reverse_iterator(Iterator x);`` + +:Returns: An instance of ``reverse_iterator`` with a + base object copy constructed from ``x``. + + +:: + + template + reverse_iterator( + reverse_iterator const& r + , typename enable_if_convertible::type* = 0 // exposition + ); + +:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``. +:Returns: An instance of ``reverse_iterator`` that is a copy of ``r``. diff --git a/doc/transform_iterator.rst b/doc/transform_iterator.rst new file mode 100644 index 0000000..6f8be45 --- /dev/null +++ b/doc/transform_iterator.rst @@ -0,0 +1,23 @@ +++++++++++++++++++++ + Transform Iterator +++++++++++++++++++++ + +:Author: David Abrahams, Jeremy Siek, Thomas Witt +:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +:organization: `Boost Consulting`_, Indiana University `Open Systems + Lab`_, University of Hanover `Institute for Transport + Railway Operation and Construction`_ +:date: $Date$ +:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved + +.. _`Boost Consulting`: http://www.boost-consulting.com +.. _`Open Systems Lab`: http://www.osl.iu.edu +.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de + +:abstract: + +.. include:: transform_iterator_abstract.rst + +.. contents:: Table of Contents + +.. include:: transform_iterator_ref.rst diff --git a/doc/transform_iterator_abstract.rst b/doc/transform_iterator_abstract.rst new file mode 100644 index 0000000..6a7534e --- /dev/null +++ b/doc/transform_iterator_abstract.rst @@ -0,0 +1,5 @@ +The transform iterator adapts an iterator by applying some function +object to the result of dereferencing the iterator. In other words, +the ``operator*`` of the transform iterator first dereferences the +base iterator, passes the result of this to the function object, and +then returns the result. diff --git a/doc/transform_iterator_ref.rst b/doc/transform_iterator_ref.rst new file mode 100644 index 0000000..bb59c1e --- /dev/null +++ b/doc/transform_iterator_ref.rst @@ -0,0 +1,95 @@ +:: + + template + class transform_iterator + : public iterator_adaptor + { + friend class iterator_core_access; + public: + transform_iterator(); + transform_iterator(Iterator const& x, AdaptableUnaryFunction f); + + template + transform_iterator( + transform_iterator const& t + , typename enable_if_convertible::type* = 0 // exposition + ); + + AdaptableUnaryFunction functor() const; + private: + typename transform_iterator::value_type dereference() const; + AdaptableUnaryFunction m_f; + }; + + +``transform_iterator`` requirements +................................... + +The type ``AdaptableUnaryFunction`` must be Assignable, Copy +Constructible, and the expression ``f(x)`` must be valid where ``f`` +is an object of type ``AdaptableUnaryFunction``, ``x`` is an object of +type ``AdaptableUnaryFunction::argument_type``, and where the type of +``f(x)`` must be ``AdaptableUnaryFunction::result_type``. + +The type ``Iterator`` must at least model Readable Iterator. The +resulting ``transform_iterator`` models the most refined of the +following options that is also modeled by ``Iterator``. + + * Writable Lvalue Iterator if the ``result_type`` of the + ``AdaptableUnaryFunction`` is a non-const reference. + + * Readable Lvalue Iterator if the ``result_type`` is a const + reference. + + * Readable Iterator otherwise. + + +The ``transform_iterator`` models the most refined standard traversal +concept that is modeled by ``Iterator``. + +The ``value_type`` of ``transform_iterator`` is +``remove_reference::type``. The ``reference`` type is +``result_type``. + + +``transform_iterator`` public operations +........................................ + + +``transform_iterator();`` + +:Returns: An instance of ``transform_iterator`` with ``m_f`` + and ``m_iterator`` default constructed. + + +``transform_iterator(Iterator const& x, AdaptableUnaryFunction f);`` + +:Returns: An instance of ``transform_iterator`` with ``m_f`` + initialized to ``f`` and ``m_iterator`` initialized to ``x``. + + +:: + + template + transform_iterator( + transform_iterator const& t + , typename enable_if_convertible::type* = 0 // exposition + ); + +:Returns: An instance of ``transform_iterator`` that is a copy of ``t``. +:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``. + +``AdaptableUnaryFunction functor() const;`` + +:Returns: ``m_f`` + +``transform_iterator`` private operations +......................................... + +``typename transform_iterator::value_type dereference() const;`` + +:Returns: ``m_f(transform_iterator::dereference());`` +