QStringEncoder Class
QStringEncoder 类提供了一个基于状态的文本编码器。更多内容...
| 头文件： | #include <QStringEncoder> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| 继承自： | QStringConverter |
- 所有成员列表（包括继承的成员）
- QStringEncoder 属于字符串数据类。
注意：该类中的所有函数均为可重入的。
公共类型
公共函数
| QStringEncoder() | |
| QStringEncoder(QAnyStringView name, QStringConverter::Flags flags = Flag::Default) | |
| QStringEncoder(QStringConverter::Encoding encoding, QStringConverter::Flags flags = Flag::Default) | |
| char * | appendToBuffer(char *out, QStringView in) |
| QStringEncoder::DecodedData<QStringView> | encode(QStringView in) |
| QStringEncoder::DecodedData<const QString &> | encode(const QString &in) |
(since 6.11) QStringEncoder::FinalizeResult | finalize() |
(since 6.11) QStringEncoder::FinalizeResult | finalize(char *out, qsizetype maxlen) |
| qsizetype | requiredSpace(qsizetype inputLength) const |
| QStringEncoder::DecodedData<QStringView> | operator()(QStringView in) |
| QStringEncoder::DecodedData<const QString &> | operator()(const QString &in) |
详细描述
文本编码器使用特定的编码将文本从 Qt 的内部表示形式转换为编码文本格式。
可以使用以下代码将字符串从 Unicode 转换为本地编码：
QString string = "...";
auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);
QByteArray encodedString = fromUtf16(string);编码器会记住调用之间所需的任何状态，因此，对于分块接收的数据（例如通过网络接收的数据），转换同样简单，只需在有新数据时调用编码器即可：
auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);
QByteArray encoded;
while (new_data_available() && !fromUtf16.hasError()) {
QString chunk = get_new_data();
encoded += fromUtf16(chunk);
}
auto result = fromUtf16.finalize();
if (result.error != QStringEncoder::FinalizeResult::Error::NoError) {
// Handle error
}QStringEncoder 对象会在数据块之间保持状态，因此即使一个 UTF-16 代理字符被分割在多个数据块中，它也能正常工作。
由于其内部状态的原因，QStringEncoder 对象无法被复制，但可以被移动。
另请参阅 QStringConverter 和QStringDecoder 。
成员函数文档
[constexpr noexcept] QStringEncoder::QStringEncoder()
默认情况下会构建一个编码器。该默认编码器无效，无法用于文本转换。
[explicit] QStringEncoder::QStringEncoder(QAnyStringView name, QStringConverter::Flags flags = Flag::Default)
使用 `name ` 和 `flags` 创建一个编码器对象。如果 `name ` 不是已知编码的名称，则会创建一个无效的转换器。
注意：在 Qt 6.8 之前的版本中，此函数仅接受一个const char * 参数，且该参数预期为 UTF-8 编码。
另请参阅 isValid()。
[explicit constexpr] QStringEncoder::QStringEncoder(QStringConverter::Encoding encoding, QStringConverter::Flags flags = Flag::Default)
使用 `encoding ` 和 `flags` 创建一个编码器对象。
char *QStringEncoder::appendToBuffer(char *out, QStringView in)
对in 进行编码，并将编码结果写入从out 开始的缓冲区。返回指向已写入数据末尾的指针。
注意： out 必须足够大，才能容纳所有解码后的数据。请使用requiredSpace() 来确定编码in 所需的最大空间。该函数可能会向out 到out + requiredSpace() 之间的任意字节写入数据，包括位于返回的结束指针之后的部分。
另请参阅 requiredSpace()。
QStringEncoder::DecodedData<QStringView> QStringEncoder::encode(QStringView in)
QStringEncoder::DecodedData<QStringView> QStringEncoder::operator()(QStringView in)
QStringEncoder::DecodedData<const QString &> QStringEncoder::encode(const QString &in)
QStringEncoder::DecodedData<const QString &> QStringEncoder::operator()(const QString &in)
将in 转换为QByteArray ，并返回一个可隐式转换为 的结构体。
QString string = "...";
auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);
auto data = fromUtf16(string); // data's type is QStringEncoder::DecodedData<const QString &>
QByteArray encodedString = fromUtf16(string); // Implicit conversion to QByteArray
// Here you have to cast "data" to QByteArray
auto func = [&]() { return !fromUtf16.hasError() ? QByteArray(data) : "foo"_ba; };[since 6.11] QStringEncoder::FinalizeResult QStringEncoder::finalize()
[since 6.11] QStringEncoder::FinalizeResult QStringEncoder::finalize(char *out, qsizetype maxlen)
向解码器发出信号，表明不再有数据到达。
还可能提供待解码的剩余内容数据。当没有剩余数据需要处理时，返回值的error 字段将被设置为NoError 。
如果提供了out 且其值不为空，则该空间必须能够容纳最多maxlen 个字符。最多此数量的残余输出字符将写入该空间，其结尾由返回值的next 字段指示。通常，这些残余数据应由每个剩余未转换输入字符对应的替换字符组成。 当使用带状态的编码（如 ISO-2022-JP）时，此操作还可能写入字节以恢复或结束字符流中的当前状态。
如果所有剩余内容已通过 `out` 传递，或者 `out ` 的值为 `nullptr`，或者不存在剩余数据，则在从 `finalize()` 返回时，解码器将被重置。否则，可以通过再次调用 `finalize()` 来检索或丢弃剩余数据。
这些函数在 Qt 6.11 中引入。
另请参阅 hasError() 和appendToBuffer()。
qsizetype QStringEncoder::requiredSpace(qsizetype inputLength) const
返回处理inputLength 解码数据所需的最大字符数。
另请参阅 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.
