QStringConverter Class
La clase QStringConverter sirve de clase base para la codificación y descodificación de texto. Más información...
| Encabezado: | #include <QStringConverter> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Heredado por: |
- Lista de todos los miembros, incluidos los heredados
- QStringConverter forma parte de las clases para datos de cadena.
Nota: Todas las funciones de esta clase son reentrantes.
Tipos públicos
(since 6.11) struct | FinalizeResultChar |
| enum | Encoding { Utf8, Utf16, Utf16BE, Utf16LE, Utf32, …, System } |
| enum class | FinalizeResultError { NoError, InvalidCharacters, NotEnoughSpace } |
| enum class | Flag { Default, ConvertInvalidToNull, WriteBom, ConvertInitialBom, Stateless } |
| flags | Flags |
Funciones públicas
| QStringConverter(QStringConverter &&) | |
| bool | hasError() const |
| bool | isValid() const |
| const char * | name() const |
| void | resetState() |
| QStringConverter & | operator=(QStringConverter &&) |
Miembros públicos estáticos
| QStringList | availableCodecs() |
| std::optional<QStringConverter::Encoding> | encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0) |
| std::optional<QStringConverter::Encoding> | encodingForHtml(QByteArrayView data) |
| std::optional<QStringConverter::Encoding> | encodingForName(QAnyStringView name) |
| const char * | nameForEncoding(QStringConverter::Encoding e) |
Funciones protegidas
Descripción detallada
Qt utiliza UTF-16 para almacenar, dibujar y manipular cadenas. En muchas situaciones, es posible que desees trabajar con datos que utilicen una codificación diferente. La mayor parte de los datos de texto transferidos a través de archivos y conexiones de red están codificados en UTF-8.
La clase `QStringConverter` es una clase base para las clases ` QStringEncoder ` y ` QStringDecoder `, que facilitan la conversión entre diferentes codificaciones de texto. ` QStringDecoder ` puede decodificar una cadena desde una representación codificada a UTF-16, el formato que utiliza Qt internamente. ` QStringEncoder ` realiza la operación inversa, codificando datos codificados en UTF-16 (normalmente en forma de ` QString`) a la codificación solicitada.
Siempre se admiten las siguientes codificaciones:
- UTF-8
- UTF-16
- UTF-16BE
- UTF-16LE
- UTF-32
- UTF-32BE
- UTF-32LE
- ISO-8859-1 (Latin-1)
- La codificación del sistema
QStringConverter puede admitir más codificaciones dependiendo de cómo se haya compilado Qt. Si se admiten más codecs, se pueden listar utilizando availableCodecs().
QStringConverterSe puede utilizar de la siguiente manera para convertir una cadena codificada a y desde UTF-16.
Supongamos que tienes una cadena codificada en UTF-8 y quieres convertirla a un ` QString`. La forma más sencilla de hacerlo es utilizar un ` QStringDecoder ` así:
QByteArray encodedString = "...";
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
QString string = toUtf16(encodedString);Tras esto, ` string ` contiene el texto en formato descodificado. Convertir una cadena de Unicode a la codificación local es igual de sencillo utilizando la clase ` QStringEncoder `:
QString string = "...";
auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);
QByteArray encodedString = fromUtf16(string);Para leer o escribir archivos de texto en diversas codificaciones, utiliza QTextStream y su función setEncoding().
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.
Tanto ` QStringEncoder ` como ` QStringDecoder ` facilitan esta tarea, ya que realizan un seguimiento de ello en un estado interno. Así pues, basta con volver a llamar al codificador o al decodificador con el siguiente fragmento de datos para que continúe automáticamente la codificación o decodificación de los datos de forma correcta:
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
QString string;
while (new_data_available() && !toUtf16.hasError()) {
QByteArray chunk = get_new_data();
string += toUtf16(chunk);
}
auto result = toUtf16.finalize();
if (result.error != QStringDecoder::FinalizeResult::Error::NoError) {
// Handle error
}El objeto QStringDecoder mantiene el estado entre fragmentos y, por lo tanto, funciona correctamente incluso si un carácter multibyte se divide entre fragmentos.
Los objetos `QStringConverter` no se pueden copiar debido a su estado interno, pero sí se pueden mover.
Véase también QTextStream, QStringDecoder y QStringEncoder.
Documentación sobre los tipos de miembros
enum QStringConverter::Encoding
| Constante | Valor | Descripción |
|---|---|---|
QStringConverter::Utf8 | 0 | Crear un conversor hacia o desde UTF-8 |
QStringConverter::Utf16 | 1 | Crea un convertidor hacia o desde UTF-16. Al decodificar, el orden de los bytes se detectará automáticamente mediante una marca de orden de bytes inicial. Si no existe ninguna o al codificar, se asumirá el orden de bytes del sistema. |
QStringConverter::Utf16BE | 3 | Crear un convertidor a o desde UTF-16 «big-endian». |
QStringConverter::Utf16LE | 2 | Crear un conversor hacia o desde UTF-16 «little-endian». |
QStringConverter::Utf32 | 4 | Crea un conversor hacia o desde UTF-32. Al decodificar, el orden de los bytes se detectará automáticamente mediante una marca de orden de bytes inicial. Si no existe ninguna o al codificar, se asumirá el orden de bytes del sistema. |
QStringConverter::Utf32BE | 6 | Crea un convertidor hacia o desde UTF-32 «big-endian». |
QStringConverter::Utf32LE | 5 | Crea un convertidor hacia o desde UTF-32 «little-endian». |
QStringConverter::Latin1 | 7 | Crea un conversor hacia o desde ISO-8859-1 (Latin1). |
QStringConverter::System | 8 | Crea un conversor hacia o desde la codificación subyacente de la configuración regional del sistema operativo. En los sistemas basados en Unix, siempre se asume que es UTF-8. En Windows, convierte hacia y desde la página de códigos de la configuración regional. |
enum class QStringConverter::FinalizeResultError
| Constante | Valor | Descripción |
|---|---|---|
QStringConverter::FinalizeResultError::NoError | 0 | Sin error. |
QStringConverter::FinalizeResultError::InvalidCharacters | 1 | El codificador ha finalizado correctamente, pero ha encontrado caracteres no válidos, ya sea durante la finalización o en algún momento anterior. |
QStringConverter::FinalizeResultError::NotEnoughSpace | 2 | La función `finalize()` no se ha ejecutado correctamente; debes ampliar el búfer y volver a llamar a `finalize()`. |
enum class QStringConverter::Flag
flags QStringConverter::Flags
| Constante | Valor | Descripción |
|---|---|---|
QStringConverter::Flag::Default | 0 | Se aplican las reglas de conversión predeterminadas. |
QStringConverter::Flag::ConvertInvalidToNull | 0x2 | Si se activa esta opción, cada carácter de entrada no válido se muestra como un carácter nulo. Si no se activa, los caracteres de entrada no válidos se representan como QChar::ReplacementCharacter si la codificación de salida puede representar ese carácter; de lo contrario, se muestran como un signo de interrogación. |
QStringConverter::Flag::WriteBom | 0x4 | Al convertir de una codificación de entrada ( QString ) a una codificación de salida, se escribe un carácter de fin de línea ( QChar::ByteOrderMark ) como primer carácter si la codificación de salida lo admite. Este es el caso de las codificaciones UTF-8, UTF-16 y UTF-32. |
QStringConverter::Flag::ConvertInitialBom | 0x8 | Al convertir de una codificación de entrada a una de e QString, el QStringDecoder suele omitir la marca de orden de bytes ( QChar::ByteOrderMark) inicial. Cuando se activa este indicador, la marca de orden de bytes no se omitirá, sino que se convertirá a UTF-16 y se insertará al principio del QString creado. |
QStringConverter::Flag::Stateless | 0x1 | Ignora los posibles estados del convertidor entre diferentes llamadas a funciones para codificar o decodificar cadenas. Esto también hará que el ` QStringConverter ` genere un error si se encuentra una secuencia de datos incompleta. |
El tipo Flags es un typedef para QFlags<Flag>. Almacena una combinación OR de valores de Flag.
Documentación de las funciones miembro
[noexcept default] QStringConverter::QStringConverter(QStringConverter &&)
Crea una instancia de ` QStringConverter` mediante la construcción «move».
[noexcept protected default] QStringConverter::~QStringConverter()
Elimina la instancia de « QStringConverter ».
[static] QStringList QStringConverter::availableCodecs()
Devuelve una lista con los nombres de los códecs compatibles. Los nombres devueltos por esta función pueden pasarse al constructor de QStringEncoder y QStringDecoder para crear un codificador o decodificador para el códec especificado.
Esta función puede utilizarse para obtener una lista de códecs adicionales, además de los estándar. La compatibilidad con códecs adicionales requiere que Qt se compile con soporte para la biblioteca ICU.
Nota: El orden de los códecs es un detalle interno de la implementación y no se garantiza que sea estable.
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0)
Devuelve la codificación del contenido de data, si es posible determinarla. Se puede pasar expectedFirstCharacter como indicación adicional para ayudar a determinar la codificación.
El objeto opcional devuelto estará vacío si la codificación no está clara.
[static] std::optional<QStringConverter::Encoding> QStringConverter::encodingForHtml(QByteArrayView data)
Intenta determinar la codificación del HTML en data analizando las marcas de orden de bytes iniciales o un especificador de juego de caracteres en la etiqueta meta HTML. Si el parámetro opcional está vacío, la codificación especificada no es compatible con QStringConverter. Si no se detecta ninguna codificación, el método devuelve Utf8.
Véase también QStringDecoder::decoderForHtml().
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForName(QAnyStringView name)
Convierte ` name ` en el miembro correspondiente de ` Encoding `, si existe.
Si el ` name ` no es el nombre de un códec incluido en la enumeración `Encoding`, se devuelve ` std::nullopt `. No obstante, dicho nombre puede ser aceptado por el constructor ` QStringConverter ` cuando Qt se compila con ICU, si ICU proporciona un convertidor con el nombre dado.
Nota: En las versiones de Qt anteriores a la 6.8, esta función solo aceptaba un ` const char *`, del que se esperaba que estuviera codificado en UTF-8.
[noexcept] bool QStringConverter::hasError() const
Devuelve «true» si una conversión no ha podido convertir correctamente un carácter. Esto podría producirse, por ejemplo, debido a una secuencia UTF-8 no válida o cuando un carácter no se puede convertir debido a limitaciones en la codificación de destino.
[noexcept] bool QStringConverter::isValid() const
Devuelve «true» si se trata de un convertidor de cadenas válido que puede utilizarse para codificar o decodificar texto.
Los convertidores de cadenas creados de forma predeterminada o aquellos creados con un nombre no admitido no son válidos.
[noexcept] const char *QStringConverter::name() const
Devuelve el nombre canónico de la codificación que este QStringConverter puede codificar o decodificar. Devuelve un nullptr si el convertidor no es válido. El nombre devuelto está codificado en UTF-8.
Véase también isValid().
[static noexcept] const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e)
Devuelve el nombre canónico de la codificación e o nullptr si e es un valor no válido.
Nota: En las versiones de Qt anteriores a la 6.10, 6.9.1, 6.8.4 o 6.5.9, llamar a esta función con un argumento no válido provocaba un comportamiento indefinido. A partir de las versiones de Qt mencionadas anteriormente, devuelve nullptr en su lugar.
[noexcept] void QStringConverter::resetState()
Restablece el estado interno del convertidor, borrando posibles errores o conversiones parciales.
[noexcept default] QStringConverter &QStringConverter::operator=(QStringConverter &&)
Asigna « other » a esta instancia de « QStringConverter ».
© 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.