002-告别乱码-libiconv-C++开源库108杰

本课文包含三个视频！

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

004-libiconv编码转换-1基础知识-c++108杰

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 函数简化封装 🎥

005-libiconv编码转换-2简化函数-C++108杰

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_openiconv_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); // 将本轮的输出结果，写入输出流} // whileiconv_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() 的解决方案。

006-libiconv编码转换-3项目应用-C++108杰

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 封装，并及时交作业。