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>
encode_one(T val,OutputIterator out,const char * hexDigits)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>
hex_char_to_int(T val)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>
iter_end(Iterator current,Iterator last)113     bool iter_end ( Iterator current, Iterator last ) { return current == last; }
114 
115     template <typename T>
ptr_end(const T * ptr,const 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
decode_one(InputIterator & first,InputIterator last,OutputIterator out,EndPred pred)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
hex(InputIterator first,InputIterator last,OutputIterator out)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
hex_lower(InputIterator first,InputIterator last,OutputIterator out)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
hex(const T * ptr,OutputIterator out)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
hex_lower(const T * ptr,OutputIterator out)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
hex(const Range & r,OutputIterator out)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
hex_lower(const Range & r,OutputIterator out)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>
unhex(InputIterator first,InputIterator last,OutputIterator out)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>
unhex(const T * ptr,OutputIterator out)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>
unhex(const Range & r,OutputIterator out)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>
hex(const String & input)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>
hex_lower(const String & input)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>
unhex(const String & input)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
327