Chris@16: /* 
Chris@16:    Copyright (c) Marshall Clow 2011-2012.
Chris@16: 
Chris@16:    Distributed under the Boost Software License, Version 1.0. (See accompanying
Chris@16:    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Chris@16:    
Chris@16:    Thanks to Nevin for his comments/help.
Chris@16: */
Chris@16: 
Chris@16: /*
Chris@16:     General problem - turn a sequence of integral types into a sequence of hexadecimal characters.
Chris@16:     - and back.
Chris@16: */
Chris@16: 
Chris@16: /// \file  hex.hpp
Chris@16: /// \brief Convert sequence of integral types into a sequence of hexadecimal 
Chris@16: ///     characters and back. Based on the MySQL functions HEX and UNHEX
Chris@16: /// \author Marshall Clow
Chris@16: 
Chris@16: #ifndef BOOST_ALGORITHM_HEXHPP
Chris@16: #define BOOST_ALGORITHM_HEXHPP
Chris@16: 
Chris@16: #include <iterator>     // for std::iterator_traits
Chris@16: #include <stdexcept>
Chris@16: 
Chris@16: #include <boost/range/begin.hpp>
Chris@16: #include <boost/range/end.hpp>
Chris@16: #include <boost/exception/all.hpp>
Chris@16: 
Chris@16: #include <boost/utility/enable_if.hpp>
Chris@16: #include <boost/type_traits/is_integral.hpp>
Chris@16: 
Chris@16: 
Chris@16: namespace boost { namespace algorithm {
Chris@16: 
Chris@16: /*! 
Chris@16:     \struct hex_decode_error 
Chris@16:     \brief  Base exception class for all hex decoding errors 
Chris@16: */ /*!
Chris@16:     \struct non_hex_input    
Chris@16:     \brief  Thrown when a non-hex value (0-9, A-F) encountered when decoding.
Chris@16:                 Contains the offending character
Chris@16: */ /*!    
Chris@16:     \struct not_enough_input 
Chris@16:     \brief  Thrown when the input sequence unexpectedly ends
Chris@16:     
Chris@16: */
Chris@16: struct hex_decode_error : virtual boost::exception, virtual std::exception {};
Chris@16: struct not_enough_input : virtual hex_decode_error {};
Chris@16: struct non_hex_input    : virtual hex_decode_error {};
Chris@16: typedef boost::error_info<struct bad_char_,char> bad_char;
Chris@16: 
Chris@16: namespace detail {
Chris@16: /// \cond DOXYGEN_HIDE
Chris@16: 
Chris@16:     template <typename T, typename OutputIterator>
Chris@16:     OutputIterator encode_one ( T val, OutputIterator out ) {
Chris@16:         const std::size_t num_hex_digits =  2 * sizeof ( T );
Chris@16:         char res [ num_hex_digits ];
Chris@16:         char  *p = res + num_hex_digits;
Chris@16:         for ( std::size_t i = 0; i < num_hex_digits; ++i, val >>= 4 )
Chris@16:             *--p = "0123456789ABCDEF" [ val & 0x0F ];
Chris@16:         return std::copy ( res, res + num_hex_digits, out );
Chris@16:         }
Chris@16: 
Chris@16:     template <typename T>
Chris@16:     unsigned char hex_char_to_int ( T val ) {
Chris@16:         char c = static_cast<char> ( val );
Chris@16:         unsigned retval = 0;
Chris@16:         if      ( c >= '0' && c <= '9' ) retval = c - '0';
Chris@16:         else if ( c >= 'A' && c <= 'F' ) retval = c - 'A' + 10;
Chris@16:         else if ( c >= 'a' && c <= 'f' ) retval = c - 'a' + 10;
Chris@16:         else BOOST_THROW_EXCEPTION (non_hex_input() << bad_char (c));
Chris@16:         return retval;
Chris@16:         }
Chris@16: 
Chris@16: //  My own iterator_traits class.
Chris@16: //  It is here so that I can "reach inside" some kinds of output iterators
Chris@16: //      and get the type to write.
Chris@16:     template <typename Iterator>
Chris@16:     struct hex_iterator_traits {
Chris@16:         typedef typename std::iterator_traits<Iterator>::value_type value_type;
Chris@16:     };
Chris@16: 
Chris@16:     template<typename Container>
Chris@16:     struct hex_iterator_traits< std::back_insert_iterator<Container> > {
Chris@16:         typedef typename Container::value_type value_type;
Chris@16:     };
Chris@16: 
Chris@16:     template<typename Container>
Chris@16:     struct hex_iterator_traits< std::front_insert_iterator<Container> > {
Chris@16:         typedef typename Container::value_type value_type;
Chris@16:     };
Chris@16: 
Chris@16:     template<typename Container>
Chris@16:     struct hex_iterator_traits< std::insert_iterator<Container> > {
Chris@16:         typedef typename Container::value_type value_type;
Chris@16:     };
Chris@16: 
Chris@16: //  ostream_iterators have three template parameters.
Chris@16: //  The first one is the output type, the second one is the character type of
Chris@16: //  the underlying stream, the third is the character traits.
Chris@16: //      We only care about the first one.
Chris@16:     template<typename T, typename charType, typename traits>
Chris@16:     struct hex_iterator_traits< std::ostream_iterator<T, charType, traits> > {
Chris@16:         typedef T value_type;
Chris@16:     };
Chris@16: 
Chris@16:     template <typename Iterator> 
Chris@16:     bool iter_end ( Iterator current, Iterator last ) { return current == last; }
Chris@16:   
Chris@16:     template <typename T>
Chris@16:     bool ptr_end ( const T* ptr, const T* /*end*/ ) { return *ptr == '\0'; }
Chris@16:   
Chris@16: //  What can we assume here about the inputs?
Chris@16: //      is std::iterator_traits<InputIterator>::value_type always 'char' ?
Chris@16: //  Could it be wchar_t, say? Does it matter?
Chris@16: //      We are assuming ASCII for the values - but what about the storage?
Chris@16:     template <typename InputIterator, typename OutputIterator, typename EndPred>
Chris@16:     typename boost::enable_if<boost::is_integral<typename hex_iterator_traits<OutputIterator>::value_type>, OutputIterator>::type
Chris@16:     decode_one ( InputIterator &first, InputIterator last, OutputIterator out, EndPred pred ) {
Chris@16:         typedef typename hex_iterator_traits<OutputIterator>::value_type T;
Chris@16:         T res (0);
Chris@16: 
Chris@16:     //  Need to make sure that we get can read that many chars here.
Chris@16:         for ( std::size_t i = 0; i < 2 * sizeof ( T ); ++i, ++first ) {
Chris@16:             if ( pred ( first, last )) 
Chris@16:                 BOOST_THROW_EXCEPTION (not_enough_input ());
Chris@16:             res = ( 16 * res ) + hex_char_to_int (*first);
Chris@16:             }
Chris@16:         
Chris@16:         *out = res;
Chris@16:         return ++out;
Chris@16:         }
Chris@16: /// \endcond
Chris@16:     }
Chris@16: 
Chris@16: 
Chris@16: /// \fn hex ( InputIterator first, InputIterator last, OutputIterator out )
Chris@16: /// \brief   Converts a sequence of integral types into a hexadecimal sequence of characters.
Chris@16: /// 
Chris@16: /// \param first    The start of the input sequence
Chris@16: /// \param last     One past the end of the input sequence
Chris@16: /// \param out      An output iterator to the results into
Chris@16: /// \return         The updated output iterator
Chris@16: /// \note           Based on the MySQL function of the same name
Chris@16: template <typename InputIterator, typename OutputIterator>
Chris@16: typename boost::enable_if<boost::is_integral<typename detail::hex_iterator_traits<InputIterator>::value_type>, OutputIterator>::type
Chris@16: hex ( InputIterator first, InputIterator last, OutputIterator out ) {
Chris@16:     for ( ; first != last; ++first )
Chris@16:         out = detail::encode_one ( *first, out );
Chris@16:     return out;
Chris@16:     }
Chris@16:     
Chris@16: 
Chris@16: /// \fn hex ( const T *ptr, OutputIterator out )
Chris@16: /// \brief   Converts a sequence of integral types into a hexadecimal sequence of characters.
Chris@16: /// 
Chris@16: /// \param ptr      A pointer to a 0-terminated sequence of data.
Chris@16: /// \param out      An output iterator to the results into
Chris@16: /// \return         The updated output iterator
Chris@16: /// \note           Based on the MySQL function of the same name
Chris@16: template <typename T, typename OutputIterator>
Chris@16: typename boost::enable_if<boost::is_integral<T>, OutputIterator>::type
Chris@16: hex ( const T *ptr, OutputIterator out ) {
Chris@16:     while ( *ptr )
Chris@16:         out = detail::encode_one ( *ptr++, out );
Chris@16:     return out;
Chris@16:     }
Chris@16: 
Chris@16: /// \fn hex ( const Range &r, OutputIterator out )
Chris@16: /// \brief   Converts a sequence of integral types into a hexadecimal sequence of characters.
Chris@16: /// 
Chris@16: /// \param r        The input range
Chris@16: /// \param out      An output iterator to the results into
Chris@16: /// \return         The updated output iterator
Chris@16: /// \note           Based on the MySQL function of the same name
Chris@16: template <typename Range, typename OutputIterator>
Chris@16: typename boost::enable_if<boost::is_integral<typename detail::hex_iterator_traits<typename Range::iterator>::value_type>, OutputIterator>::type
Chris@16: hex ( const Range &r, OutputIterator out ) {
Chris@16:     return hex (boost::begin(r), boost::end(r), out);
Chris@16: }
Chris@16: 
Chris@16: 
Chris@16: /// \fn unhex ( InputIterator first, InputIterator last, OutputIterator out )
Chris@16: /// \brief   Converts a sequence of hexadecimal characters into a sequence of integers.
Chris@16: /// 
Chris@16: /// \param first    The start of the input sequence
Chris@16: /// \param last     One past the end of the input sequence
Chris@16: /// \param out      An output iterator to the results into
Chris@16: /// \return         The updated output iterator
Chris@16: /// \note           Based on the MySQL function of the same name
Chris@16: template <typename InputIterator, typename OutputIterator>
Chris@16: OutputIterator unhex ( InputIterator first, InputIterator last, OutputIterator out ) {
Chris@16:     while ( first != last )
Chris@16:         out = detail::decode_one ( first, last, out, detail::iter_end<InputIterator> );
Chris@16:     return out;
Chris@16:     }
Chris@16: 
Chris@16: 
Chris@16: /// \fn unhex ( const T *ptr, OutputIterator out )
Chris@16: /// \brief   Converts a sequence of hexadecimal characters into a sequence of integers.
Chris@16: /// 
Chris@16: /// \param ptr      A pointer to a null-terminated input sequence.
Chris@16: /// \param out      An output iterator to the results into
Chris@16: /// \return         The updated output iterator
Chris@16: /// \note           Based on the MySQL function of the same name
Chris@16: template <typename T, typename OutputIterator>
Chris@16: OutputIterator unhex ( const T *ptr, OutputIterator out ) {
Chris@16: //  If we run into the terminator while decoding, we will throw a
Chris@16: //      malformed input exception. It would be nicer to throw a 'Not enough input'
Chris@16: //      exception - but how much extra work would that require?
Chris@16:     while ( *ptr )
Chris@16:         out = detail::decode_one ( ptr, (const T *) NULL, out, detail::ptr_end<T> );
Chris@16:     return out;
Chris@16:     }
Chris@16: 
Chris@16: 
Chris@16: /// \fn OutputIterator unhex ( const Range &r, OutputIterator out )
Chris@16: /// \brief   Converts a sequence of hexadecimal characters into a sequence of integers.
Chris@16: /// 
Chris@16: /// \param r        The input range
Chris@16: /// \param out      An output iterator to the results into
Chris@16: /// \return         The updated output iterator
Chris@16: /// \note           Based on the MySQL function of the same name
Chris@16: template <typename Range, typename OutputIterator>
Chris@16: OutputIterator unhex ( const Range &r, OutputIterator out ) {
Chris@16:     return unhex (boost::begin(r), boost::end(r), out);
Chris@16:     }
Chris@16: 
Chris@16: 
Chris@16: /// \fn String hex ( const String &input )
Chris@16: /// \brief   Converts a sequence of integral types into a hexadecimal sequence of characters.
Chris@16: /// 
Chris@16: /// \param input    A container to be converted
Chris@16: /// \return         A container with the encoded text
Chris@16: template<typename String>
Chris@16: String hex ( const String &input ) {
Chris@16:     String output;
Chris@16:     output.reserve (input.size () * (2 * sizeof (typename String::value_type)));
Chris@16:     (void) hex (input, std::back_inserter (output));
Chris@16:     return output;
Chris@16:     }
Chris@16: 
Chris@16: /// \fn String unhex ( const String &input )
Chris@16: /// \brief   Converts a sequence of hexadecimal characters into a sequence of characters.
Chris@16: /// 
Chris@16: /// \param input    A container to be converted
Chris@16: /// \return         A container with the decoded text
Chris@16: template<typename String>
Chris@16: String unhex ( const String &input ) {
Chris@16:     String output;
Chris@16:     output.reserve (input.size () / (2 * sizeof (typename String::value_type)));
Chris@16:     (void) unhex (input, std::back_inserter (output));
Chris@16:     return output;
Chris@16:     }
Chris@16: 
Chris@16: }}
Chris@16: 
Chris@16: #endif // BOOST_ALGORITHM_HEXHPP