FUtf8String

FUtf8String

FUtf8String 是 Unreal Engine 的 UTF-8 编码字符串类型，针对 UTF-8 字符数据进行了优化。

继承关系

LocalObject

相关类型

方法

ToString()

  • 返回类型： string
  • 返回值： UTF-8 编码的 Lua 字符串。

Empty()

  • 移除所有字符以清空字符串。

Clear()

  • 移除所有字符以清空字符串（与 Empty 相同）。

Len()

  • 返回类型： integer
  • 返回值： UTF-8 码元（字节）数，而非 Unicode 码点数。例如，"Hello 你好" 返回 14（字节），而不是 8（字符）。

IsEmpty()

  • 返回类型： boolean
  • 返回值： 字符串为空时为 true，否则为 false。

Append(string)

  • 参数： string - 要追加的 Lua 字符串或另一个 FUtf8String
  • 将给定字符串追加到当前字符串末尾。

Find(search)

  • 参数： search - 要搜索的 Lua 字符串
  • 返回类型： integer 或 nil
  • 返回值： 搜索字符串首次出现位置的 1 起始索引；未找到时为 nil。

StartsWith(prefix)

  • 参数： prefix - 要检查的 Lua 字符串
  • 返回类型： boolean
  • 返回值： 字符串以给定前缀开头时为 true，否则为 false。

EndsWith(suffix)

  • 参数： suffix - 要检查的 Lua 字符串
  • 返回类型： boolean
  • 返回值： 字符串以给定后缀结尾时为 true，否则为 false。

ToUpper()

  • 返回类型： FUtf8String
  • 返回值： 将 ASCII 字符（a-z）转换为大写后的新 FUtf8String。
  • ⚠️ 注意： 与 Unreal Engine 的行为一致，此操作只转换 ASCII 字符。多字节 UTF-8 字符（带重音字符、西里尔字符、中文等）保持不变。例如，"café" 会变成 "cafÉ"，而不是 "CAFÉ"。

ToLower()

  • 返回类型： FUtf8String
  • 返回值： 将 ASCII 字符（A-Z）转换为小写后的新 FUtf8String。
  • ⚠️ 注意： 与 Unreal Engine 的行为一致，此操作只转换 ASCII 字符。多字节 UTF-8 字符（带重音字符、西里尔字符、中文等）保持不变。例如，"CAFÉ" 会变成 "cafÉ"，而不是 "café"。

使用示例

-- FUtf8String works seamlessly with UTF-8 data
local utf8String = FUtf8String("Hello UTF-8! 你好")
print(utf8String:ToString()) -- Output: "Hello UTF-8! 你好"

utf8String:Append(" 世界")
print(utf8String:ToString()) -- Output: "Hello UTF-8! 你好 世界"

if utf8String:StartsWith("Hello") then
    print("String starts with Hello!")
end

local upperString = utf8String:ToUpper()
print(upperString:ToString())

local index = utf8String:Find("UTF-8")
if index then
    print("Found at index: " .. index)
end

注意事项

  • FUtf8String 尤其适用于处理国际文本或需要确保 UTF-8 编码的场景。
  • Len() 返回的是字节长度而非字符数，因为 UTF-8 使用可变长度编码（每个字符占 1-4 字节）。
  • Find()、StartsWith() 和 EndsWith() 均可正确处理多字节 UTF-8 字符。
  • 与 Unreal Engine 文档所述行为一致，ToUpper() 和 ToLower() 只转换 ASCII 字符（a-z、A-Z）。这是一项性能优化，也符合 Epic Games 对所有字符串类型的实现方式。

完整 UTF-8 大小写转换的替代方案

如需转换非 ASCII 字符的大小写，可以考虑以下替代方法：

-- Option 1: Use Lua's string library (if available and UTF-8 aware)
local text = "Café"
local upper = text:upper()  -- May work depending on Lua locale settings

-- Option 2: Convert through FString (Windows TCHAR has better Unicode support)
local utf8str = FUtf8String("Café")
local fstr = FString(utf8str:ToString())
local upper = fstr:ToUpper()  -- Works for most common accented characters
local result = FUtf8String(upper:ToString())

-- Option 3: Implement custom case conversion in Lua
-- Use UTF-8 aware libraries or Unicode case mapping tables

原文：docs/lua-api/classes/futf8string.md · 固定提交 560411f18512 · 来源与 MIT 许可