source: NonGTP/Boost/boost/algorithm/string/trim.hpp @ 857

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