Класс QTextCodec

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

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

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

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

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

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

Типы public

Функции public

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

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

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

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

Qt предоставляет набор классов QTextCodec для помощи в преобразовании форматов, отличных от Unicode, в 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 до 1258

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

QTextCodec могут использоваться следующим образом для преобразования некоторой строки локальной кодировки в Unicode. Предположим, у вас есть некоторая строка, закодированная в кодировке Russian 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 — это typedef для QFlags<ConversionFlag>. Он хранит логическое ИЛИ комбинацию значений ConversionFlag.

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

[protected] QTextCodec::QTextCodec()

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

[virtual protected] QTextCodec::~QTextCodec()

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

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

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

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

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

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

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

Кодек будет извлечен из ICU, если этот бэкэнд используется, в противном случае он может быть получен из API, специфичного для ОС. В последнем случае имя кодека может быть «System».

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

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

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

Возвращает QTextCodec, соответствующий MIBenum 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

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

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

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

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

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

state может быть nullptr, в этом случае преобразование является бессостоятельным и используются правила преобразования по умолчанию. Если 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 может быть nullptr, в этом случае преобразование является бессостоятельным и используются правила преобразования по умолчанию. Если 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 = DefaultConversion) const

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

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

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

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

Создаёт QTextEncoder с заданными flags для кодирования блоков данных Юникода как 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 равен nullptr, кодек сбрасывается до значения по умолчанию.

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

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

См. также 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 обновляется.