The iterator_category is a type convertible to the tags
+corresponding to each standard concept modeled by filter_iterator,
+as described in the models section.
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
-expression p(x) must be valid where p is an object of type
+
The Predicate argument must be Assignable, Copy Constructible, and
+the expression p(x) must be valid where p is an object of type
Predicate, x is an object of type
iterator_traits<Iterator>::value_type, and where the type of
p(x) must be convertible to bool.
+
The Iterator argument shall meet the requirements of Readable
+Iterator and Single Pass Iterator or it shall meet the requirements of
+Input Iterator.
-
-
diff --git a/doc/filter_iterator.rst b/doc/filter_iterator.rst
index acd770e..3136e48 100644
--- a/doc/filter_iterator.rst
+++ b/doc/filter_iterator.rst
@@ -21,3 +21,5 @@
.. contents:: Table of Contents
.. include:: filter_iterator_ref.rst
+
+.. include:: filter_iterator_eg.rst
diff --git a/doc/filter_iterator_eg.rst b/doc/filter_iterator_eg.rst
new file mode 100644
index 0000000..ae758e8
--- /dev/null
+++ b/doc/filter_iterator_eg.rst
@@ -0,0 +1,38 @@
+
+Example
+-------
+
+This example uses ``filter_iterator`` to output only the positive
+integers from an array of integers.
+
+::
+
+ struct is_positive_number {
+ bool operator()(int x) { return 0 < x; }
+ };
+
+ int main()
+ {
+ int numbers_[] = { 0, -1, 4, -3, 5, 8, -2 };
+ const int N = sizeof(numbers_)/sizeof(int);
+
+ typedef int* base_iterator;
+ base_iterator numbers(numbers_);
+
+ typedef boost::filter_iterator
+ FilterIter;
+
+ is_positive_number predicate;
+ FilterIter filter_iter_first(predicate, numbers, numbers + N);
+ FilterIter filter_iter_last(predicate, numbers + N, numbers + N);
+
+ std::copy(filter_iter_first, filter_iter_last, std::ostream_iterator(std::cout, " "));
+ std::cout << std::endl;
+
+ return 0;
+ }
+
+
+The output is::
+
+ 4 5 8
diff --git a/doc/filter_iterator_ref.rst b/doc/filter_iterator_ref.rst
index 239d2f8..51e47f4 100644
--- a/doc/filter_iterator_ref.rst
+++ b/doc/filter_iterator_ref.rst
@@ -2,13 +2,14 @@
template
class filter_iterator
- : public iterator_adaptor<
- filter_iterator, Iterator
- , use_default
- , /* see details */
- >
{
public:
+ typedef iterator_traits::value_type value_type;
+ typedef iterator_traits::reference reference;
+ typedef iterator_traits::pointer pointer;
+ typedef iterator_traits::difference_type difference_type;
+ typedef /* see below */ iterator_category;
+
filter_iterator();
filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
filter_iterator(Iterator x, Iterator end = Iterator());
@@ -19,51 +20,87 @@
);
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;
};
+The ``iterator_category`` is a type convertible to the tags
+corresponding to each standard concept modeled by ``filter_iterator``,
+as described in the models section.
+
+
+
``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 same as the access category of
-``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
+The ``Predicate`` argument must be Assignable, Copy Constructible, and
+the expression ``p(x)`` must be valid where ``p`` is an object of type
``Predicate``, ``x`` is an object of type
``iterator_traits::value_type``, and where the type of
``p(x)`` must be convertible to ``bool``.
+The ``Iterator`` argument shall meet the requirements of Readable
+Iterator and Single Pass Iterator or it shall meet the requirements of
+Input Iterator.
+
+
+
+``filter_iterator`` models
+--------------------------
+
+The concepts that ``filter_iterator`` models are dependent on what
+concepts the ``Iterator`` argument models, as specified in the
+following tables.
+
++-----------------------------+----------------------------------------------------------+
+| If ``Iterator`` models | then ``filter_iterator`` models |
++=============================+==========================================================+
+| Single Pass Iterator | Single Pass Iterator |
++-----------------------------+----------------------------------------------------------+
+| Forward Traversal Iterator | Forward Traversal Iterator |
++-----------------------------+----------------------------------------------------------+
+
++--------------------------------+----------------------------------------------+
+| If ``Iterator`` models | then ``filter_iterator`` models |
++================================+==============================================+
+| Readable Iterator | Readable Iterator |
++--------------------------------+----------------------------------------------+
+| Writable Iterator | Writable Iterator |
++--------------------------------+----------------------------------------------+
+| Lvalue Iterator | Lvalue Iterator |
++--------------------------------+----------------------------------------------+
+
++-------------------------------------------------------+---------------------------------+
+| If ``Iterator`` models | then ``filter_iterator`` models |
++=======================================================+=================================+
+| Readable Iterator, Single Pass Iterator | Input Iterator |
++-------------------------------------------------------+---------------------------------+
+| Readable Lvalue Iterator, Forward Traversal Iterator | Forward Iterator |
++-------------------------------------------------------+---------------------------------+
+| Writable Lvalue Iterator, Forward Traversal Iterator | Mutable Forward Iterator |
++-------------------------------------------------------+---------------------------------+
+
++-----------------------------+----------------------------------------------------------+
+| If ``Iterator`` models | then ``filter_iterator`` models |
++=============================+==========================================================+
+| Input Iterator | Input Iterator, Readable Iterator, Single Pass Iterator |
++-----------------------------+----------------------------------------------------------+
+| Forward Iterator | Forward Iterator, Readable Lvalue Iterator, |
+| | Forward Traversal Iterator |
++-----------------------------+----------------------------------------------------------+
+| Mutable Forward Iterator | Mutable Forward Iterator, Writable Lvalue Iterator, |
+| | Forward Traversal Iterator |
++-----------------------------+----------------------------------------------------------+
+
``filter_iterator`` operations
------------------------------
+In addition to those operations required by the concepts that
+``filter_iterator`` models, ``filter_iterator`` provides the following
+operations.
+
+
``filter_iterator();``
:Requires: ``Predicate`` and ``Iterator`` must be Default Constructible.
@@ -105,5 +142,5 @@ expression ``p(x)`` must be valid where ``p`` is an object of type
``Iterator end() const;``
-:Returns: The object ``end`` used to construct ``*this``.
+:Returns: A copy of the object ``end`` used to construct ``*this``.