Класс QTextCodec

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

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

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

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

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

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

Общие типы

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

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

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

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

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 до 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);

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

Подход, который необходимо использовать в этих ситуациях, заключается в создании объекта 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.

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

[alias] QTextCodec::ConversionFlags

[alias] QTextCodec::ConverterState

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

[protected] QTextCodec::QTextCodec()

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

[virtual protected] QTextCodec::~QTextCodec()

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

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

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

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

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

[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 содержит строку, проверяемую на возможность кодирования.

[since 5.10] 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.

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

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

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

Пытается определить кодировку предоставленного фрагмента HTML в заданном массиве байтов ba, проверив BOM (метку порядка байтов) и заголовок метатега content-type, и возвращает экземпляр 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.

См. также 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 из Unicode в кодировку подкласса и возвращает результат в QByteArray.

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

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

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

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

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

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

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

[since 5.10] 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.

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

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

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

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

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

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

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

[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.

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