Library Reference

version 2.112.0

Internal API

If you spot a problem with this page, click here to create a Bugzilla issue.

Quickly fork, edit online, and submit a pull request for this page.Requires a signed-in GitHub account. This works well for small changes.If you'd like to make larger changes you may want to consider usinga local clone.

std.uuid

AUUID, orUniversally 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 timestampRandomUUID
Using UUIDs	UUID.uuidVersion UUID.variant UUID.toString UUID.data UUID.swap UUID.opEquals UUID.opCmp UUID.toHash
UUID namespaces	dnsNamespace urlNamespace oidNamespace x500Namespace

UUIDs have many applications. Some examples follow: Databases may use UUIDs to identify rows or records in order to ensure that they are unique across different databases, or for publication/subscription services. Network messages may be identified with a UUID to ensure that different parts of a message are put back together again. Distributed computing may use UUIDs to identify a remote procedure call. Transactions and classes involved in serialization may be identified by UUIDs. Microsoft's component object model (COM) uses UUIDs to distinguish different software component interfaces. UUIDs are inserted into documents from Microsoft Office programs. UUIDs identify audio or video streams in the Advanced Systems Format (ASF). UUIDs are also a basis for OIDs (object identifiers), and URNs (uniform resource name).

An attractive feature of UUIDs when compared to alternatives is their relative small size, of 128 bits, or 16 bytes. Another is that the creation of UUIDs does not require a centralized authority.

When UUIDs are generated by one of the defined mechanisms, they are either guaranteed to be unique, different from all other generated UUIDs (that is, it has never been generated before and it will never be generated again), or it is extremely likely to be unique (depending on the mechanism).

For efficiency, UUID is implemented as a struct. UUIDs are therefore empty if not explicitly initialized. An UUID is empty if`UUID.empty` is true. Empty UUIDs are equal toUUID.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.

This is a port of boost.uuid from the Boost project with some minor additions and API changes for a more D-like API.

Standards:

RFC 4122

License:

Boost License 1.0.

Authors:

Johannes Pfau

Sourcestd/uuid.d

Examples:

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.randomNumberBasedwriteln(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);

structUUID;

Examples:

UUID id;assert(id.empty);id = randomUUID;assert(!id.empty);id =UUID(cast(ubyte[16]) [138, 179, 6, 14, 44, 186, 79,    35, 183, 76, 181, 45, 179, 189, 251, 70]);writeln(id.toString());// "8ab3060e-2cba-4f23-b74c-b52db3bdfb46"

enumVariant: 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.

NoteDo not confuse this withstd.variant.Variant.

ncs: NCS backward compatibility
rfc4122: Defined in RFC 4122 document
microsoft: Microsoft Corporation backward compatibility
future: Reserved for future use

enumVersion: 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.

NoteAll of these UUID versions can be read and processed bystd.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)
timestampRandom: Version 7 (milliseconds since unix epoch + random)

ubyte[16]data;

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

NoteUUID 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 datarawData[0] = 1;//modifyuuid.data = rawData;//set datauuid.data[1] = 2;//modify directly

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

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

Examples:

enumubyte[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);// datawriteln(ctfe.data);// data

pure @safe this(T...)(TuuidData) 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]);

pure @safe this(SysTimetimestamp, ubyte[10]random = generateV7RandomData());

UUID V7 constructor

This implementation is not guaranteed to use a cryptographically secure PRNG. For more information please see: std.random.unpredictableSeed

Parameters:

SysTime`timestamp`	the timestamp part of the UUID V7
ubyte[10]`random`	UUID V7 has 74 bits of random data, which rounds to 10 ubyte's. If no random data is given, random data is generated.

Examples:

import std.datetime : DateTime, SysTime;SysTime st = DateTime(2025, 8, 19, 10, 38, 45);UUID u = UUID(st);SysTime o = u.v7Timestamp();writeln(o);// st

this(T)(in T[]uuid) if (isSomeChar!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

CTFEThis 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.

NoteThis 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, seeparseUUID

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]);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!

pure nothrow @nogc @property @trusted boolempty() const;

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);

SysTimev7Timestamp() const;

If the UUID is of version 7 it has a timestamp that this function returns, otherwise and UUIDParsingException is thrown.

pure nothrow @nogc @property @safe Variantvariant() const;

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

NoteDo not confuse this withstd.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);

pure nothrow @nogc @property @safe VersionuuidVersion() const;

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 voidswap(ref UUIDrhs);

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

Examples:

immutableubyte[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

pure nothrow @nogc @safe boolopEquals(const UUIDs) const; pure nothrow @nogc @safe boolopEquals(ref scope const UUIDs) const; pure nothrow @nogc @safe intopCmp(const UUIDs) const; pure nothrow @nogc @safe intopCmp(ref scope const UUIDs) const; pure nothrow @nogc @safe UUIDopAssign(const UUIDs); pure nothrow @nogc @safe UUIDopAssign(ref scope const UUIDs); pure nothrow @nogc @safe size_ttoHash() const;

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

Examples:

//compare UUIDswriteln(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);

voidtoString(Writer)(scope Writersink) const;

Write the UUID intosink as an ASCII string in the canonical form, which is 36 characters in the form "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Parameters:

Writersink OutputRange or writeable array at least 36 entries long

pure nothrow @trusted stringtoString() const;

Return the UUID as a string in the canonical form.

Examples:

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

pure nothrow @nogc @safe UUIDmd5UUID(const(char[])name, const UUIDnamespace = UUID.init); pure nothrow @nogc @safe UUIDmd5UUID(const(ubyte[])data, const UUIDnamespace = 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 UUIDUUID.init is used.

NoteThe 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.

CTFECTFE is not supported.

NoteRFC 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 bystd.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).

NoteThis 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 namespaceauto simpleID =md5UUID("test.uuid.any.string");//use a name-based id as namespaceautonamespace =md5UUID("my.app");auto id =md5UUID("some-description",namespace);

pure nothrow @nogc @safe UUIDsha1UUID(scope const(char)[]name, scope const UUIDnamespace = UUID.init); pure nothrow @nogc @safe UUIDsha1UUID(scope const(ubyte)[]data, scope const UUIDnamespace = 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 UUIDUUID.init is used.

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

CTFECTFE is not supported.

Examples:

//Use default UUID.init namespaceauto simpleID =sha1UUID("test.uuid.any.string");//use a name-based id as namespaceautonamespace =sha1UUID("my.app");auto id =sha1UUID("some-description",namespace);

nothrow @nogc @safe UUIDrandomUUID(); UUIDrandomUUID(RNG)(ref RNGrandomGen) if (isInputRange!RNG && isIntegral!(ElementType!RNG));

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

This function is not supported at compile time.

Bugs:

Issue #9881 - Randomness in UUID generation is insufficient

WarningThis function must not be used for cryptographic purposes. UUIDs generated by this function do not have sufficient randomness for all use cases. This especially applies to the overload that accepts a caller-provided RNG. At the moment, Phobos does not provide acryptographically-secure pseudo-random number generator (CSPRNG) that could be supplied to this function.

While the function overload with no parameters will attempt to use the system CSPRNG where available and implemented, there are no guarantees. Seestd.random.unpredictableSeed for details.

Parameters:

RNGrandomGen uniform RNG

See Also:

std.random.isUniformRNG

Examples:

import std.random : Xorshift192, unpredictableSeed;//simple callauto uuid =randomUUID();//provide a custom RNG. Must be seeded manually.Xorshift192 gen;gen.seed(unpredictableSeed);auto uuid3 =randomUUID(gen);

UUIDtimestampRandomUUID();

This function returns a timestamp + random based UUID aka. uuid v7.

Examples:

UUID u =timestampRandomUUID();writeln(u.uuidVersion);// UUID.Version.timestampRandom

UUIDparseUUID(T)(TuuidString) if (isSomeString!T); UUIDparseUUID(Range)(ref RangeuuidRange) if (isInputRange!Range && isSomeChar!(ElementType!Range));

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

CTFEThis 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 dashesid =parseUUID("8ab3060e2cba4f23b74cb52db3bdfb46");//dashes at different positionsid =parseUUID("8a-b3-06-0e2cba4f23b74c-b52db3bdfb-46");//leading / trailing charactersid =parseUUID("{8ab3060e-2cba-4f23-b74c-b52db3bdfb46}");//unicodeid =parseUUID("ü8ab3060e2cba4f23b74cb52db3bdfb46ü");//multiple trailing/leading charactersid =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 UUIDdnsNamespace;

Default namespace from RFC 4122

Name string is a fully-qualified domain name

enum UUIDurlNamespace;

Default namespace from RFC 4122

Name string is a URL

enum UUIDoidNamespace;

Default namespace from RFC 4122

Name string is an ISO OID

enum UUIDx500Namespace;

Default namespace from RFC 4122

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

enum stringuuidRegex;

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"),]);

classUUIDParsingException:object.Exception;

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

Examples:

import std.exception : collectException;const inputUUID ="this-is-an-invalid-uuid";auto ex = collectException!UUIDParsingException(UUID(inputUUID));assert(ex !isnull);// check that exception was thrownwriteln(ex.input);// inputUUIDwriteln(ex.position);// 0writeln(ex.reason);// UUIDParsingException.Reason.tooLittle

Examples:

uuidv7

import std.datetime : DateTime, SysTime;SysTime st = DateTime(2025, 8, 19, 10, 38, 45);UUID u = UUID(st);writeln(u.uuidVersion);// UUID.Version.timestampRandomSysTime o = u.v7Timestamp();writeln(o);// ststring s = u.toString();UUID u2 = UUID(s);SysTime o2 = u2.v7Timestamp();writeln(o2);// st

Examples:

uuid v7 generated by external tool

import std.datetime : DateTime, SysTime;UUID u = UUID("0198c2b2-c5a8-7a0f-a1db-86aac7906c7b");auto d = DateTime(2025,8,19);writeln((cast(DateTime)u.v7Timestamp()).year);// d.year

enumReason: int; Reasonreason;

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

stringinput;

The original input string which should have been parsed.

size_tposition;

The position in the input string where the error occurred.

Movatterモバイル変換

Library Reference

std.uuid