PageRenderTime 119ms CodeModel.GetById 115ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/Src/Dependencies/Boost/libs/iterator/doc/quickbook/filter_iterator.qbk

http://hadesmem.googlecode.com/
text | 242 lines | 167 code | 75 blank | 0 comment | 0 complexity | 1ae6e8cfae633418b1cbbffc3abfcee3 MD5 | raw file
  1
  2[section:filter Filter Iterator]
  3
  4The filter iterator adaptor creates a view of an iterator range in
  5which some elements of the range are skipped. A predicate function
  6object controls which elements are skipped. When the predicate is
  7applied to an element, if it returns `true` then the element is
  8retained and if it returns `false` then the element is skipped
  9over. When skipping over elements, it is necessary for the filter
 10adaptor to know when to stop so as to avoid going past the end of the
 11underlying range. A filter iterator is therefore constructed with pair
 12of iterators indicating the range of elements in the unfiltered
 13sequence to be traversed.
 14
 15[h2 Example]
 16
 17This example uses `filter_iterator` and then
 18`make_filter_iterator` to output only the positive integers from an
 19array of integers. Then `make_filter_iterator` is is used to output
 20the integers greater than `-2`.
 21
 22
 23    struct is_positive_number {
 24      bool operator()(int x) { return 0 < x; }
 25    };
 26
 27    int main()
 28    {
 29      int numbers_[] = { 0, -1, 4, -3, 5, 8, -2 };
 30      const int N = sizeof(numbers_)/sizeof(int);
 31
 32      typedef int* base_iterator;
 33      base_iterator numbers(numbers_);
 34
 35      // Example using filter_iterator
 36      typedef boost::filter_iterator<is_positive_number, base_iterator> 
 37        FilterIter;
 38
 39      is_positive_number predicate;
 40      FilterIter filter_iter_first(predicate, numbers, numbers + N);
 41      FilterIter filter_iter_last(predicate, numbers + N, numbers + N);
 42
 43      std::copy(filter_iter_first, filter_iter_last, std::ostream_iterator<int>(std::cout, " "));
 44      std::cout << std::endl;
 45
 46      // Example using make_filter_iterator()
 47      std::copy(boost::make_filter_iterator<is_positive_number>(numbers, numbers + N),
 48                boost::make_filter_iterator<is_positive_number>(numbers + N, numbers + N),
 49                std::ostream_iterator<int>(std::cout, " "));
 50      std::cout << std::endl;
 51
 52      // Another example using make_filter_iterator()
 53      std::copy(
 54          boost::make_filter_iterator(
 55              std::bind2nd(std::greater<int>(), -2)
 56            , numbers, numbers + N)
 57
 58        , boost::make_filter_iterator(
 59              std::bind2nd(std::greater<int>(), -2)
 60            , numbers + N, numbers + N)
 61
 62        , std::ostream_iterator<int>(std::cout, " ")
 63      );
 64
 65      std::cout << std::endl;
 66
 67      return boost::exit_success;
 68    }
 69
 70
 71The output is:
 72
 73    4 5 8 
 74    4 5 8 
 75    0 -1 4 5 8 
 76
 77
 78The source code for this example can be found [@../example/filter_iterator_example.cpp here].
 79
 80[h2 Reference]
 81
 82
 83[h3 Synopsis]
 84
 85  template <class Predicate, class Iterator>
 86  class filter_iterator
 87  {
 88   public:
 89      typedef iterator_traits<Iterator>::value_type value_type;
 90      typedef iterator_traits<Iterator>::reference reference;
 91      typedef iterator_traits<Iterator>::pointer pointer;
 92      typedef iterator_traits<Iterator>::difference_type difference_type;
 93      typedef /* see below */ iterator_category;
 94
 95      filter_iterator();
 96      filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
 97      filter_iterator(Iterator x, Iterator end = Iterator());
 98      template<class OtherIterator>
 99      filter_iterator(
100          filter_iterator<Predicate, OtherIterator> const& t
101          , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
102          );
103      Predicate predicate() const;
104      Iterator end() const;
105      Iterator const& base() const;
106      reference operator*() const;
107      filter_iterator& operator++();
108  private:
109      Predicate m_pred; // exposition only
110      Iterator m_iter;  // exposition only
111      Iterator m_end;   // exposition only
112  };
113
114
115If `Iterator` models Readable Lvalue Iterator and Bidirectional Traversal
116Iterator then `iterator_category` is convertible to
117`std::bidirectional_iterator_tag`. 
118Otherwise, if `Iterator` models Readable Lvalue Iterator and Forward Traversal
119Iterator then `iterator_category` is convertible to
120`std::forward_iterator_tag`. 
121Otherwise `iterator_category` is
122convertible to `std::input_iterator_tag`.
123
124
125[h3 Requirements]
126
127The `Iterator` argument shall meet the requirements of Readable
128Iterator and Single Pass Iterator or it shall meet the requirements of
129Input Iterator.
130
131
132The `Predicate` argument must be Assignable, Copy Constructible, and
133the expression `p(x)` must be valid where `p` is an object of type
134`Predicate`, `x` is an object of type
135`iterator_traits<Iterator>::value_type`, and where the type of
136`p(x)` must be convertible to `bool`.
137
138
139[h3 Concepts]
140
141The concepts that `filter_iterator` models are dependent on which
142concepts the `Iterator` argument models, as specified in the
143following tables.
144
145[table Traversal
146       [[If `Iterator` models             ][then `filter_iterator` models   ]]
147       [[Single Pass Iterator             ][Single Pass Iterator            ]]
148       [[Forward Traversal Iterator       ][Forward Traversal Iterator      ]]
149       [[Bidirectional Traversal Iterator ][Bidirectional Traversal Iterator]]
150]
151
152[table Access
153       [[If `Iterator` models             ][then `filter_iterator` models   ]]
154       [[Readable Iterator][Readable Iterator]]
155       [[Writable Iterator][Writable Iterator]]
156       [[Lvalue Iterator  ][Lvalue Iterator  ]]
157]
158
159[table C++03
160       [[If `Iterator` models             ][then `filter_iterator` models   ]]
161       [[Readable Iterator, Single Pass Iterator             ][Input Iterator                ]]
162       [[Readable Lvalue Iterator, Forward Traversal Iterator][Forward Iterator              ]]
163       [[Writable Lvalue Iterator, Forward Traversal Iterator][Mutable Forward Iterator      ]]
164       [[Writable Lvalue Iterator, Bidirectional Iterator    ][Mutable Bidirectional Iterator]]
165]
166
167`filter_iterator<P1, X>` is interoperable with `filter_iterator<P2, Y>` 
168if and only if `X` is interoperable with `Y`.
169
170
171[h3 Operations]
172
173
174In addition to those operations required by the concepts that
175`filter_iterator` models, `filter_iterator` provides the following
176operations.
177
178
179  filter_iterator();
180
181[*Requires: ]`Predicate` and `Iterator` must be Default Constructible.\n
182[*Effects: ] Constructs a `filter_iterator` whose`m_pred`,  `m_iter`, and `m_end` 
183  members are a default constructed.
184
185
186  filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
187
188[*Effects: ] Constructs a `filter_iterator` where `m_iter` is either
189    the first position in the range `[x,end)` such that `f(*m_iter) == true` 
190    or else`m_iter == end`. The member `m_pred` is constructed from
191    `f` and `m_end` from `end`.
192
193
194
195  filter_iterator(Iterator x, Iterator end = Iterator());
196
197[*Requires: ] `Predicate` must be Default Constructible and
198  `Predicate` is a class type (not a function pointer).\n
199[*Effects: ] Constructs a `filter_iterator` where `m_iter` is either
200    the first position in the range `[x,end)` such that `m_pred(*m_iter) == true` 
201    or else`m_iter == end`. The member `m_pred` is default constructed.
202
203
204    template <class OtherIterator>
205    filter_iterator(
206        filter_iterator<Predicate, OtherIterator> const& t
207        , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
208        );`
209
210[*Requires: ] `OtherIterator` is implicitly convertible to `Iterator`.\n
211[*Effects: ] Constructs a filter iterator whose members are copied from `t`.
212
213
214  Predicate predicate() const;
215
216[*Returns: ] `m_pred`
217
218
219   Ierator end() const;
220
221[*Returns: ] `m_end`
222
223
224  Iterator const& base() const;
225
226[*Returns: ] `m_iterator`
227
228
229  reference operator*() const;
230
231[*Returns: ] `*m_iter`
232
233
234  filter_iterator& operator++();
235
236[*Effects: ] Increments `m_iter` and then continues to
237  increment `m_iter` until either `m_iter == m_end`
238  or `m_pred(*m_iter) == true`.\n
239[*Returns: ] `*this`  
240
241
242[endsect]