Класс 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, объединённых по оператору OR.

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

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

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

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

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

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

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

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

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

[static] QTextCodec *QTextCodec::codecForLocale()

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

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

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

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

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

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

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

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

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

[pure virtual protected] QByteArray QTextCodec::convertFromUnicode(const QChar *input, int number, 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, 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(const QChar *input, int number, ConverterState *state = Q_NULLPTR) const

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

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

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

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

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

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

QTextEncoder *QTextCodec::makeEncoder(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 равен null-указателю, кодек сбрасывается до значения по умолчанию.

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

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

См. также 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, ConverterState *state = Q_NULLPTR) const

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

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