|  | Home | Libraries | People | FAQ | More | 
        The filter iterator adaptor creates a view of an iterator range in which
        some elements of the range are skipped. A predicate function object controls
        which elements are skipped. When the predicate is applied to an element,
        if it returns true then the
        element is retained and if it returns false
        then the element is skipped over. When skipping over elements, it is necessary
        for the filter adaptor to know when to stop so as to avoid going past the
        end of the underlying range. A filter iterator is therefore constructed with
        pair of iterators indicating the range of elements in the unfiltered sequence
        to be traversed.
      
        This example uses filter_iterator
        and then make_filter_iterator
        to output only the positive integers from an array of integers. Then make_filter_iterator is is used to output
        the integers greater than -2.
      
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_); // Example using filter_iterator typedef boost::filter_iterator<is_positive_number, base_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<int>(std::cout, " ")); std::cout << std::endl; // Example using make_filter_iterator() std::copy(boost::make_filter_iterator<is_positive_number>(numbers, numbers + N), boost::make_filter_iterator<is_positive_number>(numbers + N, numbers + N), std::ostream_iterator<int>(std::cout, " ")); std::cout << std::endl; // Another example using make_filter_iterator() std::copy( boost::make_filter_iterator( std::bind2nd(std::greater<int>(), -2) , numbers, numbers + N) , boost::make_filter_iterator( std::bind2nd(std::greater<int>(), -2) , numbers + N, numbers + N) , std::ostream_iterator<int>(std::cout, " ") ); std::cout << std::endl; return boost::exit_success; }
The output is:
4 5 8 4 5 8 0 -1 4 5 8
The source code for this example can be found here.
template <class Predicate, class Iterator> class filter_iterator { public: typedef iterator_traits<Iterator>::value_type value_type; typedef iterator_traits<Iterator>::reference reference; typedef iterator_traits<Iterator>::pointer pointer; typedef iterator_traits<Iterator>::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()); template<class OtherIterator> filter_iterator( filter_iterator<Predicate, OtherIterator> const& t , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition ); Predicate predicate() const; Iterator end() const; Iterator const& base() const; reference operator*() const; filter_iterator& operator++(); private: Predicate m_pred; // exposition only Iterator m_iter; // exposition only Iterator m_end; // exposition only };
        If Iterator models Readable
        Lvalue Iterator and Bidirectional Traversal Iterator then iterator_category
        is convertible to std::bidirectional_iterator_tag. Otherwise,
        if Iterator models Readable
        Lvalue Iterator and Forward Traversal Iterator then iterator_category
        is convertible to std::forward_iterator_tag. Otherwise iterator_category is convertible to std::input_iterator_tag.
      
        The Iterator argument shall
        meet the requirements of Readable Iterator and Single Pass Iterator or it
        shall meet the requirements of Input Iterator.
      
        The Predicate argument must
        be Assignable, Copy Constructible, and the expression p(x)
        must be valid where p is
        an object of type Predicate,
        x is an object of type iterator_traits<Iterator>::value_type, and where the type of p(x) must be convertible to bool.
      
        The concepts that filter_iterator
        models are dependent on which concepts the Iterator
        argument models, as specified in the following tables.
      
Table 1.12. Traversal
| 
                  If  | 
                  then  | 
|---|---|
| Single Pass Iterator | Single Pass Iterator | 
| Forward Traversal Iterator | Forward Traversal Iterator | 
| Bidirectional Traversal Iterator | Bidirectional Traversal Iterator | 
Table 1.13. Access
| 
                  If  | 
                  then  | 
|---|---|
| Readable Iterator | Readable Iterator | 
| Writable Iterator | Writable Iterator | 
| Lvalue Iterator | Lvalue Iterator | 
Table 1.14. C++03
| 
                  If  | 
                  then  | 
|---|---|
| Readable Iterator, Single Pass Iterator | Input Iterator | 
| Readable Lvalue Iterator, Forward Traversal Iterator | Forward Iterator | 
| Writable Lvalue Iterator, Forward Traversal Iterator | Mutable Forward Iterator | 
| Writable Lvalue Iterator, Bidirectional Iterator | Mutable Bidirectional Iterator | 
        filter_iterator<P1, X> is interoperable with filter_iterator<P2, Y>
        if and only if X is interoperable
        with Y.
      
        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.
 Effects:  Constructs
        a filter_iterator whosem_pred, m_iter,
        and m_end members are a default
        constructed.
      
filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
        Effects:  Constructs a filter_iterator
        where m_iter is either the
        first position in the range [x,end) such that f(*m_iter) == true
        or elsem_iter ==
        end. The member m_pred
        is constructed from f and
        m_end from end.
      
filter_iterator(Iterator x, Iterator end = Iterator());
        Requires:  Predicate
        must be Default Constructible and Predicate
        is a class type (not a function pointer).
 Effects:
         Constructs a filter_iterator
        where m_iter is either the
        first position in the range [x,end) such that m_pred(*m_iter) == true
        or elsem_iter ==
        end. The member m_pred
        is default constructed.
      
template <class OtherIterator> filter_iterator( filter_iterator<Predicate, OtherIterator> const& t , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition );
        Requires:  OtherIterator
        is implicitly convertible to Iterator.
        Effects:  Constructs a filter iterator whose
        members are copied from t.
      
Predicate predicate() const;
        Returns:  m_pred
      
Ierator end() const;
        Returns:  m_end
      
Iterator const& base() const;
        Returns:  m_iterator
      
reference operator*() const;
        Returns:  *m_iter
      
filter_iterator& operator++();
        Effects:  Increments m_iter
        and then continues to increment m_iter
        until either m_iter ==
        m_end or m_pred(*m_iter) == true.
        Returns:  *this