Boost 学习之算法篇 hex

原文链接:http://www.boost.org/doc/libs/1_60_0/libs/algorithm/doc/html/the_boost_algorithm_library/Misc/hex.html

hex

    头文件“boost/algorithm/hex.hpp” 包含了两个算法：hex、unhex以及他们各自的三个版本的变体。hex将一个序列元素转换为十六进制数，unhex功能正好相反。
    hex 和 unhex ，来源于MySQL，原来他们用在数据库中做查询和保存程序用。

接口
    hex函数带一个值序列，并写入十六进制字符。有是三个不同的接口，这些接口仅仅是传入传入参数有所不同。第一个接口带一对迭代器做形参；第二个接口带一个指针，该指针指向以0结尾的序列的起始位置，就是指向一个类似C格式的字符串的起始位置；第三个接口带一个通过Boost.Range库限定的一个集合。

官方接口

template <typename InputIterator, typename OutputIterator>
OutputIterator hex ( InputIterator first, InputIterator last, OutputIterator out );

template <typename T, typename OutputIterator>
OutputIterator hex ( const T *ptr, OutputIterator out );

template <typename Range, typename OutputIterator>
OutputIterator hex ( const Range &r, OutputIterator out );

十六进制仅仅使用'0'..'9'以及'A'..'F'组成的值表示，但是输出却不止限定字符。输出的迭代器可以指向一个wstring 或者一个integers类型的vector，或者是其他任何证书类型。

函数unhex 将hex的输出转换回值序列。
unhex不同接口的输入参数和hex相同。如下所示：

template <typename InputIterator, typename OutputIterator>
OutputIterator unhex ( InputIterator first, InputIterator last, OutputIterator out );

template <typename T, typename OutputIterator>
OutputIterator unhex ( const T *ptr, OutputIterator out );

template <typename Range, typename OutputIterator>
OutputIterator unhex ( const Range &r, OutputIterator out );

错误处理

hex.hpp 文件定义了三个异常类:

struct hex_decode_error: virtual boost::exception, virtual std::exception {};
struct not_enough_input : public hex_decode_error;
struct non_hex_input : public hex_decode_error;

假如unhex的输入参数不是一个以一个十六进制表示的序列("event number"),这将抛出一个boost::algorithm::not_enough_input 异常。
假如unhex传递的参数包含了非十六进制字符,那么将会抛出boost::algorithm::non_hex_input的异常。
假如你希望捕获所有的编码错误,那么可以通过捕获ype boost::algorithm::hex_decode_error该异常来获取.

例子
假如输出是一个指向值的迭代器,同时不指向wchar_t值则:

hex ( "abcdef", out )  --> "616263646566"
hex ( "32", out )     --> "3332"
hex ( "abcdef", wout ) --> "006100620063006400650066"
hex ( "32", wout )    --> "00330032"

unhex ( "616263646566", out )  --> "abcdef"
unhex ( "3332", out )          --> "32"
unhex ( "616263646566", wout ) --> "\6162\6364\6566"    ( i.e, a 3 character string )
unhex ( "3332", wout )         --> "\3233"                ( U+3332, SQUARE HUARADDO )

unhex ( "3", out )            --> Error - not enough input
unhex ( "32", wout )          --> Error - not enough input
unhex ( "ACEG", out )         --> Error - non-hex input

迭代器要求
hex和unhex可作用于任何一类迭代器中。

时间复杂度
所有hex以及unhex函数以及派生的接口的时间复杂度都是O(N );也就是说,这些接口将依次处理每一个输入序列中的元素仅仅一次。

异常安全性
hex和unhex函数以及派生的接口，都通过值或者常引用传递参数，不依赖任何全局的状态。因此，他们提供了很强的异常安全性保证。然而，当作用在输入迭代器（input iterators）的时候，假如有异常抛，输入迭代器将不会重置为原来的状态。
注意
    hex和unhex当接受空序列的时候不做任何操作。hex and unhex both do nothing when passed empty ranges.