.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Data::GUID 3pm"
.TH Data::GUID 3pm "2017-11-04" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::GUID \- globally unique identifiers
.SH "VERSION"
.IX Header "VERSION"
version 0.049
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Data::GUID;
\&
\&  my $guid = Data::GUID\->new;
\&
\&  my $string = $guid\->as_string; # or "$guid"
\&
\&  my $other_guid = Data::GUID\->from_string($string);
\&
\&  if (($guid <=> $other_guid) == 0) {
\&    print "They\*(Aqre the same!\en";
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Data::GUID provides a simple interface for generating and using globally unique
identifiers.
.SH "GETTING A NEW GUID"
.IX Header "GETTING A NEW GUID"
.SS "new"
.IX Subsection "new"
.Vb 1
\&  my $guid = Data::GUID\->new;
.Ve
.PP
This method returns a new globally unique identifier.
.SH "GUIDS FROM EXISTING VALUES"
.IX Header "GUIDS FROM EXISTING VALUES"
These method returns a new Data::GUID object for the given \s-1GUID\s0 value.  In all
cases, these methods throw an exception if given invalid input.
.SS "from_string"
.IX Subsection "from_string"
.Vb 1
\&  my $guid = Data::GUID\->from_string("B0470602\-A64B\-11DA\-8632\-93EBF1C0E05A");
.Ve
.SS "from_hex"
.IX Subsection "from_hex"
.Vb 2
\&  # note that a hex guid is a guid string without hyphens and with a leading 0x
\&  my $guid = Data::GUID\->from_hex("0xB0470602A64B11DA863293EBF1C0E05A");
.Ve
.SS "from_base64"
.IX Subsection "from_base64"
.Vb 1
\&  my $guid = Data::GUID\->from_base64("sEcGAqZLEdqGMpPr8cDgWg==");
.Ve
.SS "from_data_uuid"
.IX Subsection "from_data_uuid"
This method returns a new Data::GUID object if given a Data::UUID value.
Because Data::UUID values are not blessed and because Data::UUID provides no
validation method, this method will only throw an exception if the given data
is of the wrong size.
.SH "IDENTIFYING GUIDS"
.IX Header "IDENTIFYING GUIDS"
.SS "string_guid_regex"
.IX Subsection "string_guid_regex"
.SS "hex_guid_regex"
.IX Subsection "hex_guid_regex"
.SS "base64_guid_regex"
.IX Subsection "base64_guid_regex"
These methods return regex objects that match regex strings of the appropriate
type.
.SS "from_any_string"
.IX Subsection "from_any_string"
.Vb 1
\&  my $string = get_string_from_ether;
\&
\&  my $guid = Data::GUID\->from_any_string($string);
.Ve
.PP
This method returns a Data::GUID object for the given string, trying all known
string interpretations.  An exception is thrown if the value is not a valid
\&\s-1GUID\s0 string.
.SS "best_guess"
.IX Subsection "best_guess"
.Vb 1
\&  my $value = get_value_from_ether;
\&
\&  my $guid = Data::GUID\->best_guess($value);
.Ve
.PP
This method returns a Data::GUID object for the given value, trying everything
it can.  It works like \f(CW"from_any_string"\fR, but will also accept Data::UUID
values.  (In effect, this means that any sixteen byte value is acceptable.)
.SH "GUIDS INTO STRINGS"
.IX Header "GUIDS INTO STRINGS"
These methods return various string representations of a \s-1GUID.\s0
.SS "as_string"
.IX Subsection "as_string"
This method returns a \*(L"traditional\*(R" \s-1GUID/UUID\s0 string representation.  This is
five hexadecimal strings, delimited by hyphens.  For example:
.PP
.Vb 1
\&  B0470602\-A64B\-11DA\-8632\-93EBF1C0E05A
.Ve
.PP
This method is also used to stringify Data::GUID objects.
.SS "as_hex"
.IX Subsection "as_hex"
This method returns a plain hexadecimal representation of the \s-1GUID,\s0 with a
leading \f(CW\*(C`0x\*(C'\fR.  For example:
.PP
.Vb 1
\&  0xB0470602A64B11DA863293EBF1C0E05A
.Ve
.SS "as_base64"
.IX Subsection "as_base64"
This method returns a base\-64 string representation of the \s-1GUID.\s0  For example:
.PP
.Vb 1
\&  sEcGAqZLEdqGMpPr8cDgWg==
.Ve
.SH "OTHER METHODS"
.IX Header "OTHER METHODS"
.SS "compare_to_guid"
.IX Subsection "compare_to_guid"
This method compares a \s-1GUID\s0 to another \s-1GUID\s0 and returns \-1, 0, or 1, as do
other comparison routines.
.SS "as_binary"
.IX Subsection "as_binary"
This method returns the packed binary representation of the \s-1GUID.\s0  At present
this method relies on Data::GUID's underlying use of Data::UUID.  It is not
guaranteed to continue to work the same way, or at all.  \fICaveat invocator\fR.
.SH "IMPORTING"
.IX Header "IMPORTING"
Data::GUID does not export any subroutines by default, but it provides a few
routines which will be imported on request.  These routines may be called as
class methods, or may be imported to be called as subroutines.  Calling them by
fully qualified name is incorrect.
.PP
.Vb 1
\&  use Data::GUID qw(guid);
\&
\&  my $guid = guid;             # OK
\&  my $guid = Data::GUID\->guid; # OK
\&  my $guid = Data::GUID::guid; # NOT OK
.Ve
.SS "guid"
.IX Subsection "guid"
This routine returns a new Data::GUID object.
.SS "guid_string"
.IX Subsection "guid_string"
This returns the string representation of a new \s-1GUID.\s0
.SS "guid_hex"
.IX Subsection "guid_hex"
This returns the hex representation of a new \s-1GUID.\s0
.SS "guid_base64"
.IX Subsection "guid_base64"
This returns the base64 representation of a new \s-1GUID.\s0
.SS "guid_from_anything"
.IX Subsection "guid_from_anything"
This returns the result of calling the \f(CW"from_any_string"\fR method.
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
add namespace support
.IP "\(bu" 4
remove dependency on wretched Data::UUID
.IP "\(bu" 4
make it work on 5.005
.SH "AUTHOR"
.IX Header "AUTHOR"
Ricardo \s-1SIGNES\s0 <rjbs@cpan.org>
.SH "CONTRIBUTOR"
.IX Header "CONTRIBUTOR"
Ricardo \s-1SIGNES\s0 <rjbs@codesimply.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2006 by Ricardo \s-1SIGNES.\s0
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.