algorithm/string/join.hpp

0001 //  Boost string_algo library join.hpp header file  ---------------------------//
0002
0003 //  Copyright Pavol Droba 2002-2006.
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_JOIN_HPP
0012 #define BOOST_STRING_JOIN_HPP
0013
0014 #include <boost/algorithm/string/config.hpp>
0015 #include <boost/algorithm/string/detail/sequence.hpp>
0016 #include <boost/range/value_type.hpp>
0017 #include <boost/range/as_literal.hpp>
0018
0019 /*! \file
0020     Defines join algorithm.
0021
0022     Join algorithm is a counterpart to split algorithms.
0023     It joins strings from a 'list' by adding user defined separator.
0024     Additionally there is a version that allows simple filtering
0025     by providing a predicate.
0026 */
0027
0028 namespace boost {
0029     namespace algorithm {
0030
0031 //  join --------------------------------------------------------------//
0032
0033         //! Join algorithm
0034         /*!
0035             This algorithm joins all strings in a 'list' into one long string.
0036             Segments are concatenated by given separator.
0037
0038             \param Input A container that holds the input strings. It must be a container-of-containers.
0039             \param Separator A string that will separate the joined segments.
0040             \return Concatenated string.
0041
0042             \note This function provides the strong exception-safety guarantee
0043         */
0044         template< typename SequenceSequenceT, typename Range1T>
0045         inline typename range_value<SequenceSequenceT>::type
0046         join(
0047             const SequenceSequenceT& Input,
0048             const Range1T& Separator)
0049         {
0050             // Define working types
0051             typedef typename range_value<SequenceSequenceT>::type ResultT;
0052             typedef typename range_const_iterator<SequenceSequenceT>::type InputIteratorT;
0053
0054             // Parse input
0055             InputIteratorT itBegin=::boost::begin(Input);
0056             InputIteratorT itEnd=::boost::end(Input);
0057
0058             // Construct container to hold the result
0059             ResultT Result;
0060
0061             // Append first element
0062             if(itBegin!=itEnd)
0063             {
0064                 detail::insert(Result, ::boost::end(Result), *itBegin);
0065                 ++itBegin;
0066             }
0067
0068             for(;itBegin!=itEnd; ++itBegin)
0069             {
0070                 // Add separator
0071                 detail::insert(Result, ::boost::end(Result), ::boost::as_literal(Separator));
0072                 // Add element
0073                 detail::insert(Result, ::boost::end(Result), *itBegin);
0074             }
0075
0076             return Result;
0077         }
0078
0079 // join_if ----------------------------------------------------------//
0080
0081         //! Conditional join algorithm
0082         /*!
0083             This algorithm joins all strings in a 'list' into one long string.
0084             Segments are concatenated by given separator. Only segments that
0085             satisfy the predicate will be added to the result.
0086
0087             \param Input A container that holds the input strings. It must be a container-of-containers.
0088             \param Separator A string that will separate the joined segments.
0089             \param Pred A segment selection predicate
0090             \return Concatenated string.
0091
0092             \note This function provides the strong exception-safety guarantee
0093         */
0094         template< typename SequenceSequenceT, typename Range1T, typename PredicateT>
0095         inline typename range_value<SequenceSequenceT>::type
0096         join_if(
0097             const SequenceSequenceT& Input,
0098             const Range1T& Separator,
0099             PredicateT Pred)
0100         {
0101             // Define working types
0102             typedef typename range_value<SequenceSequenceT>::type ResultT;
0103             typedef typename range_const_iterator<SequenceSequenceT>::type InputIteratorT;
0104
0105             // Parse input
0106             InputIteratorT itBegin=::boost::begin(Input);
0107             InputIteratorT itEnd=::boost::end(Input);
0108
0109             // Construct container to hold the result
0110             ResultT Result;
0111
0112             // Roll to the first element that will be added
0113             while(itBegin!=itEnd && !Pred(*itBegin)) ++itBegin;
0114             // Add this element
0115             if(itBegin!=itEnd)
0116             {
0117                 detail::insert(Result, ::boost::end(Result), *itBegin);
0118                 ++itBegin;
0119             }
0120
0121             for(;itBegin!=itEnd; ++itBegin)
0122             {
0123                 if(Pred(*itBegin))
0124                 {
0125                     // Add separator
0126                     detail::insert(Result, ::boost::end(Result), ::boost::as_literal(Separator));
0127                     // Add element
0128                     detail::insert(Result, ::boost::end(Result), *itBegin);
0129                 }
0130             }
0131
0132             return Result;
0133         }
0134
0135     } // namespace algorithm
0136
0137     // pull names to the boost namespace
0138     using algorithm::join;
0139     using algorithm::join_if;
0140
0141 } // namespace boost
0142
0143
0144 #endif  // BOOST_STRING_JOIN_HPP
0145