src/boost/algorithm/string/trim.hpp

   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
  35 namespace 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