Класс QTextCodec

Класс QTextCodec предоставляет преобразования между кодировками текста. Подробнее...

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

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

• setCodecForLocale(QTextCodec *c)
• ~QTextCodec()

Примечание: Эти функции также безопасны для потоков:

• codecForName(const QByteArray &name)
• codecForMib(int mib)
• availableCodecs()
• availableMibs()
• codecForLocale()

Типы public

Функции public

Статические члены public

Защищенные функции

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

Класс QTextCodec предоставляет преобразования между кодировками текста.

Qt использует Unicode для хранения, отображения и обработки строк. Во многих ситуациях вам может потребоваться работать с данными, использующими другую кодировку. Например, большинство японских документов по-прежнему хранятся в кодировках Shift-JIS или ISO 2022-JP, а российские пользователи часто имеют свои документы в кодировках KOI8-R или Windows-1251.

Qt предоставляет набор классов QTextCodec, чтобы помочь с преобразованием не-Unicode форматов в Unicode и обратно. Вы также можете создавать свои собственные классы кодировок.

Поддерживаемые кодировки:

• Big5
• Big5-HKSCS
• CP949
• EUC-JP
• EUC-KR
• GB18030
• HP-ROMAN8
• IBM 850
• IBM 866
• IBM 874
• ISO 2022-JP
• ISO 8859-1 to 10
• ISO 8859-13 to 16
• Iscii-Bng, Dev, Gjr, Knd, Mlm, Ori, Pnj, Tlg, and Tml
• KOI8-R
• KOI8-U
• Macintosh
• Shift-JIS
• TIS-620
• TSCII
• UTF-8
• UTF-16
• UTF-16BE
• UTF-16LE
• UTF-32
• UTF-32BE
• UTF-32LE
• Windows-1250 to 1258

Если Qt скомпилирован с поддержкой ICU, большинство кодировок, поддерживаемых ICU, также будут доступны приложению.

QTextCodec можно использовать следующим образом, чтобы преобразовать строку в локальной кодировке в Unicode. Предположим, у вас есть некоторая строка, закодированная в русской кодировке KOI8-R, и вы хотите преобразовать её в Unicode. Простой способ сделать это:

QByteArray encodedString = "...";
QTextCodec *codec = QTextCodec::codecForName("KOI8-R");
QString string = codec->toUnicode(encodedString);

После этого, string содержит текст, преобразованный в Unicode. Преобразование строки из Unicode в локальную кодировку также просто:

QString string = "...";
QTextCodec *codec = QTextCodec::codecForName("KOI8-R");
QByteArray encodedString = codec->fromUnicode(string);

Для чтения или записи файлов в различных кодировках используйте QTextStream и его функцию setCodec(). См. пример Кодировки для применения QTextCodec к вводу-выводу файлов.

Необходимо быть внимательным, когда пытаетесь преобразовать данные частями, например, при получении их через сеть. В таких случаях возможно, что многобайтовый символ будет разделен на две части. В лучшем случае это может привести к потере символа, а в худшем — к сбою всего преобразования.

В таких ситуациях подход заключается в создании объекта QTextDecoder для кодировки и использовании этого QTextDecoder для всего процесса декодирования, как показано ниже:

QTextCodec *codec = QTextCodec::codecForName("Shift-JIS");
QTextDecoder *decoder = codec->makeDecoder();

QString string;
while (new_data_available()) {
    QByteArray chunk = get_new_data();
    string += decoder->toUnicode(chunk);
}
delete decoder;

Объект QTextDecoder сохраняет состояние между частями и поэтому работает правильно, даже если многобайтовый символ разделен между частями.

Создание собственного класса кодировки

Поддержка новых кодировок текста может быть добавлена в Qt путём создания подклассов QTextCodec.

Чистые виртуальные функции описывают кодер для системы, и кодер используется по мере необходимости в различных форматах текстовых файлов, поддерживаемых QTextStream, а также под X11 для ввода и вывода символов, специфичных для локальной кодировки.

Для добавления поддержки другой кодировки в Qt создайте подкласс QTextCodec и реализуйте перечисленные ниже функции.

См. также QTextStream, QTextDecoder, QTextEncoder и Пример кодеров текста.

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

enum QTextCodec::ConversionFlagflags QTextCodec::ConversionFlags

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

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

[protected] QTextCodec::QTextCodec()

Создаёт QTextCodec с наивысшим приоритетом. QTextCodec всегда должен быть создан в куче (т.е. с new). Qt берёт на себя управление и удалит его при завершении работы приложения.

[virtual protected] QTextCodec::~QTextCodec()

Уничтожает QTextCodec. Обратите внимание, что вы не должны удалять кодеры самостоятельно: после создания они становятся ответственностью Qt.

Предупреждение: Эта функция не реентерабельна.

[virtual] QList<QByteArray> QTextCodec::aliases() const

Подклассы могут возвращать ряд псевдонимов для кодировки.

Стандартные псевдонимы для кодеров можно найти в файле кодировок IANA character-sets encoding.

[static] QList<QByteArray> QTextCodec::availableCodecs()

Возвращает список всех доступных кодеров по имени. Используйте QTextCodec::codecForName(), чтобы получить QTextCodec по имени.

Список может содержать множество упоминаний одного и того же кодера, если у кодера есть псевдонимы.

Примечание: Эта функция безопасна для потоков.

См. также availableMibs(), name() и aliases().

[static] QList<int> QTextCodec::availableMibs()

Возвращает список MIB для всех доступных кодеров. Используйте QTextCodec::codecForMib(), чтобы получить QTextCodec для MIB.

Примечание: Эта функция безопасна для потоков.

См. также availableCodecs() и mibEnum().

bool QTextCodec::canEncode(QChar ch) const

Возвращает true, если символ Unicode ch может быть полностью закодирован с помощью данного кодера; в противном случае возвращает false.

bool QTextCodec::canEncode(const QString &s) const

Это перегруженная функция.

s содержит строку, проверяемую на возможность кодирования.

bool QTextCodec::canEncode(QStringView s) const

Это перегруженная функция.

Возвращает true, если строка Unicode s может быть полностью закодирована с помощью данного кодера; в противном случае возвращает false.

Эта функция была добавлена в Qt 5.10.

[static] QTextCodec *QTextCodec::codecForHtml(const QByteArray &ba, QTextCodec *defaultCodec)

Пытается определить кодировку предоставленного фрагмента HTML в данном массиве байтов ba, проверив BOM (метку порядка байтов) и заголовок метаданных content-type, и возвращает экземпляр QTextCodec, способный декодировать HTML в Unicode. Если кодировка не может быть определена из предоставленных данных, возвращается defaultCodec.

Эта функция была добавлена в Qt 4.4.

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

[static] QTextCodec *QTextCodec::codecForHtml(const QByteArray &ba)

Это перегруженная функция.

Пытается определить кодировку предоставленного фрагмента HTML в данном массиве байтов ba, проверив BOM (метку порядка байтов) и заголовок метаданных content-type, и возвращает экземпляр QTextCodec, способный декодировать HTML в Unicode. Если кодировка не может быть определена, эта перегрузка возвращает QTextCodec Latin-1.

[static] QTextCodec *QTextCodec::codecForLocale()

Возвращает указатель на кодер, наиболее подходящий для данной локальной кодировки.

В Windows кодер будет основан на системной локальной кодировке. В системах Unix кодер может использовать библиотеку iconv, если встроенный кодер для данной локальной кодировки не найден.

Обратите внимание, что в этих случаях имя кодера будет «System».

Примечание: Эта функция безопасна для потоков.

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

[static] QTextCodec *QTextCodec::codecForMib(int mib)

Возвращает QTextCodec, соответствующий значению MIB mib.

Примечание: Эта функция безопасна для потоков.

[static] QTextCodec *QTextCodec::codecForName(const QByteArray &name)

Ищет все установленные объекты QTextCodec и возвращает тот, который лучше всего соответствует name; сопоставление нечувствительно к регистру. Возвращает 0, если не удалось найти кодер, соответствующий имени name.

Примечание: Эта функция безопасна для потоков.

[static] QTextCodec *QTextCodec::codecForName(const char *name)

Ищет все установленные объекты QTextCodec и возвращает тот, который лучше всего соответствует name; сопоставление нечувствительно к регистру. Возвращает 0, если не удалось найти кодер, соответствующий имени name.

[static] QTextCodec *QTextCodec::codecForUtfText(const QByteArray &ba, QTextCodec *defaultCodec)

Пытается определить кодировку предоставленного фрагмента ba, используя BOM (метку порядка байтов), и возвращает экземпляр QTextCodec, способный декодировать текст в Unicode. Если кодировка не может быть определена из предоставленных данных, возвращается defaultCodec.

Эта функция была добавлена в Qt 4.6.

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

[static] QTextCodec *QTextCodec::codecForUtfText(const QByteArray &ba)

Это перегруженная функция.

Пытается определить кодировку предоставленного фрагмента ba, используя BOM (Byte Order Mark), и возвращает экземпляр QTextCodec, способный декодировать текст в Unicode. Если кодек не может быть определен, этот перегруз возвращает Latin-1 QTextCodec.

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

[pure virtual protected] QByteArray QTextCodec::convertFromUnicode(const QChar *input, int number, QTextCodec::ConverterState *state) const

Подклассы QTextCodec должны переопределять эту функцию.

Преобразует первые number символов из массива input из Unicode в кодировку подкласса и возвращает результат в QByteArray.

state может быть 0, в этом случае преобразование является бессостоятельным и должны использоваться стандартные правила преобразования. Если state не равен 0, кодек должен сохранить состояние после преобразования в state и скорректировать члены структуры remainingChars и invalidChars.

[pure virtual protected] QString QTextCodec::convertToUnicode(const char *chars, int len, QTextCodec::ConverterState *state) const

Подклассы QTextCodec должны переопределять эту функцию.

Преобразует первые len символов из chars из кодировки подкласса в Unicode и возвращает результат в QString.

state может быть 0, в этом случае преобразование является бессостоятельным и должны использоваться стандартные правила преобразования. Если state не равен 0, кодек должен сохранить состояние после преобразования в state и скорректировать члены структуры remainingChars и invalidChars.

QByteArray QTextCodec::fromUnicode(const QString &str) const

Преобразует str из Unicode в кодировку этого кодека и возвращает результат в QByteArray.

QByteArray QTextCodec::fromUnicode(QStringView str) const

Это перегруженная функция.

Преобразует str из Unicode в кодировку этого кодека и возвращает результат в QByteArray.

Эта функция была добавлена в Qt 5.10.

QByteArray QTextCodec::fromUnicode(const QChar *input, int number, QTextCodec::ConverterState *state = nullptr) const

Преобразует первые number символов из массива input из Unicode в кодировку этого кодека и возвращает результат в QByteArray.

Состояние используемого преобразователя обновляется.

QTextDecoder *QTextCodec::makeDecoder(QTextCodec::ConversionFlags flags = DefaultConversion) const

Создаёт QTextDecoder со специфицированными flags для декодирования кусков char * данных для создания кусков данных Unicode.

Вызывающий объект несет ответственность за удаление возвращённого объекта.

Эта функция была добавлена в Qt 4.7.

QTextEncoder *QTextCodec::makeEncoder(QTextCodec::ConversionFlags flags = DefaultConversion) const

Создаёт QTextEncoder со специфицированными flags для кодирования кусков данных Unicode как char * данных.

Вызывающий объект несет ответственность за удаление возвращённого объекта.

Эта функция была добавлена в Qt 4.7.

[pure virtual] int QTextCodec::mibEnum() const

Подклассы QTextCodec должны переопределять эту функцию. Она возвращает MIBenum (см. файл кодировки наборов символов IANA для получения дополнительной информации). Важно, чтобы каждый подкласс QTextCodec возвращал корректное уникальное значение для этой функции.

[pure virtual] QByteArray QTextCodec::name() const

Подклассы QTextCodec должны переопределять эту функцию. Она возвращает имя кодировки, поддерживаемой подклассом.

Если кодек зарегистрирован как набор символов в файле кодировки наборов символов IANA, этот метод должен вернуть предпочтительное имя MIME для кодека, если оно определено, в противном случае — его имя.

[static] void QTextCodec::setCodecForLocale(QTextCodec *c)

Устанавливает кодек на c; это будет возвращено функцией codecForLocale(). Если c — нулевой указатель, кодек сбрасывается до значения по умолчанию.

Это может потребоваться для некоторых приложений, которые хотят использовать собственный механизм для установки локали.

Предупреждение: Эта функция не является реентерабельной.

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

QString QTextCodec::toUnicode(const QByteArray &a) const

Преобразует a из кодировки этого кодека в Unicode и возвращает результат в QString.

QString QTextCodec::toUnicode(const char *chars) const

Это перегруженная функция.

chars содержит исходные символы.

QString QTextCodec::toUnicode(const char *input, int size, QTextCodec::ConverterState *state = nullptr) const

Преобразует первые size символов из input из кодировки этого кодека в Unicode и возвращает результат в QString.

Состояние используемого преобразователя обновляется.