QTextCodec Class
La clase QTextCodec permite realizar conversiones entre codificaciones de texto. Más información...
| Encabezado: | #include <QTextCodec> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core5Compat) target_link_libraries(mytarget PRIVATE Qt6::Core5Compat) |
| qmake: | QT += core5compat |
Nota: Todas las funciones de esta clase son reentrantes.
- setCodecForLocale(QTextCodec *c)
- ~QTextCodec()
Nota: Estas funciones también son seguras para subprocesos:
- codecForName(const QByteArray &name)
- codecForMib(int mib)
- availableCodecs()
- availableMibs()
- codecForLocale()
Funciones públicas
| virtual QList<QByteArray> | aliases() const |
| bool | canEncode(QChar ch) const |
| bool | canEncode(QStringView s) const |
| bool | canEncode(const QString &s) const |
| QByteArray | fromUnicode(const QString &str) const |
| QByteArray | fromUnicode(const QChar *input, int number, int *state = nullptr) const |
| QByteArray | fromUnicode(QStringView str) const |
| QTextDecoder * | makeDecoder(int flags = DefaultConversion) const |
| QTextEncoder * | makeEncoder(int flags = DefaultConversion) const |
| virtual int | mibEnum() const = 0 |
| virtual QByteArray | name() const = 0 |
| QString | toUnicode(const QByteArray &a) const |
| QString | toUnicode(const char *input, int size, int *state = nullptr) const |
| QString | toUnicode(const char *chars) const |
Miembros públicos estáticos
| QList<QByteArray> | availableCodecs() |
| QList<int> | availableMibs() |
| QTextCodec * | codecForHtml(const QByteArray &ba, QTextCodec *defaultCodec) |
| QTextCodec * | codecForHtml(const QByteArray &ba) |
| QTextCodec * | codecForLocale() |
| QTextCodec * | codecForMib(int mib) |
| QTextCodec * | codecForName(const QByteArray &name) |
| QTextCodec * | codecForName(const char *name) |
| QTextCodec * | codecForUtfText(const QByteArray &ba, QTextCodec *defaultCodec) |
| QTextCodec * | codecForUtfText(const QByteArray &ba) |
| void | setCodecForLocale(QTextCodec *c) |
Funciones protegidas
| QTextCodec() | |
| virtual | ~QTextCodec() |
| virtual QByteArray | convertFromUnicode(const QChar *input, int number, int *state) const = 0 |
| virtual QString | convertToUnicode(const char *chars, int len, int *state) const = 0 |
Descripción detallada
Qt utiliza Unicode para almacenar, dibujar y manipular cadenas de caracteres. En muchas situaciones, es posible que desees trabajar con datos que utilicen una codificación diferente. Por ejemplo, la mayoría de los documentos japoneses siguen almacenándose en Shift-JIS o ISO 2022-JP, mientras que los usuarios rusos suelen tener sus documentos en KOI8-R o Windows-1251.
Qt proporciona un conjunto de clases QTextCodec para facilitar la conversión de formatos que no son Unicode a Unicode y viceversa. También puedes crear tus propias clases de códec.
Las codificaciones compatibles son:
- Big5
- Big5-HKSCS
- CP949
- EUC-JP
- EUC-KR
- GB18030
- HP-ROMAN8
- IBM 850
- IBM 866
- IBM 874
- ISO 2022-JP
- ISO 8859-1 a 10
- ISO 8859-13 a 16
- Iscii-Bng, Dev, Gjr, Knd, Mlm, Ori, Pnj, Tlg y 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
- De Windows-1250 a 1258
Si Qt se compila con el soporte para ICU habilitado, la mayoría de los códecs compatibles con ICU también estarán disponibles para la aplicación.
QTextCodecSe puede utilizar de la siguiente manera para convertir una cadena codificada localmente a Unicode. Supongamos que tienes una cadena codificada en ruso con la codificación KOI8-R y quieres convertirla a Unicode. La forma más sencilla de hacerlo es así:
QByteArray encodedString = "...";
QTextCodec *codec = QTextCodec::codecForName("KOI8-R");
QString string = codec->toUnicode(encodedString);Tras ello, ` string ` contendrá el texto convertido a Unicode. Convertir una cadena de Unicode a la codificación local es igual de sencillo:
QString string = "...";
QTextCodec *codec = QTextCodec::codecForName("KOI8-R");
QByteArray encodedString = codec->fromUnicode(string);Hay que tener cierto cuidado al intentar convertir los datos por fragmentos, por ejemplo, al recibirlos a través de una red. En tales casos, es posible que un carácter multibyte se divida en dos fragmentos. En el mejor de los casos, esto podría provocar la pérdida de un carácter y, en el peor, hacer que toda la conversión falle.
El enfoque que hay que seguir en estas situaciones es crear un objeto ` QTextDecoder ` para el códec y utilizar este ` QTextDecoder ` durante todo el proceso de decodificación, tal y como se muestra a continuación:
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;El objeto ` QTextDecoder ` mantiene el estado entre fragmentos y, por lo tanto, funciona correctamente incluso si un carácter multibyte se divide entre fragmentos.
Creación de tu propia clase de códec
Se puede añadir compatibilidad con nuevas codificaciones de texto a Qt creando subclases de QTextCodec.
Las funciones virtuales puras describen el codificador al sistema, y el codificador se utiliza según sea necesario en los diferentes formatos de archivo de texto compatibles con QTextStream, así como en X11, para la entrada y salida de caracteres específicos de la configuración regional.
Para añadir compatibilidad con otra codificación a Qt, crea una subclase de QTextCodec e implementa las funciones que se enumeran en la tabla siguiente.
| Función | Descripción |
|---|---|
| name() | Devuelve el nombre oficial de la codificación. Si la codificación figura en el fichero de codificaciones de conjuntos de caracteres de la IANA, el nombre debe ser el nombre MIME preferido para dicha codificación. |
| aliases() | Devuelve una lista de nombres alternativos para la codificación. QTextCodec proporciona una implementación por defecto que devuelve una lista vacía. Por ejemplo, «ISO-8859-1» tiene como alias «latin1», «CP819», «IBM819» e «iso-ir-100». |
| mibEnum() | Devuelve la enumeración MIB de la codificación si esta figura en el archivo de codificaciones de conjuntos de caracteres de la IANA. |
| convertToUnicode() | Convierte una cadena de caracteres de 8 bits a Unicode. |
| convertFromUnicode() | Convierte una cadena Unicode en una cadena de caracteres de 8 bits. |
Véase también QTextStream, QTextDecoder y QTextEncoder.
Documentación de funciones de miembro
[protected] QTextCodec::QTextCodec()
Crea un QTextCodec y le asigna la máxima prioridad. El QTextCodec siempre debe crearse en el montón (es decir, con ` new`). Qt asume la propiedad y lo eliminará cuando la aplicación finalice.
[virtual noexcept protected] QTextCodec::~QTextCodec()
Elimina el objeto ` QTextCodec`. Ten en cuenta que no debes eliminar los códecs tú mismo: una vez creados, pasan a ser responsabilidad de Qt.
Advertencia: esta función no es reentrante.
[virtual] QList<QByteArray> QTextCodec::aliases() const
Las subclases pueden devolver varios alias para el códec en cuestión.
Los alias estándar de los códecs se pueden encontrar en el archivo de codificación de conjuntos de caracteres de la IANA.
[static] QList<QByteArray> QTextCodec::availableCodecs()
Devuelve la lista de todos los códecs disponibles, ordenados por nombre. Llama a QTextCodec::codecForName() para obtener el QTextCodec correspondiente al nombre.
La lista puede contener varias entradas del mismo códec si este tiene alias.
Nota: Esta función es segura para subprocesos.
Véanse también availableMibs(), name() y aliases().
[static] QList<int> QTextCodec::availableMibs()
Devuelve la lista de MIB de todos los códecs disponibles. Llama a QTextCodec::codecForMib() para obtener el QTextCodec de la MIB.
Nota: Esta función es segura para subprocesos.
Véanse también availableCodecs() y mibEnum().
bool QTextCodec::canEncode(QChar ch) const
Devuelve ` true ` si el carácter Unicode ` ch ` puede codificarse por completo con este códec; en caso contrario, devuelve ` false`.
bool QTextCodec::canEncode(QStringView s) const
Devuelve « true » si la cadena Unicode « s » se puede codificar íntegramente con este códec; en caso contrario, devuelve « false ».
Nota: si el tamaño de la entrada supera INT_MAX, esta función no realiza ninguna comprobación y devuelve false.
Esta es una función sobrecargada.
bool QTextCodec::canEncode(const QString &s) const
s contiene la cadena cuya capacidad de codificación se va a comprobar.
Nota: si el tamaño de la entrada supera INT_MAX, esta función no realiza ninguna comprobación y devuelve false.
Se trata de una función sobrecargada.
[static] QTextCodec *QTextCodec::codecForHtml(const QByteArray &ba, QTextCodec *defaultCodec)
Intenta detectar la codificación del fragmento de HTML proporcionado en la matriz de bytes dada, ba, comprobando la marca de orden de bytes (BOM) y el metaencabezado «content-type», y devuelve una instancia de QTextCodec capaz de decodificar el HTML a Unicode. Si no se puede detectar el códec a partir del contenido proporcionado, se devuelve defaultCodec.
Véase también codecForUtfText().
[static] QTextCodec *QTextCodec::codecForHtml(const QByteArray &ba)
Intenta detectar la codificación del fragmento de HTML proporcionado en la matriz de bytes dada, ba, comprobando la marca de orden de bytes (BOM) y el metaencabezado «content-type», y devuelve una instancia de QTextCodec capaz de decodificar el HTML a Unicode. Si no se puede detectar el códec, esta sobrecarga devuelve un objeto de tipo Latin-1 QTextCodec.
Esta es una función sobrecargada.
[static] QTextCodec *QTextCodec::codecForLocale()
Devuelve un puntero al códec más adecuado para esta configuración regional.
El códec se obtendrá de ICU cuando se utilice ese backend; en caso contrario, se obtendrá a través de una API específica del sistema operativo. En este último caso, el nombre del códec puede ser «System».
Nota: Esta función es segura para subprocesos.
Véase también setCodecForLocale().
[static] QTextCodec *QTextCodec::codecForMib(int mib)
Devuelve el objeto ` QTextCodec ` que coincide con el objeto ` MIBenum ` mib.
Nota: Esta función es segura para subprocesos.
[static] QTextCodec *QTextCodec::codecForName(const QByteArray &name)
Busca entre todos los objetos « QTextCodec » instalados y devuelve el que mejor se ajuste a « name »; la coincidencia no distingue entre mayúsculas y minúsculas. Devuelve « nullptr » si no se ha encontrado ningún códec que coincida con el nombre « name ».
Nota: Esta función es segura para subprocesos.
[static] QTextCodec *QTextCodec::codecForName(const char *name)
Busca entre todos los objetos « QTextCodec » instalados y devuelve el que mejor se ajusta a « name »; la coincidencia no distingue entre mayúsculas y minúsculas. Devuelve « nullptr » si no se ha encontrado ningún códec que coincida con el nombre « name ».
[static] QTextCodec *QTextCodec::codecForUtfText(const QByteArray &ba, QTextCodec *defaultCodec)
Intenta detectar la codificación del fragmento de código proporcionado ba utilizando el BOM (Byte Order Mark) y devuelve una instancia de ` QTextCodec ` capaz de decodificar el texto a Unicode. Esta función puede detectar uno de los siguientes códecs:
- UTF-32 Little Endian
- UTF-32 Big Endian
- UTF-16 Little Endian
- UTF-16 Big Endian
- UTF-8
Si no se puede detectar el códec a partir del contenido proporcionado, se devuelve « defaultCodec ».
Véase también codecForHtml().
[static] QTextCodec *QTextCodec::codecForUtfText(const QByteArray &ba)
Intenta detectar la codificación del fragmento de código proporcionado ba utilizando la marca de orden de bytes (BOM) y devuelve una instancia de ` QTextCodec ` capaz de decodificar el texto a Unicode. Esta función puede detectar uno de los siguientes códecs:
- UTF-32 Little Endian
- UTF-32 Big Endian
- UTF-16 Little Endian
- UTF-16 Big Endian
- UTF-8
Si no se puede detectar el códec a partir del contenido proporcionado, esta sobrecarga devuelve un « QTextCodec » en Latin-1.
Esta es una función sobrecargada.
Véase también codecForHtml().
[pure virtual protected] QByteArray QTextCodec::convertFromUnicode(const QChar *input, int number, int *state) const
QTextCodec Las subclases deben reimplementar esta función.
Convierte los primeros number de caracteres de la matriz input de Unicode a la codificación de la subclase, y devuelve el resultado en un QByteArray.
state Puede ser ` nullptr `, en cuyo caso la conversión no tiene estado y deben utilizarse las reglas de conversión predeterminadas. Si ` state ` no es ` nullptr`, el códec debe guardar el estado tras la conversión en ` state` y ajustar los miembros ` remainingChars ` y ` invalidChars ` de la estructura.
[pure virtual protected] QString QTextCodec::convertToUnicode(const char *chars, int len, int *state) const
QTextCodec Las subclases deben reimplementar esta función.
Convierte los primeros len caracteres de chars de la codificación de la subclase a Unicode, y devuelve el resultado en un QString.
state Puede ser ` nullptr`, en cuyo caso la conversión es sin estado y deben utilizarse las reglas de conversión predeterminadas. Si ` state ` no es ` nullptr`, el códec debe guardar el estado tras la conversión en ` state` y ajustar los miembros ` remainingChars ` y ` invalidChars ` de la estructura.
QByteArray QTextCodec::fromUnicode(const QString &str) const
Convierte ` str ` de Unicode a la codificación de este códec y devuelve el resultado en un ` QByteArray`.
Nota: si la entrada supera el tamaño de « INT_MAX », esta función no realiza ninguna conversión y devuelve un objeto « QByteArray » vacío. Para entradas más largas, implementa la división en fragmentos en el lado de la llamada, utilizando la sobrecarga que toma «ConverterState».
QByteArray QTextCodec::fromUnicode(const QChar *input, int number, int *state = nullptr) const
Convierte los primeros number de caracteres de la matriz input de Unicode a la codificación de este códec, y devuelve el resultado en un QByteArray.
Se actualiza el state del convertidor utilizado.
QByteArray QTextCodec::fromUnicode(QStringView str) const
Convierte str de Unicode a la codificación de este códec y devuelve el resultado en un QByteArray.
Nota: si la entrada supera los ` INT_MAX`, esta función no realiza ninguna conversión y devuelve un ` QByteArray` vacío. Para entradas más largas, implementa el fragmentado en el lado de la llamada, utilizando la sobrecarga que toma `ConverterState`.
Esta es una función sobrecargada.
QTextDecoder *QTextCodec::makeDecoder(int flags = DefaultConversion) const
Crea un objeto ` QTextDecoder ` con un ` flags ` especificado para decodificar fragmentos de datos ` char * ` y generar fragmentos de datos Unicode.
El autor de la llamada es responsable de eliminar el objeto devuelto.
QTextEncoder *QTextCodec::makeEncoder(int flags = DefaultConversion) const
Crea un objeto ` QTextEncoder ` con un ` flags ` especificado para codificar fragmentos de datos Unicode como datos ` char * `.
El usuario que realiza la llamada es responsable de eliminar el objeto devuelto.
[pure virtual] int QTextCodec::mibEnum() const
Las subclases de ` QTextCodec ` deben reimplementar esta función. Devuelve el `MIBenum` (véase el archivo de codificación de conjuntos de caracteres de la IANA para obtener más información). Es importante que cada subclase de ` QTextCodec ` devuelva el valor único correcto para esta función.
[pure virtual] QByteArray QTextCodec::name() const
QTextCodec Las subclases deben reimplementar esta función. Devuelve el nombre de la codificación compatible con la subclase.
Si el códec está registrado como un juego de caracteres en el archivo de codificación de juegos de caracteres de la IANA, este método debe devolver el nombre MIME preferido para el códec, si está definido; de lo contrario, debe devolver su nombre.
[static] void QTextCodec::setCodecForLocale(QTextCodec *c)
Establece el códec en « c »; este valor es el que devuelve la función « codecForLocale()». Si « c » es « nullptr », el códec se restablece a su valor por defecto.
Esto puede ser necesario para algunas aplicaciones que deseen utilizar su propio mecanismo para configurar la configuración regional.
Advertencia: Esta función no es reentrante.
Véase también codecForLocale().
QString QTextCodec::toUnicode(const QByteArray &a) const
Convierte ` a ` de la codificación de este códec a Unicode y devuelve el resultado en un ` QString`.
Nota: si la entrada supera INT_MAX, esta función no realiza ninguna conversión y devuelve un QString vacío. Para entradas más largas, implementa la división en fragmentos en el lado de la llamada, utilizando la sobrecarga que toma ConverterState.
QString QTextCodec::toUnicode(const char *input, int size, int *state = nullptr) const
Convierte los primeros size caracteres de la cadena input de la codificación de este códec a Unicode, y devuelve el resultado en un objeto QString.
Se actualiza el state del convertidor utilizado.
QString QTextCodec::toUnicode(const char *chars) const
chars contiene los caracteres de origen.
Nota: si la entrada supera INT_MAX, esta función no realiza ninguna conversión y devuelve un QString vacío. Para entradas más largas, implementa el fragmentado en el lado de la llamada, utilizando la sobrecarga que toma ConverterState.
Esta es una función sobrecargada.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.