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 
38 namespace 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>
trim_left_copy_if(OutputIteratorT Output,const RangeT & Input,PredicateT IsSpace)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>
trim_left_copy_if(const SequenceT & Input,PredicateT IsSpace)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>
trim_left_copy(const SequenceT & Input,const std::locale & Loc=std::locale ())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>
trim_left_if(SequenceT & Input,PredicateT IsSpace)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>
trim_left(SequenceT & Input,const std::locale & Loc=std::locale ())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>
trim_right_copy_if(OutputIteratorT Output,const RangeT & Input,PredicateT IsSpace)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>
trim_right_copy_if(const SequenceT & Input,PredicateT IsSpace)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>
trim_right_copy(const SequenceT & Input,const std::locale & Loc=std::locale ())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>
trim_right_if(SequenceT & Input,PredicateT IsSpace)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>
trim_right(SequenceT & Input,const std::locale & Loc=std::locale ())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>
trim_copy_if(OutputIteratorT Output,const RangeT & Input,PredicateT IsSpace)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>
trim_copy_if(const SequenceT & Input,PredicateT IsSpace)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>
trim_copy(const SequenceT & Input,const std::locale & Loc=std::locale ())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>
trim_if(SequenceT & Input,PredicateT IsSpace)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>
trim(SequenceT & Input,const std::locale & Loc=std::locale ())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