UUID Generator Usage

The UuidGenerator class provides methods for generating unique identifiers in hexadecimal format (e.g., 0x50626ea, 0x1b7c7646).

Features

Random UUID Generation: Generate cryptographically random 32-bit UUIDs
Sequential UUID Generation: Generate incrementing UUIDs from a seed value
Hex String Conversion: Convert between uint32_t and hex string formats
Validation: Check if a UUID is valid (non-zero)

Basic Usage

Through App Class

// Generate a random UUID
uint32_t randomId = app->GenerateRandomUuid();
// Example: 0x50626ea

// Generate a sequential UUID
uint32_t sequentialId = app->GenerateSequentialUuid();
// Example: 0x1000000, 0x1000001, 0x1000002, ...

// Convert UUID to hex string
std::string hexStr = app->UuidToHexString(randomId);
// Output: "0x50626ea"

// Parse hex string to UUID
uint32_t parsedId = app->HexStringToUuid("0x1b7c7646");
// Result: 0x1b7c7646 (84411974 in decimal)

Direct UuidGenerator Access

// Get direct access to the generator
ed::UuidGenerator& generator = app->GetUuidGenerator();

// Generate random UUID
uint32_t uuid1 = generator.GenerateRandom();

// Generate sequential UUID
uint32_t uuid2 = generator.GenerateSequential();

// Convert to hex string
std::string hexString = ed::UuidGenerator::ToHexString(uuid1);

// Parse from hex string (supports both "0x50626ea" and "50626ea")
uint32_t parsed1 = ed::UuidGenerator::FromHexString("0x50626ea");
uint32_t parsed2 = ed::UuidGenerator::FromHexString("50626ea");  // Same result

// Validate UUID
bool isValid = ed::UuidGenerator::IsValid(uuid1);  // true if non-zero

// Reset sequential counter
generator.ResetSequential(0x2000000);  // Start from custom seed

// Set random seed for deterministic generation (useful for testing)
generator.SetRandomSeed(12345);

Examples

Example 1: Generate Node IDs

// Generate unique node IDs
uint32_t nodeId1 = app->GenerateRandomUuid();
uint32_t nodeId2 = app->GenerateRandomUuid();
uint32_t nodeId3 = app->GenerateRandomUuid();

printf("Node IDs: %s, %s, %s\n",
    app->UuidToHexString(nodeId1).c_str(),
    app->UuidToHexString(nodeId2).c_str(),
    app->UuidToHexString(nodeId3).c_str());
// Output: Node IDs: 0x50626ea, 0x1b7c7646, 0xa3f2b891

Example 2: Sequential IDs for Ordered Items

// Generate sequential IDs for a list of items
std::vector<uint32_t> itemIds;
for (int i = 0; i < 5; i++)
{
    itemIds.push_back(app->GenerateSequentialUuid());
}

// Output: 0x1000000, 0x1000001, 0x1000002, 0x1000003, 0x1000004

Example 3: Save/Load UUIDs from JSON

// Saving to JSON
json nodeData;
nodeData["id"] = app->UuidToHexString(nodeId);

// Loading from JSON
std::string hexId = nodeData["id"].get<std::string>();
uint32_t loadedId = app->HexStringToUuid(hexId);

Example 4: Using as NodeEditor IDs

// Generate UUID for node editor
uint32_t uuid = app->GenerateRandomUuid();
ed::NodeId nodeId(uuid);

// Or for links
uint32_t linkUuid = app->GenerateRandomUuid();
ed::LinkId linkId(linkUuid);

Technical Details

Range: UUIDs are generated in the range 0x1000000 to 0xFFFFFFFF
Format: 32-bit unsigned integers (4 bytes)
Hex String Format: Always prefixed with "0x" (e.g., "0x50626ea")
Random Generation: Uses Mersenne Twister (mt19937) for high-quality randomness
Sequential Generation: Increments from seed value (default: 0x1000000)

When to Use

Random UUIDs: Use when you need globally unique identifiers with no ordering requirement
Sequential UUIDs: Use when you need unique IDs with predictable ordering (useful for testing or debugging)

Standard UUID Format Support

Convert between standard UUID format (RFC4122 with dashes) and our format:

// Parse standard UUID: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
ed::Uuid64 uuid = app->StandardStringToUuid("9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d");

// Convert to standard format: "00000000-0000-0000-HHHHHHHH-LLLLLLLL"
std::string standardStr = app->UuidToStandardString(uuid);

See STANDARD_UUID_CONVERSION.md for detailed examples.

Notes

UUIDs are stored as uint32_t (32-bit integers)
Format differs from standard RFC4122 UUIDs (those are 128-bit)
Collision probability for random generation is very low (1 in 4 billion)
Sequential UUIDs are guaranteed to be unique within the same generator instance
Standard UUID conversion available for 64-bit UUIDs (128-bit → 64-bit is lossy)

4.6 KiB Raw Blame History