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,可以帮助开发者调试和跟踪特定对象,尤其是在多人游戏或复杂场景中。

发表回复

您的电子邮箱地址不会被公开。 必填项已用 * 标注