std.uuid

import std.uuid;

UUID[] ids;
ids ~= randomUUID();
ids ~= md5UUID("test.name.123");
ids ~= sha1UUID("test.name.123");

foreach(entry; ids)
{
    assert(entry.variant == UUID.Variant.rfc4122);
}
assert(ids[0].uuidVersion == UUID.Version.randomNumberBased);
assert(ids[1].toString() == "22390768-cced-325f-8f0f-cfeaa19d0ccd");
assert(ids[1].data == [34, 57, 7, 104, 204, 237, 50, 95, 143, 15, 207,
    234, 161, 157, 12, 205]);
UUID id;
assert(id.empty);

struct UUID;

enum Variant: int;

RFC 4122 defines different internal data layouts for UUIDs. These are the UUID formats supported by this module. It's possible to read, compare and use all these Variants, but UUIDs generated by this module will always be in rfc4122 format.

Note: Do not confuse this with std.variant.Variant.

ncs

NCS backward compatibility

rfc4122

Defined in RFC 4122 document

microsoft

Microsoft Corporation backward compatibility

future

Reserved for future use

enum Version: int;

RFC 4122 defines different UUID versions. The version shows how a UUID was generated, e.g. a version 4 UUID was generated from a random number, a version 3 UUID from an MD5 hash of a name.

Note: All of these UUID versions can be read and processed by std.uuid, but only version 3, 4 and 5 UUIDs can be generated.

unknown

Unknown version

timeBased

Version 1

dceSecurity

Version 2

nameBasedMD5

Version 3 (Name based + MD5)

randomNumberBased

Version 4 (Random)

nameBasedSHA1

Version 5 (Name based + SHA-1)

ubyte[16] data;

It is sometimes useful to get or set the 16 bytes of a UUID directly.

Note: UUID uses a 16-ubyte representation for the UUID data. RFC 4122 defines a UUID as a special structure in big-endian format. These 16-ubytes always equal the big-endian structure defined in RFC 4122.

Example:

auto rawData = uuid.data; //get data
rawData[0] = 1; //modify
uuid.data = rawData; //set data
uuid.data[1] = 2; //modify directly

pure nothrow @nogc @safe this(ref ubyte[16] uuidData);

pure nothrow @nogc @safe this(in ubyte[16] uuidData);

Construct a UUID struct from the 16 byte representation of a UUID.

Examples:

enum ubyte[16] data = [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15];
auto uuid = UUID(data);
enum ctfe = UUID(data);
assert(uuid.data == data);
assert(ctfe.data == data);

pure @safe this(T...)(T uuidData)
if (uuidData.length == 16 && allSatisfy!(isIntegral, T));

Construct a UUID struct from the 16 byte representation of a UUID. Variadic constructor to allow a simpler syntax, see examples. You need to pass exactly 16 ubytes.

Examples:

auto tmp = UUID(0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15);
assert(tmp.data == cast(ubyte[16])[0,1,2,3,4,5,6,7,8,9,10,11,
    12,13,14,15]);

this(T)(in T[] uuid)
if (isSomeChar!(Unqual!T));

Parse a UUID from its canonical string form. An UUID in its canonical form looks like this: 8ab3060e-2cba-4f23-b74c-b52db3bdfb46

Throws:

UUIDParsingException if the input is invalid

CTFE: This function is supported in CTFE code. Note that error messages caused by a malformed UUID parsed at compile time can be cryptic, but errors are detected and reported at compile time.

Note: This is a strict parser. It only accepts the pattern above. It doesn't support any leading or trailing characters. It only accepts characters used for hex numbers and the string must have hyphens exactly like above.

For a less strict parser, see parseUUID

Examples:

auto id = UUID("8AB3060E-2cba-4f23-b74c-b52db3bdfb46");
assert(id.data == [138, 179, 6, 14, 44, 186, 79, 35, 183, 76,
   181, 45, 179, 189, 251, 70]);
assert(id.toString() == "8ab3060e-2cba-4f23-b74c-b52db3bdfb46");

//Can also be used in CTFE, for example as UUID literals:
enum ctfeID = UUID("8ab3060e-2cba-4f23-b74c-b52db3bdfb46");
//here parsing is done at compile time, no runtime overhead!

const pure nothrow @nogc @property @trusted bool empty();

Returns true if and only if the UUID is equal to {00000000-0000-0000-0000-000000000000}

Examples:

UUID id;
assert(id.empty);
id = UUID("00000000-0000-0000-0000-000000000001");
assert(!id.empty);

const pure nothrow @nogc @property @safe Variant variant();

RFC 4122 defines different internal data layouts for UUIDs. Returns the format used by this UUID.

Note: Do not confuse this with std.variant.Variant. The type of this property is std.uuid.UUID.Variant.

See Also:

UUID.Variant

Examples:

assert(UUID("8ab3060e-2cba-4f23-b74c-b52db3bdfb46").variant
   == UUID.Variant.rfc4122);

const pure nothrow @nogc @property @safe Version uuidVersion();

RFC 4122 defines different UUID versions. The version shows how a UUID was generated, e.g. a version 4 UUID was generated from a random number, a version 3 UUID from an MD5 hash of a name. Returns the version used by this UUID.

See Also:

UUID.Version

Examples:

assert(UUID("8ab3060e-2cba-4f23-b74c-b52db3bdfb46").uuidVersion
    == UUID.Version.randomNumberBased);

pure nothrow @nogc @safe void swap(ref UUID rhs);

Swap the data of this UUID with the data of rhs.

Examples:

immutable ubyte[16] data = [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15];
UUID u1;
UUID u2 = UUID(data);
u1.swap(u2);

assert(u1 == UUID(data));
assert(u2 == UUID.init);

const pure nothrow @nogc @safe bool opEquals(in UUID s);

const pure nothrow @nogc @safe bool opEquals(ref UUID s);

const pure nothrow @nogc @safe int opCmp(in UUID s);

const pure nothrow @nogc @safe int opCmp(ref UUID s);

pure nothrow @nogc @safe UUID opAssign(in UUID s);

pure nothrow @nogc @safe UUID opAssign(ref UUID s);

const pure nothrow @nogc @safe size_t toHash();

All of the standard numeric operators are defined for the UUID struct.

Examples:

//compare UUIDs
assert(UUID("00000000-0000-0000-0000-000000000000") == UUID.init);

//UUIDs in associative arrays:
int[UUID] test = [UUID("8a94f585-d180-44f7-8929-6fca0189c7d0") : 1,
    UUID("7c351fd4-b860-4ee3-bbdc-7f79f3dfb00a") : 2,
    UUID("9ac0a4e5-10ee-493a-86fc-d29eeb82ecc1") : 3];

assert(test[UUID("9ac0a4e5-10ee-493a-86fc-d29eeb82ecc1")] == 3);

//UUIDS can be sorted:
import std.algorithm;
UUID[] ids = [UUID("8a94f585-d180-44f7-8929-6fca0189c7d0"),
              UUID("7c351fd4-b860-4ee3-bbdc-7f79f3dfb00a"),
              UUID("9ac0a4e5-10ee-493a-86fc-d29eeb82ecc1")];
sort(ids);

const pure nothrow @nogc @safe void toString(Range)(Range result)
if (isRandomAccessRange!Range && hasAssignableElements!Range && hasLength!Range && (isSomeChar!(typeof(Range.init[0])) || isUnsigned!(typeof(Range.init[0]))) || isSomeString!Range && isMutable!(typeof(Range.init[0])));

Write the UUID into result as an ASCII string in the canonical form.

const void toString(scope void delegate(const(char)[]) sink);

Call a delegate with a string in the canonical form.

const pure nothrow @trusted string toString();

Return the UUID as a string in the canonical form.

Examples:

immutable str = "8ab3060e-2cba-4f23-b74c-b52db3bdfb46";
auto id = UUID(str);
assert(id.toString() == str);

pure nothrow @nogc @safe UUID md5UUID(const(char[]) name, const UUID namespace = UUID.init);

pure nothrow @nogc @safe UUID md5UUID(const(ubyte[]) data, const UUID namespace = UUID.init);

This function generates a name based (Version 3) UUID from a namespace UUID and a name. If no namespace UUID was passed, the empty UUID UUID.init is used.

Note: The default namespaces (dnsNamespace, ...) defined by this module should be used when appropriate.

RFC 4122 recommends to use Version 5 UUIDs (SHA-1) instead of Version 3 UUIDs (MD5) for new applications.

CTFE: CTFE is not supported.

Note: RFC 4122 isn't very clear on how UUIDs should be generated from names. It is possible that different implementations return different UUIDs for the same input, so be warned. The implementation for UTF-8 strings and byte arrays used by std.uuid is compatible with Boost's implementation. std.uuid guarantees that the same input to this function will generate the same output at any time, on any system (this especially means endianness doesn't matter).

Note: This function does not provide overloads for wstring and dstring, as there's no clear answer on how that should be implemented. It could be argued, that string, wstring and dstring input should have the same output, but that wouldn't be compatible with Boost, which generates different output for strings and wstrings. It's always possible to pass wstrings and dstrings by using the ubyte[] function overload (but be aware of endianness issues!).

Examples:

//Use default UUID.init namespace
auto simpleID = md5UUID("test.uuid.any.string");

//use a name-based id as namespace
auto namespace = md5UUID("my.app");
auto id = md5UUID("some-description", namespace);

pure nothrow @nogc @safe UUID sha1UUID(in char[] name, const UUID namespace = UUID.init);

pure nothrow @nogc @safe UUID sha1UUID(in ubyte[] data, const UUID namespace = UUID.init);

This function generates a name based (Version 5) UUID from a namespace UUID and a name. If no namespace UUID was passed, the empty UUID UUID.init is used.

Note: The default namespaces (dnsNamespace, ...) defined by this module should be used when appropriate.

CTFE: CTFE is not supported.

Note: RFC 4122 isn't very clear on how UUIDs should be generated from names. It is possible that different implementations return different UUIDs for the same input, so be warned. The implementation for UTF-8 strings and byte arrays used by std.uuid is compatible with Boost's implementation. std.uuid guarantees that the same input to this function will generate the same output at any time, on any system (this especially means endianness doesn't matter).

Note: This function does not provide overloads for wstring and dstring, as there's no clear answer on how that should be implemented. It could be argued, that string, wstring and dstring input should have the same output, but that wouldn't be compatible with Boost, which generates different output for strings and wstrings. It's always possible to pass wstrings and dstrings by using the ubyte[] function overload (but be aware of endianness issues!).

Examples:

//Use default UUID.init namespace
auto simpleID = sha1UUID("test.uuid.any.string");

//use a name-based id as namespace
auto namespace = sha1UUID("my.app");
auto id = sha1UUID("some-description", namespace);

@safe UUID randomUUID();

This function generates a random number based UUID from a random number generator.

CTFE: This function is not supported at compile time.

UUID randomUUID(RNG)(ref RNG randomGen)
if (isInputRange!RNG && isIntegral!(ElementType!RNG));

ditto

Parameters:

RNG randomGen

uniform RNG

See Also:

std.random.isUniformRNG

Examples:

import std.random : Xorshift192, unpredictableSeed;

//simple call
auto uuid = randomUUID();

//provide a custom RNG. Must be seeded manually.
Xorshift192 gen;

gen.seed(unpredictableSeed);
auto uuid3 = randomUUID(gen);

UUID parseUUID(T)(T uuidString)
if (isSomeString!T);

UUID parseUUID(Range)(ref Range uuidRange)
if (isInputRange!Range && is(Unqual!(ElementType!Range) == dchar));

This is a less strict parser compared to the parser used in the UUID constructor. It enforces the following rules:

• hex numbers are always two hexdigits([0-9a-fA-F])
• there must be exactly 16 such pairs in the input, not less, not more
• there can be exactly one dash between two hex-pairs, but not more
• there can be multiple characters enclosing the 16 hex pairs, as long as these characters do not contain [0-9a-fA-F]

Note: Like most parsers, it consumes its argument. This means:

string s = "8AB3060E-2CBA-4F23-b74c-B52Db3BDFB46";
parseUUID(s);
assert(s == "");

Throws:

UUIDParsingException if the input is invalid

CTFE: This function is supported in CTFE code. Note that error messages caused by a malformed UUID parsed at compile time can be cryptic, but errors are detected and reported at compile time.

Examples:

auto id = parseUUID("8AB3060E-2CBA-4F23-b74c-B52Db3BDFB46");
//no dashes
id = parseUUID("8ab3060e2cba4f23b74cb52db3bdfb46");
//dashes at different positions
id = parseUUID("8a-b3-06-0e2cba4f23b74c-b52db3bdfb-46");
//leading / trailing characters
id = parseUUID("{8ab3060e-2cba-4f23-b74c-b52db3bdfb46}");
//unicode
id = parseUUID("ü8ab3060e2cba4f23b74cb52db3bdfb46ü");
//multiple trailing/leading characters
id = parseUUID("///8ab3060e2cba4f23b74cb52db3bdfb46||");

//Can also be used in CTFE, for example as UUID literals:
enum ctfeID = parseUUID("8ab3060e-2cba-4f23-b74c-b52db3bdfb46");
//here parsing is done at compile time, no runtime overhead!

enum UUID dnsNamespace;

Default namespace from RFC 4122

Name string is a fully-qualified domain name

enum UUID urlNamespace;

Default namespace from RFC 4122

Name string is a URL

enum UUID oidNamespace;

Default namespace from RFC 4122

Name string is an ISO OID

enum UUID x500Namespace;

Default namespace from RFC 4122

Name string is an X.500 DN (in DER or a text output format)

enum string uuidRegex;

Regex string to extract UUIDs from text.

Examples:

import std.algorithm;
import std.regex;

string test = "Lorem ipsum dolor sit amet, consetetur "~
"6ba7b814-9dad-11d1-80b4-00c04fd430c8 sadipscing \n"~
"elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore \r\n"~
"magna aliquyam erat, sed diam voluptua. "~
"8ab3060e-2cba-4f23-b74c-b52db3bdfb46 At vero eos et accusam et "~
"justo duo dolores et ea rebum.";

auto r = regex(uuidRegex, "g");
UUID[] found;
foreach(c; match(test, r))
{
    found ~= UUID(c.hit);
}
assert(found == [
    UUID("6ba7b814-9dad-11d1-80b4-00c04fd430c8"),
    UUID("8ab3060e-2cba-4f23-b74c-b52db3bdfb46"),
]);

class UUIDParsingException: object.Exception;

This exception is thrown if an error occurs when parsing a UUID from a string.

Examples:

auto ex = new UUIDParsingException("foo", 10, UUIDParsingException.Reason.tooMuch);
assert(ex.input == "foo");
assert(ex.position == 10);
assert(ex.reason == UUIDParsingException.Reason.tooMuch);

enum Reason: int;

Reason reason;

The reason why parsing the UUID string failed (if known)

unknown

tooLittle

The passed in input was correct, but more input was expected.

tooMuch

The input data is too long (There's no guarantee the first part of the data is valid)

invalidChar

Encountered an invalid character

string input;

The original input string which should have been parsed.

size_t position;

The position in the input string where the error occurred.