本课文包含三个视频！

为什么中文版Windows是编程出现乱码的高发地带？怎么用 libiconv 把国标编码的汉字转换成宇宙统一码？怎么简化 libiconv 那些充满坑的 纯C 函数API？

1. 安装 libiconv

通常，你在 MSYS2 中安装过 GCC 编译套件，你的 msys2 系统中就会有 libiconv 开发库可用。可通过如下指令验证：

pacman -S libiconv

查看是否出现带有 “[已安装]” （或 installed）的 libiconv 库？

如果确实需要单独安装，指令为：

pacman -S mingw-w64-ucrt-x86_64-libiconv 

再次提醒，如果你使用的 GCC 不是 UCRT64 版本，那么你可能需要的库名称应是 mingw-w64-x86_64-libiconv （64位OS）或 mingw-w64-i686-libiconv （32位OS，不敢相信你在还在用）

2. 转码基础知识 🎥

Windows （中文版）是 编程出现乱码的高发地带之一。原因来自历史包袱：当年，各国政府（自然包括我国）都要求微软出的本地语言版本的操作系统，其字符编码，必须遵守当年各国国标。

3. 函数使用包装

3.1 主要函数介绍

libiconv 主要函数有三个：

• iconv_open

原型：

iconv_t iconv_open(char const* toCode, char const * fromcode)

• 其中, iconv_t 为 “void *” 的别名
• 函数失败时，并不返回 nullptr，而是返回 (iconv_t)(-1)
• 入参依序为：目标编码名称，源编码名称

以下称该函数打开成功得到的结果为 “句柄”。

• iconv

原型：

size_t iconv( iconv_t cd,
              char** in, size_t* inBytesLeft, 
              char** out, size_t* outBytesLeft);

第一个参数为句柄。其余四个参数都既为入参也为出参。

1. in：作入参，用于指示当前待转换的源字符串缓存区开始位置；作出参，用于告诉调用者，本次转换的结束位置（即下次转换的开始位置）；

2. inByteLeft：作入参，指示当前待转换的源字符串缓存区有多大；作出参，告诉调用者，本次转换后还剩下多少字节未转换；

3. out: 作入参，用于指示可用于存储转换结果的缓存区开始位置；作出参，用于告诉调用者，本次转换后，结果存放的结束位置（可考虑作为下次用于存储结果的开始位置，本课堂出于简化，未采用此方法）；

4. outBytesLeft: 作入参，用于指示本次转换可用来存储结果的缓存区大小（字节数）；作出参，用于告诉调用者，本次转换后，用于存储结果的缓存区还剩余多少字节。

in 和 out 的内容都有可能造成本函数转换中途停下。最典型的如：out ，也就是输出缓存区大小不够了。比如说，源字符串有 61 字节，但目标输出缓存区（也就是 out）只有20个字节，就会造成 iconv() 转换若干字节后，就停下，并借助 errno （C库的一个宏，类似全局变量，但本质是对应到一个函数调用，且线程安全），告诉调用者：输出缓存区不足。

注意，编码转换并非 1:1 转换，由于源编码和目标编码用以表达单一个本地字符（比如一个汉字）的长度不一样，因此二者之间并不存在某个简单的比例关系。典型的如使用 UTF-8 编码表达一个汉字，可能是 2字节，也可能是 3字节、4字节。

为了避免 “输出缓存区不足” ，最粗暴的方法就是为 out 分配一个 “巨大” 的空间——比如，是源字符串长度的 4 倍、5 倍……这种方法既浪费内存，并且通常需要使用到 new 来动态分配内存，进一步拉低性能。

我们的解决方法相对复杂，但高效（或者说性能均衡）：采用固定大小的临时连续内存来存储每次转换的结果，同时准备一个字符串流（std::stringstream）来连续存储每次转换的结果（新结果追加到旧结果之后）。

3.2 函数简化封装 🎥

3.3 函数封装主要代码

namespace d2::myiconv
{

// 转换结构
struct IConvResult
{
    std::string result; // 转换成功得到的，使用新编码的字符串

    int errorNumber = 0; // 对应 errno, 出错号
    std::string errorMessage; // 出错信息
};

// 转换函数
IConvResult Convert(std::string_view in, char const* fromCode, char const* toCode)
{

IConvResult Convert(std::string_view in, char const* fromCode, char const* toCode)
{
    IConvResult ir;

    // 调用 iconv_open
    iconv_t cd = iconv_open(toCode, fromCode);

    if (cd ==(iconv_t)(-1)) // 打开失败
    {
        ir.errorNumber = errno; // C -> C++

        switch (ir.errorNumber)
        {
        case EINVAL:
            ir.errorMessage = "不支持的编码";
            break;
        case ENOMEM:
            ir.errorMessage = "内存不足";
            break;
        default:
            ir.errorMessage = "未知错误";
            break;
        }

        return ir;
    }

    char* inBufferPtr = const_cast<char *>(in.data()); // 指向输入缓存位置 （非常量）
    size_t inBytesLeft = in.size(); // 输入缓存大小

    std::stringstream ss;

    std::size_t const sizeOfOutBuffer = 20; // 输出缓存区大小
    char outBuffer[sizeOfOutBuffer]; // 输出缓存

    while (inBytesLeft > 0) // 输入缓存中，还有剩余字符未被转换
    {
        char *outBufferPtr = outBuffer;
        size_t outBufferLeft = sizeOfOutBuffer;

        size_t result = iconv(cd, &inBufferPtr, &inBytesLeft, &outBufferPtr, &outBufferLeft);

        if (result == (size_t)(-1)) // 转换停止了
        {
            auto n = errno;

            switch (n)
            {
                case E2BIG: // 输出缓存区不够用了……
                {                
                    break;
                }

                case EILSEQ: 
                {
                    ir.errorNumber = n;
                    ir.errorMessage = "输入字符序列不符合指定编码规则";
                    break;
                }

                case EINVAL:
                {
                    ir.errorNumber = n;
                    ir.errorMessage = "输入的字符序列不完整"; 
                    break;
                }
                
                default:
                {
                    ir.errorNumber = n;
                    ir.errorMessage = "转换过程发生未知错误";                
                    break;
                }
            }
        }

        if (ir.errorNumber != 0)
        {
            break; // while
        }

        ss.write(outBuffer, sizeOfOutBuffer - outBufferLeft); // 将本轮的输出结果，写入输出流
    } // while

    iconv_close(cd);
    
    if (ir.errorNumber == 0)
    {
        ir.result = ss.str();
    }

    return ir;
}       

} //namespace d2::myiconv

使用示例：

char const* gbk = "假设这是一个GBK编码的字符串";

auto ir = d2:myiconv::Convert(gbk, "GBK", "UTF-8");

if (ir.errorNumber != 0)
{
    std::cout << ir.errorNumber << " : " << ir.errorMessage << "\n";
}
else
{
    // 转换成功：
    std::cout << ir.result << std::endl;
}

对应的 CMakeLists.txt 示例：

cmake_minimum_required(VERSION 3.10.0)
project(HelloLibIconv VERSION 0.1.0 LANGUAGES C CXX)

add_executable(HelloLibIconv main.cpp gbk_str.cpp)

target_link_libraries(${PROJECT_NAME} PRIVATE iconv)
target_link_directories(${PROJECT_NAME} PRIVATE "c:/msys64/ucrt64/lib")

其中的 gbk_str.cpp 在 VSCODE 中应明确使用 GBK 编码保存，其内容为：

char const* gbk_str = "我是一个GBK字符编码的字符串！请保障我所在的CPP文件编码为GBK！"; 

4. 项目应用 🎥

上一节中 libfswatch 在监控 Windows 下名字带汉字的文件对象时，文件名输出会出现乱码。其原因于：libfswatch 从 Windows 读文件对象信息时，未使用特定的 UNICODE 版本的 API，而是使用 Windows 本地语言版 API，因此读到的文件名中的中文字符是 GBxxxx 编码（既中国国标），但 libfswatch 将它视为 UTF-8 编码。

基于 libiconv，使用我们所包装的函数，解决乱码的核心代码是：

        // 输出变动的文件路径：
        auto utf8Path = d2::myiconv::Convert(event.get_path(), "GBK", "UTF-8"); // 编码转换
        if (utf8Path.errorNumber != 0)
        {
            std::cout << utf8Path.errorMessage << std::endl;
            break;
        }

        std::cout << utf8Path.result << "\n";

下面的视频给出了采用我们所写的 Convert() 的解决方案。

5. C++ 封装

d2::myiconv::Convert（）函数使用起来，比原来的纯C函数“三板斧”组合，要方便不少，但也有个比较明显的缺点：无法复用 iconv_open() 得到的句柄，每次转换都需要先打开最后再关闭。如果仅是一次性转换无所谓，但有时有多个字符串需要分开转换，句柄不能复用的弊端就比较明显了。

解决方法是使用 C++ 面向对象的思想进一步加以封装，我们给出一种思路的类设计（仅 class 设计）：

namespace d2::myiconv
{

// 转换结果
struct IConvResult
{
    std::string result; // 转换成功得到的，使用新编码的字符串

    int errorNumber = 0; // 对应 errno, 出错号
    std::string errorMessage; // 出错信息
};

class IconvHelper final // 注：实现为 final 类
{
public:
    // 构造（失败时可抛出异常）
    IconvHelper(char const* fromCode, char const* toCode) noexcept(false);
   
    IconvHelper(IconvHelper const& ) = delete; // 不允许复制
    IconvHelper& operator = (IconvHelper const&) = delete;

    IconvHelper(IconvHelper&& ih) noexcept; // 支持转移
    IconvHelper& operator = (IconvHelper&& ih) noexcept; 

    ~IconvHelper() noexcept; // 析构

    // 静态转换，方便一次性转换 (不允许抛出异常)
    static IConvResult Convert(std::string_view in,
                  char const* fromCode, char const* toCode) noexcept;

    // 非静态的转换方法，方便多次复用 (不允许抛出异常)
    IConvResult Convert(std::string_view in) noexcept;  

private:
    iconv_t cd;
};

} //  namespace d2::myiconv

请进入 d2school 网站 本课的作业区，完成符合上述类定义的 C++ 版本的 libiconv 封装，并及时交作业。