Tools - UTF-8 编码工具类

cToolsUtf8 - UTF-8 编解码

概述

提供 Unicode 字符串与 UTF-8 字节数组之间的转换功能。

---

基础编解码

Encode

将 Unicode 字符串编码为 UTF-8 字节数组。

Public Function Encode(ByVal UCS As String) As Byte()

参数：

参数名	类型	说明
UCS	String	Unicode 字符串

返回值：

UTF-8 编码的字节数组。

示例：

Dim Utf8Bytes() As Byte
Utf8Bytes = VBMAN.ToolsUtf8.Encode("你好世界")

' 查看字节内容
Dim i As Long
For i = LBound(Utf8Bytes) To UBound(Utf8Bytes)
    Debug.Print Hex(Utf8Bytes(i));
Next i
' 输出: E4 BD A0 E5 A5 BD E4 B8 96 E7 95 8C

Decode

将 UTF-8 字节数组解码为 Unicode 字符串。

Public Function Decode(ByRef Utf() As Byte) As String

参数：

参数名	类型	说明
Utf	Byte()	UTF-8 字节数组

返回值：

解码后的 Unicode 字符串。

示例：

Dim Utf8Bytes() As Byte
Utf8Bytes = VBMAN.ToolsUtf8.Encode("你好世界")

Dim Text As String
Text = VBMAN.ToolsUtf8.Decode(Utf8Bytes)
Debug.Print Text  ' 输出: 你好世界

DecodeToByteArray

将 UTF-8 字节数组解码为 Unicode 字节数组（WideChar）。

Public Function DecodeToByteArray(ByRef Utf() As Byte) As Byte()

说明：

• 将 UTF-8 字节转换为 Unicode（UTF-16LE）字节数组
• 每个字符占2字节

示例：

Dim Utf8Bytes() As Byte
Dim UnicodeBytes() As Byte

Utf8Bytes = VBMAN.ToolsUtf8.Encode("Hello")
UnicodeBytes = VBMAN.ToolsUtf8.DecodeToByteArray(Utf8Bytes)

' UnicodeBytes 现在包含 UTF-16LE 编码的字节
' "H" = 0x48 0x00, "e" = 0x65 0x00, ...

---

带 BOM 的编解码

EncodeWithBom

将字符串编码为带 BOM 的 UTF-8 字节数组。

Public Function EncodeWithBom(strIn As String) As Byte()

说明：

• BOM（Byte Order Mark）为 EF BB BF
• 某些 Windows 程序需要 BOM 来识别 UTF-8 编码

示例：

Dim Utf8Bytes() As Byte
Utf8Bytes = VBMAN.ToolsUtf8.EncodeWithBom("你好世界")

' 查看字节内容（前3字节是BOM）
Dim i As Long
For i = LBound(Utf8Bytes) To UBound(Utf8Bytes)
    Debug.Print Hex(Utf8Bytes(i));
Next i
' 输出: EF BB BF E4 BD A0 E5 A5 BD E4 B8 96 E7 95 8C
'       [  BOM  ] [        你好世界（UTF-8）        ]

DecodeWithBom

将带 BOM 的 UTF-8 字节数组解码为字符串。

Public Function DecodeWithBom(ByVal varIn As Variant) As String

参数：

参数名	类型	说明
varIn	Variant	字节数组或包含字节数组的 Variant

说明：

• 自动检测并跳过 BOM
• 支持带或不带 BOM 的数据

示例：

Dim Utf8Bytes() As Byte
Utf8Bytes = VBMAN.ToolsUtf8.EncodeWithBom("你好世界")

Dim Text As String
Text = VBMAN.ToolsUtf8.DecodeWithBom(Utf8Bytes)
Debug.Print Text  ' 输出: 你好世界

' 不带 BOM 的数据也能解码
Dim NoBomBytes() As Byte
NoBomBytes = VBMAN.ToolsUtf8.Encode("Hello")
Text = VBMAN.ToolsUtf8.DecodeWithBom(NoBomBytes)
Debug.Print Text  ' 输出: Hello

---

完整示例

Private Sub Utf8Demo()
    Dim Original As String
    Dim Utf8Bytes() As Byte
    Dim Decoded As String
    
    Original = "VBMAN 框架 v1.0"
    
    ' 编码为 UTF-8
    Utf8Bytes = VBMAN.ToolsUtf8.Encode(Original)
    Debug.Print "UTF-8 字节数: " & (UBound(Utf8Bytes) + 1)
    
    ' 解码回字符串
    Decoded = VBMAN.ToolsUtf8.Decode(Utf8Bytes)
    Debug.Print "解码结果: " & Decoded
    
    ' 验证
    Debug.Print "是否一致: " & (Original = Decoded)
    
    ' ===== 带 BOM 的操作 =====
    
    Dim Utf8BytesWithBom() As Byte
    Utf8BytesWithBom = VBMAN.ToolsUtf8.EncodeWithBom(Original)
    Debug.Print "带 BOM 的字节数: " & (UBound(Utf8BytesWithBom) + 1)
    
    ' 解码带 BOM 的数据
    Decoded = VBMAN.ToolsUtf8.DecodeWithBom(Utf8BytesWithBom)
    Debug.Print "BOM 解码结果: " & Decoded
End Sub

Private Sub Utf8FileDemo()
    ' 保存 UTF-8 文件（不带 BOM）
    Dim Text As String
    Text = "你好，世界！"
    
    Dim Utf8Bytes() As Byte
    Utf8Bytes = VBMAN.ToolsUtf8.Encode(Text)
    
    ' 使用 cFileIO 保存
    VBMAN.FileIO.SetBuffer(Utf8Bytes).SaveData "C:\\utf8_nobom.txt"
    
    ' 保存带 BOM 的 UTF-8 文件
    Dim Utf8BytesWithBom() As Byte
    Utf8BytesWithBom = VBMAN.ToolsUtf8.EncodeWithBom(Text)
    VBMAN.FileIO.SetBuffer(Utf8BytesWithBom).SaveData "C:\\utf8_bom.txt"
    
    ' 读取并解码
    Dim ReadBytes() As Byte
    VBMAN.FileIO.OpenFile("C:\\utf8_nobom.txt").ReadData()
    ReadBytes = VBMAN.FileIO.ReturnBytes()
    
    Dim ReadText As String
    ReadText = VBMAN.ToolsUtf8.Decode(ReadBytes)
    Debug.Print "读取内容: " & ReadText
End Sub

---

应用场景

场景	示例
网络传输	将字符串转为 UTF-8 字节后发送
文件存储	将文本以 UTF-8 编码保存
加密解密	先转 UTF-8 字节再加密
数据校验	计算 UTF-8 字节的哈希值
跨平台兼容	使用带 BOM 的 UTF-8 确保 Windows 程序正确识别

---

编码对比

编码方式	优点	缺点
Encode	标准 UTF-8，兼容性好	部分 Windows 程序可能无法识别
EncodeWithBom	Windows 记事本等程序可正确识别	多3字节 BOM 开销

---

注意事项

1. BOM 的使用

   • Windows 记事本保存 UTF-8 文件会带 BOM
   • 部分程序（如某些 Unix 工具）可能不识别 BOM
   • Web 开发中通常推荐不带 BOM

2. 字节序

   • UTF-8 没有字节序问题
   • UTF-16 才有大端/小端之分

3. 内存占用

   • 中文字符：UTF-8 通常占3字节，UTF-16 占2字节
   • ASCII 字符：UTF-8 占1字节，UTF-16 占2字节