std.uuid

A UUID, или универсальный уникальный идентификатор, предназначен для уникальной идентификации информации в распределенной среде без существенной централизованной координации. Он может использоваться для маркировки объектов с очень коротким жизненным циклом или для надежной идентификации очень устойчивых объектов в сети.

UUID имеют множество применений. Некоторые примеры: базы данных могут использовать UUID для идентификации строк или записей, чтобы гарантировать их уникальность в разных базах данных, или для сервисов публикации/подписки. Сеть сообщения могут идентифицироваться с помощью UUID, чтобы гарантировать, что различные части сообщения собираются воедино. Распределённые вычисления могут использовать UUID для идентификации удалённого вызова процедуры. Транзакции и классы, участвующие в сериализации, могут идентифицироваться UUID. Модель компонентов Microsoft (COM) использует UUID для различения различных интерфейсов программных компонентов. UUID вставляются в документы из программ Microsoft Office. UUID идентифицируют аудио или видео потоки в формате ASF (Advanced Systems Format). UUID также являются основой для OID (идентификаторов объектов) и URN (унифицированных имен ресурсов).

Привлекательной особенностью UUID по сравнению с альтернативами является их относительно небольшой размер, 128 бит или 16 байт. Другой особенностью является то, что для создания UUID не требуется центральный орган.

Когда UUID генерируются одним из определённых механизмов, они либо гарантированно уникальны, отличаются от всех других сгенерированных UUID (то есть, они никогда не генерировались ранее и никогда не будут сгенерированы снова), или чрезвычайно вероятно, что они уникальны (в зависимости от механизма).

Для повышения эффективности UUID реализован как структура. UUID, следовательно, пустые, если не инициализированы явно. UUID пустой, если `UUID.empty` имеет значение true. Пустые UUID равны UUID.init, что является UUID, у которого все 16 байт установлены в 0. Используйте конструкторы UUID или функции генерации UUID для получения инициализированного UUID.

Это порт boost.uuid из проекта Boost с некоторыми незначительными дополнениями и изменениями API для более D-подобного API.

Стандарты:

RFC 4122

См. также:

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

Лицензия:

Boost License 1.0.

Авторы:

Johannes Pfau

Источник

std/uuid.d

Примеры:

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

struct UUID;

Примеры:

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"

enum Вариант: int;

RFC 4122 определяет разные внутренние структуры данных для UUID. Это форматы UUID, поддерживаемые этим модулем. Возможен вывод, сравнение и использование всех этих вариантов, но UUID, сгенерированные этим модулем, всегда будут в формате rfc4122.

Примечание

Не путайте это с std.variant.Variant.

ncs

Обратная совместимость NCS

rfc4122

Определено в документе RFC 4122

microsoft

Обратная совместимость корпорации Майкрософт

будущее

Зарезервировано для будущего использования

enum Версия: int;

RFC 4122 определяет различные версии UUID. Версия показывает, как был сгенерирован UUID, например, UUID версии 4 был сгенерирован из случайного числа, а UUID версии 3 — из хеша MD5 имени.

Примечание

Все эти версии UUID могут быть прочитаны и обработаны std.uuid, но только UUID версии 3, 4 и 5 могут быть сгенерированы.

неизвестно

Неизвестная версия

базирующаяся на времени

Версия 1

dceSecurity

Версия 2

базирующаяся на имени MD5

Версия 3 (базирующаяся на имени + MD5)

базирующаяся на случайном числе

Версия 4 (Случайная)

базирующаяся на имени SHA-1

Версия 5 (базирующаяся на имени + SHA-1)

ubyte[16] данные;

Иногда полезно получить или установить 16 байтов UUID напрямую.

Примечание

UUID использует 16-байтовое представление данных UUID. RFC 4122 определяет UUID как специальную структуру в формате big-endian. Эти 16 байтов всегда равны структуре big-endian, определенной в RFC 4122.

Пример

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 scope const ubyte[16] uuidData);

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

Создать структуру UUID из 16-байтового представления 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

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

Создать структуру UUID из 16-байтового представления UUID. Вариативный конструктор для более простого синтаксиса, см. примеры. Необходимо передать ровно 16 байт.

Примеры:

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)
Constraints: if (isSomeChar!(Unqual!T));

Разобрать UUID из его канонической строковой формы. UUID в канонической форме выглядит так: 8ab3060e-2cba-4f23-b74c-b52db3bdfb46

Выбрасывает:

UUIDParsingException, если входной данные некорректны

CTFE

Эта функция поддерживается в коде CTFE. Обратите внимание, что сообщения об ошибках, вызванные некорректным UUID, разобранным во время компиляции, могут быть неявными, но ошибки обнаруживаются и сообщаются во время компиляции.

Примечание

Это строгий парсер. Он принимает только указанный выше шаблон. Он не поддерживает какие-либо ведущие или хвостовые символы. Он принимает только символы, используемые для шестнадцатеричных чисел, и строка должна содержать дефисы точно так же, как указано выше.

Для менее строгого парсера см. 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!

const pure nothrow @nogc @property @trusted bool пустой();

Возвращает true, если и только если UUID равен {00000000-0000-0000-0000-000000000000}

Примеры:

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

const pure nothrow @nogc @property @safe Variant вариант();

RFC 4122 определяет разные внутренние структуры данных для UUID. Возвращает формат, используемый этим UUID.

Примечание

Не путайте это с std.variant.Variant. Тип этого свойства — `std.uuid.UUID.Вариант`.

См. также:

`UUID.Вариант`

Примеры:

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

const pure nothrow @nogc @property @safe Version версияUUID();

RFC 4122 определяет различные версии UUID. Версия показывает, как был сгенерирован UUID, например, UUID версии 4 был сгенерирован из случайного числа, а UUID версии 3 — из хеша MD5 имени. Возвращает используемую версию этого UUID.

См. также:

`UUID.Версия`

Примеры:

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

pure nothrow @nogc @safe void поменять(ref UUID rhs);

Поменять данные этого UUID с данными 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

const pure nothrow @nogc @safe bool равен(const UUID s);

const pure nothrow @nogc @safe bool равен(ref scope const UUID s);

const pure nothrow @nogc @safe int сравнение(const UUID s);

const pure nothrow @nogc @safe int сравнение(ref scope const UUID s);

pure nothrow @nogc @safe UUID присвоить(const UUID s);

pure nothrow @nogc @safe UUID присвоить(ref scope const UUID s);

const pure nothrow @nogc @safe size_t хеширование();

Для структуры UUID определены все стандартные числовые операторы.

Примеры:

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

const void вСтроку(Writer)(scope Writer sink);

Записать UUID в sink как строку ASCII в канонической форме, которая имеет 36 символов в формате "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Параметры:

Writer sink

Диапазон вывода или записываемый массив не менее 36 элементов

const pure nothrow @trusted string вСтроку();

Возвращает UUID как строку в канонической форме.

Примеры:

immutable str = "8ab3060e-2cba-4f23-b74c-b52db3bdfb46";
auto id = UUID(str);
writeln(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);

Эта функция генерирует UUID, базирующийся на имени (Версия 3), из UUID пространства имён и имени. Если UUID пространства имён не был передан, используется пустой UUID UUID.init.

Примечание

Следует использовать предустановленные пространства имён (dnsNamespace, ...), определенные этим модулем, при необходимости.

RFC 4122 рекомендует использовать UUID версии 5 (SHA-1) вместо UUID версии 3 (MD5) для новых приложений.

CTFE

CTFE не поддерживается.

Примечание

RFC 4122 не очень ясно описывает, как UUID должны быть сгенерированы из имён. Возможно, разные реализации возвращают разные UUID для одного и того же входного значения, поэтому будьте осторожны. Реализация для строк UTF-8 и массивов байт, используемая std.uuid совместима с реализацией Boost. std.uuid гарантирует, что один и тот же ввод в эту функцию будет генерировать один и тот же вывод в любое время, на любой системе (это особенно относится к порядку байтов).

Примечание

Эта функция не предоставляет перегрузки для wstring и dstring, так как нет однозначного ответа о том, как это должно быть реализовано. Можно утверждать, что строка, wstring и dstring должны иметь одинаковый вывод, но это не будет совместимо с Boost, который генерирует разные выводы для строк и wstrings. Всегда можно передать wstring и dstring, используя перегрузку функции ubyte[] (но будьте внимательны к проблемам порядка байтов!).

Примеры:

//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(scope const(char)[] name, scope const UUID namespace = UUID.init);

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

Эта функция генерирует UUID, базирующийся на имени (Версия 5), из UUID пространства имён и имени. Если UUID пространства имён не был передан, используется пустой UUID UUID.init.

Примечание

Следует использовать предустановленные пространства имён (dnsNamespace, ...), определенные этим модулем, при необходимости.

CTFE

CTFE не поддерживается.

Примечание

RFC 4122 не очень ясно описывает, как UUID должны быть сгенерированы из имён. Возможно, разные реализации возвращают разные UUID для одного и того же входного значения, поэтому будьте осторожны. Реализация для строк UTF-8 и массивов байт, используемая std.uuid совместима с реализацией Boost. std.uuid гарантирует, что один и тот же ввод в эту функцию будет генерировать один и тот же вывод в любое время, на любой системе (это особенно относится к порядку байтов).

Примечание

Эта функция не предоставляет перегрузки для wstring и dstring, так как нет однозначного ответа о том, как это должно быть реализовано. Можно утверждать, что строка, wstring и dstring должны иметь одинаковый вывод, но это не будет совместимо с Boost, который генерирует разные выводы для строк и wstrings. Всегда можно передать wstring и dstring, используя перегрузку функции ubyte[] (но будьте внимательны к проблемам порядка байтов!).

Примеры:

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

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

Эта функция генерирует случайное число, основанное на UUID, из генератора случайных чисел.

Эта функция не поддерживается на этапе компиляции.

Параметры:

RNG randomGen

равномерный генератор случайных чисел

См. также:

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

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

UUID parseUUID(Range)(ref Range uuidRange)
Constraints: if (isInputRange!Range && isSomeChar!(ElementType!Range));

Это менее строгий анализатор по сравнению с анализатором, используемым в конструкторе UUID. Он применяет следующие правила:

• шестнадцатеричные числа всегда состоят из двух шестнадцатеричных цифр ([0-9a-fA-F])
• входные данные должны содержать ровно 16 таких пар, ни меньше, ни больше
• между двумя парами шестнадцатеричных цифр может быть ровно один дефис, но не больше
• вокруг 16 пар шестнадцатеричных цифр могут быть дополнительные символы, но эти символы не должны содержать [0-9a-fA-F]

Примечание

Как и большинство анализаторов, он потребляет свой аргумент. Это означает:

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

Исключения:

UUIDParsingException, если входные данные неверны

CTFE

Эта функция поддерживается в коде CTFE. Обратите внимание, что сообщения об ошибках, вызванные неверным UUID, проанализированным на этапе компиляции, могут быть неясными, но ошибки обнаруживаются и сообщаются на этапе компиляции.

Примеры:

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;

Умолчательный пространство имен из RFC 4122

Строка имени — полностью квалифицированное доменное имя

enum UUID urlNamespace;

Умолчательный пространство имен из RFC 4122

Строка имени — URL

enum UUID oidNamespace;

Умолчательный пространство имен из RFC 4122

Строка имени — ISO OID

enum UUID x500Namespace;

Умолчательный пространство имен из RFC 4122

Строка имени — DN X.500 (в формате DER или текстовом формате)

enum string uuidRegex;

Строка регулярного выражения для извлечения UUID из текста.

Примеры:

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;

Это исключение генерируется, если при анализе UUID из строки произошла ошибка.

Примеры:

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

enum Reason: int;

Reason reason;

Причина, по которой произошел сбой анализа строки UUID (если известна)

unknown

tooLittle

Переданные входные данные были корректными, но ожидалось больше входных данных.

tooMuch

Входные данные слишком длинные (нет гарантии, что первая часть данных является валидной)

invalidChar

Встречен недопустимый символ

string input;

Исходная строка входных данных, которая должна была быть проанализирована.

size_t position;

Позиция в строке входных данных, где произошла ошибка.