Класс QStringConverter

Класс QStringConverter предоставляет базовый класс для кодирования и декодирования текста. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются многопоточными (реентерабельными).

Типы

Открытые функции

Статические открытые члены

Подробное описание

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 можно использовать следующим образом для преобразования закодированной строки в 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(encodedString);

Для чтения или записи текстовых файлов в различных кодировках используйте 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

enum class QStringConverter::Flagфлаги QStringConverter::Flags

Тип Flags — это typedef для QFlags<Flag>. Он хранит комбинацию значений Flag через операцию ИЛИ.

Документация по функциям-членам

[static] std::optional<Encoding> QStringConverter::encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0)

Возвращает кодировку для содержимого data, если она может быть определена. expectedFirstCharacter может передаваться в качестве дополнительной подсказки для определения кодировки.

Возвращаемое значение — пустое, если кодировка неясна.

[static] std::optional<Encoding> QStringConverter::encodingForHtml(QByteArrayView data)

Пытается определить кодировку HTML в data, просматривая ведущие байтовые порядковые метки или спецификатор кодировки в теге meta HTML. Если опциональное значение пустое, указанная кодировка не поддерживается QStringConverter. Если кодировка не обнаружена, метод возвращает Utf8.

[static] std::optional<Encoding> QStringConverter::encodingForName(const char *name)

Возвращает опциональную кодировку для name. Опциональное значение пустое, если имя не может быть преобразовано в допустимую кодировку.

bool QStringConverter::hasError() const

Возвращает true, если преобразование не смогло корректно преобразовать символ. Это может, например, произойти из-за некорректной последовательности UTF-8 или когда символ не может быть преобразован из-за ограничений целевой кодировки.

bool QStringConverter::isValid() const

Возвращает true, если это корректный преобразователь строк, который может использоваться для кодирования или декодирования текста.

Преобразователи строк, созданные по умолчанию или с недопустимым именем, не являются корректными.

const char *QStringConverter::name() const

Возвращает каноническое имя кодировки, которую этот QStringConverter может кодировать или декодировать. Возвращает nullptr, если преобразователь не корректен.

См. также isValid().

[static] const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e)

Возвращает каноническое имя для кодировки e.

void QStringConverter::resetState()

Сбрасывает внутреннее состояние преобразователя, очищая возможные ошибки или частичные преобразования.