1// Boost string_algo library finder.hpp header file ---------------------------//
2
3// Copyright Pavol Droba 2002-2006.
4//
5// Distributed under the Boost Software License, Version 1.0.
6// (See accompanying file LICENSE_1_0.txt or copy at
7// http://www.boost.org/LICENSE_1_0.txt)
8
9// See http://www.boost.org/ for updates, documentation, and revision history.
10
11#ifndef BOOST_STRING_FINDER_HPP
12#define BOOST_STRING_FINDER_HPP
13
14#include <boost/algorithm/string/config.hpp>
15
16#include <boost/range/iterator_range_core.hpp>
17#include <boost/range/begin.hpp>
18#include <boost/range/end.hpp>
19#include <boost/range/iterator.hpp>
20#include <boost/range/const_iterator.hpp>
21
22#include <boost/algorithm/string/constants.hpp>
23#include <boost/algorithm/string/detail/finder.hpp>
24#include <boost/algorithm/string/compare.hpp>
25
26/*! \file
27 Defines Finder generators. Finder object is a functor which is able to
28 find a substring matching a specific criteria in the input.
29 Finders are used as a pluggable components for replace, find
30 and split facilities. This header contains generator functions
31 for finders provided in this library.
32*/
33
34namespace boost {
35 namespace algorithm {
36
37// Finder generators ------------------------------------------//
38
39 //! "First" finder
40 /*!
41 Construct the \c first_finder. The finder searches for the first
42 occurrence of the string in a given input.
43 The result is given as an \c iterator_range delimiting the match.
44
45 \param Search A substring to be searched for.
46 \param Comp An element comparison predicate
47 \return An instance of the \c first_finder object
48 */
49 template<typename RangeT>
50 inline detail::first_finderF<
51 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
52 is_equal>
53 first_finder( const RangeT& Search )
54 {
55 return
56 detail::first_finderF<
57 BOOST_STRING_TYPENAME
58 range_const_iterator<RangeT>::type,
59 is_equal>( ::boost::as_literal(Search), is_equal() ) ;
60 }
61
62 //! "First" finder
63 /*!
64 \overload
65 */
66 template<typename RangeT,typename PredicateT>
67 inline detail::first_finderF<
68 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
69 PredicateT>
70 first_finder(
71 const RangeT& Search, PredicateT Comp )
72 {
73 return
74 detail::first_finderF<
75 BOOST_STRING_TYPENAME
76 range_const_iterator<RangeT>::type,
77 PredicateT>( ::boost::as_literal(Search), Comp );
78 }
79
80 //! "Last" finder
81 /*!
82 Construct the \c last_finder. The finder searches for the last
83 occurrence of the string in a given input.
84 The result is given as an \c iterator_range delimiting the match.
85
86 \param Search A substring to be searched for.
87 \param Comp An element comparison predicate
88 \return An instance of the \c last_finder object
89 */
90 template<typename RangeT>
91 inline detail::last_finderF<
92 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
93 is_equal>
94 last_finder( const RangeT& Search )
95 {
96 return
97 detail::last_finderF<
98 BOOST_STRING_TYPENAME
99 range_const_iterator<RangeT>::type,
100 is_equal>( ::boost::as_literal(Search), is_equal() );
101 }
102 //! "Last" finder
103 /*!
104 \overload
105 */
106 template<typename RangeT, typename PredicateT>
107 inline detail::last_finderF<
108 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
109 PredicateT>
110 last_finder( const RangeT& Search, PredicateT Comp )
111 {
112 return
113 detail::last_finderF<
114 BOOST_STRING_TYPENAME
115 range_const_iterator<RangeT>::type,
116 PredicateT>( ::boost::as_literal(Search), Comp ) ;
117 }
118
119 //! "Nth" finder
120 /*!
121 Construct the \c nth_finder. The finder searches for the n-th (zero-indexed)
122 occurrence of the string in a given input.
123 The result is given as an \c iterator_range delimiting the match.
124
125 \param Search A substring to be searched for.
126 \param Nth An index of the match to be find
127 \param Comp An element comparison predicate
128 \return An instance of the \c nth_finder object
129 */
130 template<typename RangeT>
131 inline detail::nth_finderF<
132 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
133 is_equal>
134 nth_finder(
135 const RangeT& Search,
136 int Nth)
137 {
138 return
139 detail::nth_finderF<
140 BOOST_STRING_TYPENAME
141 range_const_iterator<RangeT>::type,
142 is_equal>( ::boost::as_literal(Search), Nth, is_equal() ) ;
143 }
144 //! "Nth" finder
145 /*!
146 \overload
147 */
148 template<typename RangeT, typename PredicateT>
149 inline detail::nth_finderF<
150 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
151 PredicateT>
152 nth_finder(
153 const RangeT& Search,
154 int Nth,
155 PredicateT Comp )
156 {
157 return
158 detail::nth_finderF<
159 BOOST_STRING_TYPENAME
160 range_const_iterator<RangeT>::type,
161 PredicateT>( ::boost::as_literal(Search), Nth, Comp );
162 }
163
164 //! "Head" finder
165 /*!
166 Construct the \c head_finder. The finder returns a head of a given
167 input. The head is a prefix of a string up to n elements in
168 size. If an input has less then n elements, whole input is
169 considered a head.
170 The result is given as an \c iterator_range delimiting the match.
171
172 \param N The size of the head
173 \return An instance of the \c head_finder object
174 */
175 inline detail::head_finderF
176 head_finder( int N )
177 {
178 return detail::head_finderF(N);
179 }
180
181 //! "Tail" finder
182 /*!
183 Construct the \c tail_finder. The finder returns a tail of a given
184 input. The tail is a suffix of a string up to n elements in
185 size. If an input has less then n elements, whole input is
186 considered a head.
187 The result is given as an \c iterator_range delimiting the match.
188
189 \param N The size of the head
190 \return An instance of the \c tail_finder object
191 */
192 inline detail::tail_finderF
193 tail_finder( int N )
194 {
195 return detail::tail_finderF(N);
196 }
197
198 //! "Token" finder
199 /*!
200 Construct the \c token_finder. The finder searches for a token
201 specified by a predicate. It is similar to std::find_if
202 algorithm, with an exception that it return a range of
203 instead of a single iterator.
204
205 If "compress token mode" is enabled, adjacent matching tokens are
206 concatenated into one match. Thus the finder can be used to
207 search for continuous segments of characters satisfying the
208 given predicate.
209
210 The result is given as an \c iterator_range delimiting the match.
211
212 \param Pred An element selection predicate
213 \param eCompress Compress flag
214 \return An instance of the \c token_finder object
215 */
216 template< typename PredicateT >
217 inline detail::token_finderF<PredicateT>
218 token_finder(
219 PredicateT Pred,
220 token_compress_mode_type eCompress=token_compress_off )
221 {
222 return detail::token_finderF<PredicateT>( Pred, eCompress );
223 }
224
225 //! "Range" finder
226 /*!
227 Construct the \c range_finder. The finder does not perform
228 any operation. It simply returns the given range for
229 any input.
230
231 \param Begin Beginning of the range
232 \param End End of the range
233 \param Range The range.
234 \return An instance of the \c range_finger object
235 */
236 template< typename ForwardIteratorT >
237 inline detail::range_finderF<ForwardIteratorT>
238 range_finder(
239 ForwardIteratorT Begin,
240 ForwardIteratorT End )
241 {
242 return detail::range_finderF<ForwardIteratorT>( Begin, End );
243 }
244
245 //! "Range" finder
246 /*!
247 \overload
248 */
249 template< typename ForwardIteratorT >
250 inline detail::range_finderF<ForwardIteratorT>
251 range_finder( iterator_range<ForwardIteratorT> Range )
252 {
253 return detail::range_finderF<ForwardIteratorT>( Range );
254 }
255
256 } // namespace algorithm
257
258 // pull the names to the boost namespace
259 using algorithm::first_finder;
260 using algorithm::last_finder;
261 using algorithm::nth_finder;
262 using algorithm::head_finder;
263 using algorithm::tail_finder;
264 using algorithm::token_finder;
265 using algorithm::range_finder;
266
267} // namespace boost
268
269
270#endif // BOOST_STRING_FINDER_HPP
271