UEC++ API——FGuid 全局唯一标识符

FGuid 简介

FGuid 是 Unreal Engine 中用于表示全局唯一标识符 (GUID, Globally Unique Identifier) 的数据结构。GUID 通常用于唯一标识对象、文件等，在分布式系统或需要确保唯一性的场景下非常常用。

FGuid 主要属性

• GUID 的本质：由四个 32 位的无符号整数组成的 128 位数值，用于确保唯一性。
• 不可变性：生成后的 GUID 在应用的整个生命周期内通常不会改变。

1. FGuid::NewGuid()

• 功能：生成一个新的唯一的 GUID。
• 使用场景：用于创建全新的 GUID，常用于需要唯一标识对象或文件的场景。
• 示例：
  FGuid MyGuid = FGuid::NewGuid();
• 返回值：返回一个新的 FGuid 对象。

2. FGuid::IsValid()

• 功能：检查当前 GUID 是否有效。一个 GUID 是有效的，如果它不是全 0。
• 使用场景：用于判断 GUID 是否已经初始化或分配。
• 示例：
  if (MyGuid.IsValid()) { // 执行某些操作 }
• 返回值：bool，若 GUID 有效则返回 true，否则返回 false。

3. FGuid::Invalidate()

• 功能：使当前的 GUID 无效，将其设置为全 0。
• 使用场景：需要重置或清空 GUID 时使用。
• 示例：
  cpp MyGuid.Invalidate();
• 返回值：无返回值，直接将 GUID 置为无效状态。

4. FGuid::ToString(EGuidFormats Format = EGuidFormats::Digits)

• 功能：将 GUID 转换为字符串格式，支持不同的格式化方式。
• 使用场景：需要将 GUID 作为字符串保存或显示时。
• 示例：
  cpp FString GuidStr = MyGuid.ToString();
• 返回值：返回一个 FString 类型的字符串。
• 可选参数：
• EGuidFormats::Digits: 只包含数字，不带分隔符。
• EGuidFormats::DigitsWithHyphens: 数字间带有连字符。
• EGuidFormats::Braces: 用大括号包围的 GUID。
• EGuidFormats::Parentheses: 用圆括号包围的 GUID。

5. FGuid::Parse(const FString& GuidString, FGuid& OutGuid)

• 功能：从字符串解析并生成 GUID。
• 使用场景：当你从外部数据（比如文件、网络请求）中获得一个 GUID 字符串，需要将其转化为 FGuid 对象时使用。
• 示例：
  cpp FString GuidStr = TEXT("D3C1A2B4-7896-1234-5678-9ABCDEF01234"); FGuid ParsedGuid; if (FGuid::Parse(GuidStr, ParsedGuid)) { // 解析成功，ParsedGuid 现在有效 }
• 返回值：bool，成功解析则返回 true，否则返回 false。

6. FGuid::operator== 和 FGuid::operator!=

• 功能：用于比较两个 GUID 是否相同或不同。
• 使用场景：需要判断两个对象是否相同，尤其是在需要唯一性判定的场合。
• 示例：
  cpp if (Guid1 == Guid2) { // GUID 相等 }
• 返回值：bool，两个 GUID 相等则返回 true，否则返回 false。

7. FGuid::ExportTextItem

• 功能：将 GUID 导出为字符串，可用于保存到文本文件或其他序列化操作。
• 使用场景：需要将 GUID 序列化为文本格式时使用。
• 示例：
  cpp FString ExportedText; MyGuid.ExportTextItem(ExportedText, FGuid(), nullptr, 0, nullptr);
• 返回值：FString，生成的 GUID 序列化后的字符串。

8. FGuid::ImportTextItem

• 功能：从文本中导入 GUID，用于反序列化操作。
• 使用场景：从文件或外部数据中读取 GUID 并将其恢复为 FGuid 对象时使用。
• 示例：
  cpp FGuid ImportedGuid; FString Text = TEXT("{D3C1A2B4-7896-1234-5678-9ABCDEF01234}"); ImportedGuid.ImportTextItem(*Text, nullptr, 0, nullptr);
• 返回值：bool，导入成功返回 true，否则返回 false。

9. FGuid::GetComponent(int32 Index)

• 功能：获取 GUID 的指定部分 (0-3)。
• 使用场景：分解 GUID 的 128 位数据，特别是对底层数据操作或调试时。
• 返回值：uint32，指定部分的值。

uint32 Part = MyGuid.GetComponent(0); // 获取第一部分

10. FGuid::LexFromString(FGuid& OutGuid, const TCHAR* Str)

• 功能：从字符数组中解析 GUID。
• 使用场景：需要从底层字符数组中读取 GUID 时。
• 返回值：bool，解析成功返回 true。

FGuid ParsedGuid;
FGuid::LexFromString(ParsedGuid, TEXT("D3C1A2B4-7896-1234-5678-9ABCDEF01234"));

11. FGuid::operator< 和 FGuid::operator>

• 功能：比较两个 GUID 的大小。
• 使用场景：用于对 GUID 进行排序。
• 返回值：bool。

if (Guid1 < Guid2)
{
    // Guid1 小于 Guid2
}

12. FGuid::MostSignificantBits() 和 LeastSignificantBits()

• 功能：获取 GUID 的高 64 位或低 64 位。
• 使用场景：对 GUID 的前后 64 位进行操作（如哈希）。
• 返回值：uint64。

uint64 MSB = MyGuid.MostSignificantBits();
uint64 LSB = MyGuid.LeastSignificantBits();

13. FGuid::IsZero()

• 功能：检查 GUID 是否为全零。
• 使用场景：用于确认 GUID 是否完全无效。
• 返回值：bool，全零返回 true。

if (MyGuid.IsZero())
{
    // GUID 是无效的
}

实际用途：

存档系统：在需要保存游戏进度时，GUID 可以用于唯一标识存档中的每个对象，确保读取时不会出错。

唯一标识对象：GUID 可以确保每个对象在整个游戏中都是唯一的，避免在大型场景或多人游戏中发生混淆。

调试和跟踪：通过在日志中打印 GUID，可以帮助开发者调试和跟踪特定对象，尤其是在多人游戏或复杂场景中。