The MaybeBoost Hash Library

The MaybeBoost Hash Library: Classes

`digest<Bits>`

Defined in <boost/hash/digest.hpp>

The digest class template stores a Bits-bit message digest as a sequence of 8-bit octets. Octets are stored in the smallest unsigned type able to hold 8 bits, hereinafter referred to as octet_type. Bits must be a multiple of 8.

It is independent of any particular algorithm; For example sha2<224> and cubehash<224> both produce a digest<224>. Each algorithm generates its digest such that it will be displayed in the canonical order for that algorithm. The truncate and resize function templates are provided to handle digests with lengths other than you're expecting. For instance, generating name-based UUIDs uses only 128 bits but SHA-1 provides a 160-bit digest, so it would be truncated. (Using truncate instead of resize means that a compilation error will result from trying to use a hash algorithm with too small an output.) On the other hand, for storing as much as possible of the results of various algorithms, resize allows you to pad them out to a large size, such as a digest<512>.

digest<Bits> derives publicly from boost::array<octet_type, Bits/8> and supports all of its operations in order to provide direct access to the contained octets. Note that a digest is not an aggregate; A default-constructed digest has all its contained octets set to zero. The base_array() member function provides a reference to the boost::array sub-object.

digests with different numbers of bits may be compared. For the comparison, the smaller is considered as though it were padded with 0s out to the size of the larger. The operator< provides a strict total order. For convenience, equality comparison with narrow c-style strings is also provided.

In addition, the following operations are supported:

template <int NewBits, int OldBits> digest<NewBits> truncate(digest<OldBits> const&);: Returns a digest containing only the first NewBits bits of the argument digest. Requires that NewBits <= OldBits.; Truncating a message digest generally does not weaken the hash algorithm beyond the amount necessitated by the shorted output size.
template <int NewBits, int OldBits> digest<NewBits> resize(digest<OldBits> const&);: Returns a digest containing the first min(NewBits, OldBits) bits of the argument digest followed by max(0, NewBits - OldBits) 0 bits.

The <boost/hash/digest_io.hpp> header provides these additional operations:

template <int Bits> std::ostream &operator<<(std::ostream &, digest<Bits> const &);: Writes the stored octets to the sink as Bits/4 lower-case hexadecimal digits in big-bit order.
template <int Bits> std::istream &operator>>(std::istream &, digest<Bits> &);: Reads the stored octets from the source as Bits/4 case-insensitive hexadecimal digits in big-bit order. If fewer hexadecimal digits are available, they are assumed to be 0 and the stream's failbit is set.

Previous: Quickstart Next: Functions

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt).