libs/algorithm/doc/html/the_boost_algorithm_library/Misc/hex.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>hex</title>
   5 <link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../index.html" title="The Boost Algorithm Library">
   8 <link rel="up" href="../../algorithm/Misc.html" title="Other Algorithms">
   9 <link rel="prev" href="gather.html" title="gather">
  10 <link rel="next" href="is_palindrome.html" title="is_palindrome">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="gather.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../algorithm/Misc.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="is_palindrome.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="the_boost_algorithm_library.Misc.hex"></a><a class="link" href="hex.html" title="hex">hex</a>
  28 </h3></div></div></div>
  29 <p>
  30         The header file <code class="computeroutput"><span class="char">'boost/algorithm/hex.hpp'</span></code>
  31         contains three variants each of two algorithms, <code class="computeroutput"><span class="identifier">hex</span></code>
  32         and <code class="computeroutput"><span class="identifier">unhex</span></code>. They are inverse
  33         algorithms; that is, one undoes the effort of the other. <code class="computeroutput"><span class="identifier">hex</span></code>
  34         takes a sequence of values, and turns them into hexadecimal characters.
  35         <code class="computeroutput"><span class="identifier">unhex</span></code> takes a sequence of
  36         hexadecimal characters, and outputs a sequence of values.
  37       </p>
  38 <p>
  39         <code class="computeroutput"><span class="identifier">hex</span></code> and <code class="computeroutput"><span class="identifier">unhex</span></code>
  40         come from MySQL, where they are used in database queries and stored procedures.
  41       </p>
  42 <h5>
  43 <a name="the_boost_algorithm_library.Misc.hex.h0"></a>
  44         <span class="phrase"><a name="the_boost_algorithm_library.Misc.hex.interface"></a></span><a class="link" href="hex.html#the_boost_algorithm_library.Misc.hex.interface">interface</a>
  45       </h5>
  46 <p>
  47         The function <code class="computeroutput"><span class="identifier">hex</span></code> takes a
  48         sequence of values and writes hexadecimal characters. There are three different
  49         interfaces, differing only in how the input sequence is specified.
  50       </p>
  51 <p>
  52         The first one takes an iterator pair. The second one takes a pointer to the
  53         start of a zero-terminated sequence, such as a c string, and the third takes
  54         a range as defined by the Boost.Range library.
  55       </p>
  56 <p>
  57 </p>
  58 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">InputIterator</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span>
  59 <span class="identifier">OutputIterator</span> <span class="identifier">hex</span> <span class="special">(</span> <span class="identifier">InputIterator</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">InputIterator</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">OutputIterator</span> <span class="identifier">out</span> <span class="special">);</span>
  60
  61 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span>
  62 <span class="identifier">OutputIterator</span> <span class="identifier">hex</span> <span class="special">(</span> <span class="keyword">const</span> <span class="identifier">T</span> <span class="special">*</span><span class="identifier">ptr</span><span class="special">,</span> <span class="identifier">OutputIterator</span> <span class="identifier">out</span> <span class="special">);</span>
  63
  64 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Range</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span>
  65 <span class="identifier">OutputIterator</span> <span class="identifier">hex</span> <span class="special">(</span> <span class="keyword">const</span> <span class="identifier">Range</span> <span class="special">&amp;</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">OutputIterator</span> <span class="identifier">out</span> <span class="special">);</span>
  66 </pre>
  67 <p>
  68       </p>
  69 <p>
  70         <code class="computeroutput"><span class="identifier">hex</span></code> writes only values in
  71         the range '0'..'9' and 'A'..'F', but is not limited to character output.
  72         The output iterator could refer to a wstring, or a vector of integers, or
  73         any other integral type.
  74       </p>
  75 <p>
  76         The function <code class="computeroutput"><span class="identifier">unhex</span></code> takes
  77         the output of <code class="computeroutput"><span class="identifier">hex</span></code> and turns
  78         it back into a sequence of values.
  79       </p>
  80 <p>
  81         The input parameters for the different variations of <code class="computeroutput"><span class="identifier">unhex</span></code>
  82         are the same as <code class="computeroutput"><span class="identifier">hex</span></code>.
  83       </p>
  84 <p>
  85 </p>
  86 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">InputIterator</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span>
  87 <span class="identifier">OutputIterator</span> <span class="identifier">unhex</span> <span class="special">(</span> <span class="identifier">InputIterator</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">InputIterator</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">OutputIterator</span> <span class="identifier">out</span> <span class="special">);</span>
  88
  89 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span>
  90 <span class="identifier">OutputIterator</span> <span class="identifier">unhex</span> <span class="special">(</span> <span class="keyword">const</span> <span class="identifier">T</span> <span class="special">*</span><span class="identifier">ptr</span><span class="special">,</span> <span class="identifier">OutputIterator</span> <span class="identifier">out</span> <span class="special">);</span>
  91
  92 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Range</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span>
  93 <span class="identifier">OutputIterator</span> <span class="identifier">unhex</span> <span class="special">(</span> <span class="keyword">const</span> <span class="identifier">Range</span> <span class="special">&amp;</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">OutputIterator</span> <span class="identifier">out</span> <span class="special">);</span>
  94 </pre>
  95 <p>
  96       </p>
  97 <h5>
  98 <a name="the_boost_algorithm_library.Misc.hex.h1"></a>
  99         <span class="phrase"><a name="the_boost_algorithm_library.Misc.hex.error_handling"></a></span><a class="link" href="hex.html#the_boost_algorithm_library.Misc.hex.error_handling">Error
 100         Handling</a>
 101       </h5>
 102 <p>
 103         The header 'hex.hpp' defines three exception classes:
 104 </p>
 105 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">hex_decode_error</span><span class="special">:</span> <span class="keyword">virtual</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">exception</span><span class="special">,</span> <span class="keyword">virtual</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span> <span class="special">{};</span>
 106 <span class="keyword">struct</span> <span class="identifier">not_enough_input</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">hex_decode_error</span><span class="special">;</span>
 107 <span class="keyword">struct</span> <span class="identifier">non_hex_input</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">hex_decode_error</span><span class="special">;</span>
 108 </pre>
 109 <p>
 110       </p>
 111 <p>
 112         If the input to <code class="computeroutput"><span class="identifier">unhex</span></code> does
 113         not contain an "even number" of hex digits, then an exception of
 114         type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">not_enough_input</span></code> is thrown.
 115       </p>
 116 <p>
 117         If the input to <code class="computeroutput"><span class="identifier">unhex</span></code> contains
 118         any non-hexadecimal characters, then an exception of type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">non_hex_input</span></code>
 119         is thrown.
 120       </p>
 121 <p>
 122         If you want to catch all the decoding errors, you can catch exceptions of
 123         type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">hex_decode_error</span></code>.
 124       </p>
 125 <h5>
 126 <a name="the_boost_algorithm_library.Misc.hex.h2"></a>
 127         <span class="phrase"><a name="the_boost_algorithm_library.Misc.hex.examples"></a></span><a class="link" href="hex.html#the_boost_algorithm_library.Misc.hex.examples">Examples</a>
 128       </h5>
 129 <p>
 130         Assuming that <code class="computeroutput"><span class="identifier">out</span></code> is an iterator
 131         that accepts <code class="computeroutput"><span class="keyword">char</span></code> values, and
 132         <code class="computeroutput"><span class="identifier">wout</span></code> accepts <code class="computeroutput"><span class="keyword">wchar_t</span></code> values (and that sizeof ( wchar_t
 133         ) == 2)
 134       </p>
 135 <p>
 136 </p>
 137 <pre class="programlisting"><span class="identifier">hex</span> <span class="special">(</span> <span class="string">"abcdef"</span><span class="special">,</span> <span class="identifier">out</span> <span class="special">)</span>  <span class="special">--&gt;</span> <span class="string">"616263646566"</span>
 138 <span class="identifier">hex</span> <span class="special">(</span> <span class="string">"32"</span><span class="special">,</span> <span class="identifier">out</span> <span class="special">)</span>     <span class="special">--&gt;</span> <span class="string">"3332"</span>
 139 <span class="identifier">hex</span> <span class="special">(</span> <span class="string">"abcdef"</span><span class="special">,</span> <span class="identifier">wout</span> <span class="special">)</span> <span class="special">--&gt;</span> <span class="string">"006100620063006400650066"</span>
 140 <span class="identifier">hex</span> <span class="special">(</span> <span class="string">"32"</span><span class="special">,</span> <span class="identifier">wout</span> <span class="special">)</span>    <span class="special">--&gt;</span> <span class="string">"00330032"</span>
 141
 142 <span class="identifier">unhex</span> <span class="special">(</span> <span class="string">"616263646566"</span><span class="special">,</span> <span class="identifier">out</span> <span class="special">)</span>  <span class="special">--&gt;</span> <span class="string">"abcdef"</span>
 143 <span class="identifier">unhex</span> <span class="special">(</span> <span class="string">"3332"</span><span class="special">,</span> <span class="identifier">out</span> <span class="special">)</span>          <span class="special">--&gt;</span> <span class="string">"32"</span>
 144 <span class="identifier">unhex</span> <span class="special">(</span> <span class="string">"616263646566"</span><span class="special">,</span> <span class="identifier">wout</span> <span class="special">)</span> <span class="special">--&gt;</span> <span class="string">"\6162\6364\6566"</span>     <span class="special">(</span> <span class="identifier">i</span><span class="special">.</span><span class="identifier">e</span><span class="special">,</span> <span class="identifier">a</span> <span class="number">3</span> <span class="identifier">character</span> <span class="identifier">string</span> <span class="special">)</span>
 145 <span class="identifier">unhex</span> <span class="special">(</span> <span class="string">"3332"</span><span class="special">,</span> <span class="identifier">wout</span> <span class="special">)</span>         <span class="special">--&gt;</span> <span class="string">"\3233"</span>                               <span class="special">(</span> <span class="identifier">U</span><span class="special">+</span><span class="number">3332</span><span class="special">,</span> <span class="identifier">SQUARE</span> <span class="identifier">HUARADDO</span> <span class="special">)</span>
 146
 147 <span class="identifier">unhex</span> <span class="special">(</span> <span class="string">"3"</span><span class="special">,</span> <span class="identifier">out</span> <span class="special">)</span>            <span class="special">--&gt;</span> <span class="identifier">Error</span> <span class="special">-</span> <span class="keyword">not</span> <span class="identifier">enough</span> <span class="identifier">input</span>
 148 <span class="identifier">unhex</span> <span class="special">(</span> <span class="string">"32"</span><span class="special">,</span> <span class="identifier">wout</span> <span class="special">)</span>          <span class="special">--&gt;</span> <span class="identifier">Error</span> <span class="special">-</span> <span class="keyword">not</span> <span class="identifier">enough</span> <span class="identifier">input</span>
 149
 150 <span class="identifier">unhex</span> <span class="special">(</span> <span class="string">"ACEG"</span><span class="special">,</span> <span class="identifier">out</span> <span class="special">)</span>         <span class="special">--&gt;</span> <span class="identifier">Error</span> <span class="special">-</span> <span class="identifier">non</span><span class="special">-</span><span class="identifier">hex</span> <span class="identifier">input</span>
 151 </pre>
 152 <p>
 153       </p>
 154 <h5>
 155 <a name="the_boost_algorithm_library.Misc.hex.h3"></a>
 156         <span class="phrase"><a name="the_boost_algorithm_library.Misc.hex.iterator_requirements"></a></span><a class="link" href="hex.html#the_boost_algorithm_library.Misc.hex.iterator_requirements">Iterator
 157         Requirements</a>
 158       </h5>
 159 <p>
 160         <code class="computeroutput"><span class="identifier">hex</span></code> and <code class="computeroutput"><span class="identifier">unhex</span></code>
 161         work on all iterator types.
 162       </p>
 163 <h5>
 164 <a name="the_boost_algorithm_library.Misc.hex.h4"></a>
 165         <span class="phrase"><a name="the_boost_algorithm_library.Misc.hex.complexity"></a></span><a class="link" href="hex.html#the_boost_algorithm_library.Misc.hex.complexity">Complexity</a>
 166       </h5>
 167 <p>
 168         All of the variants of <code class="computeroutput"><span class="identifier">hex</span></code>
 169         and <code class="computeroutput"><span class="identifier">unhex</span></code> run in <span class="emphasis"><em>O(N)</em></span>
 170         (linear) time; that is, that is, they process each element in the input sequence
 171         once.
 172       </p>
 173 <h5>
 174 <a name="the_boost_algorithm_library.Misc.hex.h5"></a>
 175         <span class="phrase"><a name="the_boost_algorithm_library.Misc.hex.exception_safety"></a></span><a class="link" href="hex.html#the_boost_algorithm_library.Misc.hex.exception_safety">Exception
 176         Safety</a>
 177       </h5>
 178 <p>
 179         All of the variants of <code class="computeroutput"><span class="identifier">hex</span></code>
 180         and <code class="computeroutput"><span class="identifier">unhex</span></code> take their parameters
 181         by value or const reference, and do not depend upon any global state. Therefore,
 182         all the routines in this file provide the strong exception guarantee. However,
 183         when working on input iterators, if an exception is thrown, the input iterators
 184         will not be reset to their original values (i.e, the characters read from
 185         the iterator cannot be un-read)
 186       </p>
 187 <h5>
 188 <a name="the_boost_algorithm_library.Misc.hex.h6"></a>
 189         <span class="phrase"><a name="the_boost_algorithm_library.Misc.hex.notes"></a></span><a class="link" href="hex.html#the_boost_algorithm_library.Misc.hex.notes">Notes</a>
 190       </h5>
 191 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 192             <code class="computeroutput"><span class="identifier">hex</span></code> and <code class="computeroutput"><span class="identifier">unhex</span></code> both do nothing when passed empty
 193             ranges.
 194           </li></ul></div>
 195 </div>
 196 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 197 <td align="left"></td>
 198 <td align="right"><div class="copyright-footer">Copyright &#169; 2010-2012 Marshall Clow<p>
 199         Distributed under the Boost Software License, Version 1.0. (See accompanying
 200         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 201       </p>
 202 </div></td>
 203 </tr></table>
 204 <hr>
 205 <div class="spirit-nav">
 206 <a accesskey="p" href="gather.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../algorithm/Misc.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="is_palindrome.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 207 </div>
 208 </body>
 209 </html>