1UUID(3)               User Contributed Perl Documentation              UUID(3)
2
3
4

NAME

6       Data::UUID - Globally/Universally Unique Identifiers (GUIDs/UUIDs)
7

SEE INSTEAD?

9       The module Data::GUID provides another interface for generating GUIDs.
10       Right now, it relies on Data::UUID, but it may not in the future.  Its
11       interface may be just a little more straightforward for the average
12       Perl programer.
13

SYNOPSIS

15         use Data::UUID;
16
17         $ug    = Data::UUID->new;
18         $uuid1 = $ug->create();
19         $uuid2 = $ug->create_from_name(<namespace>, <name>);
20
21         $res   = $ug->compare($uuid1, $uuid2);
22
23         $str   = $ug->to_string( $uuid );
24         $uuid  = $ug->from_string( $str );
25

DESCRIPTION

27       This module provides a framework for generating v3 UUIDs (Universally
28       Unique Identifiers, also known as GUIDs (Globally Unique Identifiers).
29       A UUID is 128 bits long, and is guaranteed to be different from all
30       other UUIDs/GUIDs generated until 3400 CE.
31
32       UUIDs were originally used in the Network Computing System (NCS) and
33       later in the Open Software Foundation's (OSF) Distributed Computing
34       Environment.  Currently many different technologies rely on UUIDs to
35       provide unique identity for various software components. Microsoft
36       COM/DCOM for instance, uses GUIDs very extensively to uniquely identify
37       classes, applications and components across network-connected systems.
38
39       The algorithm for UUID generation, used by this extension, is described
40       in the Internet Draft "UUIDs and GUIDs" by Paul J. Leach and Rich Salz.
41       (See RFC 4122.)  It provides reasonably efficient and reliable
42       framework for generating UUIDs and supports fairly high allocation
43       rates -- 10 million per second per machine -- and therefore is suitable
44       for identifying both extremely short-lived and very persistent objects
45       on a given system as well as across the network.
46
47       This modules provides several methods to create a UUID.  In all
48       methods, "<namespace>" is a UUID and "<name>" is a free form string.
49
50          # creates binary (16 byte long binary value) UUID.
51          $ug->create();
52          $ug->create_bin();
53
54          # creates binary (16-byte long binary value) UUID based on particular
55          # namespace and name string.
56          $ug->create_from_name(<namespace>, <name>);
57          $ug->create_from_name_bin(<namespace>, <name>);
58
59          # creates UUID string, using conventional UUID string format,
60          # such as: 4162F712-1DD2-11B2-B17E-C09EFE1DC403
61          # Note that digits A-F are capitalized, which is contrary to rfc4122
62          $ug->create_str();
63          $ug->create_from_name_str(<namespace>, <name>);
64
65          # creates UUID string as a hex string,
66          # such as: 0x4162F7121DD211B2B17EC09EFE1DC403
67          # Note that digits A-F are capitalized, which is contrary to rfc4122
68          $ug->create_hex();
69          $ug->create_from_name_hex(<namespace>, <name>);
70
71          # creates UUID string as a Base64-encoded string
72          $ug->create_b64();
73          $ug->create_from_name_b64(<namespace>, <name>);
74
75          Binary UUIDs can be converted to printable strings using following methods:
76
77          # convert to conventional string representation
78          $ug->to_string(<uuid>);
79
80          # convert to hex string (using upper, rather than lower, case letters)
81          $ug->to_hexstring(<uuid>);
82
83          # convert to Base64-encoded string
84          $ug->to_b64string(<uuid>);
85
86          Conversely, string UUIDs can be converted back to binary form:
87
88          # recreate binary UUID from string
89          $ug->from_string(<uuid>);
90          $ug->from_hexstring(<uuid>);
91
92          # recreate binary UUID from Base64-encoded string
93          $ug->from_b64string(<uuid>);
94
95          Finally, two binary UUIDs can be compared using the following method:
96
97          # returns -1, 0 or 1 depending on whether uuid1 less
98          # than, equals to, or greater than uuid2
99          $ug->compare(<uuid1>, <uuid2>);
100
101       Examples:
102
103          use Data::UUID;
104
105          # this creates a new UUID in string form, based on the standard namespace
106          # UUID NameSpace_URL and name "www.mycompany.com"
107
108          $ug = Data::UUID->new;
109          print $ug->create_from_name_str(NameSpace_URL, "www.mycompany.com");
110
111   EXPORT
112       The module allows exporting of several standard namespace UUIDs:
113
114       NameSpace_DNS
115       NameSpace_URL
116       NameSpace_OID
117       NameSpace_X500
118

AUTHOR

120       Alexander Golomshtok <agolomsh@cpan.org>
121

SEE ALSO

123       The Internet Draft "UUIDs and GUIDs" by Paul J. Leach and Rich Salz
124       (RFC 4122)
125
126
127
128perl v5.36.0                      2022-07-22                           UUID(3)
Impressum