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