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 \return An instance of the \c first_finder object
47 */
48 template<typename RangeT>
49 inline detail::first_finderF<
50 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
51 is_equal>
52 first_finder( const RangeT& Search )
53 {
54 return
55 detail::first_finderF<
56 BOOST_STRING_TYPENAME
57 range_const_iterator<RangeT>::type,
58 is_equal>( ::boost::as_literal(Search), is_equal() ) ;
59 }
60
61 //! "First" finder
62 /*!
63 \overload
64 */
65 template<typename RangeT,typename PredicateT>
66 inline detail::first_finderF<
67 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
68 PredicateT>
69 first_finder(
70 const RangeT& Search, PredicateT Comp )
71 {
72 return
73 detail::first_finderF<
74 BOOST_STRING_TYPENAME
75 range_const_iterator<RangeT>::type,
76 PredicateT>( ::boost::as_literal(Search), Comp );
77 }
78
79 //! "Last" finder
80 /*!
81 Construct the \c last_finder. The finder searches for the last
82 occurrence of the string in a given input.
83 The result is given as an \c iterator_range delimiting the match.
84
85 \param Search A substring to be searched for.
86 \return An instance of the \c last_finder object
87 */
88 template<typename RangeT>
89 inline detail::last_finderF<
90 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
91 is_equal>
92 last_finder( const RangeT& Search )
93 {
94 return
95 detail::last_finderF<
96 BOOST_STRING_TYPENAME
97 range_const_iterator<RangeT>::type,
98 is_equal>( ::boost::as_literal(Search), is_equal() );
99 }
100 //! "Last" finder
101 /*!
102 \overload
103 */
104 template<typename RangeT, typename PredicateT>
105 inline detail::last_finderF<
106 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
107 PredicateT>
108 last_finder( const RangeT& Search, PredicateT Comp )
109 {
110 return
111 detail::last_finderF<
112 BOOST_STRING_TYPENAME
113 range_const_iterator<RangeT>::type,
114 PredicateT>( ::boost::as_literal(Search), Comp ) ;
115 }
116
117 //! "Nth" finder
118 /*!
119 Construct the \c nth_finder. The finder searches for the n-th (zero-indexed)
120 occurrence of the string in a given input.
121 The result is given as an \c iterator_range delimiting the match.
122
123 \param Search A substring to be searched for.
124 \param Nth An index of the match to be find
125 \return An instance of the \c nth_finder object
126 */
127 template<typename RangeT>
128 inline detail::nth_finderF<
129 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
130 is_equal>
131 nth_finder(
132 const RangeT& Search,
133 int Nth)
134 {
135 return
136 detail::nth_finderF<
137 BOOST_STRING_TYPENAME
138 range_const_iterator<RangeT>::type,
139 is_equal>( ::boost::as_literal(Search), Nth, is_equal() ) ;
140 }
141 //! "Nth" finder
142 /*!
143 \overload
144 */
145 template<typename RangeT, typename PredicateT>
146 inline detail::nth_finderF<
147 BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type,
148 PredicateT>
149 nth_finder(
150 const RangeT& Search,
151 int Nth,
152 PredicateT Comp )
153 {
154 return
155 detail::nth_finderF<
156 BOOST_STRING_TYPENAME
157 range_const_iterator<RangeT>::type,
158 PredicateT>( ::boost::as_literal(Search), Nth, Comp );
159 }
160
161 //! "Head" finder
162 /*!
163 Construct the \c head_finder. The finder returns a head of a given
164 input. The head is a prefix of a string up to n elements in
165 size. If an input has less then n elements, whole input is
166 considered a head.
167 The result is given as an \c iterator_range delimiting the match.
168
169 \param N The size of the head
170 \return An instance of the \c head_finder object
171 */
172 inline detail::head_finderF
173 head_finder( int N )
174 {
175 return detail::head_finderF(N);
176 }
177
178 //! "Tail" finder
179 /*!
180 Construct the \c tail_finder. The finder returns a tail of a given
181 input. The tail is a suffix of a string up to n elements in
182 size. If an input has less then n elements, whole input is
183 considered a head.
184 The result is given as an \c iterator_range delimiting the match.
185
186 \param N The size of the head
187 \return An instance of the \c tail_finder object
188 */
189 inline detail::tail_finderF
190 tail_finder( int N )
191 {
192 return detail::tail_finderF(N);
193 }
194
195 //! "Token" finder
196 /*!
197 Construct the \c token_finder. The finder searches for a token
198 specified by a predicate. It is similar to std::find_if
199 algorithm, with an exception that it return a range of
200 instead of a single iterator.
201
202 If "compress token mode" is enabled, adjacent matching tokens are
203 concatenated into one match. Thus the finder can be used to
204 search for continuous segments of characters satisfying the
205 given predicate.
206
207 The result is given as an \c iterator_range delimiting the match.
208
209 \param Pred An element selection predicate
210 \param eCompress Compress flag
211 \return An instance of the \c token_finder object
212 */
213 template< typename PredicateT >
214 inline detail::token_finderF<PredicateT>
215 token_finder(
216 PredicateT Pred,
217 token_compress_mode_type eCompress=token_compress_off )
218 {
219 return detail::token_finderF<PredicateT>( Pred, eCompress );
220 }
221
222 //! "Range" finder
223 /*!
224 Construct the \c range_finder. The finder does not perform
225 any operation. It simply returns the given range for
226 any input.
227
228 \param Begin Beginning of the range
229 \param End End of the range
230 \return An instance of the \c range_finger object
231 */
232 template< typename ForwardIteratorT >
233 inline detail::range_finderF<ForwardIteratorT>
234 range_finder(
235 ForwardIteratorT Begin,
236 ForwardIteratorT End )
237 {
238 return detail::range_finderF<ForwardIteratorT>( Begin, End );
239 }
240
241 //! "Range" finder
242 /*!
243 \overload
244 */
245 template< typename ForwardIteratorT >
246 inline detail::range_finderF<ForwardIteratorT>
247 range_finder( iterator_range<ForwardIteratorT> Range )
248 {
249 return detail::range_finderF<ForwardIteratorT>( Range );
250 }
251
252 } // namespace algorithm
253
254 // pull the names to the boost namespace
255 using algorithm::first_finder;
256 using algorithm::last_finder;
257 using algorithm::nth_finder;
258 using algorithm::head_finder;
259 using algorithm::tail_finder;
260 using algorithm::token_finder;
261 using algorithm::range_finder;
262
263} // namespace boost
264
265
266#endif // BOOST_STRING_FINDER_HPP
267

source code of include/boost/algorithm/string/finder.hpp