QStringDecoder Class
QStringDecoder 类提供了一个基于状态的文本解码器。更多内容...
| 头文件： | #include <QStringDecoder> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
| 继承自： | QStringConverter |
- 所有成员列表，包括继承的成员
- QStringDecoder 属于字符串数据类。
注意：该类中的所有函数均为可重入函数。
公共类型
公共函数
| QStringDecoder() | |
| QStringDecoder(QAnyStringView name, QStringConverter::Flags flags = Flag::Default) | |
| QStringDecoder(QStringConverter::Encoding encoding, QStringConverter::Flags flags = Flag::Default) | |
| QChar * | appendToBuffer(QChar *out, QByteArrayView in) |
(since 6.6) char16_t * | appendToBuffer(char16_t *out, QByteArrayView in) |
| QStringDecoder::EncodedData<QByteArrayView> | decode(QByteArrayView ba) |
| QStringDecoder::EncodedData<const QByteArray &> | decode(const QByteArray &ba) |
(since 6.11) QStringDecoder::FinalizeResult | finalize() |
(since 6.11) QStringDecoder::FinalizeResultQChar | finalize(QChar *out, qsizetype maxlen) |
(since 6.11) QStringDecoder::FinalizeResult | finalize(char16_t *out, qsizetype maxlen) |
| qsizetype | requiredSpace(qsizetype inputLength) const |
| QStringDecoder::EncodedData<QByteArrayView> | operator()(QByteArrayView ba) |
| QStringDecoder::EncodedData<const QByteArray &> | operator()(const QByteArray &ba) |
静态公共成员
| QStringDecoder | decoderForHtml(QByteArrayView data) |
详细说明
文本解码器将使用特定编码的编码文本格式转换为 Qt 的内部表示形式。
可通过以下代码将编码数据转换为QString ：
QByteArray encodedString = "...";
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
QString string = toUtf16(encodedString);解码器会记住调用之间所需的任何状态，因此，即使数据是分块接收的（例如通过网络接收），转换起来也同样简单——只需在有新数据时调用解码器即可：
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
QString string;
while (new_data_available() && !toUtf16.hasError()) {
QByteArray chunk = get_new_data();
string += toUtf16(chunk);
}
auto result = toUtf16.finalize();
if (result.error != QStringDecoder::FinalizeResult::Error::NoError) {
// Handle error
}QStringDecoder 对象会在数据块之间保持状态，因此即使数据块在多字节字符序列的中间被分割，也能正常工作。
由于其内部状态的原因，QStringDecoder 对象无法被复制，但可以被移动。
另请参阅 QStringConverter 和QStringEncoder 。
成员类型文档
[alias] QStringDecoder::FinalizeResult
这是QStringConverter::FinalizeResultChar<char16_t> 的别名。
[alias] QStringDecoder::FinalizeResultQChar
成员函数文档
[constexpr noexcept] QStringDecoder::QStringDecoder()
默认情况下会构建一个解码器。默认解码器无效，无法用于文本转换。
[explicit] QStringDecoder::QStringDecoder(QAnyStringView name, QStringConverter::Flags flags = Flag::Default)
使用 `name ` 和 `flags` 创建一个解码器对象。如果 `name ` 不是已知编码的名称，则会创建一个无效的转换器。
注意：在 Qt 6.8 之前的版本中，此函数仅接受一个const char * 参数，且该参数预期为 UTF-8 编码。
另请参阅 isValid()。
[explicit constexpr] QStringDecoder::QStringDecoder(QStringConverter::Encoding encoding, QStringConverter::Flags flags = Flag::Default)
使用 `encoding ` 和 `flags` 创建一个解码器对象。
QChar *QStringDecoder::appendToBuffer(QChar *out, QByteArrayView in)
对in 所处理的字节序列进行解码，并将解码结果写入从out 开始的缓冲区。返回指向已写入数据末尾的指针。
out 该缓冲区大小需足够大，以容纳所有解码后的数据。请使用requiredSpace 确定解码一个in.size() 字节的编码数据缓冲区所需的最大空间。该函数可能会写入out 与out + requiredSpace() 之间的任意字节，包括位于返回的结束指针之后的字节。
另请参阅 requiredSpace 。
[since 6.6] char16_t *QStringDecoder::appendToBuffer(char16_t *out, QByteArrayView in)
这是一个重载函数。
该函数在 Qt 6.6 中引入。
QStringDecoder::EncodedData<QByteArrayView> QStringDecoder::decode(QByteArrayView ba)
QStringDecoder::EncodedData<QByteArrayView> QStringDecoder::operator()(QByteArrayView ba)
QStringDecoder::EncodedData<const QByteArray &> QStringDecoder::decode(const QByteArray &ba)
QStringDecoder::EncodedData<const QByteArray &> QStringDecoder::operator()(const QByteArray &ba)
将ba 转换为QString ，并返回一个可隐式转换为 的结构体。
QByteArray encodedString = "...";
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
auto data = toUtf16(encodedString); // data's type is QStringDecoder::EncodedData<const QByteArray &>
QString string = toUtf16(encodedString); // Implicit conversion to QString
// Here you have to cast "data" to QString
auto func = [&]() { return !toUtf16.hasError() ? QString(data) : u"foo"_s; };[static] QStringDecoder QStringDecoder::decoderForHtml(QByteArrayView data)
尝试通过检查HTML元标签中的字节顺序标记或字符集指定符，来确定data 中HTML的编码，并返回一个与该编码匹配的QStringDecoder 。如果返回的解码器无效，则说明QStringConverter 不支持所指定的编码。如果未检测到任何编码，则该方法返回一个Utf8解码器。
另请参阅 isValid()。
[since 6.11] QStringDecoder::FinalizeResult QStringDecoder::finalize()
[since 6.11] QStringDecoder::FinalizeResultQChar QStringDecoder::finalize(QChar *out, qsizetype maxlen)
[since 6.11] QStringDecoder::FinalizeResult QStringDecoder::finalize(char16_t *out, qsizetype maxlen)
向解码器发出信号，表明不会再有数据到达。
还可能提供待解码的剩余内容数据。当没有剩余数据需要处理时，返回值的error 字段将被设置为NoError 。
如果提供了out 且其值不为空，则该字段必须留有空间，以便写入最多maxlen 个字符。最多此数量的残余输出字符将被写入该空间，其结束位置由返回值的next 字段指示。通常，这些残余数据应由每个剩余未转换输入字符对应的替换字符组成。
如果所有剩余内容已通过 `out` 传递，或者 `out ` 为 `nullptr`，或者不存在剩余数据，则在 `finalize()` 返回时解码器将被重置。否则，可以通过再次调用 `finalize()` 来检索或丢弃剩余数据。
这些函数在 Qt 6.11 中引入。
另请参阅 hasError() 和appendToBuffer()。
qsizetype QStringDecoder::requiredSpace(qsizetype inputLength) const
返回处理inputLength 编码数据所需的最大UTF-16代码单元数。
另请参阅 appendToBuffer 。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
