Класс 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(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::FlagФлаги QStringConverter::Flags

Тип Flags — это тип-синоним для QFlags<Flag>. Он хранит комбинацию значений Flag, полученную с помощью операции OR.

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

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

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

Возвращаемый объект optional пустой, если кодировка неясна.

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

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

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

Возвращает необязательную кодировку для name. Объект optional пустой, если имя не удалось преобразовать в допустимую кодировку.

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()

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