diff --git a/filter_iterator.htm b/filter_iterator.htm index e662116..3c79776 100644 --- a/filter_iterator.htm +++ b/filter_iterator.htm @@ -19,25 +19,179 @@ Defined in header

-The filter iterator adaptor ... +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. +

Synopsis

+ +
+namespace boost {
+  template <class Predicate, class Iterator, ...>
+  class filter_iterator_generator;
+
+  template <class Predicate, class Iterator>
+  typename filter_iterator_generator<Predicate, Iterator>::type
+  make_filter_iterator(Iterator first, Iterator last, const Predicate& p = Predicate());
+}
+
+ + +

The Filter Iterator Type +Generator

+ +The class filter_iterator_generator is a helper class who's +purpose is to construct a filter iterator adaptor type. The template +parameters for this class are the Predicate function object +type and the Iterator type that is being wrapped. In most +cases the associated types for the wrapped iterator can be deduced +from std::iterator_traits, but in some situations the user +may want to override these types, so there are also template +parameters for each of the iterator's associated types. + +
+template <class Predicate, 
+          class Iterator,
+          class Value = std::iterator_traits<Iterator>::value_type,
+          class Pointer = std::iterator_traits<Iterator>::pointer,
+          class Reference = std::iterator_traits<Iterator>::reference,
+          class Category = std::iterator_traits<Iterator>::iterator_category,
+          class Distance = std::iterator_traits<Iterator>::difference_type,
+class filter_iterator_generator
+{
+public:
+  typedef ... type;          // the filter iterator_adaptor type
+  typedef ... policies_type; // the filter policies type
+}
+

Example

The following example uses filter iterator to print out all the -positive integers in an array. +positive integers in an array. 
-#include <boost/config.hpp>
-#include <algorithm>
-#include <iostream>
-#include <boost/iterator_adaptors.hpp>
-
 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 boost::filter_iterator_generator<is_positive_number, int*, int> Gen;
+  is_positive_number predicate;
+  Gen::policies_type policies(numbers + N, predicate);
+  Gen::type filter_iter_first(numbers, policies);
+  Gen::type filter_iter_last(numbers + N, policies);
+
+  std::copy(filter_iter_first, filter_iter_last, std::ostream_iterator<int>(std::cout, " "));
+  std::cout << std::endl;
+  return 0;
+}
+
+The output is: +
+4 5 8
+
+ + +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
PredicateThe function object that determines which elements are retained and which elements are skipped. +
IteratorThe iterator type being wrapped. This type must be a model + of either the InputIterator concept or the OutputIterator concept.
ValueThe value_type for the iterator adaptor. Typically the default for +this parameter is the appropriate type[1].
+Default: std::iterator_traits<Iterator>::value_type
PointerThe pointer type for the iterator adaptor. Typically the default for +this parameter is the appropriate type.
+Default: std::iterator_traits<Iterator>::pointer
ReferenceThe reference type for the iterator adaptor. Typically the default for +this parameter is the appropriate type.
+Default: std::iterator_traits<Iterator>::reference
CategoryThe iterator_category type for the iterator adaptor. +Typically the +default for this parameter is the appropriate type. If you override +this parameter, do not use bidirectional_iterator_tag +because filter iterators can not go in reverse.
+Default: std::iterator_traits<Iterator>::iterator_category
DistanceThe difference_type for the iterator adaptor. Typically the default for +this parameter is the appropriate type.
+Default: std::iterator_traits<Iterator>::difference_type
+ + +

Model of

+ +The filter iterator adaptor (the type +filter_iterator_generator<...>::type) may be a model of InputIterator or ForwardIterator +depending on the adapted iterator type. + +

+ +

+

+ +

The Make Filter Iterator Function

+ +
+template <class Predicate, class Iterator>
+typename detail::filter_generator<Predicate, Iterator>::type
+make_filter_iterator(Iterator first, Iterator last, const Predicate& p = Predicate())
+
+ +This function provides a convenient way to create filter iterators. + +

Example

+ +In this example we print the positive number again, this time using +the make_filter_iterator() function. + +
+struct is_positive_number {
+  bool operator()(int x) { return 0 < x; }
+};
 int main()
 {
   int numbers[] = { 0, -1, 4, -3, 5, 8, -2 };
@@ -56,39 +210,12 @@ The output is:
-The filter iterator adaptors -models ForwardIterator +

Notes

- - -

The Filter Iterator Type Generator

- -
-template <class Predicate, 
-          class Iterator,
-          class Value = value default,
-          class Pointer = pointer default,
-          class Reference = reference default,
-          class Category = category default,
-          class Distance = difference type default>
-class filter_iterator_generator
-{
-  typedef ... type;
-  typedef ... policies_type;
-}
-
- -

-show another example and explain defaults... - - -

The Make Filter Iterator Helper Function

- -
-template <class Predicate, class Iterator>
-inline typename detail::filter_generator<Predicate, Iterator>::type
-make_filter_iterator(Iterator first, Iterator last, const Predicate& p = Predicate())
-
+[1] If the compiler does not support partial +specialization and the wrapped iterator type is a builtin pointer then +the Value type must be explicitly specified (don't use the +default).