A UUID, or Universally unique identifier, is intended to uniquely identify information in a distributed environment without significant central coordination. It can be used to tag objects with very short lifetimes, or to reliably identify very persistent objects across a network.
Category | Functions |
---|---|
Parsing UUIDs | parseUUID UUID UUIDParsingException uuidRegex |
Generating UUIDs | sha1UUID randomUUID md5UUID |
Using UUIDs | UUID.uuidVersion UUID.variant UUID.toString UUID.data UUID.swap UUID.opEquals UUID.opCmp UUID.toHash |
UUID namespaces | dnsNamespace urlNamespace oidNamespace x500Namespace |
UUID.empty
is true
. Empty UUIDs are equal to UUID.init
, which is a UUID with all 16 bytes set to 0. Use UUID's constructors or the UUID generator functions to get an initialized UUID. import std.uuid; UUID[] ids; ids ~= randomUUID(); ids ~= md5UUID("test.name.123"); ids ~= sha1UUID("test.name.123"); foreach (entry; ids) { writeln(entry.variant); // UUID.Variant.rfc4122 } writeln(ids[0].uuidVersion); // UUID.Version.randomNumberBased writeln(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);
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.
std.variant.Variant
.NCS backward compatibility
Defined in RFC 4122 document
Microsoft Corporation backward compatibility
Reserved for future
use
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.
std.uuid
, but only version 3, 4 and 5 UUIDs can be generated.Unknown version
Version 1
Version 2
Version 3 (Name based + MD5)
Version 4 (Random)
Version 5 (Name based + SHA-1)
It is sometimes useful to get or set the 16 bytes of a UUID directly.
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. auto rawData = uuid.data; //get data rawData[0] = 1; //modify uuid.data = rawData; //set data uuid.data[1] = 2; //modify directly
Construct a UUID struct from the 16 byte representation of a UUID.
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); writeln(uuid.data); // data writeln(ctfe.data); // data
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.
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]);
Parse a UUID from its canonical string form. An UUID in its canonical form looks like this: 8ab3060e-2cba-4f23-b74c-b52db3bdfb46
UUIDParsingException
if the input is invalid parseUUID
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]); writeln(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!
Returns true
if and only if the UUID is equal to {00000000-0000-0000-0000-000000000000}
UUID id; assert(id.empty); id = UUID("00000000-0000-0000-0000-000000000001"); assert(!id.empty);
RFC 4122 defines different internal data layouts for UUIDs. Returns the format used by this UUID.
std.variant.Variant
. The type of this property is std.uuid.UUID.Variant
. UUID.Variant
assert(UUID("8ab3060e-2cba-4f23-b74c-b52db3bdfb46").variant == UUID.Variant.rfc4122);
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.
UUID.Version
assert(UUID("8ab3060e-2cba-4f23-b74c-b52db3bdfb46").uuidVersion == UUID.Version.randomNumberBased);
Swap the data of this UUID with the data of rhs
.
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); writeln(u1); // UUID(data) writeln(u2); // UUID.init
All of the standard numeric operators are defined for the UUID struct.
//compare UUIDs writeln(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]; writeln(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);
Write the UUID into sink
as an ASCII string in the canonical form, which is 36 characters in the form "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Writer sink
| OutputRange or writeable array at least 36 entries long |
Return the UUID as a string in the canonical form.
immutable str = "8ab3060e-2cba-4f23-b74c-b52db3bdfb46"; auto id = UUID(str); writeln(id.toString()); // str
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.
dnsNamespace
, ...) defined by this module should be used when appropriate. 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). //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);
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.
dnsNamespace
, ...) defined by this module should be used when appropriate. 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). //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);
This function generates a random number based UUID from a random number generator.
This function is not supported at compile time.
RNG randomGen
| uniform RNG |
std.random.isUniformRNG
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);
This is a less strict parser compared to the parser used in the UUID constructor. It enforces the following rules:
string s = "8AB3060E-2CBA-4F23-b74c-B52Db3BDFB46"; parseUUID(s); assert(s == "");
UUIDParsingException
if the input is invalid 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!
Default namespace from RFC 4122
Name string is a fully-qualified domain name
Default namespace from RFC 4122
Name string is a URL
Default namespace from RFC 4122
Name string is an ISO OID
Default namespace from RFC 4122
Name string is an X.500 DN (in DER or a text output format)
Regex string to extract UUIDs from text.
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"), ]);
This exception is thrown if an error occurs when parsing a UUID from a string.
import std.exception : collectException; const inputUUID = "this-is-an-invalid-uuid"; auto ex = collectException!UUIDParsingException(UUID(inputUUID)); assert(ex !is null); // check that exception was thrown writeln(ex.input); // inputUUID writeln(ex.position); // 0 writeln(ex.reason); // UUIDParsingException.Reason.tooLittle
The reason
why parsing the UUID string failed (if known)
The passed in input was correct, but more input was expected.
The input data is too long (There's no guarantee the first part of the data is valid)
Encountered an invalid character
The original input
string which should have been parsed.
The position
in the input string where the error occurred.
© 1999–2017 The D Language Foundation
Licensed under the Boost License 1.0.
https://dlang.org/phobos/std_uuid.html