algorithm/string/trim.hpp

0001 //  Boost string_algo library trim.hpp header file  ---------------------------//
0002
0003 //  Copyright Pavol Droba 2002-2003.
0004 //
0005 // Distributed under the Boost Software License, Version 1.0.
0006 //    (See accompanying file LICENSE_1_0.txt or copy at
0007 //          http://www.boost.org/LICENSE_1_0.txt)
0008
0009 //  See http://www.boost.org/ for updates, documentation, and revision history.
0010
0011 #ifndef BOOST_STRING_TRIM_HPP
0012 #define BOOST_STRING_TRIM_HPP
0013
0014 #include <boost/algorithm/string/config.hpp>
0015
0016 #include <boost/range/begin.hpp>
0017 #include <boost/range/end.hpp>
0018 #include <boost/range/const_iterator.hpp>
0019 #include <boost/range/as_literal.hpp>
0020 #include <boost/range/iterator_range_core.hpp>
0021
0022 #include <boost/algorithm/string/detail/trim.hpp>
0023 #include <boost/algorithm/string/classification.hpp>
0024 #include <locale>
0025
0026 /*! \file
0027     Defines trim algorithms.
0028     Trim algorithms are used to remove trailing and leading spaces from a
0029     sequence (string). Space is recognized using given locales.
0030
0031     Parametric (\c _if) variants use a predicate (functor) to select which characters
0032     are to be trimmed..
0033     Functions take a selection predicate as a parameter, which is used to determine
0034     whether a character is a space. Common predicates are provided in classification.hpp header.
0035
0036 */
0037
0038 namespace boost {
0039     namespace algorithm {
0040
0041     //  left trim  -----------------------------------------------//
0042
0043
0044         //! Left trim - parametric
0045         /*!
0046             Remove all leading spaces from the input.
0047             The supplied predicate is used to determine which characters are considered spaces.
0048             The result is a trimmed copy of the input. It is returned as a sequence
0049             or copied to the output iterator
0050
0051             \param Output An output iterator to which the result will be copied
0052             \param Input An input range
0053             \param IsSpace A unary predicate identifying spaces
0054             \return
0055                 An output iterator pointing just after the last inserted character or
0056                 a copy of the input
0057
0058                \note The second variant of this function provides the strong exception-safety guarantee
0059         */
0060         template<typename OutputIteratorT, typename RangeT, typename PredicateT>
0061         inline OutputIteratorT trim_left_copy_if(
0062             OutputIteratorT Output,
0063             const RangeT& Input,
0064             PredicateT IsSpace)
0065         {
0066             iterator_range<BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type> lit_range(::boost::as_literal(Input));
0067
0068             std::copy(
0069                 ::boost::algorithm::detail::trim_begin(
0070                     ::boost::begin(lit_range),
0071                     ::boost::end(lit_range),
0072                     IsSpace ),
0073                 ::boost::end(lit_range),
0074                 Output);
0075
0076             return Output;
0077         }
0078
0079         //! Left trim - parametric
0080         /*!
0081             \overload
0082         */
0083         template<typename SequenceT, typename PredicateT>
0084         inline SequenceT trim_left_copy_if(const SequenceT& Input, PredicateT IsSpace)
0085         {
0086             return SequenceT(
0087                 ::boost::algorithm::detail::trim_begin(
0088                     ::boost::begin(Input),
0089                     ::boost::end(Input),
0090                     IsSpace ),
0091                 ::boost::end(Input));
0092         }
0093
0094         //! Left trim - parametric
0095         /*!
0096             Remove all leading spaces from the input.
0097             The result is a trimmed copy of the input.
0098
0099             \param Input An input sequence
0100             \param Loc a locale used for 'space' classification
0101             \return A trimmed copy of the input
0102
0103             \note This function provides the strong exception-safety guarantee
0104         */
0105         template<typename SequenceT>
0106         inline SequenceT trim_left_copy(const SequenceT& Input, const std::locale& Loc=std::locale())
0107         {
0108             return
0109                 ::boost::algorithm::trim_left_copy_if(
0110                     Input,
0111                     is_space(Loc));
0112         }
0113
0114         //! Left trim
0115         /*!
0116             Remove all leading spaces from the input. The supplied predicate is
0117             used to determine which characters are considered spaces.
0118             The input sequence is modified in-place.
0119
0120             \param Input An input sequence
0121             \param IsSpace A unary predicate identifying spaces
0122         */
0123         template<typename SequenceT, typename PredicateT>
0124         inline void trim_left_if(SequenceT& Input, PredicateT IsSpace)
0125         {
0126             Input.erase(
0127                 ::boost::begin(Input),
0128                 ::boost::algorithm::detail::trim_begin(
0129                     ::boost::begin(Input),
0130                     ::boost::end(Input),
0131                     IsSpace));
0132         }
0133
0134         //! Left trim
0135         /*!
0136             Remove all leading spaces from the input.
0137             The Input sequence is modified in-place.
0138
0139             \param Input An input sequence
0140             \param Loc A locale used for 'space' classification
0141         */
0142         template<typename SequenceT>
0143         inline void trim_left(SequenceT& Input, const std::locale& Loc=std::locale())
0144         {
0145             ::boost::algorithm::trim_left_if(
0146                 Input,
0147                 is_space(Loc));
0148         }
0149
0150     //  right trim  -----------------------------------------------//
0151
0152         //! Right trim - parametric
0153         /*!
0154             Remove all trailing spaces from the input.
0155             The supplied predicate is used to determine which characters are considered spaces.
0156             The result is a trimmed copy of the input. It is returned as a sequence
0157             or copied to the output iterator
0158
0159             \param Output An output iterator to which the result will be copied
0160             \param Input An input range
0161             \param IsSpace A unary predicate identifying spaces
0162             \return
0163                 An output iterator pointing just after the last inserted character or
0164                 a copy of the input
0165
0166              \note The second variant of this function provides the strong exception-safety guarantee
0167         */
0168         template<typename OutputIteratorT, typename RangeT, typename PredicateT>
0169         inline OutputIteratorT trim_right_copy_if(
0170             OutputIteratorT Output,
0171             const RangeT& Input,
0172             PredicateT IsSpace )
0173         {
0174             iterator_range<BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type> lit_range(::boost::as_literal(Input));
0175
0176             std::copy(
0177                 ::boost::begin(lit_range),
0178                 ::boost::algorithm::detail::trim_end(
0179                     ::boost::begin(lit_range),
0180                     ::boost::end(lit_range),
0181                     IsSpace ),
0182                 Output );
0183
0184             return Output;
0185         }
0186
0187         //! Right trim - parametric
0188         /*!
0189             \overload
0190          */
0191         template<typename SequenceT, typename PredicateT>
0192         inline SequenceT trim_right_copy_if(const SequenceT& Input, PredicateT IsSpace)
0193         {
0194             return SequenceT(
0195                 ::boost::begin(Input),
0196                 ::boost::algorithm::detail::trim_end(
0197                     ::boost::begin(Input),
0198                     ::boost::end(Input),
0199                     IsSpace)
0200                 );
0201         }
0202
0203         //! Right trim
0204         /*!
0205             Remove all trailing spaces from the input.
0206             The result is a trimmed copy of the input
0207
0208             \param Input An input sequence
0209             \param Loc A locale used for 'space' classification
0210             \return A trimmed copy of the input
0211
0212             \note This function provides the strong exception-safety guarantee
0213         */
0214         template<typename SequenceT>
0215         inline SequenceT trim_right_copy(const SequenceT& Input, const std::locale& Loc=std::locale())
0216         {
0217             return
0218                 ::boost::algorithm::trim_right_copy_if(
0219                     Input,
0220                     is_space(Loc));
0221         }
0222
0223
0224         //! Right trim - parametric
0225         /*!
0226             Remove all trailing spaces from the input.
0227             The supplied predicate is used to determine which characters are considered spaces.
0228             The input sequence is modified in-place.
0229
0230             \param Input An input sequence
0231             \param IsSpace A unary predicate identifying spaces
0232         */
0233         template<typename SequenceT, typename PredicateT>
0234         inline void trim_right_if(SequenceT& Input, PredicateT IsSpace)
0235         {
0236             Input.erase(
0237                 ::boost::algorithm::detail::trim_end(
0238                     ::boost::begin(Input),
0239                     ::boost::end(Input),
0240                     IsSpace ),
0241                 ::boost::end(Input)
0242                 );
0243         }
0244
0245
0246         //! Right trim
0247         /*!
0248             Remove all trailing spaces from the input.
0249             The input sequence is modified in-place.
0250
0251             \param Input An input sequence
0252             \param Loc A locale used for 'space' classification
0253         */
0254         template<typename SequenceT>
0255         inline void trim_right(SequenceT& Input, const std::locale& Loc=std::locale())
0256         {
0257             ::boost::algorithm::trim_right_if(
0258                 Input,
0259                 is_space(Loc) );
0260         }
0261
0262     //  both side trim  -----------------------------------------------//
0263
0264         //! Trim - parametric
0265         /*!
0266             Remove all trailing and leading spaces from the input.
0267             The supplied predicate is used to determine which characters are considered spaces.
0268             The result is a trimmed copy of the input. It is returned as a sequence
0269             or copied to the output iterator
0270
0271             \param Output An output iterator to which the result will be copied
0272             \param Input An input range
0273             \param IsSpace A unary predicate identifying spaces
0274             \return
0275                 An output iterator pointing just after the last inserted character or
0276                 a copy of the input
0277
0278              \note The second variant of this function provides the strong exception-safety guarantee
0279         */
0280         template<typename OutputIteratorT, typename RangeT, typename PredicateT>
0281         inline OutputIteratorT trim_copy_if(
0282             OutputIteratorT Output,
0283             const RangeT& Input,
0284             PredicateT IsSpace)
0285         {
0286             iterator_range<BOOST_STRING_TYPENAME range_const_iterator<RangeT>::type> lit_range(::boost::as_literal(Input));
0287
0288             BOOST_STRING_TYPENAME
0289                 range_const_iterator<RangeT>::type TrimEnd=
0290                 ::boost::algorithm::detail::trim_end(
0291                     ::boost::begin(lit_range),
0292                     ::boost::end(lit_range),
0293                     IsSpace);
0294
0295             std::copy(
0296                 detail::trim_begin(
0297                     ::boost::begin(lit_range), TrimEnd, IsSpace),
0298                 TrimEnd,
0299                 Output
0300                 );
0301
0302             return Output;
0303         }
0304
0305         //! Trim - parametric
0306         /*!
0307             \overload
0308          */
0309         template<typename SequenceT, typename PredicateT>
0310         inline SequenceT trim_copy_if(const SequenceT& Input, PredicateT IsSpace)
0311         {
0312             BOOST_STRING_TYPENAME
0313                 range_const_iterator<SequenceT>::type TrimEnd=
0314                     ::boost::algorithm::detail::trim_end(
0315                         ::boost::begin(Input),
0316                         ::boost::end(Input),
0317                         IsSpace);
0318
0319             return SequenceT(
0320                 detail::trim_begin(
0321                     ::boost::begin(Input),
0322                     TrimEnd,
0323                     IsSpace),
0324                 TrimEnd
0325                 );
0326         }
0327
0328         //! Trim
0329         /*!
0330             Remove all leading and trailing spaces from the input.
0331             The result is a trimmed copy of the input
0332
0333             \param Input An input sequence
0334             \param Loc A locale used for 'space' classification
0335             \return A trimmed copy of the input
0336
0337             \note This function provides the strong exception-safety guarantee
0338         */
0339         template<typename SequenceT>
0340         inline SequenceT trim_copy( const SequenceT& Input, const std::locale& Loc=std::locale() )
0341         {
0342             return
0343                 ::boost::algorithm::trim_copy_if(
0344                     Input,
0345                     is_space(Loc) );
0346         }
0347
0348         //! Trim
0349         /*!
0350             Remove all leading and trailing spaces from the input.
0351             The supplied predicate is used to determine which characters are considered spaces.
0352             The input sequence is modified in-place.
0353
0354             \param Input An input sequence
0355             \param IsSpace A unary predicate identifying spaces
0356         */
0357         template<typename SequenceT, typename PredicateT>
0358         inline void trim_if(SequenceT& Input, PredicateT IsSpace)
0359         {
0360             ::boost::algorithm::trim_right_if( Input, IsSpace );
0361             ::boost::algorithm::trim_left_if( Input, IsSpace );
0362         }
0363
0364         //! Trim
0365         /*!
0366             Remove all leading and trailing spaces from the input.
0367             The input sequence is modified in-place.
0368
0369             \param Input An input sequence
0370             \param Loc A locale used for 'space' classification
0371         */
0372         template<typename SequenceT>
0373         inline void trim(SequenceT& Input, const std::locale& Loc=std::locale())
0374         {
0375             ::boost::algorithm::trim_if(
0376                 Input,
0377                 is_space( Loc ) );
0378         }
0379
0380     } // namespace algorithm
0381
0382     // pull names to the boost namespace
0383     using algorithm::trim_left;
0384     using algorithm::trim_left_if;
0385     using algorithm::trim_left_copy;
0386     using algorithm::trim_left_copy_if;
0387     using algorithm::trim_right;
0388     using algorithm::trim_right_if;
0389     using algorithm::trim_right_copy;
0390     using algorithm::trim_right_copy_if;
0391     using algorithm::trim;
0392     using algorithm::trim_if;
0393     using algorithm::trim_copy;
0394     using algorithm::trim_copy_if;
0395
0396 } // namespace boost
0397
0398 #endif  // BOOST_STRING_TRIM_HPP