Класс QTextCodec

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

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

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

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

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

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

Типы

Общедоступные функции

Статические общедоступные члены

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

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

Класс 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 и 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 IANA character-sets encoding file.

[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 (метку порядка байтов) и заголовок мета-типа содержимого, и возвращает экземпляр QTextCodec, способный декодировать HTML в Unicode. Если кодек не может быть определён из предоставленного содержимого, возвращается defaultCodec.

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

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

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

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

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

[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. Эта функция может определить один из следующих кодеков:

• UTF-32 Little Endian
• UTF-32 Big Endian
• UTF-16 Little Endian
• UTF-16 Big Endian
• UTF-8

Если кодек не может быть определён из предоставленного содержимого, возвращается defaultCodec.

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

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

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

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

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

• UTF-32 Little Endian
• UTF-32 Big Endian
• UTF-16 Little Endian
• UTF-16 Big Endian
• UTF-8

Если кодек не может быть определён из предоставленного содержимого, этот перегруз возвращает Latin-1 QTextCodec.

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

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

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

Преобразует первые number символов из массива input из Юникода в кодировку подкласса и возвращает результат в 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 из кодировки подкласса в Юникод и возвращает результат в QString.

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

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

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

QByteArray QTextCodec::fromUnicode(QStringView str) const

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

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

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

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

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

Состояние конвертера state обновляется.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Состояние конвертера state обновляется.