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/core/enable_if.hpp>
34#include <boost/type_traits/is_integral.hpp>
35
36
37namespace 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*/
51struct BOOST_SYMBOL_VISIBLE hex_decode_error : virtual boost::exception, virtual std::exception {};
52struct BOOST_SYMBOL_VISIBLE not_enough_input : virtual hex_decode_error {};
53struct BOOST_SYMBOL_VISIBLE non_hex_input : virtual hex_decode_error {};
54typedef boost::error_info<struct bad_char_,char> bad_char;
55
56namespace 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
150template <typename InputIterator, typename OutputIterator>
151typename boost::enable_if<boost::is_integral<typename detail::hex_iterator_traits<InputIterator>::value_type>, OutputIterator>::type
152hex ( 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
167template <typename InputIterator, typename OutputIterator>
168typename boost::enable_if<boost::is_integral<typename detail::hex_iterator_traits<InputIterator>::value_type>, OutputIterator>::type
169hex_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
183template <typename T, typename OutputIterator>
184typename boost::enable_if<boost::is_integral<T>, OutputIterator>::type
185hex ( 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
199template <typename T, typename OutputIterator>
200typename boost::enable_if<boost::is_integral<T>, OutputIterator>::type
201hex_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
215template <typename Range, typename OutputIterator>
216typename boost::enable_if<boost::is_integral<typename detail::hex_iterator_traits<typename Range::iterator>::value_type>, OutputIterator>::type
217hex ( 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
229template <typename Range, typename OutputIterator>
230typename boost::enable_if<boost::is_integral<typename detail::hex_iterator_traits<typename Range::iterator>::value_type>, OutputIterator>::type
231hex_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
244template <typename InputIterator, typename OutputIterator>
245OutputIterator 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
259template <typename T, typename OutputIterator>
260OutputIterator 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
277template <typename Range, typename OutputIterator>
278OutputIterator 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
288template<typename String>
289String 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
302template<typename String>
303String 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
316template<typename String>
317String 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

source code of boost/libs/algorithm/include/boost/algorithm/hex.hpp