1// Boost string_algo library trim.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_TRIM_HPP
12#define BOOST_STRING_TRIM_HPP
13
14#include <boost/algorithm/string/config.hpp>
15
16#include <boost/range/begin.hpp>
17#include <boost/range/end.hpp>
18#include <boost/range/const_iterator.hpp>
19#include <boost/range/as_literal.hpp>
20#include <boost/range/iterator_range_core.hpp>
21
22#include <boost/algorithm/string/detail/trim.hpp>
23#include <boost/algorithm/string/classification.hpp>
24#include <locale>
25
26/*! \file
27 Defines trim algorithms.
28 Trim algorithms are used to remove trailing and leading spaces from a
29 sequence (string). Space is recognized using given locales.
30
31 Parametric (\c _if) variants use a predicate (functor) to select which characters
32 are to be trimmed..
33 Functions take a selection predicate as a parameter, which is used to determine
34 whether a character is a space. Common predicates are provided in classification.hpp header.
35
36*/
37
38namespace boost {
39 namespace algorithm {
40
41 // left trim -----------------------------------------------//
42
43
44 //! Left trim - parametric
45 /*!
46 Remove all leading spaces from the input.
47 The supplied predicate is used to determine which characters are considered spaces.
48 The result is a trimmed copy of the input. It is returned as a sequence
49 or copied to the output iterator
50
51 \param Output An output iterator to which the result will be copied
52 \param Input An input range
53 \param IsSpace A unary predicate identifying spaces
54 \return
55 An output iterator pointing just after the last inserted character or
56 a copy of the input
57
58 \note The second variant of this function provides the strong exception-safety guarantee
59 */
60 template<typename OutputIteratorT, typename RangeT, typename PredicateT>
61 inline OutputIteratorT trim_left_copy_if(
62 OutputIteratorT Output,
63 const RangeT& Input,
64 PredicateT IsSpace)
65 {
66 iterator_range<BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type> lit_range(::boost::as_literal(Input));
67
68 std::copy(
69 ::boost::algorithm::detail::trim_begin(
70 ::boost::begin(lit_range),
71 ::boost::end(lit_range),
72 IsSpace ),
73 ::boost::end(lit_range),
74 Output);
75
76 return Output;
77 }
78
79 //! Left trim - parametric
80 /*!
81 \overload
82 */
83 template<typename SequenceT, typename PredicateT>
84 inline SequenceT trim_left_copy_if(const SequenceT& Input, PredicateT IsSpace)
85 {
86 return SequenceT(
87 ::boost::algorithm::detail::trim_begin(
88 ::boost::begin(Input),
89 ::boost::end(Input),
90 IsSpace ),
91 ::boost::end(Input));
92 }
93
94 //! Left trim - parametric
95 /*!
96 Remove all leading spaces from the input.
97 The result is a trimmed copy of the input.
98
99 \param Input An input sequence
100 \param Loc a locale used for 'space' classification
101 \return A trimmed copy of the input
102
103 \note This function provides the strong exception-safety guarantee
104 */
105 template<typename SequenceT>
106 inline SequenceT trim_left_copy(const SequenceT& Input, const std::locale& Loc=std::locale())
107 {
108 return
109 ::boost::algorithm::trim_left_copy_if(
110 Input,
111 is_space(Loc));
112 }
113
114 //! Left trim
115 /*!
116 Remove all leading spaces from the input. The supplied predicate is
117 used to determine which characters are considered spaces.
118 The input sequence is modified in-place.
119
120 \param Input An input sequence
121 \param IsSpace A unary predicate identifying spaces
122 */
123 template<typename SequenceT, typename PredicateT>
124 inline void trim_left_if(SequenceT& Input, PredicateT IsSpace)
125 {
126 Input.erase(
127 ::boost::begin(Input),
128 ::boost::algorithm::detail::trim_begin(
129 ::boost::begin(Input),
130 ::boost::end(Input),
131 IsSpace));
132 }
133
134 //! Left trim
135 /*!
136 Remove all leading spaces from the input.
137 The Input sequence is modified in-place.
138
139 \param Input An input sequence
140 \param Loc A locale used for 'space' classification
141 */
142 template<typename SequenceT>
143 inline void trim_left(SequenceT& Input, const std::locale& Loc=std::locale())
144 {
145 ::boost::algorithm::trim_left_if(
146 Input,
147 is_space(Loc));
148 }
149
150 // right trim -----------------------------------------------//
151
152 //! Right trim - parametric
153 /*!
154 Remove all trailing spaces from the input.
155 The supplied predicate is used to determine which characters are considered spaces.
156 The result is a trimmed copy of the input. It is returned as a sequence
157 or copied to the output iterator
158
159 \param Output An output iterator to which the result will be copied
160 \param Input An input range
161 \param IsSpace A unary predicate identifying spaces
162 \return
163 An output iterator pointing just after the last inserted character or
164 a copy of the input
165
166 \note The second variant of this function provides the strong exception-safety guarantee
167 */
168 template<typename OutputIteratorT, typename RangeT, typename PredicateT>
169 inline OutputIteratorT trim_right_copy_if(
170 OutputIteratorT Output,
171 const RangeT& Input,
172 PredicateT IsSpace )
173 {
174 iterator_range<BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type> lit_range(::boost::as_literal(Input));
175
176 std::copy(
177 ::boost::begin(lit_range),
178 ::boost::algorithm::detail::trim_end(
179 ::boost::begin(lit_range),
180 ::boost::end(lit_range),
181 IsSpace ),
182 Output );
183
184 return Output;
185 }
186
187 //! Right trim - parametric
188 /*!
189 \overload
190 */
191 template<typename SequenceT, typename PredicateT>
192 inline SequenceT trim_right_copy_if(const SequenceT& Input, PredicateT IsSpace)
193 {
194 return SequenceT(
195 ::boost::begin(Input),
196 ::boost::algorithm::detail::trim_end(
197 ::boost::begin(Input),
198 ::boost::end(Input),
199 IsSpace)
200 );
201 }
202
203 //! Right trim
204 /*!
205 Remove all trailing spaces from the input.
206 The result is a trimmed copy of the input
207
208 \param Input An input sequence
209 \param Loc A locale used for 'space' classification
210 \return A trimmed copy of the input
211
212 \note This function provides the strong exception-safety guarantee
213 */
214 template<typename SequenceT>
215 inline SequenceT trim_right_copy(const SequenceT& Input, const std::locale& Loc=std::locale())
216 {
217 return
218 ::boost::algorithm::trim_right_copy_if(
219 Input,
220 is_space(Loc));
221 }
222
223
224 //! Right trim - parametric
225 /*!
226 Remove all trailing spaces from the input.
227 The supplied predicate is used to determine which characters are considered spaces.
228 The input sequence is modified in-place.
229
230 \param Input An input sequence
231 \param IsSpace A unary predicate identifying spaces
232 */
233 template<typename SequenceT, typename PredicateT>
234 inline void trim_right_if(SequenceT& Input, PredicateT IsSpace)
235 {
236 Input.erase(
237 ::boost::algorithm::detail::trim_end(
238 ::boost::begin(Input),
239 ::boost::end(Input),
240 IsSpace ),
241 ::boost::end(Input)
242 );
243 }
244
245
246 //! Right trim
247 /*!
248 Remove all trailing spaces from the input.
249 The input sequence is modified in-place.
250
251 \param Input An input sequence
252 \param Loc A locale used for 'space' classification
253 */
254 template<typename SequenceT>
255 inline void trim_right(SequenceT& Input, const std::locale& Loc=std::locale())
256 {
257 ::boost::algorithm::trim_right_if(
258 Input,
259 is_space(Loc) );
260 }
261
262 // both side trim -----------------------------------------------//
263
264 //! Trim - parametric
265 /*!
266 Remove all trailing and leading spaces from the input.
267 The supplied predicate is used to determine which characters are considered spaces.
268 The result is a trimmed copy of the input. It is returned as a sequence
269 or copied to the output iterator
270
271 \param Output An output iterator to which the result will be copied
272 \param Input An input range
273 \param IsSpace A unary predicate identifying spaces
274 \return
275 An output iterator pointing just after the last inserted character or
276 a copy of the input
277
278 \note The second variant of this function provides the strong exception-safety guarantee
279 */
280 template<typename OutputIteratorT, typename RangeT, typename PredicateT>
281 inline OutputIteratorT trim_copy_if(
282 OutputIteratorT Output,
283 const RangeT& Input,
284 PredicateT IsSpace)
285 {
286 iterator_range<BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type> lit_range(::boost::as_literal(Input));
287
288 BOOST_STRING_TYPENAME
289 range_const_iterator<RangeT>::type TrimEnd=
290 ::boost::algorithm::detail::trim_end(
291 ::boost::begin(lit_range),
292 ::boost::end(lit_range),
293 IsSpace);
294
295 std::copy(
296 detail::trim_begin(
297 ::boost::begin(lit_range), TrimEnd, IsSpace),
298 TrimEnd,
299 Output
300 );
301
302 return Output;
303 }
304
305 //! Trim - parametric
306 /*!
307 \overload
308 */
309 template<typename SequenceT, typename PredicateT>
310 inline SequenceT trim_copy_if(const SequenceT& Input, PredicateT IsSpace)
311 {
312 BOOST_STRING_TYPENAME
313 range_const_iterator<SequenceT>::type TrimEnd=
314 ::boost::algorithm::detail::trim_end(
315 ::boost::begin(Input),
316 ::boost::end(Input),
317 IsSpace);
318
319 return SequenceT(
320 detail::trim_begin(
321 ::boost::begin(Input),
322 TrimEnd,
323 IsSpace),
324 TrimEnd
325 );
326 }
327
328 //! Trim
329 /*!
330 Remove all leading and trailing spaces from the input.
331 The result is a trimmed copy of the input
332
333 \param Input An input sequence
334 \param Loc A locale used for 'space' classification
335 \return A trimmed copy of the input
336
337 \note This function provides the strong exception-safety guarantee
338 */
339 template<typename SequenceT>
340 inline SequenceT trim_copy( const SequenceT& Input, const std::locale& Loc=std::locale() )
341 {
342 return
343 ::boost::algorithm::trim_copy_if(
344 Input,
345 is_space(Loc) );
346 }
347
348 //! Trim
349 /*!
350 Remove all leading and trailing spaces from the input.
351 The supplied predicate is used to determine which characters are considered spaces.
352 The input sequence is modified in-place.
353
354 \param Input An input sequence
355 \param IsSpace A unary predicate identifying spaces
356 */
357 template<typename SequenceT, typename PredicateT>
358 inline void trim_if(SequenceT& Input, PredicateT IsSpace)
359 {
360 ::boost::algorithm::trim_right_if( Input, IsSpace );
361 ::boost::algorithm::trim_left_if( Input, IsSpace );
362 }
363
364 //! Trim
365 /*!
366 Remove all leading and trailing spaces from the input.
367 The input sequence is modified in-place.
368
369 \param Input An input sequence
370 \param Loc A locale used for 'space' classification
371 */
372 template<typename SequenceT>
373 inline void trim(SequenceT& Input, const std::locale& Loc=std::locale())
374 {
375 ::boost::algorithm::trim_if(
376 Input,
377 is_space( Loc ) );
378 }
379
380 } // namespace algorithm
381
382 // pull names to the boost namespace
383 using algorithm::trim_left;
384 using algorithm::trim_left_if;
385 using algorithm::trim_left_copy;
386 using algorithm::trim_left_copy_if;
387 using algorithm::trim_right;
388 using algorithm::trim_right_if;
389 using algorithm::trim_right_copy;
390 using algorithm::trim_right_copy_if;
391 using algorithm::trim;
392 using algorithm::trim_if;
393 using algorithm::trim_copy;
394 using algorithm::trim_copy_if;
395
396} // namespace boost
397
398#endif // BOOST_STRING_TRIM_HPP
399

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