/src/boost/boost/algorithm/string/trim.hpp

Source
//  Boost string_algo library trim.hpp header file  ---------------------------//

//  Copyright Pavol Droba 2002-2003.
//
// Distributed under the Boost Software License, Version 1.0.
//    (See accompanying file LICENSE_1_0.txt or copy at
//          http://www.boost.org/LICENSE_1_0.txt)

//  See http://www.boost.org/ for updates, documentation, and revision history.

#ifndef BOOST_STRING_TRIM_HPP
#define BOOST_STRING_TRIM_HPP

#include <boost/algorithm/string/config.hpp>

#include <boost/range/begin.hpp>
#include <boost/range/end.hpp>
#include <boost/range/const_iterator.hpp>
#include <boost/range/as_literal.hpp>
#include <boost/range/iterator_range_core.hpp>

#include <boost/algorithm/string/detail/trim.hpp>
#include <boost/algorithm/string/classification.hpp>
#include <locale>

/*! \file
    Defines trim algorithms.
    Trim algorithms are used to remove trailing and leading spaces from a 
    sequence (string). Space is recognized using given locales.

    Parametric (\c _if) variants use a predicate (functor) to select which characters
    are to be trimmed.. 
    Functions take a selection predicate as a parameter, which is used to determine 
    whether a character is a space. Common predicates are provided in classification.hpp header.

*/

namespace boost {
    namespace algorithm {

    //  left trim  -----------------------------------------------//


        //! Left trim - parametric
        /*!
            Remove all leading spaces from the input. 
            The supplied predicate is used to determine which characters are considered spaces.
            The result is a trimmed copy of the input. It is returned as a sequence 
            or copied to the output iterator

            \param Output An output iterator to which the result will be copied
            \param Input An input range
            \param IsSpace A unary predicate identifying spaces
            \return 
                An output iterator pointing just after the last inserted character or
                a copy of the input

               \note The second variant of this function provides the strong exception-safety guarantee
        */
        template<typename OutputIteratorT, typename RangeT, typename PredicateT>
        inline OutputIteratorT trim_left_copy_if( 
            OutputIteratorT Output,
            const RangeT& Input,
            PredicateT IsSpace)
        {
            iterator_range<BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type> lit_range(::boost::as_literal(Input));

            std::copy( 
                ::boost::algorithm::detail::trim_begin( 
                    ::boost::begin(lit_range), 
                    ::boost::end(lit_range), 
                    IsSpace ),
                ::boost::end(lit_range),
                Output);

            return Output;
        }

        //! Left trim - parametric
        /*!
            \overload
        */
        template<typename SequenceT, typename PredicateT>
        inline SequenceT trim_left_copy_if(const SequenceT& Input, PredicateT IsSpace)
        {
            return SequenceT( 
                ::boost::algorithm::detail::trim_begin( 
                    ::boost::begin(Input), 
                    ::boost::end(Input), 
                    IsSpace ),
                ::boost::end(Input));
        }

        //! Left trim - parametric
        /*!
            Remove all leading spaces from the input. 
            The result is a trimmed copy of the input.

            \param Input An input sequence
            \param Loc a locale used for 'space' classification
            \return A trimmed copy of the input

            \note This function provides the strong exception-safety guarantee
        */
        template<typename SequenceT>
        inline SequenceT trim_left_copy(const SequenceT& Input, const std::locale& Loc=std::locale())
        {
            return            
                ::boost::algorithm::trim_left_copy_if(
                    Input, 
                    is_space(Loc));
        }

        //! Left trim
        /*!
            Remove all leading spaces from the input. The supplied predicate is 
            used to determine which characters are considered spaces.
            The input sequence is modified in-place.

            \param Input An input sequence
            \param IsSpace A unary predicate identifying spaces
        */
        template<typename SequenceT, typename PredicateT>
        inline void trim_left_if(SequenceT& Input, PredicateT IsSpace)
        {
            Input.erase( 
                ::boost::begin(Input),
                ::boost::algorithm::detail::trim_begin( 
                    ::boost::begin(Input), 
                    ::boost::end(Input), 
                    IsSpace));
        }

        //! Left trim
        /*!
            Remove all leading spaces from the input.
            The Input sequence is modified in-place.

            \param Input An input sequence
            \param Loc A locale used for 'space' classification
        */
        template<typename SequenceT>
        inline void trim_left(SequenceT& Input, const std::locale& Loc=std::locale())
        {
            ::boost::algorithm::trim_left_if( 
                Input, 
                is_space(Loc));
        }

    //  right trim  -----------------------------------------------//

        //! Right trim - parametric
        /*!
            Remove all trailing spaces from the input.             
            The supplied predicate is used to determine which characters are considered spaces.
            The result is a trimmed copy of the input. It is returned as a sequence 
            or copied to the output iterator

            \param Output An output iterator to which the result will be copied
            \param Input An input range
            \param IsSpace A unary predicate identifying spaces
            \return 
                An output iterator pointing just after the last inserted character or
                a copy of the input

             \note The second variant of this function provides the strong exception-safety guarantee
        */
        template<typename OutputIteratorT, typename RangeT, typename PredicateT>
        inline OutputIteratorT trim_right_copy_if( 
            OutputIteratorT Output,
            const RangeT& Input,
            PredicateT IsSpace )
        {
            iterator_range<BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type> lit_range(::boost::as_literal(Input));
         
            std::copy( 
                ::boost::begin(lit_range),
                ::boost::algorithm::detail::trim_end( 
                    ::boost::begin(lit_range), 
                    ::boost::end(lit_range), 
                    IsSpace ),
                Output );

            return Output;
        }

        //! Right trim - parametric
        /*!
            \overload
         */
        template<typename SequenceT, typename PredicateT>
        inline SequenceT trim_right_copy_if(const SequenceT& Input, PredicateT IsSpace)
        {
            return SequenceT( 
                ::boost::begin(Input),
                ::boost::algorithm::detail::trim_end( 
                    ::boost::begin(Input), 
                    ::boost::end(Input), 
                    IsSpace)
                );
        }

        //! Right trim
        /*!
            Remove all trailing spaces from the input. 
            The result is a trimmed copy of the input

            \param Input An input sequence
            \param Loc A locale used for 'space' classification
            \return A trimmed copy of the input

            \note This function provides the strong exception-safety guarantee
        */
        template<typename SequenceT>
        inline SequenceT trim_right_copy(const SequenceT& Input, const std::locale& Loc=std::locale())
        {
            return 
                ::boost::algorithm::trim_right_copy_if( 
                    Input, 
                    is_space(Loc));
        }

            
        //! Right trim - parametric
        /*!
            Remove all trailing spaces from the input.
            The supplied predicate is used to determine which characters are considered spaces.
            The input sequence is modified in-place.

            \param Input An input sequence
            \param IsSpace A unary predicate identifying spaces
        */
        template<typename SequenceT, typename PredicateT>
        inline void trim_right_if(SequenceT& Input, PredicateT IsSpace)
        {
            Input.erase(
                ::boost::algorithm::detail::trim_end( 
                    ::boost::begin(Input), 
                    ::boost::end(Input), 
                    IsSpace ),
                ::boost::end(Input)
                );
        }


        //! Right trim
        /*!
            Remove all trailing spaces from the input. 
            The input sequence is modified in-place.

            \param Input An input sequence
            \param Loc A locale used for 'space' classification
        */
        template<typename SequenceT>
        inline void trim_right(SequenceT& Input, const std::locale& Loc=std::locale())
        {
            ::boost::algorithm::trim_right_if(
                Input, 
                is_space(Loc) );
        }

    //  both side trim  -----------------------------------------------//

        //! Trim - parametric
        /*!
            Remove all trailing and leading spaces from the input. 
            The supplied predicate is used to determine which characters are considered spaces.
            The result is a trimmed copy of the input. It is returned as a sequence 
            or copied to the output iterator

            \param Output An output iterator to which the result will be copied
            \param Input An input range
            \param IsSpace A unary predicate identifying spaces
            \return 
                An output iterator pointing just after the last inserted character or
                a copy of the input

             \note The second variant of this function provides the strong exception-safety guarantee
        */
        template<typename OutputIteratorT, typename RangeT, typename PredicateT>
        inline OutputIteratorT trim_copy_if( 
            OutputIteratorT Output,
            const RangeT& Input,
            PredicateT IsSpace)
        {
            iterator_range<BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type> lit_range(::boost::as_literal(Input));

            BOOST_STRING_TYPENAME 
                range_const_iterator<RangeT>::type TrimEnd=
                ::boost::algorithm::detail::trim_end( 
                    ::boost::begin(lit_range), 
                    ::boost::end(lit_range), 
                    IsSpace);

            std::copy( 
                detail::trim_begin( 
                    ::boost::begin(lit_range), TrimEnd, IsSpace),
                TrimEnd,
                Output
                );

            return Output;
        }

        //! Trim - parametric
        /*!
            \overload
         */
        template<typename SequenceT, typename PredicateT>
        inline SequenceT trim_copy_if(const SequenceT& Input, PredicateT IsSpace)
        {
            BOOST_STRING_TYPENAME 
                range_const_iterator<SequenceT>::type TrimEnd=
                    ::boost::algorithm::detail::trim_end( 
                        ::boost::begin(Input), 
                        ::boost::end(Input), 
                        IsSpace);

            return SequenceT( 
                detail::trim_begin( 
                    ::boost::begin(Input), 
                    TrimEnd, 
                    IsSpace),
                TrimEnd
                );
        }

        //! Trim
        /*!
            Remove all leading and trailing spaces from the input. 
            The result is a trimmed copy of the input

            \param Input An input sequence
            \param Loc A locale used for 'space' classification
            \return A trimmed copy of the input

            \note This function provides the strong exception-safety guarantee
        */
        template<typename SequenceT>
        inline SequenceT trim_copy( const SequenceT& Input, const std::locale& Loc=std::locale() )
        {
            return
                ::boost::algorithm::trim_copy_if(
                    Input, 
                    is_space(Loc) );
        }
     
        //! Trim
        /*!
            Remove all leading and trailing spaces from the input. 
            The supplied predicate is used to determine which characters are considered spaces.
            The input sequence is modified in-place.

            \param Input An input sequence
            \param IsSpace A unary predicate identifying spaces
        */
        template<typename SequenceT, typename PredicateT>
        inline void trim_if(SequenceT& Input, PredicateT IsSpace)
        {
            ::boost::algorithm::trim_right_if( Input, IsSpace );
            ::boost::algorithm::trim_left_if( Input, IsSpace );
        }

        //! Trim
        /*!
            Remove all leading and trailing spaces from the input. 
            The input sequence is modified in-place.

            \param Input An input sequence
            \param Loc A locale used for 'space' classification
        */
        template<typename SequenceT>
        inline void trim(SequenceT& Input, const std::locale& Loc=std::locale())
        {
            ::boost::algorithm::trim_if(
                Input, 
                is_space( Loc ) );
        }

    } // namespace algorithm 

    // pull names to the boost namespace
    using algorithm::trim_left;
    using algorithm::trim_left_if;
    using algorithm::trim_left_copy;
    using algorithm::trim_left_copy_if;
    using algorithm::trim_right;
    using algorithm::trim_right_if;
    using algorithm::trim_right_copy;
    using algorithm::trim_right_copy_if;
    using algorithm::trim;
    using algorithm::trim_if;
    using algorithm::trim_copy;
    using algorithm::trim_copy_if;

} // namespace boost

#endif  // BOOST_STRING_TRIM_HPP

Coverage Report

Created: 2026-06-30 07:19

Line	Count	Source
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>
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	412	{
312	412	BOOST_STRING_TYPENAME
313	412	range_const_iterator<SequenceT>::type TrimEnd=
314	412	::boost::algorithm::detail::trim_end(
315	412	::boost::begin(Input),
316	412	::boost::end(Input),
317	412	IsSpace);
318
319	412	return SequenceT(
320	412	detail::trim_begin(
321	412	::boost::begin(Input),
322	412	TrimEnd,
323	412	IsSpace),
324	412	TrimEnd
325	412	);
326	412	}
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	412	{
342	412	return
343	412	::boost::algorithm::trim_copy_if(
344	412	Input,
345	412	is_space(Loc) );
346	412	}
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