std.digest.digest

struct ExampleDigest;

This documents the general structure of a Digest in the template API. All digest implementations should implement the following members and therefore pass the isDigest test.

Note:

• A digest must be a struct (value type) to pass the isDigest test.
• A digest passing the isDigest test is always an OutputRange

Examples:

//Using the OutputRange feature
import std.algorithm : copy;
import std.range : repeat;
import std.digest.md;

auto oneMillionRange = repeat!ubyte(cast(ubyte)'a', 1000000);
auto ctx = makeDigest!MD5();
copy(oneMillionRange, &ctx); //Note: You must pass a pointer to copy!
assert(ctx.finish().toHexString() == "7707D6AE4E027C70EEA2A935C2296F21");

@trusted void put(scope const(ubyte)[] data...);

Use this to feed the digest with data. Also implements the std.range.primitives.isOutputRange interface for ubyte and const(ubyte)[]. The following usages of put must work for any type which passes isDigest:

Examples:

ExampleDigest dig;
dig.put(cast(ubyte)0); //single ubyte
dig.put(cast(ubyte)0, cast(ubyte)0); //variadic
ubyte[10] buf;
dig.put(buf); //buffer

@trusted void start();

This function is used to (re)initialize the digest. It must be called before using the digest and it also works as a 'reset' function if the digest has already processed data.

@trusted ubyte[16] finish();

The finish function returns the final hash sum and resets the Digest.

Note: The actual type returned by finish depends on the digest implementation. ubyte[16] is just used as an example. It is guaranteed that the type is a static array of ubytes.

• Use DigestType to obtain the actual return type.
• Use digestLength to obtain the length of the ubyte array.

enum bool isDigest(T);

Use this to check if a type is a digest. See ExampleDigest to see what a type must provide to pass this check.

Note: This is very useful as a template constraint (see examples)

Bugs:

• Does not yet verify that put takes scope parameters.
• Should check that finish() returns a ubyte[num] array

Examples:

import std.digest.crc;
static assert(isDigest!CRC32);

Examples:

import std.digest.crc;
void myFunction(T)() if(isDigest!T)
{
    T dig;
    dig.start();
    auto result = dig.finish();
}
myFunction!CRC32();

template DigestType(T)

Use this template to get the type which is returned by a digest's finish method.

Examples:

import std.digest.crc;
assert(is(DigestType!(CRC32) == ubyte[4]));

Examples:

import std.digest.crc;
CRC32 dig;
dig.start();
DigestType!CRC32 result = dig.finish();

enum bool hasPeek(T);

Used to check if a digest supports the peek method. Peek has exactly the same function signatures as finish, but it doesn't reset the digest's internal state.

Note:

• This is very useful as a template constraint (see examples)
• This also checks if T passes isDigest

Examples:

import std.digest.crc, std.digest.md;
assert(!hasPeek!(MD5));
assert(hasPeek!CRC32);

Examples:

import std.digest.crc;
void myFunction(T)() if(hasPeek!T)
{
    T dig;
    dig.start();
    auto result = dig.peek();
}
myFunction!CRC32();

template hasBlockSize(T) if (isDigest!T)

Checks whether the digest has a blockSize member, which contains the digest's internal block size in bits. It is primarily used by std.digest.hmac.HMAC.

Examples:

import std.digest.md, std.digest.hmac;
static assert(hasBlockSize!MD5        && MD5.blockSize      == 512);
static assert(hasBlockSize!(HMAC!MD5) && HMAC!MD5.blockSize == 512);

DigestType!Hash digest(Hash, Range)(auto ref Range range) if (!isArray!Range && isDigestibleRange!Range);

This is a convenience function to calculate a hash using the template API. Every digest passing the isDigest test can be used with this function.

Parameters:

Range range

an InputRange with ElementType ubyte, ubyte[] or ubyte[num]

Examples:

import std.digest.md;
import std.range : repeat;
auto testRange = repeat!ubyte(cast(ubyte)'a', 100);
auto md5 = digest!MD5(testRange);

DigestType!Hash digest(Hash, T...)(scope const T data) if (allSatisfy!(isArray, typeof(data)));

This overload of the digest function handles arrays.

Parameters:

T data

one or more arrays of any type

Examples:

import std.digest.md, std.digest.sha, std.digest.crc;
auto md5   = digest!MD5(  "The quick brown fox jumps over the lazy dog");
auto sha1  = digest!SHA1( "The quick brown fox jumps over the lazy dog");
auto crc32 = digest!CRC32("The quick brown fox jumps over the lazy dog");
assert(toHexString(crc32) == "39A34F41");

Examples:

import std.digest.crc;
auto crc32 = digest!CRC32("The quick ", "brown ", "fox jumps over the lazy dog");
assert(toHexString(crc32) == "39A34F41");

char[digestLength!Hash * 2] hexDigest(Hash, Order order = Order.increasing, Range)(ref Range range) if (!isArray!Range && isDigestibleRange!Range);

This is a convenience function similar to digest, but it returns the string representation of the hash. Every digest passing the isDigest test can be used with this function.

Parameters:

order	the order in which the bytes are processed (see toHexString)
Range range	an InputRange with ElementType ubyte, ubyte[] or ubyte[num]

Examples:

import std.digest.md;
import std.range : repeat;
auto testRange = repeat!ubyte(cast(ubyte)'a', 100);
assert(hexDigest!MD5(testRange) == "36A92CC94A9E0FA21F625F8BFB007ADF");

char[digestLength!Hash * 2] hexDigest(Hash, Order order = Order.increasing, T...)(scope const T data) if (allSatisfy!(isArray, typeof(data)));

This overload of the hexDigest function handles arrays.

Parameters:

order	the order in which the bytes are processed (see toHexString)
T data	one or more arrays of any type

Examples:

import std.digest.crc;
assert(hexDigest!(CRC32, Order.decreasing)("The quick brown fox jumps over the lazy dog") == "414FA339");

Examples:

import std.digest.crc;
assert(hexDigest!(CRC32, Order.decreasing)("The quick ", "brown ", "fox jumps over the lazy dog") == "414FA339");

Hash makeDigest(Hash)();

This is a convenience function which returns an initialized digest, so it's not necessary to call start manually.

Examples:

import std.digest.md;
auto md5 = makeDigest!MD5();
md5.put(0);
assert(toHexString(md5.finish()) == "93B885ADFE0DA089CDF634904FD59F71");

interface Digest;

This describes the OOP API. To understand when to use the template API and when to use the OOP API, see the module documentation at the top of this page.

The Digest interface is the base interface which is implemented by all digests.

Note: A Digest implementation is always an OutputRange

Examples:

//Using the OutputRange feature
import std.algorithm : copy;
import std.range : repeat;
import std.digest.md;

auto oneMillionRange = repeat!ubyte(cast(ubyte)'a', 1000000);
auto ctx = new MD5Digest();
copy(oneMillionRange, ctx);
assert(ctx.finish().toHexString() == "7707D6AE4E027C70EEA2A935C2296F21");

Examples:

import std.digest.md, std.digest.sha, std.digest.crc;
ubyte[] md5   = (new MD5Digest()).digest("The quick brown fox jumps over the lazy dog");
ubyte[] sha1  = (new SHA1Digest()).digest("The quick brown fox jumps over the lazy dog");
ubyte[] crc32 = (new CRC32Digest()).digest("The quick brown fox jumps over the lazy dog");
assert(crcHexString(crc32) == "414FA339");

Examples:

import std.digest.crc;
ubyte[] crc32 = (new CRC32Digest()).digest("The quick ", "brown ", "fox jumps over the lazy dog");
assert(crcHexString(crc32) == "414FA339");

Examples:

void test(Digest dig)
{
    dig.put(cast(ubyte)0); //single ubyte
    dig.put(cast(ubyte)0, cast(ubyte)0); //variadic
    ubyte[10] buf;
    dig.put(buf); //buffer
}

abstract nothrow @trusted void put(scope const(ubyte)[] data...);

Use this to feed the digest with data. Also implements the std.range.primitives.isOutputRange interface for ubyte and const(ubyte)[].

Examples:

void test(Digest dig)
{
    dig.put(cast(ubyte)0); //single ubyte
    dig.put(cast(ubyte)0, cast(ubyte)0); //variadic
    ubyte[10] buf;
    dig.put(buf); //buffer
}

abstract nothrow @trusted void reset();

Resets the internal state of the digest.

Note: finish calls this internally, so it's not necessary to call reset manually after a call to finish.

abstract const nothrow @property @trusted size_t length();

This is the length in bytes of the hash value which is returned by finish. It's also the required size of a buffer passed to finish.

abstract nothrow @trusted ubyte[] finish();
abstract nothrow ubyte[] finish(scope ubyte[] buf);

The finish function returns the hash value. It takes an optional buffer to copy the data into. If a buffer is passed, it must be at least length bytes big.

final nothrow @trusted ubyte[] digest(scope const(void[])[] data...);

This is a convenience function to calculate the hash of a value using the OOP API.

enum Order: bool;

See toHexString

increasing

decreasing

char[num * 2] toHexString(Order order = Order.increasing, size_t num, LetterCase letterCase = LetterCase.upper)(in ubyte[num] digest);
char[num * 2] toHexString(LetterCase letterCase, Order order = Order.increasing, size_t num)(in ubyte[num] digest);
string toHexString(Order order = Order.increasing, LetterCase letterCase = LetterCase.upper)(in ubyte[] digest);
string toHexString(LetterCase letterCase, Order order = Order.increasing)(in ubyte[] digest);

Used to convert a hash value (a static or dynamic array of ubytes) to a string. Can be used with the OOP and with the template API.

The additional order parameter can be used to specify the order of the input data. By default the data is processed in increasing order, starting at index 0. To process it in the opposite order, pass Order.decreasing as a parameter.

The additional letterCase parameter can be used to specify the case of the output data. By default the output is in upper case. To change it to the lower case pass LetterCase.lower as a parameter.

Note: The function overloads returning a string allocate their return values using the GC. The versions returning static arrays use pass-by-value for the return value, effectively avoiding dynamic allocation.

Examples:

import std.digest.crc;
//Test with template API:
auto crc32 = digest!CRC32("The quick ", "brown ", "fox jumps over the lazy dog");
//Lower case variant:
assert(toHexString!(LetterCase.lower)(crc32) == "39a34f41");
//Usually CRCs are printed in this order, though:
assert(toHexString!(Order.decreasing)(crc32) == "414FA339");
assert(toHexString!(LetterCase.lower, Order.decreasing)(crc32) == "414fa339");

Examples:

import std.digest.crc;
// With OOP API
auto crc32 = (new CRC32Digest()).digest("The quick ", "brown ", "fox jumps over the lazy dog");
//Usually CRCs are printed in this order, though:
assert(toHexString!(Order.decreasing)(crc32) == "414FA339");

template digestLength(T) if (isDigest!T)

This helper is used internally in the WrapperDigest template, but it might be useful for other purposes as well. It returns the length (in bytes) of the hash value produced by T.

class WrapperDigest(T) if (isDigest!T): Digest;

Wraps a template API hash struct into a Digest interface. Modules providing digest implementations will usually provide an alias for this template (e.g. MD5Digest, SHA1Digest, ...).

Examples:

import std.digest.md;
//Simple example
auto hash = new WrapperDigest!MD5();
hash.put(cast(ubyte)0);
auto result = hash.finish();

Examples:

//using a supplied buffer
import std.digest.md;
ubyte[16] buf;
auto hash = new WrapperDigest!MD5();
hash.put(cast(ubyte)0);
auto result = hash.finish(buf[]);
//The result is now in result (and in buf). If you pass a buffer which is bigger than
//necessary, result will have the correct length, but buf will still have it's original
//length

this();

Initializes the digest.

nothrow @trusted void put(scope const(ubyte)[] data...);

Use this to feed the digest with data. Also implements the std.range.primitives.isOutputRange interface for ubyte and const(ubyte)[].

nothrow @trusted void reset();

Resets the internal state of the digest.

Note: finish calls this internally, so it's not necessary to call reset manually after a call to finish.

const pure nothrow @property @trusted size_t length();

This is the length in bytes of the hash value which is returned by finish. It's also the required size of a buffer passed to finish.

nothrow ubyte[] finish(scope ubyte[] buf);
nothrow @trusted ubyte[] finish();

The finish function returns the hash value. It takes an optional buffer to copy the data into. If a buffer is passed, it must have a length at least length bytes.

Examples:

import std.digest.md;
ubyte[16] buf;
auto hash = new WrapperDigest!MD5();
hash.put(cast(ubyte)0);
auto result = hash.finish(buf[]);
//The result is now in result (and in buf). If you pass a buffer which is bigger than
//necessary, result will have the correct length, but buf will still have it's original
//length

const @trusted ubyte[] peek(scope ubyte[] buf);
const @trusted ubyte[] peek();

Works like finish but does not reset the internal state, so it's possible to continue putting data into this WrapperDigest after a call to peek.

These functions are only available if hasPeek!T is true.