About

maxon::Uuid is a MAXON API ALIASES class based on maxon::UuidInterface and used to create universally unique identifiers. IDs generated via maxon::Uuid are unique and persistent which makes them perfect to create Uniform Resource Names (URN)

Creation and initialization

A maxon::UUID can be created on the stack and initialized through the proper method:

maxon::Uuid::Uuid(): create a new maxon::Uuid;
maxon::Uuid::Uuid(const String& uuid): create a new maxon::Uuid object with the valid identifier;
maxon::Uuid::Uuid(const UChar* uuid, Int uuidSize): create a new maxon::Uuid given the pointer to the UUID and the size of the memory block storing the Uuid.

    // This example allocates two maxon::Uuid and initializes the latter.
 
    // just allocate an empty Uuid object
    const maxon::Uuid emptyUuid { };
 
    // allocate and init an Uuid object
    const maxon::Uuid filledUuid { "01234567-89AB-CDEF-FEDC-BA9876543210"_s };
 

A maxon::Uuid can also be initialized, after being created, using:

maxon::UuidInterface::CreateId().

    // This example initializes a maxon::Uuid object.
 
    // allocate the Uuid
    maxon::Uuid uniqueid;
    // populate the Uuid object
    uniqueid.CreateId() iferr_return;
 

Content

The content of a maxon::Uuid can be managed with these functions:

maxon::UuidInterface::IsEmpty(): returns whether the UUID is empty or not;
maxon::UuidInterface::IsPopulated(): returns whether the UUID is populated or not.

    // This example tests if a maxon::Uuid is populated.
 
    // allocate the Uuid
    maxon::Uuid uniqueid;
 
    // init the Uuid
    uniqueid.CreateId() iferr_return;
 
    const Bool uuidIsPopulated = uniqueid.IsPopulated();
 
    if (uuidIsPopulated)
    {
      // uniqueid is populated do something
    }

A maxon::Uuid object's value can be set and retrieved using:

maxon::UuidInterface::Set(const String& uuid): given a valid string sets a UUID;
maxon::UuidInterface::Set(const UChar* uuid, Int uuidSize): given an UUID pointer and the size of the memory block sets a given memory block of a UUID;
maxon::UuidInterface::Get(): given an UUID pointer and the size of the memory block gets a given memory block of a UUID.

    // This example shows how to set and retrieve the raw-values.
 
    // allocate an Uuid
    maxon::Uuid firstUuid, secondUuid;
 
    // set the value of the first UUID by using a given string
    firstUuid.Set("AABBCCDD-EEFF-0123-4567-FFEEDDCCBBAA"_s) iferr_return;
 
    // allocate a BaseArray of UChar
    const Int        size = 16;
    BaseArray<UChar> data;
 
    // resize the array accordingly to the expected size of the UUID object
    data.Resize(size) iferr_return;
 
    // retrieve the value of the first UUID and fill the data array
    firstUuid.Get(data.GetFirst(), size) iferr_return;
 
    // set the value of the second UUID using the retrieved data
    secondUuid.Set(data.GetFirst(), size) iferr_return;
 

Comparison

A given maxon::Uuid can be compared to another using:

maxon::UuidInterface::Compare(): compare the UUID against the passed UUID.

    // This example shows how to compare two Uuids.
 
    const maxon::Uuid uniqueIdZeroToFour { "00000000-1111-2222-3333-444444444444"_s };
    const maxon::Uuid uniqueIdFiveToNine { "55555555-6666-7777-8888-999999999999"_s };
 
    maxon::COMPARERESULT res = uniqueIdZeroToFour.Compare(uniqueIdFiveToNine);

Conversion

A given maxon::Uuid can be converted to a maxon::String using:

maxon::UuidInterface::ToString(): Converts the UUID into a string.

Note: The format will be "00000000-0000-0000-0000-000000000000" and the letters will be uppercase.

    // This example shows how to convert an Uuid object to a string.
 
    // allocate an Uuid object
    maxon::Uuid uniqueId;
 
    // initialize the Uuid
    uniqueId.CreateId() iferr_return;
 
    // convert the Uuid to a String
    const maxon::String uniqueIdString = uniqueId.ToString(nullptr);
 
    // display the string
    DiagnosticOutput("The uniqueIdString is @", uniqueIdString);

Utility

A given maxon::Uuid can return the hash-code of the UUID using:

maxon::UuidInterface::GetHashCode(): returns the hash-code of the UUID; if UUID is empty returns 0.

    // This example shows how to generate the hash of a Uuid object.
 
    // allocate an Uuid object
    maxon::Uuid uniqueId;
 
    // initialize the Uuid
    uniqueId.CreateId() iferr_return;
 
    // generate the hash code from the Uuid
    const maxon::UInt uuidHash = uniqueId.GetHashCode();
 
    // display the hash code
    DiagnosticOutput("The hash of uniqueId is @", uuidHash);

To generate a string containing a UUID it's available for immediate use:

maxon::UuidInterface::CreateUuidString().

    // This example shows how to immediately generate a string containing a Uuid value.
 
    // allocate directly a string containing an Uuid value
    maxon::String uuidString = maxon::Uuid::CreateUuidString() iferr_return;
 
    // display the string
    DiagnosticOutput("The string is populated with @", uuidString);

A maxon::Uuid object can be read from and written to disk by serializing the data contained using the conventional functions.

    // This example shows how to store and retrieve a Uuid from a file.
 
    const maxon::Uuid savedUuid { "AABBCCDD-EEFF-0123-4567-FFEEDDCCBBAA"_s };
 
    // file URL
    const maxon::Url url = (targetFolder + "uuid.txt"_s)iferr_return;
    const maxon::Id  fileID { "net.maxonexample.uuid" };
 
    // save to file
    maxon::WriteDocument(url, maxon::OPENSTREAMFLAGS::NONE, fileID, savedUuid, maxon::IOFORMAT::JSON) iferr_return;
 
    // read from file
    maxon::Uuid loadedUuid;
    maxon::ReadDocument(url, fileID, loadedUuid) iferr_return;
 
    // display loaded uuid
    DiagnosticOutput("Loaded Uuid: @", loadedUuid.ToString(nullptr));

Table of Contents