<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from Data/UUID.rs. Do not edit. -->

```{index} single: Data::UUID
```

# Data::UUID

```{pperl-module-badges} Data::UUID
```

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

```perl
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`](UUID/new)

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

#### [`create`](UUID/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`](UUID/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`](UUID/compare)

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

#### [`to_b64string`](UUID/to_b64string)

Convert a binary UUID to text.

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

#### [`from_b64string`](UUID/from_b64string)

Convert text back to a binary UUID.

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

```{toctree}
:hidden:
:maxdepth: 1

UUID/new
UUID/create
UUID/create_from_name
UUID/compare
UUID/to_b64string
UUID/from_b64string
```