1[/ File hex.qbk] 2 3[section:hex hex] 4 5[/license 6Copyright (c) 2011-2012 Marshall Clow 7 8Distributed under the Boost Software License, Version 1.0. 9(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 10] 11 12The header file `'boost/algorithm/hex.hpp'` contains three variants each of two algorithms, `hex` and `unhex`. They are inverse algorithms; that is, one undoes the effort of the other. `hex` takes a sequence of values, and turns them into hexadecimal characters. `unhex` takes a sequence of hexadecimal characters, and outputs a sequence of values. 13 14`hex` and `unhex` come from MySQL, where they are used in database queries and stored procedures. 15 16[heading interface] 17 18The function `hex` takes a sequence of values and writes hexadecimal characters. There are three different interfaces, differing only in how the input sequence is specified. 19 20The first one takes an iterator pair. The second one takes a pointer to the start of a zero-terminated sequence, such as a c string, and the third takes a range as defined by the Boost.Range library. 21 22`` 23template <typename InputIterator, typename OutputIterator> 24OutputIterator hex ( InputIterator first, InputIterator last, OutputIterator out ); 25 26template <typename T, typename OutputIterator> 27OutputIterator hex ( const T *ptr, OutputIterator out ); 28 29template <typename Range, typename OutputIterator> 30OutputIterator hex ( const Range &r, OutputIterator out ); 31`` 32 33`hex` writes only values in the range '0'..'9' and 'A'..'F', but is not limited to character output. The output iterator could refer to a wstring, or a vector of integers, or any other integral type. 34 35The function `unhex` takes the output of `hex` and turns it back into a sequence of values. 36 37The input parameters for the different variations of `unhex` are the same as `hex`. 38 39`` 40template <typename InputIterator, typename OutputIterator> 41OutputIterator unhex ( InputIterator first, InputIterator last, OutputIterator out ); 42 43template <typename T, typename OutputIterator> 44OutputIterator unhex ( const T *ptr, OutputIterator out ); 45 46template <typename Range, typename OutputIterator> 47OutputIterator unhex ( const Range &r, OutputIterator out ); 48`` 49 50[heading Error Handling] 51The header 'hex.hpp' defines three exception classes: 52`` 53struct hex_decode_error: virtual boost::exception, virtual std::exception {}; 54struct not_enough_input : public hex_decode_error; 55struct non_hex_input : public hex_decode_error; 56`` 57 58If the input to `unhex` does not contain an "even number" of hex digits, then an exception of type `boost::algorithm::not_enough_input` is thrown. 59 60If the input to `unhex` contains any non-hexadecimal characters, then an exception of type `boost::algorithm::non_hex_input` is thrown. 61 62If you want to catch all the decoding errors, you can catch exceptions of type `boost::algorithm::hex_decode_error`. 63 64[heading Examples] 65 66Assuming that `out` is an iterator that accepts `char` values, and `wout` accepts `wchar_t` values (and that sizeof ( wchar_t ) == 2) 67 68`` 69hex ( "abcdef", out ) --> "616263646566" 70hex ( "32", out ) --> "3332" 71hex ( "abcdef", wout ) --> "006100620063006400650066" 72hex ( "32", wout ) --> "00330032" 73 74unhex ( "616263646566", out ) --> "abcdef" 75unhex ( "3332", out ) --> "32" 76unhex ( "616263646566", wout ) --> "\6162\6364\6566" ( i.e, a 3 character string ) 77unhex ( "3332", wout ) --> "\3233" ( U+3332, SQUARE HUARADDO ) 78 79unhex ( "3", out ) --> Error - not enough input 80unhex ( "32", wout ) --> Error - not enough input 81 82unhex ( "ACEG", out ) --> Error - non-hex input 83 84`` 85 86[heading Iterator Requirements] 87 88`hex` and `unhex` work on all iterator types. 89 90[heading Complexity] 91 92All of the variants of `hex` and `unhex` run in ['O(N)] (linear) time; that is, that is, they process each element in the input sequence once. 93 94[heading Exception Safety] 95 96All of the variants of `hex` and `unhex` take their parameters by value or const reference, and do not depend upon any global state. Therefore, all the routines in this file provide the strong exception guarantee. However, when working on input iterators, if an exception is thrown, the input iterators will not be reset to their original values (i.e, the characters read from the iterator cannot be un-read) 97 98[heading Notes] 99 100* `hex` and `unhex` both do nothing when passed empty ranges. 101 102[endsect] 103 104[/ File hex.qbk 105Copyright 2011 Marshall Clow 106Distributed under the Boost Software License, Version 1.0. 107(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt). 108] 109 110