ceph/src/boost/libs/algorithm/doc/hex.qbk

   1 [/ File hex.qbk]
   2
   3 [section:hex hex]
   4
   5 [/license
   6 Copyright (c) 2011-2012 Marshall Clow
   7
   8 Distributed 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
  12 The 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
  18 The 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
  20 The 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 ``
  23 template <typename InputIterator, typename OutputIterator>
  24 OutputIterator hex ( InputIterator first, InputIterator last, OutputIterator out );
  25
  26 template <typename T, typename OutputIterator>
  27 OutputIterator hex ( const T *ptr, OutputIterator out );
  28
  29 template <typename Range, typename OutputIterator>
  30 OutputIterator 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
  35 The function `unhex` takes the output of `hex` and turns it back into a sequence of values.
  36
  37 The input parameters for the different variations of `unhex` are the same as `hex`.
  38
  39 ``
  40 template <typename InputIterator, typename OutputIterator>
  41 OutputIterator unhex ( InputIterator first, InputIterator last, OutputIterator out );
  42
  43 template <typename T, typename OutputIterator>
  44 OutputIterator unhex ( const T *ptr, OutputIterator out );
  45
  46 template <typename Range, typename OutputIterator>
  47 OutputIterator unhex ( const Range &r, OutputIterator out );
  48 ``
  49
  50 [heading Error Handling]
  51 The header 'hex.hpp' defines three exception classes:
  52 ``
  53 struct hex_decode_error: virtual boost::exception, virtual std::exception {};
  54 struct not_enough_input : public hex_decode_error;
  55 struct non_hex_input : public hex_decode_error;
  56 ``
  57
  58 If 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
  60 If the input to `unhex` contains any non-hexadecimal characters, then an exception of type `boost::algorithm::non_hex_input` is thrown.
  61
  62 If you want to catch all the decoding errors, you can catch exceptions of type `boost::algorithm::hex_decode_error`.
  63
  64 [heading Examples]
  65
  66 Assuming that `out` is an iterator that accepts `char` values, and `wout` accepts `wchar_t` values (and that sizeof ( wchar_t ) == 2)
  67
  68 ``
  69 hex ( "abcdef", out )  --> "616263646566"
  70 hex ( "32", out )     --> "3332"
  71 hex ( "abcdef", wout ) --> "006100620063006400650066"
  72 hex ( "32", wout )    --> "00330032"
  73
  74 unhex ( "616263646566", out )  --> "abcdef"
  75 unhex ( "3332", out )          --> "32"
  76 unhex ( "616263646566", wout ) --> "\6162\6364\6566"    ( i.e, a 3 character string )
  77 unhex ( "3332", wout )         --> "\3233"                              ( U+3332, SQUARE HUARADDO )
  78
  79 unhex ( "3", out )            --> Error - not enough input
  80 unhex ( "32", wout )          --> Error - not enough input
  81
  82 unhex ( "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
  92 All 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
  96 All 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
 105 Copyright 2011 Marshall Clow
 106 Distributed 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