Data::UUID#

📦 std

Generate UUIDs (GUIDs): time-based ones that differ from every other, and name-based ones that are the same for the same namespace and name.

A generator object (Data::UUID->new) makes version 1 UUIDs from the clock and a node id of its own, and version 3 UUIDs from an MD5 of a namespace UUID and a name. Every UUID comes in four forms: 16 raw bytes, the 36-character string, 0x and 32 hex digits, or Base64.

Synopsis#

use Data::UUID;    # exports NameSpace_DNS, NameSpace_URL, NameSpace_OID, NameSpace_X500

my $ug   = Data::UUID->new;
my $uuid = $ug->create;                         # 16 bytes, version 1
print $ug->to_string($uuid), "\n";              # e.g. 4162F712-1DD2-11B2-B17E-C09EFE1DC403
print $ug->create_from_name_str(NameSpace_DNS, 'www.example.com'), "\n";
                                                 # 5DF41881-3AED-3515-88A7-2F4A814CF09E
my $back = $ug->from_string('6ba7b810-9dad-11d1-80b4-00c04fd430c8');
print $ug->compare($uuid, $back), "\n";         # -1, 0 or 1

The binary form#

The 16 bytes are Data::UUID’s own: the time and version fields in the machine’s byte order, as its C structure holds them, not the network order of RFC 4122. to_string and from_string convert correctly between them and the standard text form; the binary form itself is for Data::UUID’s own functions.

This is a native implementation of Data::UUID 1.227’s UUID.xs; its Data/UUID.pm is used unchanged.

Differences from upstream#

Five, each where perl 5.44 with UUID.xs reads or writes memory it does not own (t/81-xs-native/Data-UUID/150-or-better.t):

  • A binary UUID argument shorter than 16 bytes is taken with zero bytes after its end; perl5 reads past the string.

  • from_b64string of fewer than 16 bytes fills the rest with zero bytes; perl5 returns uninitialised memory there.

  • from_b64string of more than 16 bytes keeps the first 16; perl5 writes the rest past its buffer.

  • A byte above 0x7F in from_b64string’s input is skipped like any other character outside Base64; perl5 looks it up before its table.

  • from_string of a string that ends after a single hex digit of a byte before the last dies “from_string(…) failed…”; perl5 takes the next byte from past the end of the string.

Functions#

Generator#

new#

Create a generator, with a node id of its own.

create#

Make a new time-based (version 1) UUID.

Also available as Data::UUID::create_b64, Data::UUID::create_bin, Data::UUID::create_hex, Data::UUID::create_str.

create_from_name#

Make the name-based (version 3) UUID of a name in a namespace: the same namespace and name give the same UUID, everywhere and always.

Also available as Data::UUID::create_from_name_b64, Data::UUID::create_from_name_bin, Data::UUID::create_from_name_hex, Data::UUID::create_from_name_str.

Conversion#

compare#

Compare two binary UUIDs: -1, 0 or 1.

to_b64string#

Convert a binary UUID to text.

Also available as Data::UUID::to_hexstring, Data::UUID::to_string.

from_b64string#

Convert text back to a binary UUID.

Also available as Data::UUID::from_hexstring, Data::UUID::from_string.