ceph/src/boost/boost/algorithm/hex.hpp

   1 /*
   2    Copyright (c) Marshall Clow 2011-2012.
   3
   4    Distributed under the Boost Software License, Version 1.0. (See accompanying
   5    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6
   7    Thanks to Nevin for his comments/help.
   8 */
   9
  10 /*
  11     General problem - turn a sequence of integral types into a sequence of hexadecimal characters.
  12     - and back.
  13 */
  14
  15 /// \file  hex.hpp
  16 /// \brief Convert sequence of integral types into a sequence of hexadecimal
  17 ///     characters and back. Based on the MySQL functions HEX and UNHEX
  18 /// \author Marshall Clow
  19
  20 #ifndef BOOST_ALGORITHM_HEXHPP
  21 #define BOOST_ALGORITHM_HEXHPP
  22
  23 #include <iterator>     // for std::iterator_traits
  24 #include <stdexcept>
  25
  26 #include <boost/range/begin.hpp>
  27 #include <boost/range/end.hpp>
  28 #include <boost/exception/exception.hpp>
  29 #include <boost/exception/info.hpp>
  30 #include <boost/throw_exception.hpp>
  31
  32 #include <boost/utility/enable_if.hpp>
  33 #include <boost/type_traits/is_integral.hpp>
  34
  35
  36 namespace boost { namespace algorithm {
  37
  38 /*!
  39     \struct hex_decode_error
  40     \brief  Base exception class for all hex decoding errors
  41 */ /*!
  42     \struct non_hex_input
  43     \brief  Thrown when a non-hex value (0-9, A-F) encountered when decoding.
  44                 Contains the offending character
  45 */ /*!
  46     \struct not_enough_input
  47     \brief  Thrown when the input sequence unexpectedly ends
  48
  49 */
  50 struct hex_decode_error : virtual boost::exception, virtual std::exception {};
  51 struct not_enough_input : virtual hex_decode_error {};
  52 struct non_hex_input    : virtual hex_decode_error {};
  53 typedef boost::error_info<struct bad_char_,char> bad_char;
  54
  55 namespace detail {
  56 /// \cond DOXYGEN_HIDE
  57
  58     template <typename T, typename OutputIterator>
  59     OutputIterator encode_one ( T val, OutputIterator out, const char * hexDigits ) {
  60         const std::size_t num_hex_digits =  2 * sizeof ( T );
  61         char res [ num_hex_digits ];
  62         char  *p = res + num_hex_digits;
  63         for ( std::size_t i = 0; i < num_hex_digits; ++i, val >>= 4 )
  64             *--p = hexDigits [ val & 0x0F ];
  65         return std::copy ( res, res + num_hex_digits, out );
  66         }
  67
  68     template <typename T>
  69     unsigned char hex_char_to_int ( T val ) {
  70         char c = static_cast<char> ( val );
  71         unsigned retval = 0;
  72         if      ( c >= '0' && c <= '9' ) retval = c - '0';
  73         else if ( c >= 'A' && c <= 'F' ) retval = c - 'A' + 10;
  74         else if ( c >= 'a' && c <= 'f' ) retval = c - 'a' + 10;
  75         else BOOST_THROW_EXCEPTION (non_hex_input() << bad_char (c));
  76         return static_cast<char>(retval);
  77         }
  78
  79 //  My own iterator_traits class.
  80 //  It is here so that I can "reach inside" some kinds of output iterators
  81 //      and get the type to write.
  82     template <typename Iterator>
  83     struct hex_iterator_traits {
  84         typedef typename std::iterator_traits<Iterator>::value_type value_type;
  85     };
  86
  87     template<typename Container>
  88     struct hex_iterator_traits< std::back_insert_iterator<Container> > {
  89         typedef typename Container::value_type value_type;
  90     };
  91
  92     template<typename Container>
  93     struct hex_iterator_traits< std::front_insert_iterator<Container> > {
  94         typedef typename Container::value_type value_type;
  95     };
  96
  97     template<typename Container>
  98     struct hex_iterator_traits< std::insert_iterator<Container> > {
  99         typedef typename Container::value_type value_type;
 100     };
 101
 102 //  ostream_iterators have three template parameters.
 103 //  The first one is the output type, the second one is the character type of
 104 //  the underlying stream, the third is the character traits.
 105 //      We only care about the first one.
 106     template<typename T, typename charType, typename traits>
 107     struct hex_iterator_traits< std::ostream_iterator<T, charType, traits> > {
 108         typedef T value_type;
 109     };
 110
 111     template <typename Iterator>
 112     bool iter_end ( Iterator current, Iterator last ) { return current == last; }
 113
 114     template <typename T>
 115     bool ptr_end ( const T* ptr, const T* /*end*/ ) { return *ptr == '\0'; }
 116
 117 //  What can we assume here about the inputs?
 118 //      is std::iterator_traits<InputIterator>::value_type always 'char' ?
 119 //  Could it be wchar_t, say? Does it matter?
 120 //      We are assuming ASCII for the values - but what about the storage?
 121     template <typename InputIterator, typename OutputIterator, typename EndPred>
 122     typename boost::enable_if<boost::is_integral<typename hex_iterator_traits<OutputIterator>::value_type>, OutputIterator>::type
 123     decode_one ( InputIterator &first, InputIterator last, OutputIterator out, EndPred pred ) {
 124         typedef typename hex_iterator_traits<OutputIterator>::value_type T;
 125         T res (0);
 126
 127     //  Need to make sure that we get can read that many chars here.
 128         for ( std::size_t i = 0; i < 2 * sizeof ( T ); ++i, ++first ) {
 129             if ( pred ( first, last ))
 130                 BOOST_THROW_EXCEPTION (not_enough_input ());
 131             res = ( 16 * res ) + hex_char_to_int (*first);
 132             }
 133
 134         *out = res;
 135         return ++out;
 136         }
 137 /// \endcond
 138     }
 139
 140
 141 /// \fn hex ( InputIterator first, InputIterator last, OutputIterator out )
 142 /// \brief   Converts a sequence of integral types into a hexadecimal sequence of characters.
 143 ///
 144 /// \param first    The start of the input sequence
 145 /// \param last     One past the end of the input sequence
 146 /// \param out      An output iterator to the results into
 147 /// \return         The updated output iterator
 148 /// \note           Based on the MySQL function of the same name
 149 template <typename InputIterator, typename OutputIterator>
 150 typename boost::enable_if<boost::is_integral<typename detail::hex_iterator_traits<InputIterator>::value_type>, OutputIterator>::type
 151 hex ( InputIterator first, InputIterator last, OutputIterator out ) {
 152     for ( ; first != last; ++first )
 153         out = detail::encode_one ( *first, out, "0123456789ABCDEF" );
 154     return out;
 155     }
 156
 157
 158 /// \fn hex_lower ( InputIterator first, InputIterator last, OutputIterator out )
 159 /// \brief   Converts a sequence of integral types into a lower case hexadecimal sequence of characters.
 160 ///
 161 /// \param first    The start of the input sequence
 162 /// \param last     One past the end of the input sequence
 163 /// \param out      An output iterator to the results into
 164 /// \return         The updated output iterator
 165 /// \note           Based on the MySQL function of the same name
 166 template <typename InputIterator, typename OutputIterator>
 167 typename boost::enable_if<boost::is_integral<typename detail::hex_iterator_traits<InputIterator>::value_type>, OutputIterator>::type
 168 hex_lower ( InputIterator first, InputIterator last, OutputIterator out ) {
 169     for ( ; first != last; ++first )
 170         out = detail::encode_one ( *first, out, "0123456789abcdef" );
 171     return out;
 172     }
 173
 174
 175 /// \fn hex ( const T *ptr, OutputIterator out )
 176 /// \brief   Converts a sequence of integral types into a hexadecimal sequence of characters.
 177 ///
 178 /// \param ptr      A pointer to a 0-terminated sequence of data.
 179 /// \param out      An output iterator to the results into
 180 /// \return         The updated output iterator
 181 /// \note           Based on the MySQL function of the same name
 182 template <typename T, typename OutputIterator>
 183 typename boost::enable_if<boost::is_integral<T>, OutputIterator>::type
 184 hex ( const T *ptr, OutputIterator out ) {
 185     while ( *ptr )
 186         out = detail::encode_one ( *ptr++, out, "0123456789ABCDEF" );
 187     return out;
 188     }
 189
 190
 191 /// \fn hex_lower ( const T *ptr, OutputIterator out )
 192 /// \brief   Converts a sequence of integral types into a lower case hexadecimal sequence of characters.
 193 ///
 194 /// \param ptr      A pointer to a 0-terminated sequence of data.
 195 /// \param out      An output iterator to the results into
 196 /// \return         The updated output iterator
 197 /// \note           Based on the MySQL function of the same name
 198 template <typename T, typename OutputIterator>
 199 typename boost::enable_if<boost::is_integral<T>, OutputIterator>::type
 200 hex_lower ( const T *ptr, OutputIterator out ) {
 201     while ( *ptr )
 202         out = detail::encode_one ( *ptr++, out, "0123456789abcdef" );
 203     return out;
 204     }
 205
 206
 207 /// \fn hex ( const Range &r, OutputIterator out )
 208 /// \brief   Converts a sequence of integral types into a hexadecimal sequence of characters.
 209 ///
 210 /// \param r        The input range
 211 /// \param out      An output iterator to the results into
 212 /// \return         The updated output iterator
 213 /// \note           Based on the MySQL function of the same name
 214 template <typename Range, typename OutputIterator>
 215 typename boost::enable_if<boost::is_integral<typename detail::hex_iterator_traits<typename Range::iterator>::value_type>, OutputIterator>::type
 216 hex ( const Range &r, OutputIterator out ) {
 217     return hex (boost::begin(r), boost::end(r), out);
 218 }
 219
 220
 221 /// \fn hex_lower ( const Range &r, OutputIterator out )
 222 /// \brief   Converts a sequence of integral types into a lower case hexadecimal sequence of characters.
 223 ///
 224 /// \param r        The input range
 225 /// \param out      An output iterator to the results into
 226 /// \return         The updated output iterator
 227 /// \note           Based on the MySQL function of the same name
 228 template <typename Range, typename OutputIterator>
 229 typename boost::enable_if<boost::is_integral<typename detail::hex_iterator_traits<typename Range::iterator>::value_type>, OutputIterator>::type
 230 hex_lower ( const Range &r, OutputIterator out ) {
 231     return hex_lower (boost::begin(r), boost::end(r), out);
 232 }
 233
 234
 235 /// \fn unhex ( InputIterator first, InputIterator last, OutputIterator out )
 236 /// \brief   Converts a sequence of hexadecimal characters into a sequence of integers.
 237 ///
 238 /// \param first    The start of the input sequence
 239 /// \param last     One past the end of the input sequence
 240 /// \param out      An output iterator to the results into
 241 /// \return         The updated output iterator
 242 /// \note           Based on the MySQL function of the same name
 243 template <typename InputIterator, typename OutputIterator>
 244 OutputIterator unhex ( InputIterator first, InputIterator last, OutputIterator out ) {
 245     while ( first != last )
 246         out = detail::decode_one ( first, last, out, detail::iter_end<InputIterator> );
 247     return out;
 248     }
 249
 250
 251 /// \fn unhex ( const T *ptr, OutputIterator out )
 252 /// \brief   Converts a sequence of hexadecimal characters into a sequence of integers.
 253 ///
 254 /// \param ptr      A pointer to a null-terminated input sequence.
 255 /// \param out      An output iterator to the results into
 256 /// \return         The updated output iterator
 257 /// \note           Based on the MySQL function of the same name
 258 template <typename T, typename OutputIterator>
 259 OutputIterator unhex ( const T *ptr, OutputIterator out ) {
 260 //  If we run into the terminator while decoding, we will throw a
 261 //      malformed input exception. It would be nicer to throw a 'Not enough input'
 262 //      exception - but how much extra work would that require?
 263     while ( *ptr )
 264         out = detail::decode_one ( ptr, (const T *) NULL, out, detail::ptr_end<T> );
 265     return out;
 266     }
 267
 268
 269 /// \fn OutputIterator unhex ( const Range &r, OutputIterator out )
 270 /// \brief   Converts a sequence of hexadecimal characters into a sequence of integers.
 271 ///
 272 /// \param r        The input range
 273 /// \param out      An output iterator to the results into
 274 /// \return         The updated output iterator
 275 /// \note           Based on the MySQL function of the same name
 276 template <typename Range, typename OutputIterator>
 277 OutputIterator unhex ( const Range &r, OutputIterator out ) {
 278     return unhex (boost::begin(r), boost::end(r), out);
 279     }
 280
 281
 282 /// \fn String hex ( const String &input )
 283 /// \brief   Converts a sequence of integral types into a hexadecimal sequence of characters.
 284 ///
 285 /// \param input    A container to be converted
 286 /// \return         A container with the encoded text
 287 template<typename String>
 288 String hex ( const String &input ) {
 289     String output;
 290     output.reserve (input.size () * (2 * sizeof (typename String::value_type)));
 291     (void) hex (input, std::back_inserter (output));
 292     return output;
 293     }
 294
 295
 296 /// \fn String hex_lower ( const String &input )
 297 /// \brief   Converts a sequence of integral types into a lower case hexadecimal sequence of characters.
 298 ///
 299 /// \param input    A container to be converted
 300 /// \return         A container with the encoded text
 301 template<typename String>
 302 String hex_lower ( const String &input ) {
 303     String output;
 304     output.reserve (input.size () * (2 * sizeof (typename String::value_type)));
 305     (void) hex_lower (input, std::back_inserter (output));
 306     return output;
 307     }
 308
 309
 310 /// \fn String unhex ( const String &input )
 311 /// \brief   Converts a sequence of hexadecimal characters into a sequence of characters.
 312 ///
 313 /// \param input    A container to be converted
 314 /// \return         A container with the decoded text
 315 template<typename String>
 316 String unhex ( const String &input ) {
 317     String output;
 318     output.reserve (input.size () / (2 * sizeof (typename String::value_type)));
 319     (void) unhex (input, std::back_inserter (output));
 320     return output;
 321     }
 322
 323 }}
 324
 325 #endif // BOOST_ALGORITHM_HEXHPP