Back to Qt.io
Contact Us Blog Download Qt
在本页

QStringEncoder Class

QStringEncoder 类为文本提供了基于状态的编码器。更多

Header： #include <QStringEncoder>
CMake： find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake： QT += core
继承： QStringConverter

注意：该类中的所有函数都是可重入的。

公共类型

FinalizeResult

公共函数

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 。

成员类型文档

[alias] QStringEncoder::FinalizeResult

QStringConverter::FinalizeResultChar<char> 的别名。

成员函数文档

[constexpr noexcept] QStringEncoder::QStringEncoder()

默认构建一个编码器。默认编码器无效，不能用于转换文本。

[explicit] QStringEncoder::QStringEncoder(QAnyStringView name, QStringConverter::Flags flags = Flag::Default)

使用name 和flags 创建一个编码器对象。如果name 不是已知编码的名称，则将创建一个无效的转换器。

注意： 在 6.8 之前的 Qt XML 版本中，此函数只接受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<const QString &> QStringEncoder::encode(const QString &in)

QStringEncoder::DecodedData<QStringView> QStringEncoder::encode(QStringView in)

QStringEncoder::DecodedData<const QString &> QStringEncoder::operator()(const QString &in)

QStringEncoder::DecodedData<QStringView> QStringEncoder::operator()(QStringView 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(char *out, qsizetype maxlen)

[since 6.11] QStringEncoder::FinalizeResult QStringEncoder::finalize()

向解码器发出不再有数据到达的信号。

也可提供待解码的残余内容数据。当没有剩余数据时，返回的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.