Boost.Nowide

更新日志

目录

• 什么是 Boost.Nowide
• 基本原理
  • 问题
  • 解决方案
  • 为什么不用窄字符和宽字符?
  • 替代方案
  • 延伸阅读
• 使用库
  • 构建库
  • 标准功能
  • 自定义 API
  • 与 Boost.Filesystem 集成
• 技术细节
  • Windows 与 POSIX
  • 控制台 I/O
• 问答
• 独立版本
• 来源和下载

什么是 Boost.Nowide

Boost.Nowide 是 Artyom Beilis 最初实现的一个库，它使跨平台 Unicode 感知编程更加容易。

该库提供了标准 C 和 C++ 库函数的实现，使得在 Windows 上输入为 UTF-8 感知，而无需使用 Wide API。在非 Windows/POSIX 平台上，则别名为 StdLib 的等价项，因此不会进行转换，因为 UTF-8 已经普遍使用。

因此，您可以在所有平台上使用与 std 版本同名的 Boost.Nowide 函数，并使用窄字符串，它就能正常工作。

基本原理

问题

考虑一个将大文件分割成块以便通过电子邮件发送的简单应用程序。它需要执行一些非常简单的任务：

• 访问命令行参数：int main(int argc,char **argv)
• 打开输入文件，打开几个输出文件：std::fstream::open(const char*,std::ios::openmode m)
• 发生故障时删除文件：std::remove(const char* file)
• 在控制台上打印进度报告：std::cout << file_name

不幸的是，如果文件名包含非 ASCII 字符，则无法用纯 C++ 实现此简单任务。

使用该 API 的简单程序将在内部使用 UTF-8 的系统上运行——绝大多数 Unix-Line 操作系统：Linux、Mac OS X、Solaris、BSD。但在 Microsoft Windows 上，文件名如 War and Peace - Война и мир - מלחמה ושלום.zip 将会失败，因为原生的 Windows Unicode 感知 API 是 Wide API——UTF-16。

这个极其微小的任务在跨平台方面非常难以实现。

解决方案

Boost.Nowide 提供了一组标准库函数，这些函数在 Windows 上是 UTF-8 感知的，并使 Unicode 感知编程更加容易。

该库提供：

• 易于使用的 UTF-8 与 UTF-16 之间的转换函数
• 一个类，用于使 main 函数的 argc、argc 和 env 参数使用 UTF-8
• UTF-8 感知函数
  • cstdio 函数
    • fopen
    • freopen
    • remove
    • rename
  • cstdlib 函数
    • system
    • getenv
    • setenv
    • unsetenv
    • putenv
  • fstream
    • filebuf
    • fstream/ofstream/ifstream
  • iostream
    • cout
    • cerr
    • clog
    • cin

所有这些函数都可以在 Boost.Nowide 的同名头文件中找到。因此，您不必包含 cstdio 并使用 std::fopen，只需包含 boost/nowide/cstdio.hpp 并使用 boost::nowide::fopen。这些函数接受与其 std 对应项相同的参数，实际上在非 Windows 构建中它们只是别名。但在 Windows 上，Boost.Nowide 会发挥其魔力：窄字符串参数被解释为 UTF-8，转换为宽字符串（UTF-16），然后传递给能够正确处理特殊字符的宽 API。

如果传入的字符串中存在非 UTF-8 字符，转换会将它们替换为替换字符（默认值：U+FFFD），类似于 NT 内核的做法。这意味着无效的 UTF-8 序列不会在窄->宽->窄的往返过程中保留，例如，如果文件名格式错误，则无法打开文件。

为什么不用窄字符和宽字符?

为什么不同时提供宽字符和窄字符实现，以便开发人员可以选择在类 Unix 平台上使用宽字符?

几个原因：

• wchar_t 实际上并不便携，它可以是 2 字节、4 字节甚至 1 字节，这使得 Unicode 感知编程更加困难。
• C 和 C++ 标准库在 OS 交互中使用窄字符串。该库遵循相同的通用规则。标准库中不存在 fopen(const wchar_t*, const wchar_t*)，因此最好坚持标准而不是重新实现“Microsoft Windows 风格”的 Wide API。

替代方案

自 2019 年 5 月更新以来，Windows 10 通过清单文件支持窄字符串的 UTF-8。因此，将“UTF-8”设置为活动代码页将允许使用窄 API，而无需对 UTF-8 编码的字符串进行任何其他更改。有关详细信息，请参阅 文档。

自 2018 年 4 月以来，Windows 10 中提供了一个（Beta 版）函数，可以通过用户设置默认使用 UTF-8 代码页。

这两种方法都有效，但有一个主要缺点：它们对于应用程序开发者来说并不完全可靠。当使用比 1903 版本旧的 Windows 版本时，通过清单的代码页方法将回退到旧的代码页。因此，只有在目标系统为 2019 年 5 月之后的 Windows 10 时才可以使用。
第二种方法依赖于程序启动前的用户交互。显然，当期望代码中只包含 UTF-8 时，这种方法并不可靠。

此外，自 Windows 10 1803（即 2018 年 4 月以来），可以通过编程方式将当前代码页设置为 UTF-8，例如使用 setlocale(LC_ALL, ".UTF8");。这使得许多函数接受或生成 UTF-8 编码的字符串，这对于 std::filesystem::path 及其 string() 函数特别有用。有关详细信息，请参阅 文档。虽然这对于大多数函数都有效，但对于程序参数（main 函数的 argv 和 env 参数）等则无效。

因此，在某些情况下（并且希望将来某个时候总是如此），将不需要此库，甚至可以使用 UTF-8 编码文本来使用 Windows I/O。

延伸阅读

• www.utf8everywhere.org
• Windows 控制台 I/O 方法

使用库

构建库

Boost.Nowide 通常作为 Boost 的一部分，通过 b2 进行构建。
它需要 C++11 功能，如果缺少任何功能，该库将不会被构建。

如果意外发生这种情况，请查看配置检查输出，查找类似 cxx11_constexpr : no 的内容。
这意味着您的编译器不使用 C++11（或更高版本），例如，因为它默认为 C++03。您可以将 cxxstd=11 传递给 b2 以在 C++11 模式下构建。

使用 Boost CMake 构建系统进行构建的实验性支持也可用。
为此，请运行例如 cmake -DBOOST_INCLUDE_LIBRARIES=nowide <path-to-boost-root> <other options>。

标准功能

作为开发人员，您应该使用 boost::nowide 函数，而不是 std 命名空间中可用的函数。

例如，这是一个不考虑 Unicode 的行计数器实现：

#include <fstream>
#include <iostream>
 
int main(int argc,char **argv)
{
    if(argc!=2) {
std::cerr << "Usage: file_name" << std::endl;
        返回 1;
    }
 
std::ifstream f(argv[1]);
    if(!f) {
std::cerr << "Can't open " << argv[1] << std::endl;
        返回 1;
    }
    int total_lines = 0;
    while(f) {
        if(f.get() == '\n')
total_lines++;
    }
f.close();
std::cout << "File " << argv[1] << " has " << total_lines << " lines" << std::endl;
    返回 0;
}

为了使此程序正确处理 Unicode，我们进行以下更改：

#include <boost/nowide/args.hpp>
#include <boost/nowide/fstream.hpp>
#include <boost/nowide/iostream.hpp>
 
int main(int argc,char **argv)
{
    boost::nowide::args a(argc,argv); // 修复参数 - 使其为 UTF-8
    if(argc!=2) {
        boost::nowide::cerr << "Usage: file_name" << std::endl; // Unicode 感知控制台
        返回 1;
    }
 
    boost::nowide::ifstream f(argv[1]); // argv[1] - 是 UTF-8
    if(!f) {
        // 控制台可以显示 UTF-8
        boost::nowide::cerr << "Can't open " << argv[1] << std::endl;
        返回 1;
    }
    int total_lines = 0;
    while(f) {
        if(f.get() == '\n')
total_lines++;
    }
f.close();
    // 控制台可以显示 UTF-8
    boost::nowide::cout << "File " << argv[1] << " has " << total_lines << " lines" << std::endl;
    返回 0;
}

这种非常简单直接的方法有助于编写 Unicode 感知的程序。

注意 boost::nowide::args、boost::nowide::ifstream 和 boost::nowide::cerr/cout 的使用。在非 Windows 系统上，它什么也不做，但在 Windows 上会发生以下情况：

• boost::nowide::args 从 Windows API 获取 UTF-16 参数，将它们转换为 UTF-8，并在其实例的生命周期内临时用指向这些内部存储的 UTF-8 字符串的指针替换原始的 argv（以及可选的 env）。
• boost::nowide::ifstream 将传入的文件名（现在是有效的 UTF-8）转换为 UTF-16，并调用 Windows Wide API 打开文件流，然后可以像平常一样使用。
• 类似地，boost::nowide::cerr 和 boost::nowide::cout 使用一个底层的流缓冲区，该缓冲区将 UTF-8 字符串转换为 UTF-16，并使用另一个 Wide API 函数将其写入控制台。

自定义 API

当然，这一组简单的函数并不足以满足所有需求。如果您需要从使用内部 UTF-8 的 Windows 应用程序访问 Wide API，您可以使用 boost::nowide::widen 和 boost::nowide::narrow 函数。

例如：

CopyFileW( boost::nowide::widen(existing_file).c_str(),
            boost::nowide::widen(new_file).c_str(),
TRUE);

转换在最后阶段完成，您在其他地方继续使用 UTF-8 字符串。您只在粘合点切换到 Wide API。

boost::nowide::widen 返回 std::string。有时，为了避免分配并使用堆栈缓冲区，使用 boost::nowide::basic_stackstring 类会更方便。

上面的示例可以重写为：

boost::nowide::basic_stackstring<wchar_t,char,64> wexisting_file(existing_file), wnew_file(new_file);
CopyFileW(wexisting_file.c_str(), wnew_file.c_str(), TRUE);

注意

有一些方便的 typedefs：stackstring 和 wstackstring 使用 256 字节缓冲区，short_stackstring 和 wshort_stackstring 使用 16 字节缓冲区。如果字符串更长，它们将回退到堆内存分配。

windows.h 头文件

该库不包含 windows.h，以避免命名空间被大量宏定义和类型污染。相反，该库定义了 Win32 API 函数的原型。

但是，您可以通过在包含任何 Boost.Nowide 头文件之前定义 BOOST_USE_WINDOWS_H 来请求使用 windows.h 头文件。

与 Boost.Filesystem 集成

Boost.Filesystem 支持窄编码的选择。不幸的是，Windows 上的默认窄编码不是 UTF-8。但是，您可以通过在程序开头调用 boost::nowide::nowide_filesystem() 来启用 UTF-8 作为 Boost.Filesystem 的默认编码，该函数会注入一个带有 UTF-8 转换方面的区域设置，用于在 char 和 wchar_t 之间进行转换。这会将传递给 boost::filesystem::path 和从其返回的所有窄字符串解释为 UTF-8，并在将其转换为宽字符串时（内部存储需要）进行处理。在 POSIX 上，这通常没有影响，因为窄字符串被用作存储格式，因此不进行转换。

对于 C++17 中可用的 std::filesystem::path，无法注入区域设置。但是，可以使用 u8string() 成员函数从 path 获取 UTF-8 编码的字符串。要从 UTF-8 编码的字符串获取 path，可以使用 std::filesystem::u8path，或者自 C++20 起，可以使用接受 char8_t 类型输入的 path 构造函数之一。

要从流读取/写入 std::filesystem::path 实例，通常会使用例如 os << path。但这实际上会作为 os << std::quoted(path.string()) 运行，这意味着可能转换为窄字符串，而该字符串可能不是 UTF-8 编码的。为此，可以使用 quoted。

#include <boost/nowide/quoted.hpp>
#include <filesystem>
#include <sstream>
 
std::string write(const std::filesystem::path& path)
{
std::ostringstream s;
s << boost::nowide::quoted(path);
    return s.str();
}
 
std::experimental::path read(std::istream& is)
{
std::filesystem::path path;
is >> boost::nowide::quoted(path);
    return path;
}

技术细节

Windows 与 POSIX

对于 Microsoft Windows，该库在 boost::nowide 命名空间中提供了某些 std: 函数的 UTF-8 感知变体。例如，std::fopen 变为 boost::nowide::fopen。

在 POSIX 平台上，boost::nowide 中的函数是其标准库对应项的别名。

namespace boost {
namespace nowide {
#ifdef BOOST_WINDOWS
inline FILE *fopen(const char* name, const char* mode)
{
    ...
}
#else
using std::fopen
#endif
} // nowide
} // boost

还为 Windows 提供了一个兼容 std::filebuf 的实现，该实现支持 UTF-8 文件路径的 open，并且在行为上（API 方面）完全相同。

在所有系统上，std::fstream 类及其同类项都作为自定义实现提供，支持 std::string 和 *::filesystem::path，以及构造函数和 open 的 wchar_t*（仅限 Windows）重载。这样做是为了让用户能够例如将 boost::filesystem::path 与 boost::nowide::fstream 一起使用，而无需依赖 C++17 支持。此外，如果任何路径类匹配 std::filesystem::path 的接口“足够”，那么它也支持。

请注意，boost::nowide::filebuf 中并没有对 path 和 std::string 的通用支持。这是因为在非 Windows 系统上使用了 std 版本，在某些情况下可能更快。由于 filebuf 很少被用户代码直接使用，而是通过 fstream 间接使用，因此不支持字符串或路径似乎是可以接受的小代价，尤其是 C++11 增加了 std::string 支持，C++17 增加了 path 支持，并且仍然可以通过 string_or_path.c_str() 进行可移植的使用。

控制台 I/O

当流输出到“真实”控制台时，控制台 I/O 实现为 ReadConsoleW/WriteConsoleW 的包装器。当流被管道传输/重定向时，则使用标准的 cin/cout。

这种方法消除了手动处理代码页的需求。如果使用 TrueType 字体，Unicode 感知的输入和输出将按预期工作。

问答

问：当无效的 UTF 字符通过 Boost.Nowide 时会发生什么？例如，Windows 使用 UCS-2 而不是 UTF-16。

答：Boost.Nowide 的策略是始终产生有效的 UTF 编码字符串。因此，无效的 UTF 字符将被替换字符 U+FFFD 替换。

这发生在两个方向：
当将（假定的）UTF-8 编码字符串传递给 Boost.Nowide 时，它会将其转换为 UTF-16，并在将其传递给操作系统之前替换所有无效字符。
从操作系统检索值时（例如，boost::nowide::getenv 或通过 boost::nowide::args 获取的命令行参数），该值假定为 UTF-16 并转换为 UTF-8，替换任何无效字符。

这意味着，如果以某种方式在 Windows 中创建了无效的 UTF-16 文件名，那么使用 Boost.Nowide 将无法处理它。但由于 Microsoft 已从 UCS-2（又名值任意的 2 字节字符串）切换到 Windows 2000 中的 UTF-16，因此在大多数环境中这不是问题。

问：使用的是哪种错误报告方式？

答：实际上是三种：

• 无效的 UTF 编码字符串通过用替换字符 U+FFFD 替换无效字符来使用。
• 镜像标准 API 的 API 调用使用与该 API 相同的错误报告方式，例如，在失败时返回一个非零值。
• 不可继续的错误通过标准异常报告。主要示例是通过 WinAPI 无法获取命令行参数。

问：为什么该库不在 POSIX 系统上将字符串转换为/自区域设置的编码（而不是 UTF-8）？

答：在 POSIX 平台上将字符串转换为/自区域设置编码在本质上是不正确的。

您可以创建一个名为“\xFF\xFF.txt”（无效 UTF-8）的文件，删除它，然后将其名称作为参数传递给程序，无论当前区域设置是 UTF-8 还是其他，它都会正常工作。此外，将区域设置从例如 en_US.UTF-8 更改为 en_US.ISO-8859-1 不会神奇地改变操作系统中的所有文件或用户可能传递给程序的字符串（这与 Windows 不同）。

POSIX 操作系统将字符串视为 NULL 终止的“Cookie”。

因此，根据区域设置更改它们的含义实际上会导致错误行为。

例如，这是一个标准程序“rm”的粗略实现：

#include <cstdio>
 
int main(int argc,char **argv)
{
    for(int i=1;i<argc;i++)
std::remove(argv[i]);
    返回 0;
}

它将适用于任何区域设置，而更改字符串将导致错误行为。

区域设置在 POSIX 和 Windows 平台上的含义是不同的，并且具有非常不同的效果。

独立版本

可以在没有庞大的 Boost 项目作为依赖的情况下使用 Nowide 库。有一个独立版本，它拥有 nowide 命名空间中的所有功能，而不是 boost::nowide。上面的示例将如下所示：

#include <nowide/args.hpp>
#include <nowide/fstream.hpp>
#include <nowide/iostream.hpp>
 
int main(int argc,char **argv)
{
nowide::args a(argc,argv); // 修复参数 - 使其为 UTF-8
    if(argc!=2) {
nowide::cerr << "Usage: file_name" << std::endl; // Unicode 感知控制台
        返回 1;
    }
 
nowide::ifstream f(argv[1]); // argv[1] - 是 UTF-8
    if(!f) {
        // 控制台可以显示 UTF-8
nowide::cerr << "Can't open a file " << argv[1] << std::endl;
        返回 1;
    }
    int total_lines = 0;
    while(f) {
        if(f.get() == '\n')
total_lines++;
    }
f.close();
    // 控制台可以显示 UTF-8
nowide::cout << "File " << argv[1] << " has " << total_lines << " lines" << std::endl;
    返回 0;
}

来源和下载

上游源代码可以在 GitHub 上找到：https://github.com/boostorg/nowide

您可以在那里下载最新的源代码。

• 标准版本：nowide-master.zip