En esta página

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:

QStringDecoder y QStringEncoder

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

ConstanteValorDescripción
QStringConverter::Utf80Crear un conversor hacia o desde UTF-8
QStringConverter::Utf161Crea 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::Utf16BE3Crear un convertidor a o desde UTF-16 «big-endian».
QStringConverter::Utf16LE2Crear un conversor hacia o desde UTF-16 «little-endian».
QStringConverter::Utf324Crea 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::Utf32BE6Crea un convertidor hacia o desde UTF-32 «big-endian».
QStringConverter::Utf32LE5Crea un convertidor hacia o desde UTF-32 «little-endian».
QStringConverter::Latin17Crea un conversor hacia o desde ISO-8859-1 (Latin1).
QStringConverter::System8Crea 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

ConstanteValorDescripción
QStringConverter::FinalizeResultError::NoError0Sin error.
QStringConverter::FinalizeResultError::InvalidCharacters1El 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::NotEnoughSpace2La 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

ConstanteValorDescripción
QStringConverter::Flag::Default0Se aplican las reglas de conversión predeterminadas.
QStringConverter::Flag::ConvertInvalidToNull0x2Si 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::WriteBom0x4Al 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::ConvertInitialBom0x8Al 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::Stateless0x1Ignora 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.