1UUID::Tiny(3) User Contributed Perl Documentation UUID::Tiny(3)
2
6 UUID::Tiny - Pure Perl UUID Support With Functional Interface
7
9 Version 1.04
10
12 Create version 1, 3, 4 and 5 UUIDs:
13 use UUID::Tiny ':std';
15 my $v1_mc_UUID = create_uuid();
17 my $v1_mc_UUID_2 = create_uuid(UUID_V1);
18 my $v1_mc_UUID_3 = create_uuid(UUID_TIME);
19 my $v3_md5_UUID = create_uuid(UUID_V3, $str);
20 my $v3_md5_UUID_2 = create_uuid(UUID_MD5, UUID_NS_DNS, 'caugustin.de');
21 my $v4_rand_UUID = create_uuid(UUID_V4);
22 my $v4_rand_UUID_2 = create_uuid(UUID_RANDOM);
23 my $v5_sha1_UUID = create_uuid(UUID_V5, $str);
24 my $v5_with_NS_UUID = create_uuid(UUID_SHA1, UUID_NS_DNS, 'caugustin.de');
25 my $v1_mc_UUID_string = create_uuid_as_string(UUID_V1);
27 my $v3_md5_UUID_string = uuid_to_string($v3_md5_UUID);
28 if ( version_of_uuid($v1_mc_UUID) == 1 ) { ... };
30 if ( version_of_uuid($v5_sha1_UUID) == 5 ) { ... };
31 if ( is_uuid_string($v1_mc_UUID_string) ) { ... };
32 if ( equal_uuids($uuid1, $uuid2) ) { ... };
33 my $uuid_time = time_of_uuid($v1_mc_UUID);
35 my $uuid_clk_seq = clk_seq_of_uuid($v1_mc_UUID);
36
38 UUID::Tiny is a lightweight, low dependency Pure Perl module for UUID
39 creation and testing. This module provides the creation of version 1
40 time based UUIDs (using random multicast MAC addresses), version 3 MD5
41 based UUIDs, version 4 random UUIDs, and version 5 SHA-1 based UUIDs.
42 ATTENTION! UUID::Tiny uses Perl's rand() to create the basic random
44 numbers, so the created v4 UUIDs are not cryptographically strong!
45 No fancy OO interface, no plethora of different UUID representation
47 formats and transformations - just string and binary. Conversion, test
48 and time functions equally accept UUIDs and UUID strings, so don't
49 bother to convert UUIDs for them!
50 Continuing with 1.0x versions all constants and public functions are
52 exported by default, but this will change in the future (see below).
53 UUID::Tiny deliberately uses a minimal functional interface for UUID
55 creation (and conversion/testing), because in this case OO looks like
56 overkill to me and makes the creation and use of UUIDs unnecessarily
57 complicated.
58 If you need raw performance for UUID creation, or the real MAC address
60 in version 1 UUIDs, or an OO interface, and if you can afford module
61 compilation and installation on the target system, then better look at
62 other CPAN UUID modules like Data::UUID.
63 This module is "fork safe", especially for random UUIDs (it works
65 around Perl's rand() problem when forking processes).
66 This module is currently not "thread safe". Even though I've
68 incorporated some changes proposed by Michael G. Schwern (thanks!),
69 Digest::MD5 and Digest::SHA seem so have trouble with threads. There is
70 a test file for threads, but it is de-activated. So use at your own
71 risk!
72
74 This module should run from Perl 5.8 up and uses mostly standard (5.8
75 core) modules for its job. No compilation or installation required.
76 These are the modules UUID::Tiny depends on:
77 Carp
79 Digest::MD5 Perl 5.8 core
80 Digest::SHA Perl 5.10 core (or Digest::SHA1, or Digest::SHA::PurePerl)
81 MIME::Base64 Perl 5.8 core
82 Time::HiRes Perl 5.8 core
83 POSIX Perl 5.8 core
84 If you are using this module on a Perl prior to 5.10 and you don't have
86 Digest::SHA1 installed, you can use Digest::SHA::PurePerl instead.
87
89 After some debate I'm convinced that it is more Perlish (and far easier
90 to write) to use all-lowercase function names - without exceptions. And
91 that it is more polite to export symbols only on demand.
92 While the 1.0x versions will continue to export the old, "legacy"
94 interface on default, the future standard interface is available using
95 the ":std" tag on import from version 1.02 on:
96 use UUID::Tiny ':std';
98 my $md5_uuid = create_uuid(UUID_MD5, $str);
99 In preparation for future version of UUID::Tiny you have to use the
101 ":legacy" tag if you want to stay with the version 1.0 interface:
102 use UUID::Tiny ':legacy';
104 my $md5_uuid = create_UUID(UUID_V3, $str);
105
107 NIL UUID
108 This module provides the NIL UUID (shown with its string
109 representation):
110 UUID_NIL: '00000000-0000-0000-0000-000000000000'
112 Pre-defined Namespace UUIDs
114 This module provides the common pre-defined namespace UUIDs (shown
115 with their string representation):
116 UUID_NS_DNS: '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
118 UUID_NS_URL: '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
119 UUID_NS_OID: '6ba7b812-9dad-11d1-80b4-00c04fd430c8'
120 UUID_NS_X500: '6ba7b814-9dad-11d1-80b4-00c04fd430c8'
121 UUID versions
123 This module provides the UUID version numbers as constants:
124 UUID_V1
126 UUID_V3
127 UUID_V4
128 UUID_V5
129 With "use UUID::Tiny ':std';" you get additional, "speaking"
131 constants:
132 UUID_TIME
134 UUID_MD5
135 UUID_RANDOM
136 UUID_SHA1
137 UUID_SHA1_AVAIL
139 my $uuid = create_UUID( UUID_SHA1_AVAIL? UUID_V5 : UUID_V3, $str );
140 This function returns 1 if a module to create SHA-1 digests could
142 be loaded, 0 otherwise.
143 UUID::Tiny (since version 1.02) tries to load Digest::SHA,
145 Digest::SHA1 or Digest::SHA::PurePerl, but does not die if none of
146 them is found. Instead create_UUID() and create_UUID_as_string()
147 die when trying to create an SHA-1 based UUID without an
148 appropriate module available.
149
151 All public functions are exported by default (they should not collide
152 with other functions).
153 create_UUID() creates standard binary UUIDs in network byte order (MSB
155 first), create_UUID_as_string() creates the standard string
156 representation of UUIDs.
157 All query and test functions (except "is_UUID_string") accept both
159 representations.
160 create_UUID(), create_uuid() (:std)
162 my $v1_mc_UUID = create_UUID();
163 my $v1_mc_UUID = create_UUID(UUID_V1);
164 my $v3_md5_UUID = create_UUID(UUID_V3, $ns_uuid, $name_or_filehandle);
165 my $v3_md5_UUID = create_UUID(UUID_V3, $name_or_filehandle);
166 my $v4_rand_UUID = create_UUID(UUID_V4);
167 my $v5_sha1_UUID = create_UUID(UUID_V5, $ns_uuid, $name_or_filehandle);
168 my $v5_sha1_UUID = create_UUID(UUID_V5, $name_or_filehandle);
169 Creates a binary UUID in network byte order (MSB first). For v3 and
171 v5 UUIDs a "SCALAR" (normally a string), "GLOB" ("classic" file
172 handle) or "IO" object (i.e. "IO::File") can be used; files have to
173 be opened for reading.
174 I found no hint if and how UUIDs should be created from file
176 content. It seems to be undefined, but it is useful - so I would
177 suggest to use UUID_NIL as the namespace UUID, because no "real
178 name" is used; UUID_NIL is used by default if a namespace UUID is
179 missing (only 2 arguments are used).
180 create_UUID_as_string(), create_uuid_as_string() (:std)
182 Similar to "create_UUID", but creates a UUID string.
183 is_UUID_string(), is_uuid_string() (:std)
185 my $bool = is_UUID_string($str);
186 UUID_to_string(), uuid_to_string() (:std)
188 my $uuid_str = UUID_to_string($uuid);
189 This function returns $uuid unchanged if it is a UUID string
191 already.
192 string_to_UUID(), string_to_uuid() (:std)
194 my $uuid = string_to_UUID($uuid_str);
195 This function returns $uuid_str unchanged if it is a UUID already.
197 In addition to the standard UUID string representation and its URN
199 forms (starting with "urn:uuid:" or "uuid:"), this function accepts
200 32 digit hex strings, variants with different positions of "-" and
201 Base64 encoded UUIDs.
202 Throws an exception if string can't be interpreted as a UUID.
204 If you want to make sure to have a "pure" standard UUID
206 representation, check with "is_UUID_string"!
207 version_of_UUID(), version_of_uuid() (:std)
209 my $version = version_of_UUID($uuid);
210 This function accepts binary and string UUIDs.
212 time_of_UUID(), time_of_uuid() (:std)
214 my $uuid_time = time_of_UUID($uuid);
215 This function accepts UUIDs and UUID strings. Returns the time as a
217 floating point value, so use int() to get a time() compatible
218 value.
219 Returns "undef" if the UUID is not version 1.
221 clk_seq_of_UUID(), clk_seq_of_uuid() (:std)
223 my $uuid_clk_seq = clk_seq_of_UUID($uuid);
224 This function accepts UUIDs and UUID strings. Returns the clock
226 sequence for a version 1 UUID. Returns "undef" if UUID is not
227 version 1.
228 equal_UUIDs(), equal_uuids() (:std)
230 my $bool = equal_UUIDs($uuid1, $uuid2);
231 Returns true if the provided UUIDs are equal. Accepts UUIDs and
233 UUID strings (can be mixed).
234
236 Why version 1 only with random multi-cast MAC addresses?
237 The random multi-cast MAC address gives privacy, and getting the
238 real MAC address with Perl is really dirty (and slow);
239 Should version 3 or version 5 be used?
241 Using SHA-1 reduces the probability of collisions and provides a
242 better "randomness" of the resulting UUID compared to MD5. Version
243 5 is recommended in RFC 4122 if backward compatibility is not an
244 issue.
245 Using MD5 (version 3) has a better performance. This could be
247 important with creating UUIDs from file content rather than names.
248
250 See RFC 4122 (<http://www.ietf.org/rfc/rfc4122.txt>) for technical
251 details on UUIDs. Wikipedia gives a more palatable description at
252 <http://en.wikipedia.org/wiki/Universally_unique_identifier>.
253
255 Christian Augustin, "<mail at caugustin.de>"
256
258 Some of this code is based on UUID::Generator by ITO Nobuaki
259 <banb@cpan.org>. But that module is announced to be marked as
260 "deprecated" in the future and it is much too complicated for my
261 liking.
262 So I decided to reduce it to the necessary parts and to re-implement
264 those parts with a functional interface ...
265 Jesse Vincent, "<jesse at bestpractical.com>", improved version 1.02
267 with his tips and a heavy refactoring.
268 Michael G. Schwern provided a patch for better thread support (as far
270 as UUID::Tiny can be improved itself) that is incorporated in version
271 1.04.
272
274 Please report any bugs or feature requests to "bug-uuid-tiny at
275 rt.cpan.org", or through the web interface at
276 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=UUID-Tiny>. I will be
277 notified, and then you'll automatically be notified of progress on your
278 bug as I make changes.
279
281 You can find documentation for this module with the perldoc command.
282 perldoc UUID::Tiny
284 You can also look for information at:
286 • RT: CPAN's request tracker
288 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=UUID-Tiny>
290 • AnnoCPAN: Annotated CPAN documentation
292 <http://annocpan.org/dist/UUID-Tiny>
294 • CPAN Ratings
296 <http://cpanratings.perl.org/d/UUID-Tiny>
298 • Search CPAN
300 <http://search.cpan.org/dist/UUID-Tiny/>
302
304 Kudos to ITO Nobuaki <banb@cpan.org> for his UUID::Generator::PurePerl
305 module! My work is based on his code, and without it I would've been
306 lost with all those incomprehensible RFC texts and C codes ...
307 Thanks to Jesse Vincent ("<jesse at bestpractical.com>") for his
309 feedback, tips and refactoring!
310
312 Copyright 2009, 2010, 2013 Christian Augustin, all rights reserved.
313 This program is free software; you can redistribute it and/or modify it
315 under the same terms as Perl itself.
316 ITO Nobuaki has very graciously given me permission to take over
318 copyright for the portions of code that are copied from or resemble his
319 work (see rt.cpan.org #53642
320 <https://rt.cpan.org/Public/Bug/Display.html?id=53642>).
321perl v5.38.0 2023-07-21 UUID::Tiny(3)