deargui-vpl/examples/blueprints-example/utilities/STANDARD_UUID_CONVERSION.md

Standard UUID Format Conversion (RFC4122)

Convert between standard UUID format (with dashes) and Uuid64 structure.

Overview

Standard UUIDs are 128-bit (e.g., 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d)
Our Uuid64 uses 64-bit (two 32-bit words)

Conversion strategy: Extract 64 bits from the 128-bit UUID

Quick Start

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

// Convert back to standard format (zero-padded)
std::string standardStr = app->UuidToStandardString(uuid);
// Output: "00000000-0000-0000-9bdd2b0d-7b3dcb6d"

Parsing Standard UUIDs

Example 1: Parse Full Standard UUID (Take Last 64 Bits)

// Standard UUID: "9b1deb4d-3b7d-4bad-9bdd-2b0d-7b3dcb6d"
//                 [--- 64 bits ---][--- 64 bits ---]
//                                   ^^^^^^^^^^^^^^^^
//                                   We take these!

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

printf("High: 0x%08x, Low: 0x%08x\n", uuid.high, uuid.low);
// Output: High: 0x9bdd2b0d, Low: 0x7b3dcb6d

Example 2: Parse Full Standard UUID (Take First 64 Bits)

// Standard UUID: "9b1deb4d-3b7d-4bad-9bdd-2b0d-7b3dcb6d"
//                 [--- 64 bits ---][--- 64 bits ---]
//                 ^^^^^^^^^^^^^^^^
//                 We take these!

ed::Uuid64 uuid = app->StandardStringToUuid("9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", false);
//                                                                                   ^^^^^
//                                                                           takeLast64=false

printf("High: 0x%08x, Low: 0x%08x\n", uuid.high, uuid.low);
// Output: High: 0x9b1deb4d, Low: 0x3b7d4bad

Example 3: Direct Method Call

// Using Uuid64 static method directly
ed::Uuid64 uuid = ed::Uuid64::FromStandardUuidString("9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d");

// Or via app
ed::Uuid64 uuid2 = app->StandardStringToUuid("9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d");

Converting to Standard UUID Format

Example 1: Convert Uuid64 to Standard Format

ed::Uuid64 uuid(0x9bdd2b0d, 0x7b3dcb6d);

std::string standardStr = app->UuidToStandardString(uuid);
printf("UUID: %s\n", standardStr.c_str());
// Output: "00000000-0000-0000-9bdd2b0d-7b3dcb6d"

// Or direct call
std::string standardStr2 = uuid.ToStandardUuidString();

Example 2: Zero-Padding Behavior

// Our 64-bit UUIDs are zero-padded in the upper 64 bits
ed::Uuid64 uuid(0x12345678, 0xabcdef90);

std::string standardStr = uuid.ToStandardUuidString();
printf("%s\n", standardStr.c_str());
// Output: "00000000-0000-0000-12345678-abcdef90"
//          ^^^^^^^^^^^^^^^^^^^^^^^
//          Always zero-padded

Flexible Format Support

The parser handles various formats:

// All of these work:
ed::Uuid64 uuid1 = app->StandardStringToUuid("9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d");  // Standard
ed::Uuid64 uuid2 = app->StandardStringToUuid("9b1deb4d3b7d4bad9bdd2b0d7b3dcb6d");      // No dashes
ed::Uuid64 uuid3 = app->StandardStringToUuid("9BDD2B0D7B3DCB6D");                      // Uppercase, short
ed::Uuid64 uuid4 = app->StandardStringToUuid("9bdd2b0d-7b3dcb6d");                     // Partial with dashes

Real-World Use Cases

Use Case 1: Import from External System

// External system provides standard UUIDs
std::string externalUuid = "550e8400-e29b-41d4-a716-446655440000";

// Convert to our format
ed::Uuid64 internalId = app->StandardStringToUuid(externalUuid);

// Use in our system
Node* node = new Node();
node->SetId(internalId);

printf("Imported node with ID: 0x%08x%08x\n", internalId.high, internalId.low);

Use Case 2: Export for External Systems

// Our internal ID
ed::Uuid64 nodeId = app->GenerateRandomUuid64();

// Export as standard UUID for external API
std::string exportedUuid = app->UuidToStandardString(nodeId);

// Send to external system
ExternalAPI::CreateResource(exportedUuid);
// They receive: "00000000-0000-0000-12345678-abcdef90"

Use Case 3: Database Storage

// Store in database as standard UUID string
void SaveNode(Node* node)
{
    std::string uuidStr = app->UuidToStandardString(node->GetUuid64());
    
    Database::Execute(
        "INSERT INTO nodes (id, name) VALUES (?, ?)",
        uuidStr,
        node->GetName()
    );
}

// Load from database
Node* LoadNode(const std::string& dbUuidStr)
{
    ed::Uuid64 uuid = app->StandardStringToUuid(dbUuidStr);
    return FindNodeByUuid(uuid);
}

Use Case 4: JSON Import/Export

// Export to JSON
json nodeData;
ed::Uuid64 id = node->GetUuid64();
nodeData["id"] = app->UuidToStandardString(id);
// JSON: { "id": "00000000-0000-0000-12345678-abcdef90" }

// Import from JSON
std::string uuidStr = nodeData["id"].get<std::string>();
ed::Uuid64 loadedId = app->StandardStringToUuid(uuidStr);

Use Case 5: URL Parameters

// Generate shareable link with standard UUID
ed::Uuid64 sessionId = app->GenerateRandomUuid64();
std::string shareUrl = "https://example.com/session/" + 
                       app->UuidToStandardString(sessionId);
// URL: https://example.com/session/00000000-0000-0000-12345678-abcdef90

// Parse from URL
std::string uuidFromUrl = ExtractUuidFromUrl(url);
ed::Uuid64 session = app->StandardStringToUuid(uuidFromUrl);

Format Details

Standard UUID Format (RFC4122)

9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
├─────┤ ├──┤ ├──┤ ├──┤ ├──────────┤
8 hex   4    4    4    12 hex chars
chars   hex  hex  hex
        
Total: 36 characters (32 hex + 4 dashes)
Represents: 128 bits (16 bytes)

Our Uuid64 Format

Uuid64 { high: 0x9bdd2b0d, low: 0x7b3dcb6d }
         ├──────────┤       ├──────────┤
         32 bits             32 bits

Total: 64 bits (8 bytes)

Conversion Mapping

Standard UUID (128-bit):
9b1deb4d-3b7d-4bad-9bdd-2b0d-7b3dcb6d
└─────────────────┘└─────────────────┘
   First 64 bits       Last 64 bits
   (takeLast64=false)  (takeLast64=true, default)

takeLast64=true (default):
  Input:  "9b1deb4d-3b7d-4bad-9bdd-2b0d-7b3dcb6d"
  Output: Uuid64(0x9bdd2b0d, 0x7b3dcb6d)

takeLast64=false:
  Input:  "9b1deb4d-3b7d-4bad-9bdd-2b0d-7b3dcb6d"
  Output: Uuid64(0x9b1deb4d, 0x3b7d4bad)

Error Handling

// Invalid formats return zero UUID
ed::Uuid64 invalid1 = app->StandardStringToUuid("");                    // Empty
ed::Uuid64 invalid2 = app->StandardStringToUuid("not-a-uuid");         // Invalid chars
ed::Uuid64 invalid3 = app->StandardStringToUuid("12345");              // Too short

// Check if parsing succeeded
ed::Uuid64 uuid = app->StandardStringToUuid(someString);
if (!uuid.IsValid())
{
    printf("Failed to parse UUID\n");
}

API Reference

App Class Methods

// Convert to standard UUID string (with dashes)
std::string UuidToStandardString(const ed::Uuid64& uuid);

// Parse standard UUID string (with or without dashes)
// takeLast64: true = use last 64 bits, false = use first 64 bits
ed::Uuid64 StandardStringToUuid(const std::string& uuidStr, bool takeLast64 = true);

Uuid64 Structure Methods

// Convert to standard UUID format
std::string ToStandardUuidString() const;

// Parse from standard UUID format
static Uuid64 FromStandardUuidString(const std::string& uuidStr, bool takeLast64 = true);

Best Practices

✅ DO:

• Use takeLast64=true (default) for consistency
• Validate parsed UUIDs with IsValid()
• Document which 64 bits you're using in your API
• Store original 128-bit UUID if you need to preserve it

❌ DON'T:

• Assume round-trip conversion preserves the original 128-bit UUID
• Mix takeLast64=true and takeLast64=false without documentation
• Use standard format for internal IDs (use hex format for efficiency)

Interoperability Matrix

External System	Provides	We Extract	Round-Trip?
UUIDv4 APIs	128-bit	Last 64 bits	❌ Lost upper 64 bits
PostgreSQL UUID	128-bit	Last 64 bits	❌ Lost upper 64 bits
MongoDB ObjectId	96-bit	Last 64 bits	❌ Lost upper 32 bits
Our System	64-bit	All	✅ Perfect

Note: Converting 128-bit UUIDs to 64-bit is lossy. The upper 64 bits are discarded.

Summary

• ✅ Parse standard UUID format: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
• ✅ Convert to standard format: "00000000-0000-0000-HHHHHHHH-LLLLLLLL"
• ✅ Flexible parsing (with/without dashes, any length)
• ✅ Choose which 64 bits to extract (takeLast64 parameter)
• ⚠️ Lossy conversion: 128-bit → 64-bit discards data
• ✅ Perfect for importing external UUIDs into your system
• ✅ Export format compatible with standard UUID parsers