root/trunk/tango/scrapple/util/uuid/Uuid.d

/*******************************************************************************

        copyright:      Copyright (c) 2008 Max Samukha. All rights reserved

        license:        BSD style: $(LICENSE)

        authorS:        Max Samukha

        This module defines a 128-bit Universally Unique Identifier structure
        conforming to Proposed Stardard RFC-4122.

        Examples:

---------------------
Uuid uuid = "24bb3c5e-988b-4833-9d9a-77bf84b3284c";

auto uuid2 = Uuid("24bb3c5e-988b-4833-9d9a-77bf84b3284c");

char[Uuid.StringLength] buf;
uuid.toString(buf);

Stdout(uuid).newline;

// Convert to an array of bytes for sending over a network
ubyte[Uuid.StringLength] ubytes;
uuid.toOctets(ubytes);
---------------------


*******************************************************************************/
module tango.scrapple.util.uuid.Uuid;

import tango.core.Exception;

private
{
    const char[] InvalidUuidMsg = "Invalid UUID string format";
    const char[] Digits = "0123456789abcdef";
}

private bool hexToUbyte(char[] hex, out ubyte ub)
{
    if (hex.length != 2)
        return false;

    char c1 = hex[0];
    char c2 = hex[1];

    if (c1 >= 'A' && c1 <='F')
        c1 += 32;
    if (c2 >= 'A' && c2 <='F')
        c2 += 32;

    int cCount;

    foreach (i, d; Digits)
    {
        if (d == c1)
        {
            ub = ub | i << 4;
            cCount++;
        }

        if (d == c2)
        {
            ub |= i;
            cCount++;
        }

        if (cCount == 2)
            break;
    }

    return cCount == 2;
}

private void ubyteToHex(ubyte ub, char[] hex)
{
    assert (hex.length == 2);

    hex[0] = Digits[ub >> 4];
    hex[1] = Digits[ub & 0x0F];
}

/*****************************************************************************************
   The UUID variants. The UUID variant determines the layout of the UUID.
*****************************************************************************************/
enum UuidVariant : ubyte
{
    /// Reserved, NCS backward compatibility.
    Ncs,
    /// The UUID is compatible with RFC-4122.
    Standard,
    /// Reserved, _Microsoft backward compatibility.
    Microsoft,
    /// Reserved for future definition.
    Future
}

/*****************************************************************************************
    Versions of a standard UUID.
*****************************************************************************************/
enum UuidVersion : ubyte
{
    /// The time-based version.
    TimeBased = 1,
    /// The DCE security version, with embedded POSIX UIDs.
    Dce = 2,
    /// The name-based version that uses MD5 hashing.
    NameBasedMd5 = 3,
    /// The randomly or pseudo-randomly generated version.
    Random = 4,
    /// The name-based version specified that uses SHA1 hashing.
    NameBasedSha1 = 5
}

/*****************************************************************************************
    The UUID structure.
*****************************************************************************************/
struct Uuid
{
    align(1):

    /// The low field of the timestamp.
    uint timeLow;
    /// The middle field of the timestamp.
    ushort timeMid;
    /// The high field of the timestamp multiplexed with the version number.
    ushort versionTimeHigh;
    /// The high field of the clock sequence multiplexed with the variant.
    ubyte variantClockSeqHigh;
    /// The low field of the clock sequence.
    ubyte clockSeqLow;
    /// The spatially unique node identifier.
    ubyte[6] node;

    enum : size_t
    {
        /*****************************************************************************************
            The length of the string representation of a UUID (36 characters).
        *****************************************************************************************/
        StringLength = 36
    }

    /*****************************************************************************************
        Changes the byte order of the UUID fields.
    *****************************************************************************************/
    void swap()
    {
        ubyte octet;
        ubyte* octets = cast(ubyte*)this;

        //timeLow
        octet = octets[3];
        octets[3] = octets[0];
        octets[0] = octet;
        octet = octets[2];
        octets[2] = octets[1];
        octets[1] = octet;

        //timeMid
        octet = octets[5];
        octets[5] = octets[4];
        octets[4] = octet;

        //verAndTimeHi
        octet = octets[7];
        octets[7] = octets[6];
        octets[6] = octet;
    }

    /*****************************************************************************************
        Gets the UUID _variant.
    *****************************************************************************************/
    UuidVariant variant()
    {
        if ((variantClockSeqHigh & 0b1000_0000) == 0)
            return UuidVariant.Ncs;
        if ((variantClockSeqHigh & 0b1100_0000) == 0b1000_0000)
            return UuidVariant.Standard;
        if ((variantClockSeqHigh & 0b1110_0000) == 0b1100_0000)
            return UuidVariant.Microsoft;

        return UuidVariant.Future;
    }

    /*****************************************************************************************
        Sets the UUID _variant.

        Params:
            v  = UUID _variant.
    *****************************************************************************************/
    UuidVariant variant(UuidVariant v)
    {
        if (v == UuidVariant.Ncs)
            variantClockSeqHigh &= 0b0111_1111;
        else if (v == UuidVariant.Standard)
            variantClockSeqHigh = (variantClockSeqHigh | 0b1100_0000) & 0b1011_1111;
        else if (v == UuidVariant.Microsoft)
            variantClockSeqHigh = (variantClockSeqHigh | 0b1110_0000) & 0b1101_1111;
        else if (v == UuidVariant.Future)
            variantClockSeqHigh = (variantClockSeqHigh | 0b1110_0000) & 0b1111_1111;
        else
            assert(false, "Unknown UUID variant.");

        return v;
    }

    /*****************************************************************************************
        Gets the UUID version.
    *****************************************************************************************/
    UuidVersion ver()
    {
        return cast(UuidVersion)(versionTimeHigh >> 12);
    }

    /*****************************************************************************************
        Sets the UUID version.

        Params:
            v  = UUID version.
    *****************************************************************************************/
    UuidVersion ver(UuidVersion v)
    {
        versionTimeHigh = (versionTimeHigh & 0x0FFF) | (v << 12);
        return v;
    }

    /*****************************************************************************************
        Gets the string representation of this UUID.
    *****************************************************************************************/
    char[] toString()
    {
        return toString(null);
    }

    /*****************************************************************************************
        Fills buf with the string representation of this UUID. If the length of buf is zero,
        allocates a new buffer.

        Returns:
            The UUID string.

        Params:
            buf     = Buffer to recieve the UUID string.

        Throws: IllegalArgumentException if the length of the buffer is not zero and
            is less than 36 characters.
    *****************************************************************************************/
    char[] toString(char[] buf)
    {
        if (!buf.length)
            buf = new char[36];
        else if (buf.length < 36)
            throw new IllegalArgumentException("Supplied buffer is too small.");

        version (LittleEndian)
        {
            Uuid temp = *this;
            temp.swap();
            ubyte* octets = cast(ubyte*)&temp;
        }
        else
            ubyte* octets = cast(ubyte*)this;

        size_t cIdx, octIdx;
        while (cIdx < 36)
        {
            if (cIdx == 8 || cIdx == 13 || cIdx == 18 || cIdx == 23)
            {
                buf[cIdx] = '-';
                cIdx++;
                continue;
            }

            ubyteToHex(octets[octIdx], buf[cIdx..cIdx + 2]);
            cIdx += 2;
            octIdx++;
        }

        return buf;
    }

    /*****************************************************************************************
        Gets the URN representation of this UUID.

        Params:
            buf         = Buffer to receive the result. If the length of buf is zero,
                          a new buffer is dynamically allocated.
        Returns:
            Reference to the buffer.

        Throws: IllegalArgumentException if the length of the supplied buffer is not zero and
            not big enough for the URN (45 chars).
    *****************************************************************************************/
    char[] toUrn(char[] buf = null)
    {
        char[] urn;

        if (!buf.length)
            buf = new char[45];
        else if (buf.length < 45)
            throw new IllegalArgumentException("Supplied buffer is too small.");

        buf[0..9] = "urn:uuid:";
        toString(urn[9..$]);
    }

    /*****************************************************************************************
      Fills the supplied buffer with the UUID _octets arranged in network order. A new array is
      created if the length of the buffer is zero.

      Params:
            octets           = Buffer to recieve the result,

      Returns: Reference to the array.

      Throws: IllegalArgumentException if the length of the supplied array is not zero and not big enough
              for the UUID _octets (16 bytes).
    *****************************************************************************************/
    ubyte[] toOctets(ubyte[] octets = null)
    {
        Uuid* pUuid;

        if (!octets.length)
            pUuid = new Uuid;
        else if (octets.length >= 16)
            pUuid = cast(Uuid*)octets.ptr;
        else
            throw new IllegalArgumentException("Supplied array is too small");

        *pUuid = *this;

        version (LittleEndian)
            pUuid.swap();

        return (cast(ubyte*)pUuid)[0..16];
    }

    /*****************************************************************************************
        Parses the UUID string and assigns the result to this UUID.
        Params:
            str         = UUID string.

Examples:
---------
Uuid uuid;
uuid = "24bb3c5e-988b-4833-9d9a-77bf84b3284c";
---------
    *****************************************************************************************/
    Uuid opAssign(char[] str)
    {
        *this = opCall(str);
        return *this;
    }

    /*****************************************************************************************
        Assigns the UUID _octets arranged in network byte order to this UUID .
        Params:
            octets = UUID _octets in network byte order.
    *****************************************************************************************/
    Uuid opAssign(ubyte[] octets)
    {
        *this = opCall(octets);
        return *this;
    }


    /*****************************************************************************************
        Creates a UUID from UUID field values.
    *****************************************************************************************/
    static Uuid opCall(uint timeLow, ushort timeMid, ushort versionTimeHigh,
        ubyte variantClockSeqHigh, ubyte clockSeqLow, ubyte[6] node)
    {
        Uuid uuid;

        uuid.timeLow = timeLow;
        uuid.timeMid = timeMid;
        uuid.versionTimeHigh = versionTimeHigh;
        uuid.variantClockSeqHigh = variantClockSeqHigh;
        uuid.clockSeqLow = clockSeqLow;
        uuid.node[] = node;

        return uuid;
    }

    /*****************************************************************************************
        Creates a new UUID from the supplied string.

        Throws: IllegalArgumentException if the input string is not a valid
            UUID string.
    *****************************************************************************************/
    static Uuid opCall(char[] str)
    {
        Uuid result;

        if (str.length != 36 || str[8] != '-' || str[13] != '-' ||
                str[18] != '-' || str[23] != '-')
        {
            throw new IllegalArgumentException(InvalidUuidMsg);
        }

        ubyte* octets = cast(ubyte*)&result;

        uint cIdx, octIdx;
        ubyte ub;
        while (octIdx < 16)
        {
            if (cIdx == 8 || cIdx == 13 || cIdx == 18 || cIdx == 23)
            {
                cIdx++;
                continue;
            }

            if (!hexToUbyte(str[cIdx..cIdx + 2], ub))
                throw new IllegalArgumentException(InvalidUuidMsg);

            octets[octIdx] = ub;

            cIdx += 2;
            octIdx++;
        }

        version (LittleEndian)
            result.swap();

        return result;
    }

    /*****************************************************************************************
        Creates a UUID from _octets arranged in network byte order.
        This is the reverse of toOctets().

        Params:
            octets      = UUID _octets in network byte order.

        Throws:
            IllegalArgumentException if the length of octets is less than 16 bytes.
    *****************************************************************************************/
    static Uuid opCall(ubyte[] octets)
    {
        if (octets.length < 16)
            throw new IllegalArgumentException("Number of supplied octets is less than 16.");

        version (LittleEndian)
        {
            Uuid result = *(cast(Uuid*)octets.ptr);
            result.swap();
            return result;
        }
        else
            return *(cast(Uuid*)octets.ptr);
    }

    /*****************************************************************************************
        Returns the hash code of this UUID.
    *****************************************************************************************/
    int toHash()
    {
        return timeLow; // provides a decent distribution
    }

    /*****************************************************************************************
        Compares this UUID with uuid.
    *****************************************************************************************/
    int opCmp(Uuid uuid)
    {
        if (timeLow < uuid.timeLow)
            return -1;
        else if (timeLow > uuid.timeLow)
            return 1;

        if (timeMid < uuid.timeMid)
            return -1;
        else if (timeMid > uuid.timeMid)
            return 1;

        if (timeMid < uuid.timeMid)
            return -1;
        else if (timeMid > uuid.timeMid)
            return 1;

        if (versionTimeHigh < uuid.versionTimeHigh)
            return -1;
        else if (versionTimeHigh > uuid.versionTimeHigh)
            return 1;

        ubyte* p = cast(ubyte*)this;
        ubyte* pUuid = cast(ubyte*)&uuid;

        for (uint i = 8; i < 16; i++)
        {
            if (p[i] < pUuid[i])
                return -1;
            else if (p[i] > pUuid[i])
                return 1;
        }

        return 0;
    }

    /*****************************************************************************************
        Returns true if all UUID fields are equal to zero.
    *****************************************************************************************/
    bool isNil()
    {
        ulong* ulongs = cast(ulong*)this;
        return !(ulongs[0] || ulongs[1]);
    }
}

debug (UuidUnitTest)
{
    unittest
    {
        static assert(Uuid.sizeof == 16);
        ubyte ub;

        hexToUbyte("AF", ub);
        assert(ub == 0xAF);

        char[] hex = new char[2];
        ubyteToHex(ub, hex);
        assert(hex == "af");

        const char[] testUuidStr = "24bb3c5e-988b-4833-9d9a-77bf84b3284c";
        const char[] testUuidStr2 = "24bb3c5e-988b-4833-9d9a-80bf84b3284c";

        Uuid uuid;
        assert(uuid.isNil);

        uuid = testUuidStr;
        assert(!uuid.isNil);

        char[36] buffer;
        uuid.toString(buffer);
        assert(buffer == testUuidStr);

        uuid.ver = UuidVersion.TimeBased;
        assert(uuid.ver == UuidVersion.TimeBased);

        auto uuid2 = Uuid(uuid.toString);
        assert(uuid == uuid2);

        uuid = testUuidStr;
        assert(uuid.toString == testUuidStr);

        ubyte[] octets = uuid.toOctets;

        assert(octets[0] == 0x24);
        assert(octets[1] == 0xbb);
        assert(octets[2] == 0x3c);
        assert(octets[3] == 0x5e);
        assert(octets[4] == 0x98);
        assert(octets[5] == 0x8b);
        assert(octets[6] == 0x48);
        assert(octets[7] == 0x33);
        assert(octets[8] == 0x9d);
        assert(octets[9] == 0x9a);
        assert(octets[10] == 0x77);
        assert(octets[11] == 0xbf);
        assert(octets[12] == 0x84);
        assert(octets[13] == 0xb3);
        assert(octets[14] == 0x28);
        assert(octets[15] == 0x4c);

        uuid2 = cast(Uuid)octets;
        assert(uuid == uuid2);

        uuid2 = testUuidStr2;
        assert(uuid2 > uuid && uuid < uuid2);

        uuid = uuid2;
        auto v = uuid.variant;

        uuid.variant = UuidVariant.Future;
        assert(uuid.variant == UuidVariant.Future);

        uuid.variant = UuidVariant.Microsoft;
        assert(uuid.variant == UuidVariant.Microsoft);

        uuid.variant = UuidVariant.Standard;
        assert(uuid.variant == UuidVariant.Standard);

        uuid.variant = UuidVariant.Ncs;
        assert(uuid.variant == UuidVariant.Ncs);

        uuid.variant = v;
        assert (uuid == uuid2);
    }
}

debug (UuidStandalone)
{
    import
        tango.scrapple.util.uuid.NativeUuidGen,
        tango.scrapple.util.uuid.RandomUuidGen,
        tango.scrapple.util.uuid.NameUuidGen;

    void main()
    {
    }
}