view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Data::UUID::MT - Fast random UUID generator using the Mersenne Twister
    algorithm

VERSION
    version 1.001

SYNOPSIS
      use Data::UUID::MT;
      my $ug1 = Data::UUID::MT->new( version => 4 ); # "1", "4" or "4s"
      my $ug2 = Data::UUID::MT->new();               # default is "4"

      # method interface
      my $uuid1 = $ug->create();        # 16 byte binary string
      my $uuid2 = $ug->create_hex();
      my $uuid3 = $ug->create_string();

      # iterator -- avoids some method call overhead
      my $next = $ug->iterator;
      my $uuid4 = $next->();

DESCRIPTION
    This UUID generator uses the excellent Math::Random::MT::Auto module as
    a source of fast, high-quality (pseudo) random numbers.

    Three different types of UUIDs are supported. Two are consistent with
    RFC 4122 and one is a custom variant that provides a 'sequential UUID'
    that can be advantageous when used as a primary database key.

    Note: The Mersenne Twister pseudo-random number generator has excellent
    statistical properties, but it is not considered cryptographically
    secure. Pseudo-random UUIDs are not recommended for use as security
    authentication tokens in cookies or other user-visible session
    identifiers.

  Version 1 UUIDs
    The UUID generally follows the "version 1" spec from the RFC, however
    the clock sequence and MAC address are randomly generated each time.
    (This is permissible within the spec of the RFC.) The generated MAC
    address has the the multicast bit set as mandated by the RFC to ensure
    it does not conflict with real MAC addresses. This UUID has 60 bits of
    timestamp data, 61 bits of pseudo-random data and 7 mandated bits
    (multicast bit, "variant" field and "version" field).

  Version 4 UUIDs
    The UUID follows the "version 4" spec, with 122 pseudo-random bits and 6
    mandated bits ("variant" field and "version" field).

  Version 4s UUIDs
    This is a custom UUID form that resembles "version 4" form, but that
    overlays the first 60 bits with a timestamp akin to "version 1", Unlike
    "version 1", this custom version preserves the ordering of bits from
    high to low, whereas "version 1" puts the low 32 bits of the timestamp
    first, then the middle 16 bits, then multiplexes the high bits with
    version field. This "4s" variant provides a "sequential UUID" with the
    timestamp providing order and the remaining random bits making collision
    with other UUIDs created at the exact same microsecond highly unlikely.
    This UUID has 60 timestamp bits, 62 pseudo-random bits and 6 mandated
    bits ("variant" field and "version" field).

  Unsupported: Versions 2, 3 and 5
    This module focuses on generation of UUIDs with random elements and does
    not support UUID versions 2, 3 and 5.

METHODS
  new
      my $ug = Data::UUID::MT->new( version => 4 );

    Creates a UUID generator object. The only allowed versions are "1", "4"
    and "4s". If no version is specified, it defaults to "4".

  create
      my $uuid = $ug->create;

    Returns a UUID packed into a 16 byte string.

  create_hex
      my $uuid = $ug->create_hex();

    Returns a UUID as a lowercase hex string, prefixed with "0x", e.g.
    0xb0470602a64b11da863293ebf1c0e05a

  create_string
      my $uuid = $ug->create_string(); #

    Returns UUID as a lowercase string in "standard" format, e.g.
    "b0470602-a64b-11da-8632-93ebf1c0e05a"

  iterator
      my $next = $ug->iterator;
      my $uuid = $next->();

    Returns a reference to the internal UUID generator function. Because
    this avoids method call overhead, it is slightly faster than calling
    "create".

  reseed
      $ug->reseed;

    Reseeds the internal pseudo-random number generator. This happens
    automatically after a fork or thread creation (assuming
    Scalar::Util::weaken), but may be called manually if desired for some
    reason.

    Any arguments provided are passed to Math::Random::MT::Auto::srand() for
    custom seeding.

      $ug->reseed('hotbits' => 250, '/dev/random');

UUID STRING REPRESENTATIONS
    A UUID contains 16 bytes. A hex string representation looks like