UUID Manual

About

maxon::Uuid is a MAXON API 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:

// 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:

// 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:

// 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:

// 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:

// 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:

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:

// 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:

// 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
// read from file
maxon::Uuid loadedUuid;
maxon::ReadDocument(url, fileID, loadedUuid) iferr_return;
// display loaded uuid
DiagnosticOutput("Loaded Uuid: @", loadedUuid.ToString(nullptr));

Further Reading

maxon::ReadDocument
std::enable_if< GetCollectionKind< T >::value==COLLECTION_KIND::ARRAY, Result< void > >::type ReadDocument(const Url &url, const Id &id, T &object, const DataDictionary &dict=DataDictionary())
Definition: io.h:35
Int
maxon::Int Int
Definition: ge_sys_math.h:62
maxon::String
Definition: string.h:1197
maxon::Id
Definition: apibaseid.h:250
iferr_return
#define iferr_return
Definition: resultbase.h:1434
maxon::OPENSTREAMFLAGS::NONE
@ NONE
No flags set.
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
maxon::Url
Definition: url.h:819
maxon::IOFORMAT::JSON
@ JSON
maxon::Uuid
Definition: uuid.h:144
maxon::WriteDocument
Result< void > WriteDocument(const Url &url, OPENSTREAMFLAGS flags, const Id &id, const T &object, IOFORMAT format=IOFORMAT::DEFAULT, const DataDictionary &dict=DataDictionary())
Definition: io.h:67
maxon::UInt
UInt64 UInt
unsigned 32/64 bit int, size depends on the platform
Definition: apibase.h:185
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:53
maxon::COMPARERESULT
COMPARERESULT
Data type for comparison results.
Definition: compare.h:20