QStringConverter 类
QStringConverter 类提供编码和解码文本的基类。 更多...
| 头文件 | #include <QStringConverter> |
| CMake | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake | QT += core |
| 继承自 |
注意：本类中所有函数都是 可重入的。
公共类型
| 枚举 | Encoding { Utf8, Utf16, Utf16BE, Utf16LE, Utf32, …, System } |
| 枚举类 | Flag { Default, ConvertInvalidToNull, WriteBom, ConvertInitialBom, Stateless } |
| 标志 | 标志 |
公共函数
| bool | hasError() const |
| bool | isValid() const |
| const char * | name() const |
| void | resetState() |
静态公共成员
| QStringList | availableCodecs() |
| std::optional<QStringConverter::Encoding> | encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0) |
| std::optional<QStringConverter::Encoding> | encodingForHtml(QByteArrayView data) |
| std::optional<QStringConverter::Encoding> | encodingForName(const char *name) |
| const char * | nameForEncoding(QStringConverter::Encoding e) |
详细描述
Qt 使用 UTF-16 存储和操作字符串。在许多情况下，你可能需要处理使用不同编码的数据。大多数通过文件和网络连接传输的文本数据都编码为 UTF-8。
QStringConverter 类是QStringEncoder和QStringDecoder类的基类，这些类帮助在不同文本编码之间进行转换。QStringDecoder可以将从编码表示形式解码的字符串转换为 UTF-16，这是 Qt 在内部使用的格式。QStringEncoder执行相反的操作，将 UTF-16 编码的数据（通常是QString的形式）编码为请求的编码。
以下编码始终受支持
- UTF-8
- UTF-16
- UTF-16BE
- UTF-16LE
- UTF-32
- UTF-32BE
- UTF-32LE
- ISO-8859-1 (Latin-1)
- 系统编码
QStringConverter 可以为 Qt 编译方式所支持的程度支持更多编码。如果支持更多编解码器，可以使用 availableCodecs() 编列。
以下是如何使用 QStringConverter 将某些编码的字符串转换为 UTF-16并进行转码的示例。
假设你有一些用UTF-8编码的字符串，想要将其转换为QString。最简单的方法是使用QStringDecoder，如下所示：
QByteArray encodedString = "..."; auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); QString string = toUtf16(encodedString);
这样做后，string将包含解码后的文本。将字符串从Unicode转换为本地编码使用QStringEncoder类同样简单。
QString string = "..."; auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8); QByteArray encodedString = fromUtf16(string);
要读取或写入各种编码的文本文件，请使用QTextStream及其setEncoding()函数。
在按块转换数据时（例如在网络中接收数据时），需要注意一些问题。在这种情况下，可能一个多字节字符将跨越两个块。最坏的情况下，这可能会导致字符丢失，甚至整个转换失败。
两者QStringEncoder和QStringDecoder通过跟踪内部状态使这变得简单。因此，只需再次调用编码器或解码器并传递下一块数据即可自动正确地继续编码或解码数据。
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); QString string; while (new_data_available()) { QByteArray chunk = get_new_data(); string += toUtf16(chunk); }
QStringDecoder对象在块之间保持状态，因此即使多字节字符在块之间分割也能正确工作。
由于内部状态的原因，QStringConverter对象不能复制，但可以移动。
另见QTextStream，QStringDecoder和QStringEncoder。
成员类型文档
枚举QStringConverter::Encoding
| 常量 | 值 | 描述 |
|---|---|---|
QStringConverter::Utf8 | 0 | 创建一个到或从UTF-8的转换器 |
QStringConverter::Utf16 | 1 | 创建一个到或从UTF-16的转换器。在解码时，字节顺序会自动通过一个前导字节顺序标记检测。如果不存在或在编码时，则假定系统字节顺序。 |
QStringConverter::Utf16BE | 3 | 创建一个到或从大端UTF-16的转换器。 |
QStringConverter::Utf16LE | 2 | 创建一个到或从小端UTF-16的转换器。 |
QStringConverter::Utf32 | 4 | 创建一个到或从UTF-32的转换器。在解码时，字节顺序会自动通过一个前导字节顺序标记检测。如果不存在或在编码时，则假定系统字节顺序。 |
QStringConverter::Utf32BE | 6 | 创建一个到或从大端UTF-32的转换器。 |
QStringConverter::Utf32LE | 5 | 创建一个到或从小端UTF-32的转换器。 |
QStringConverter::Latin1 | 7 | 创建一个到或从ISO-8859-1（Latin1）的转换器。 |
QStringConverter::System | 8 | 创建一个到操作系统区域设置的底层编码的转换器。对于基于Unix的系统，这始终假定是UTF-8。在Windows上，这将转换到和从区域代码页。 |
枚举类QStringConverter::Flag
标志QStringConverter::Flags
| 常量 | 值 | 描述 |
|---|---|---|
QStringConverter::Flag::Default | 0 | 应用默认转换规则。 |
QStringConverter::Flag::ConvertInvalidToNull | 0x2 | 如果设置了此标志，则将每个无效输入字符输出为null字符。如果没有设置，如果输出编码可以表示该字符，则无效输入字符将表示为QChar::ReplacementCharacter，否则表示为问号。 |
QStringConverter::Flag::WriteBom | 0x4 | 将QString转换为输出编码时，如果输出编码支持，将QChar::ByteOrderMark作为第一个字符写入。这是UTF-8，UTF-16和UTF-32编码的情况。 |
QStringConverter::Flag::ConvertInitialBom | 0x8 | 在将输入编码转换为QString时，QStringDecoder通常会跳过开头的QChar::ByteOrderMark。当此标志设置为true时，字节顺序标记将不会被跳过，而是转换为utf-16并插入到创建的QString的开头。 |
QStringConverter::Flag::Stateless | 0x1 | 忽略不同函数调用之间可能的转换器状态，以编码或解码字符串。这也将导致当遇到不完整的数据序列时，QStringConverter引发错误。 |
Flags类型是<QFlags<Flag>的typedef。它存储Flag值的或组合。
成员函数说明
[static] QStringList QStringConverter::availableCodecs()
返回支持的编解码器名称列表。此函数返回的名称可以传递给QStringEncoder和QStringDecoder的构造函数，以创建给定编解码器的编码器或解码器。
此函数可以用于获取标准编解码器之外的附加编解码器的列表。对附加编解码器的支持需要Qt编译时支持ICU库。
注意：编解码器的顺序是内部实现细节，不保证稳定。
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0)
如果可以确定，则返回data内容的编码。可以传递expectedFirstCharacter作为额外的提示，以帮助确定编码。
如果编码不明确，则返回的可选项为空。
[static] std::optional<QStringConverter::Encoding> QStringConverter::encodingForHtml(QByteArrayView data)
尝试通过查看HTML元标签中的起始字节顺序标记或charset指定符来确定data中HTML的编码。如果可选项为空，则指定的编码不受QStringConverter支持。如果没有检测到编码，则该方法返回Utf8。
另见：QStringDecoder::decoderForHtml()。
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForName(const char *name)
将name转换为相应的Encoding成员，如果有的话。
如果name不是编码枚举中列出的编解码器名称，则返回std::nullopt。然而，如果Qt构建时带有ICU，并且ICU提供了具有给定名称的转换器，则此类名称可能仍被QStringConverter的构造函数接受。
name预期为UTF-8编码。
[noexcept] bool QStringConverter::hasError() const
如果转换无法正确转换字符，则返回 true。例如，可能由无效的 UTF-8 序列或由于目标编码的限制而无法转换字符时触发。
[noexcept] bool QStringConverter::isValid() const
如果这是一个有效的字符串转换器，可用于编码或解码文本，则返回 true。
默认构造的字符串转换器或使用不受支持的名称构造的转换器无效。
[noexcept] const char *QStringConverter::name() const
返回该 QStringConverter 可编码或解码的编码的规范名称。如果转换器无效，则返回 nullptr。返回的名称是 UTF-8 编码的。
另见 isValid()。
[static] const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e)
返回 e 的规范编码名称。
[noexcept] void QStringConverter::resetState()
重置转换器的内部状态，清除可能的错误或不完整的转换。
© 2024 Qt 公司有限公司。此处包含的文档贡献归其各自所有者所有。提供的文档受自由软件基金会发布的 GNU 自由文档许可证版本 1.3 的条款约束。Qt 和相关商标是芬兰及全球其他国家的 Qt 公司的商标。所有其他商标均为其各自所有者的财产。
