Класс 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 до 10
• ISO 8859-13 до 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 IANA character-sets encoding file.

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

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

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

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

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

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

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

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

См. также 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. Если кодек не может быть определён, этот перегруз возвращает кодек Latin-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

Если кодек не может быть определён из предоставленного содержимого, этот перегруз возвращает кодек 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 может быть 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.

[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 character-sets для получения дополнительной информации). Важно, чтобы каждый подкласс QTextCodec возвращал правильное уникальное значение для этой функции.

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

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

Если кодек зарегистрирован как набор символов в файле кодировок IANA character-sets, этот метод должен вернуть предпочтительное имя 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.

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