View source code Display the source code in std/uuid.d from which this page was generated on github. Improve this page 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 using local clone. Page wiki View or edit the community-maintained wiki page associated with this page.

Module std.uuid

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

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

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

Examples

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

Standards

RFC 4122

See Also

http://en.wikipedia.org/wiki/Universally_unique_identifier

Functions

Name Description
md5UUID 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.
parseUUID This is a less strict parser compared to the parser used in the UUID constructor. It enforces the following rules:
randomUUID This function generates a random number based UUID from a random number generator.
randomUUID ditto
sha1UUID 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.

Classes

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

Structs

Name Description
UUID

Enum values

Name Type Description
dnsNamespace Default namespace from RFC 4122
oidNamespace Default namespace from RFC 4122
urlNamespace Default namespace from RFC 4122
uuidRegex Regex string to extract UUIDs from text.
x500Namespace Default namespace from RFC 4122

Authors

Johannes Pfau

License

Boost License 1.0.

Comments