QCborStreamWriter Class

Documentación de Funciones Miembro

[explicit] QCborStreamWriter::QCborStreamWriter(QByteArray *data)

Crea un objeto QCborStreamWriter que agregará el flujo a data. Todo el flujo se realiza inmediatamente a la matriz de bytes, sin necesidad de vaciar ningún búfer.

El siguiente ejemplo escribe un número en una matriz de bytes y luego lo devuelve.

QByteArray encodedNumber(qint64 value)
{
    QByteArray ba;
    QCborStreamWriter writer(&ba);
    writer.append(value);
    return ba;
}

QCborStreamWriter no se apropia de data.

[explicit] QCborStreamWriter::QCborStreamWriter(QIODevice *device)

Crea un objeto QCborStreamWriter que escribirá el flujo en device. El dispositivo debe estar abierto antes de realizar la primera llamada a append() . Este constructor puede utilizarse con cualquier clase que derive de QIODevice, como QFile, QProcess o QTcpSocket.

QCborStreamWriter no tiene buffering, por lo que cada llamada a append() resultará en una o más llamadas al método write() del dispositivo.

El siguiente ejemplo escribe un mapa vacío en un archivo:

QFile f("output");
QCborStreamWriter writer(&f);
writer.startMap(0);
writer.endMap();

QCborStreamWriter no se apropia de device.

Véase también device() y setDevice().

[noexcept] QCborStreamWriter::~QCborStreamWriter()

Destruye este objeto QCborStreamWriter y libera los recursos asociados.

QCborStreamWriter no realiza una comprobación de errores para ver si todos los elementos requeridos se escribieron en el flujo antes de que el objeto fuera destruido. Es responsabilidad del programador asegurarse de que así se hizo.

void QCborStreamWriter::append(QCborKnownTags tag)

Añade la etiqueta CBOR tag al flujo, creando un valor de etiqueta CBOR. Todas las etiquetas deben ir seguidas de otro tipo al que den significado.

En el siguiente ejemplo, añadimos una etiqueta CBOR 1 (Unix time_t) y un número entero que representa la hora actual al flujo, obtenido mediante la función time():

void writeCurrentTime(QCborStreamWriter &writer)
{
    writer.append(QCborKnownTags::UnixTime_t);
    writer.append(qint64(time(nullptr)));
}

Véase también QCborStreamReader::isTag() y QCborStreamReader::toTag().

void QCborStreamWriter::append(QCborNegativeInteger n)

Añade el valor negativo de 64 bits n al flujo CBOR. QCborNegativeInteger es un enum de 64 bits que contiene el valor absoluto del número negativo que queremos escribir. Si n es cero, el valor escrito será equivalente a²⁶⁴ (es decir, -18.446.744.073.709.551.616).

En el siguiente ejemplo, escribimos los valores -1, ^-232 e INT64_MIN:

writer.append(QCborNegativeInteger(1));
writer.append(QCborNegativeInteger(Q_INT64_C(4294967296)));
writer.append(QCborNegativeInteger(-quint64(std::numeric_limits<qint64>::min())));

Observe cómo esta función puede utilizarse para codificar números que no caben en un entero con signo de 64 bits de un ordenador estándar como qint64. Es decir, si n es mayor que std::numeric_limits<qint64>::max() o es 0, esto representará un número negativo menor que std::numeric_limits<qint64>::min().

Véase también QCborStreamReader::isNegativeInteger() y QCborStreamReader::toNegativeInteger().

void QCborStreamWriter::append(QCborSimpleType st)

Añade el tipo simple CBOR st al flujo, creando un valor de tipo simple CBOR. En el siguiente ejemplo, escribimos el tipo simple para Null así como para el tipo 32, para el que Qt no tiene soporte.

writer.append(QCborSimpleType::Null);
writer.append(QCborSimpleType(32));

Véase también QCborStreamReader::isSimpleType() y QCborStreamReader::toSimpleType().

void QCborStreamWriter::append(QCborTag tag)

Añade la etiqueta CBOR tag al flujo, creando un valor de etiqueta CBOR. Todas las etiquetas deben ir seguidas de otro tipo al que den significado.

En el siguiente ejemplo, añadimos una etiqueta CBOR 36 (expresión regular) y un patrón QRegularExpression's al flujo:

void writeRxPattern(QCborStreamWriter &writer, const QRegularExpression &rx)
{
    writer.append(QCborTag(36));
    writer.append(rx.pattern());
}

Véase también QCborStreamReader::isTag() y QCborStreamReader::toTag().

void QCborStreamWriter::append(QLatin1StringView str)

Añade la cadena Latin-1 visualizada por str al flujo, creando un valor de cadena de texto CBOR. QCborStreamWriter intentará escribir la cadena completa en un trozo.

El siguiente ejemplo añade una simple cadena literal Latin-1 al flujo:

using namespace Qt::StringLiterals;
// ...
writer.append("Hello, World"_L1);

Nota de rendimiento: CBOR requiere que todas las cadenas de texto estén codificadas en UTF-8, por lo que esta función iterará sobre los caracteres de la cadena para determinar si el contenido es US-ASCII o no. Si se encuentra que la cadena contiene caracteres fuera de US-ASCII, asignará memoria y convertirá a UTF-8. Si esta comprobación es innecesaria, utilice appendTextString() en su lugar o la sobrecarga que toma QUtf8StringView.

Véase también QCborStreamReader::isString() y QCborStreamReader::readString().

void QCborStreamWriter::append(QStringView str)

Añade la cadena de texto str al flujo, creando un valor de cadena de texto CBOR. QCborStreamWriter intentará escribir toda la cadena en un trozo.

El siguiente ejemplo escribe un QString arbitrario al flujo:

void writeString(QCborStreamWriter &writer, const QString &str)
{
    writer.append(str);
}

Véase también QCborStreamReader::isString() y QCborStreamReader::readString().

[since 6.10] void QCborStreamWriter::append(QUtf8StringView str)

Añade la cadena UTF-8 visualizada por str al flujo, creando un valor de cadena de texto CBOR. QCborStreamWriter intentará escribir toda la cadena en un trozo.

Esta función se introdujo en Qt 6.10.

Véase también appendTextString(), QCborStreamReader::isString(), y QCborStreamReader::readString().

void QCborStreamWriter::append(bool b)

Añade el valor booleano b al flujo, creando un valor CBOR Falso o un valor CBOR Verdadero. Esta función es equivalente a (e implementada como):

writer.append(b ? QCborSimpleType::True : QCborSimpleType::False);

Véase también appendNull(), appendUndefined(), QCborStreamReader::isBool() y QCborStreamReader::toBool().

Añade la matriz de bytes ba al flujo, creando un valor de cadena de bytes CBOR. QCborStreamWriter intentará escribir toda la cadena en un trozo.

El siguiente ejemplo cargará y agregará el contenido de un archivo al flujo:

void writeFile(QCborStreamWriter &writer, const QString &fileName)
{
    QFile f(fileName);
    if (f.open(QIODevice::ReadOnly))
        writer.append(f.readAll());
}

Como muestra el ejemplo, a diferencia de JSON, CBOR no requiere escapes para el contenido binario.

Véase también appendByteString(), QCborStreamReader::isByteArray(), y QCborStreamReader::readByteArray().

void QCborStreamWriter::append(double d)

Añade el número de coma flotante d al flujo, creando un valor CBOR de 64 bits en coma flotante de doble precisión. QCborStreamWriter siempre añade el número tal cual, sin realizar ninguna comprobación sobre si el número es la forma canónica para NaN, un infinito, si es denormal o si podría escribirse con un formato más corto.

El siguiente código realiza todas esas comprobaciones, excepto la de denormal, que se espera que sea tenida en cuenta por la FPU del sistema o la emulación de coma flotante directamente.

void writeDouble(QCborStreamWriter &writer, double d)
{
    float f;
    if (qIsNaN(d)) {
        writer.append(qfloat16(qQNaN()));
    } else if (qIsInf(d)) {
        writer.append(d < 0 ? -qInf() : qInf());
    } else if ((f = d) == d) {
        qfloat16 f16 = qfloat16(f);
        if (f16 == f)
            writer.append(f16);
        else
            writer.append(f);
    } else {
        writer.append(d);
    }
}

Determinar si un doble puede ser convertido a una integral sin pérdida de precisión se deja como ejercicio al lector.

Véase también QCborStreamReader::isDouble() y QCborStreamReader::toDouble().

void QCborStreamWriter::append(float f)

Añade el número de coma flotante f al flujo, creando un valor CBOR de 32 bits de coma flotante de precisión única. El siguiente código se puede utilizar para convertir un C++ double a float si no hay pérdida de precisión y anexarlo, o en su lugar anexar el double.

void writeFloat(QCborStreamWriter &writer, double d)
{
    float f = d;
    if (qIsNaN(d) || d == f)
        writer.append(f);
    else
        writer.append(d);
}

Véase también QCborStreamReader::isFloat() y QCborStreamReader::toFloat().

void QCborStreamWriter::append(qfloat16 f)

Añade el número de coma flotante f al flujo, creando un valor CBOR de 16 bits de media precisión en coma flotante. El siguiente código se puede utilizar para convertir un C++ float a qfloat16 si no hay pérdida de precisión y anexarlo, o en su lugar anexar el float.

void writeFloat(QCborStreamWriter &writer, float f)
{
    qfloat16 f16 = qfloat16(f);
    if (qIsNaN(f) || f16 == f)
        writer.append(f16);
    else
        writer.append(f);
}

Véase también QCborStreamReader::isFloat16() y QCborStreamReader::toFloat16().

void QCborStreamWriter::append(qint64 i)

Añade el valor con signo de 64 bits i al flujo CBOR. Esto creará un valor CBOR Unsigned Integer o CBOR NegativeInteger basado en el signo del parámetro. En el siguiente ejemplo, escribimos los valores 0, -1,²³² y INT64_MAX:

writer.append(0);
writer.append(-1);
writer.append(Q_INT64_C(4294967296));
writer.append(std::numeric_limits<qint64>::max());

Véase también QCborStreamReader::isInteger() y QCborStreamReader::toInteger().

void QCborStreamWriter::append(quint64 u)

Añade el valor sin signo de 64 bits u al flujo CBOR, creando un valor entero sin signo CBOR. En el siguiente ejemplo, escribimos los valores 0,²³² y UINT64_MAX:

writer.append(0U);
writer.append(Q_UINT64_C(4294967296));
writer.append(std::numeric_limits<quint64>::max());

Véase también QCborStreamReader::isUnsignedInteger() y QCborStreamReader::toUnsignedInteger().

void QCborStreamWriter::append(std::nullptr_t)

Añade un valor CBOR Null al flujo. Esta función es equivalente a (e implementada como): El parámetro es ignorado.

writer.append(QCborSimpleType::Null);

Ver también appendNull(), append(QCborSimpleType), y QCborStreamReader::isNull().

void QCborStreamWriter::append(const char *str, qsizetype size = -1)

Añade size bytes de texto a partir de str al flujo, creando un valor de cadena de texto CBOR. QCborStreamWriter intentará escribir toda la cadena en un trozo. Si size es -1, esta función escribirá strlen(\a str) bytes.

Se espera que la cadena apuntada por str esté codificada correctamente en UTF-8. QCborStreamWriter no realiza ninguna validación de que este sea el caso.

Ver también append(QLatin1StringView), append(QStringView), QCborStreamReader::isString(), y QCborStreamReader::readString().

void QCborStreamWriter::appendByteString(const char *data, qsizetype len)

Añade len bytes de datos a partir de data al flujo, creando un valor de cadena de bytes CBOR. QCborStreamWriter intentará escribir toda la cadena en un trozo.

Véase también append(), appendTextString(), QCborStreamReader::isByteArray() y QCborStreamReader::readByteArray().

void QCborStreamWriter::appendNull()

Añade un valor CBOR Null al flujo. Esta función es equivalente a (e implementada como):

writer.append(QCborSimpleType::Null);

Ver también append(std::nullptr_t), append(QCborSimpleType), y QCborStreamReader::isNull().

void QCborStreamWriter::appendTextString(const char *utf8, qsizetype len)

Añade len bytes de texto a partir de utf8 al flujo, creando un valor de cadena de texto CBOR. QCborStreamWriter intentará escribir toda la cadena en un trozo.

Se espera que la cadena apuntada por utf8 esté codificada correctamente en UTF-8. QCborStreamWriter no realiza ninguna validación de que este sea el caso.

Ver también append(QLatin1StringView), append(QStringView), QCborStreamReader::isString(), y QCborStreamReader::readString().

void QCborStreamWriter::appendUndefined()

Añade un valor CBOR Undefined al flujo. Esta función es equivalente a (e implementada como):

writer.append(QCborSimpleType::Undefined);

Véase también append(QCborSimpleType) y QCborStreamReader::isUndefined().

QIODevice *QCborStreamWriter::device() const

Devuelve el QIODevice en el que este objeto QCborStreamWriter está escribiendo. El dispositivo debe haber sido establecido previamente con el constructor o con setDevice().

Si este objeto fue creado escribiendo en un QByteArray, esta función devolverá una instancia interna de QBuffer, que es propiedad de QCborStreamWriter.

Véase también setDevice().

bool QCborStreamWriter::endArray()

Termina el array iniciado por cualquiera de las sobrecargas de startArray() y devuelve true si se ha añadido el número correcto de elementos al array. Esta función debe ser llamada por cada startArray() utilizado.

Un retorno de false indica un error en la aplicación y un error irrecuperable en este flujo. QCborStreamWriter también escribe una advertencia usando qWarning() si esto ocurre.

Llamar a esta función cuando el contenedor actual no es un array también es un error, aunque QCborStreamWriter no puede detectar actualmente esta condición.

Véase también startArray(), startArray(quint64), y endMap().

bool QCborStreamWriter::endMap()

Termina el mapa iniciado por cualquiera de las sobrecargas de startMap() y devuelve true si se ha añadido el número correcto de elementos al array. Esta función debe ser llamada por cada startMap() utilizado.

Un retorno de false indica error en la aplicación y un error irrecuperable en este flujo. QCborStreamWriter también escribe una advertencia usando qWarning() si esto ocurre.

Llamar a esta función cuando el contenedor actual no es un mapa también es un error, aunque QCborStreamWriter no puede detectar actualmente esta condición.

Véase también startMap(), startMap(quint64), y endArray().

void QCborStreamWriter::setDevice(QIODevice *device)

Reemplaza el dispositivo o matriz de bytes en el que este objeto QCborStreamWriter está escribiendo con device.

Véase también device().

void QCborStreamWriter::startArray()

Inicia una matriz CBOR de longitud indeterminada en el flujo CBOR. Cada llamada a startArray() debe ir emparejada con una llamada a endArray() y el elemento CBOR actual se extiende hasta el final de la matriz.

La matriz creada por esta función no tiene una longitud explícita. Su longitud está implícita en los elementos que contiene. Tenga en cuenta, sin embargo, que el uso de matrices de longitud indeterminada no es compatible con la codificación CBOR canónica.

El siguiente ejemplo añade elementos de la lista de cadenas pasada como entrada:

void appendList(QCborStreamWriter &writer, const QList<QString> &values)
{
    writer.startArray();
    for (const QString &s : values)
        writer.append(s);
    writer.endArray();
}

Véase también startArray(quint64), endArray(), startMap(), QCborStreamReader::isArray() y QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startArray(quint64 count)

Inicia una matriz CBOR con una longitud explícita de count elementos en el flujo CBOR. Cada llamada a startArray debe ir emparejada con una llamada a endArray() y el elemento CBOR actual se extiende hasta el final del array.

La matriz creada por esta función tiene una longitud explícita y, por lo tanto, deben añadirse exactamente count elementos al flujo CBOR. Si se añaden menos o más elementos se producirá un fallo durante endArray() y el flujo CBOR se corromperá. Sin embargo, las matrices de longitud explícita son necesarias para la codificación CBOR canónica.

El siguiente ejemplo añade todas las cadenas encontradas en QStringList pasadas como entrada:

void appendList(QCborStreamWriter &writer, const QStringList &list)
{
    writer.startArray(list.size());
    for (const QString &s : list)
        writer.append(s);
    writer.endArray();
}

Limitaciones de tamaño: El parámetro de esta función es quint64, lo que parece permitir hasta^264-1 elementos en la matriz. Sin embargo, tanto QCborStreamWriter como QCborStreamReader están actualmente limitados a^232-2 elementos en sistemas de 32 bits y a^264-2 elementos en los de 64 bits. Observe también que QCborArray está limitado actualmente a²²⁷ elementos en plataformas de 32 bits y a²⁵⁹ elementos en las de 64 bits.

Véase también startArray(), endArray(), startMap(), QCborStreamReader::isArray() y QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startMap()

Inicia un mapa CBOR de longitud indeterminada en el flujo CBOR. Cada llamada a startMap() debe ir emparejada con una llamada a endMap() y el elemento CBOR actual se extiende hasta el final del mapa.

El mapa creado por esta función no tiene una longitud explícita. Su longitud está implícita en los elementos que contiene. Tenga en cuenta, sin embargo, que el uso de mapas de longitud indeterminada no es compatible con la codificación CBOR canónica (la codificación canónica también requiere que las claves sean únicas y estén ordenadas).

El siguiente ejemplo agrega elementos de la lista de pares int y string pasados como entrada:

void appendMap(QCborStreamWriter &writer, const QList<std::pair<int, QString>> &values)
{
    writer.startMap();
    for (const auto pair : values) {
        writer.append(pair.first);
        writer.append(pair.second);
    }
    writer.endMap();
}

Véase también startMap(quint64), endMap(), startArray(), QCborStreamReader::isMap(), y QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startMap(quint64 count)

Inicia un Mapa CBOR con la longitud explícita de count elementos en el flujo CBOR. Cada llamada a startMap debe ir emparejada con una llamada a endMap() y el elemento CBOR actual se extiende hasta el final del mapa.

El mapa creado por esta función tiene una longitud explícita y, por lo tanto, deben añadirse exactamente count pares de elementos al flujo CBOR. Si se añaden menos o más elementos se producirá un fallo durante endMap() y el flujo CBOR se corromperá. Sin embargo, la codificación CBOR canónica requiere un mapa de longitud explícita.

El siguiente ejemplo añade todas las cadenas encontradas en QMap pasadas como entrada:

void appendMap(QCborStreamWriter &writer, const QMap<int, QString> &map)
{
    writer.startMap(map.size());
    for (auto it = map.cbegin(), end = map.cend(); it != end; ++it) {
        writer.append(it.key());
        writer.append(it.value());
    }
    writer.endMap();
}

Limitaciones de tamaño: El parámetro de esta función es quint64, lo que parece permitir hasta^264-1 pares en el mapa. Sin embargo, tanto QCborStreamWriter como QCborStreamReader están actualmente limitados a^231-1 elementos en sistemas de 32 bits y^263-1 elementos en los de 64 bits. Observe también que QCborMap está limitado actualmente a²²⁶ elementos en plataformas de 32 bits y a²⁵⁸ en las de 64 bits.

Véase también startMap(), endMap(), startArray(), QCborStreamReader::isMap() y QCborStreamReader::isLengthKnown().