1// Boost string_algo library find.hpp header file ---------------------------//
2
3// Copyright Pavol Droba 2002-2003.
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_FIND_HPP
12#define BOOST_STRING_FIND_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/as_literal.hpp>
21
22#include <boost/algorithm/string/finder.hpp>
23#include <boost/algorithm/string/compare.hpp>
24#include <boost/algorithm/string/constants.hpp>
25
26/*! \file
27 Defines a set of find algorithms. The algorithms are searching
28 for a substring of the input. The result is given as an \c iterator_range
29 delimiting the substring.
30*/
31
32namespace boost {
33 namespace algorithm {
34
35// Generic find -----------------------------------------------//
36
37 //! Generic find algorithm
38 /*!
39 Search the input using the given finder.
40
41 \param Input A string which will be searched.
42 \param Finder Finder object used for searching.
43 \return
44 An \c iterator_range delimiting the match.
45 Returned iterator is either \c RangeT::iterator or
46 \c RangeT::const_iterator, depending on the constness of
47 the input parameter.
48 */
49 template<typename RangeT, typename FinderT>
50 inline iterator_range<
51 BOOST_STRING_TYPENAME range_iterator<RangeT>::type>
52 find(
53 RangeT& Input,
54 const FinderT& Finder)
55 {
56 iterator_range<BOOST_STRING_TYPENAME range_iterator<RangeT>::type> lit_input(::boost::as_literal(Input));
57
58 return Finder(::boost::begin(lit_input),::boost::end(lit_input));
59 }
60
61// find_first -----------------------------------------------//
62
63 //! Find first algorithm
64 /*!
65 Search for the first occurrence of the substring in the input.
66
67 \param Input A string which will be searched.
68 \param Search A substring to be searched for.
69 \return
70 An \c iterator_range delimiting the match.
71 Returned iterator is either \c RangeT::iterator or
72 \c RangeT::const_iterator, depending on the constness of
73 the input parameter.
74
75 \note This function provides the strong exception-safety guarantee
76 */
77 template<typename Range1T, typename Range2T>
78 inline iterator_range<
79 BOOST_STRING_TYPENAME range_iterator<Range1T>::type>
80 find_first(
81 Range1T& Input,
82 const Range2T& Search)
83 {
84 return ::boost::algorithm::find(Input, ::boost::algorithm::first_finder(Search));
85 }
86
87 //! Find first algorithm ( case insensitive )
88 /*!
89 Search for the first occurrence of the substring in the input.
90 Searching is case insensitive.
91
92 \param Input A string which will be searched.
93 \param Search A substring to be searched for.
94 \param Loc A locale used for case insensitive comparison
95 \return
96 An \c iterator_range delimiting the match.
97 Returned iterator is either \c Range1T::iterator or
98 \c Range1T::const_iterator, depending on the constness of
99 the input parameter.
100
101 \note This function provides the strong exception-safety guarantee
102 */
103 template<typename Range1T, typename Range2T>
104 inline iterator_range<
105 BOOST_STRING_TYPENAME range_iterator<Range1T>::type>
106 ifind_first(
107 Range1T& Input,
108 const Range2T& Search,
109 const std::locale& Loc=std::locale())
110 {
111 return ::boost::algorithm::find(Input, ::boost::algorithm::first_finder(Search,is_iequal(Loc)));
112 }
113
114// find_last -----------------------------------------------//
115
116 //! Find last algorithm
117 /*!
118 Search for the last occurrence of the substring in the input.
119
120 \param Input A string which will be searched.
121 \param Search A substring to be searched for.
122 \return
123 An \c iterator_range delimiting the match.
124 Returned iterator is either \c Range1T::iterator or
125 \c Range1T::const_iterator, depending on the constness of
126 the input parameter.
127
128 \note This function provides the strong exception-safety guarantee
129 */
130 template<typename Range1T, typename Range2T>
131 inline iterator_range<
132 BOOST_STRING_TYPENAME range_iterator<Range1T>::type>
133 find_last(
134 Range1T& Input,
135 const Range2T& Search)
136 {
137 return ::boost::algorithm::find(Input, ::boost::algorithm::last_finder(Search));
138 }
139
140 //! Find last algorithm ( case insensitive )
141 /*!
142 Search for the last match a string in the input.
143 Searching is case insensitive.
144
145 \param Input A string which will be searched.
146 \param Search A substring to be searched for.
147 \param Loc A locale used for case insensitive comparison
148 \return
149 An \c iterator_range delimiting the match.
150 Returned iterator is either \c Range1T::iterator or
151 \c Range1T::const_iterator, depending on the constness of
152 the input parameter.
153
154 \note This function provides the strong exception-safety guarantee
155 */
156 template<typename Range1T, typename Range2T>
157 inline iterator_range<
158 BOOST_STRING_TYPENAME range_iterator<Range1T>::type>
159 ifind_last(
160 Range1T& Input,
161 const Range2T& Search,
162 const std::locale& Loc=std::locale())
163 {
164 return ::boost::algorithm::find(Input, ::boost::algorithm::last_finder(Search, is_iequal(Loc)));
165 }
166
167// find_nth ----------------------------------------------------------------------//
168
169 //! Find n-th algorithm
170 /*!
171 Search for the n-th (zero-indexed) occurrence of the substring in the
172 input.
173
174 \param Input A string which will be searched.
175 \param Search A substring to be searched for.
176 \param Nth An index (zero-indexed) of the match to be found.
177 For negative N, the matches are counted from the end of string.
178 \return
179 An \c iterator_range delimiting the match.
180 Returned iterator is either \c Range1T::iterator or
181 \c Range1T::const_iterator, depending on the constness of
182 the input parameter.
183 */
184 template<typename Range1T, typename Range2T>
185 inline iterator_range<
186 BOOST_STRING_TYPENAME range_iterator<Range1T>::type>
187 find_nth(
188 Range1T& Input,
189 const Range2T& Search,
190 int Nth)
191 {
192 return ::boost::algorithm::find(Input, ::boost::algorithm::nth_finder(Search,Nth));
193 }
194
195 //! Find n-th algorithm ( case insensitive ).
196 /*!
197 Search for the n-th (zero-indexed) occurrence of the substring in the
198 input. Searching is case insensitive.
199
200 \param Input A string which will be searched.
201 \param Search A substring to be searched for.
202 \param Nth An index (zero-indexed) of the match to be found.
203 For negative N, the matches are counted from the end of string.
204 \param Loc A locale used for case insensitive comparison
205 \return
206 An \c iterator_range delimiting the match.
207 Returned iterator is either \c Range1T::iterator or
208 \c Range1T::const_iterator, depending on the constness of
209 the input parameter.
210
211
212 \note This function provides the strong exception-safety guarantee
213 */
214 template<typename Range1T, typename Range2T>
215 inline iterator_range<
216 BOOST_STRING_TYPENAME range_iterator<Range1T>::type>
217 ifind_nth(
218 Range1T& Input,
219 const Range2T& Search,
220 int Nth,
221 const std::locale& Loc=std::locale())
222 {
223 return ::boost::algorithm::find(Input, ::boost::algorithm::nth_finder(Search,Nth,is_iequal(Loc)));
224 }
225
226// find_head ----------------------------------------------------------------------//
227
228 //! Find head algorithm
229 /*!
230 Get the head of the input. Head is a prefix of the string of the
231 given size. If the input is shorter then required, whole input is considered
232 to be the head.
233
234 \param Input An input string
235 \param N Length of the head
236 For N>=0, at most N characters are extracted.
237 For N<0, at most size(Input)-|N| characters are extracted.
238 \return
239 An \c iterator_range delimiting the match.
240 Returned iterator is either \c Range1T::iterator or
241 \c Range1T::const_iterator, depending on the constness of
242 the input parameter.
243
244 \note This function provides the strong exception-safety guarantee
245 */
246 template<typename RangeT>
247 inline iterator_range<
248 BOOST_STRING_TYPENAME range_iterator<RangeT>::type>
249 find_head(
250 RangeT& Input,
251 int N)
252 {
253 return ::boost::algorithm::find(Input, ::boost::algorithm::head_finder(N));
254 }
255
256// find_tail ----------------------------------------------------------------------//
257
258 //! Find tail algorithm
259 /*!
260 Get the tail of the input. Tail is a suffix of the string of the
261 given size. If the input is shorter then required, whole input is considered
262 to be the tail.
263
264 \param Input An input string
265 \param N Length of the tail.
266 For N>=0, at most N characters are extracted.
267 For N<0, at most size(Input)-|N| characters are extracted.
268 \return
269 An \c iterator_range delimiting the match.
270 Returned iterator is either \c RangeT::iterator or
271 \c RangeT::const_iterator, depending on the constness of
272 the input parameter.
273
274
275 \note This function provides the strong exception-safety guarantee
276 */
277 template<typename RangeT>
278 inline iterator_range<
279 BOOST_STRING_TYPENAME range_iterator<RangeT>::type>
280 find_tail(
281 RangeT& Input,
282 int N)
283 {
284 return ::boost::algorithm::find(Input, ::boost::algorithm::tail_finder(N));
285 }
286
287// find_token --------------------------------------------------------------------//
288
289 //! Find token algorithm
290 /*!
291 Look for a given token in the string. Token is a character that matches the
292 given predicate.
293 If the "token compress mode" is enabled, adjacent tokens are considered to be one match.
294
295 \param Input A input string.
296 \param Pred A unary predicate to identify a token
297 \param eCompress Enable/Disable compressing of adjacent tokens
298 \return
299 An \c iterator_range delimiting the match.
300 Returned iterator is either \c RangeT::iterator or
301 \c RangeT::const_iterator, depending on the constness of
302 the input parameter.
303
304 \note This function provides the strong exception-safety guarantee
305 */
306 template<typename RangeT, typename PredicateT>
307 inline iterator_range<
308 BOOST_STRING_TYPENAME range_iterator<RangeT>::type>
309 find_token(
310 RangeT& Input,
311 PredicateT Pred,
312 token_compress_mode_type eCompress=token_compress_off)
313 {
314 return ::boost::algorithm::find(Input, ::boost::algorithm::token_finder(Pred, eCompress));
315 }
316
317 } // namespace algorithm
318
319 // pull names to the boost namespace
320 using algorithm::find;
321 using algorithm::find_first;
322 using algorithm::ifind_first;
323 using algorithm::find_last;
324 using algorithm::ifind_last;
325 using algorithm::find_nth;
326 using algorithm::ifind_nth;
327 using algorithm::find_head;
328 using algorithm::find_tail;
329 using algorithm::find_token;
330
331} // namespace boost
332
333
334#endif // BOOST_STRING_FIND_HPP
335

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