C++ 使用 WideCharToMultiByte 生成带 BOM 的 UTF-8 文件

核心方法与准备条件

WideCharToMultiByte 是 Windows API 中用于字符集转换的核心函数。它能够将 Unicode 宽字符缓冲区映射到多字节字符缓冲区。要生成有效的 UTF-8 文件，必须满足以下条件：

• 环境依赖：仅支持 Windows 平台。需注意 Windows CE 不支持 CP_UTF8 和 CP_UTF7。
• 头文件与链接库：需要包含 <windows.h>，通常无需额外链接静态库。
• BOM 头添加：标准的 UTF-8 文件推荐包含 BOM，由三个字节 0xEF, 0xBB, 0xBF 组成，用于标识文件编码类型。

操作参数详解

在使用该函数前，理解参数含义至关重要：

1. UINT CodePage：指定目标代码页。对于 UTF-8，必须填入常量 CP_UTF8。
2. LPCWSTR lpWideCharStr：指向源宽字符字符串的地址。
3. int cchWideChar：源字符串的字符数量。设为 -1 时，函数会自动计算直到遇到空终止符 L' ' 的长度。
4. LPSTR lpMultiByteStr：指向接收转换结果的目标缓冲区的指针。
5. int cchMultiByte：目标缓冲区的大小（以字节计）。若传入 0 且 lpMultiByteStr 为 NULL，函数将返回所需缓冲区的大小而非执行转换，这常用于预先分配内存。
6. 返回值判断：成功时返回写入目标的字节数或所需字节数；失败时返回 0，此时应调用 GetLastError() 获取具体错误码（如 ERROR_INSUFFICIENT_BUFFER）。

第1步：初始化宽字符数据

首先需要构造包含中文或其他非 ASCII 字符的宽字符数组。注意所有字符串操作需使用wchar_t系列函数，例如 wcslen 和 swprintf，而非 char 系列。

#include <iostream>
#include <fstream>
#include <string>
#include <windows.h>

using namespace std;

int main() {
    // 示例：将数字编号转换为中文大写形式
    wchar_t chNum[11] = L"零壹贰叁肆伍陆柒捌玖";
    wchar_t chNum2[10] = L"亿千百拾万千百拾个";
    char szInput[] = "112304823";
    
    // 构建宽字符结果缓冲区
    wchar_t result[64] = L"";
    int offset = 0;
    
    for(int i = 0; i < strlen(szInput); ++i) {
        char c = szInput[i];
        if(c >= '0' && c <= '9') {
            wchar_t w1 = chNum[c - '0'];
            wchar_t w2 = chNum2[i];
            swprintf(result + offset, 64 - offset, L"%c%c", w1, w2);
            offset += 2;
        }
    }
    

第2步：计算缓冲区大小并执行转换

为了避免缓冲区溢出，建议分两步走：先计算所需字节数，再申请缓冲区并执行转换。虽然固定大小缓冲区在实际简单场景中可行，但严谨做法如下：

    // 1. 计算所需缓冲区大小
    int neededBytes = WideCharToMultiByte(CP_UTF8, 0, result, wcslen(result), NULL, 0, NULL, NULL);
    
    if(neededBytes == 0) {
        // 处理转换失败，如 GetLastError()
        return 1;
    }
    
    // 2. 分配缓冲区并转换
    char* szUtf8 = new char[neededBytes];
    WideCharToMultiByte(CP_UTF8, 0, result, wcslen(result), szUtf8, neededBytes, NULL, NULL);

注：简化示例中也可直接使用定长缓冲区，但需确保长度足够容纳转换后的字节流。转换后得到的是纯 UTF-8 字节序列。

第3步：写入带有 BOM 头的文件

打开文件流，首先写入 BOM 头，随后写入转换后的 UTF-8 内容，最后关闭文件。推荐使用二进制模式或确保输出流不被自动修改编码。

    // 创建并打开文件
    FILE* pFile = fopen("utf8_test.txt", "w");
    if (!pFile) {
        cerr << "无法创建文件" << endl;
        delete[] szUtf8;
        return 1;
    }
    
    // 写入 BOM 头 (EF BB BF)
    char bom[3] = {(char)0xEF, (char)0xBB, (char)0xBF};
    fwrite(bom, 1, 3, pFile);
    
    // 写入 UTF-8 内容
    fwrite(szUtf8, 1, neededBytes, pFile);
    
    // 清理资源
    fclose(pFile);
    delete[] szUtf8;
    
    cout << "文件生成成功" << endl;
    return 0;
}

注意事项与排错

• 缓冲区指针区分：lpWideCharStr 和 lpMultiByteStr 不能指向同一内存地址，否则会导致未定义行为或 GetLastError 返回 ERROR_INVALID_PARAMETER。
• 默认字符替换：若宽字符中某些字在当前代码页无对应表示，函数会使用 lpDefaultChar 指定的字符替换。为避免文件名中出现问号（通配符），在涉及文件名转换时应特别注意此参数或检查返回值中的 pfUsedDefaultChar 状态。
• 编码一致性：确保源字符串确实是合法的 Unicode 宽字符，否则转换结果可能不可读。

以上就是使用 C++ WideCharToMultiByte 函数生成 UTF-8 编码文件的详细内容，更多关于 C++ 文件编码处理与 Windows API 应用的资料请关注本站其它相关文章！