Класс 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

Перечисление QStringConverter::FlagФлаги QStringConverter::Flags

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

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

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

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