\inmodule QtCore\reentrant More...

#include <qcborstreamwriter.h>

Collaboration diagram for QCborStreamWriter:

Public Member Functions
	QCborStreamWriter (QIODevice *device)
	Creates a QCborStreamWriter object that will write the stream to device.
	QCborStreamWriter (QByteArray *data)
	Creates a QCborStreamWriter object that will append the stream to data.
	~QCborStreamWriter ()
	Destroys this QCborStreamWriter object and frees any resources associated.
void	setDevice (QIODevice *device)
	Replaces the device or byte array that this QCborStreamWriter object is writing to with device.
QIODevice *	device () const
	Returns the QIODevice that this QCborStreamWriter object is writing to.
void	append (quint64 u)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the 64-bit unsigned value u to the CBOR stream, creating a CBOR Unsigned Integer value.
void	append (qint64 i)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the 64-bit signed value i to the CBOR stream.
void	append (QCborNegativeInteger n)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the 64-bit negative value n to the CBOR stream.
Q_WEAK_OVERLOAD void	append (const QByteArray &ba)
void	append (QByteArrayView ba)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the byte array ba to the stream, creating a CBOR Byte String value.
void	append (QLatin1StringView str)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the Latin-1 string viewed by str to the stream, creating a CBOR Text String value.
void	append (QStringView str)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the text string str to the stream, creating a CBOR Text String value.
void	append (QUtf8StringView str)
void	append (QCborTag tag)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the CBOR tag tag to the stream, creating a CBOR Tag value.
void	append (QCborKnownTags tag)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the CBOR tag tag to the stream, creating a CBOR Tag value.
void	append (QCborSimpleType st)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the CBOR simple type st to the stream, creating a CBOR Simple Type value.
void	append (std::nullptr_t)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends a CBOR Null value to the stream.
void	append (qfloat16 f)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the floating point number f to the stream, creating a CBOR 16-bit Half-Precision Floating Point value.
void	append (float f)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the floating point number f to the stream, creating a CBOR 32-bit Single-Precision Floating Point value.
void	append (double d)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the floating point number d to the stream, creating a CBOR 64-bit Double-Precision Floating Point value.
void	appendByteString (const char *data, qsizetype len)
	Appends len bytes of data starting from data to the stream, creating a CBOR Byte String value.
void	appendTextString (const char *utf8, qsizetype len)
	Appends len bytes of text starting from utf8 to the stream, creating a CBOR Text String value.
void	append (bool b)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the boolean value b to the stream, creating either a CBOR False value or a CBOR True value.
void	appendNull ()
	Appends a CBOR Null value to the stream.
void	appendUndefined ()
	Appends a CBOR Undefined value to the stream.
void	append (int i)
void	append (uint u)
void	append (const char *str, qsizetype size=-1)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends size bytes of text starting from str to the stream, creating a CBOR Text String value.
void	startArray ()
	Starts a CBOR Array with indeterminate length in the CBOR stream.
void	startArray (quint64 count)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Starts a CBOR Array with explicit length of count items in the CBOR stream.
bool	endArray ()
	Terminates the array started by either overload of startArray() and returns true if the correct number of elements was added to the array.
void	startMap ()
	Starts a CBOR Map with indeterminate length in the CBOR stream.
void	startMap (quint64 count)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Starts a CBOR Map with explicit length of count items in the CBOR stream.
bool	endMap ()
	Terminates the map started by either overload of startMap() and returns true if the correct number of elements was added to the array.

Detailed Description

\inmodule QtCore

\reentrant

Since: 5.12

The QCborStreamWriter class is a simple CBOR encoder operating on a one-way stream.

This class can be used to quickly encode a stream of CBOR content directly to either a QByteArray or QIODevice. CBOR is the Concise Binary Object Representation, a very compact form of binary data encoding that is compatible with JSON. It was created by the IETF Constrained RESTful Environments (CoRE) WG, which has used it in many new RFCs. It is meant to be used alongside the \l{RFC 7252}{CoAP protocol}.

QCborStreamWriter provides a StAX-like API, similar to that of \l{QXmlStreamWriter}. It is rather low-level and requires a bit of knowledge of CBOR encoding. For a simpler API, see \l{QCborValue} and especially the encoding function QCborValue::toCbor().

The typical use of QCborStreamWriter is to create the object on the target QByteArray or QIODevice, then call one of the append() overloads with the desired type to be encoded. To create arrays and maps, QCborStreamWriter provides startArray() and startMap() overloads, which must be terminated by the corresponding endArray() and endMap() functions.

The following example encodes the equivalent of this JSON content:

\div{class="pre"} { "label": "journald", "autoDetect": false, "condition": "libs.journald", "output": [ "privateFeature" ] } \enddiv

        using namespace Qt::StringLiterals;
        // ...
        writer.startMap(4);    // 4 elements in the map
 
        writer.append("label"_L1);
        writer.append("journald"_L1);
 
        writer.append("autoDetect"_L1);
        writer.append(false);
 
        writer.append("condition"_L1);
        writer.append("libs.journald"_L1);
 
        writer.append("output"_L1);
        writer.startArray(1);
        writer.append("privateFeature"_L1);
        writer.endArray();
 
        writer.endMap();

Definition at line 32 of file qcborstreamwriter.h.

Constructor & Destructor Documentation

◆ QCborStreamWriter() [1/2]

QCborStreamWriter::QCborStreamWriter ( QIODevice * device )

explicit

Creates a QCborStreamWriter object that will write the stream to device.

The device must be opened before the first append() call is made. This constructor can be used with any class that derives from QIODevice, such as QFile, QProcess or QTcpSocket.

QCborStreamWriter has no buffering, so every append() call will result in one or more calls to the device's \l {QIODevice::}{write()} method.

The following example writes an empty map to a file:

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

QCborStreamWriter does not take ownership of device.

See also: device(), setDevice()

Definition at line 276 of file qcborstreamwriter.cpp.

◆ QCborStreamWriter() [2/2]

QCborStreamWriter::QCborStreamWriter ( QByteArray * data )

explicit

Creates a QCborStreamWriter object that will append the stream to data.

All streaming is done immediately to the byte array, without the need for flushing any buffers.

The following example writes a number to a byte array then returns it.

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

QCborStreamWriter does not take ownership of data.

Definition at line 294 of file qcborstreamwriter.cpp.

◆ ~QCborStreamWriter()

QCborStreamWriter::~QCborStreamWriter ( )

Destroys this QCborStreamWriter object and frees any resources associated.

QCborStreamWriter does not perform error checking to see if all required items were written to the stream prior to the object being destroyed. It is the programmer's responsibility to ensure that it was done.

Definition at line 309 of file qcborstreamwriter.cpp.

Member Function Documentation

◆ append() [1/19]

void QCborStreamWriter::append ( bool b )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the boolean value b to the stream, creating either a CBOR False value or a CBOR True value.

This function is equivalent to (and implemented as):

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

See also: appendNull(), appendUndefined(), QCborStreamReader::isBool(), QCborStreamReader::toBool()

Definition at line 68 of file qcborstreamwriter.h.

◆ append() [2/19]

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

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends size bytes of text starting from str to the stream, creating a CBOR Text String value.

QCborStreamWriter will attempt to write the entire string in one chunk. If size is -1, this function will write strlen(str) bytes.

The string pointed to by str is expected to be properly encoded UTF-8. QCborStreamWriter performs no validation that this is the case.

See also: append(QLatin1StringView), append(QStringView), QCborStreamReader::isString(), QCborStreamReader::readString()

Definition at line 78 of file qcborstreamwriter.h.

◆ append() [3/19]

Q_WEAK_OVERLOAD void QCborStreamWriter::append ( const QByteArray & ba )

inline

Definition at line 49 of file qcborstreamwriter.h.

◆ append() [4/19]

void QCborStreamWriter::append ( double d )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the floating point number d to the stream, creating a CBOR 64-bit Double-Precision Floating Point value.

QCborStreamWriter always appends the number as-is, performing no check for whether the number is the canonical form for NaN, an infinite, whether it is denormal or if it could be written with a shorter format.

The following code performs all those checks, except for the denormal one, which is expected to be taken into account by the system FPU or floating point emulation directly.

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);
    }
}

Determining if a double can be converted to an integral with no loss of precision is left as an exercise to the reader.

See also: QCborStreamReader::isDouble(), QCborStreamReader::toDouble()

Definition at line 599 of file qcborstreamwriter.cpp.

◆ append() [5/19]

void QCborStreamWriter::append ( float f )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the floating point number f to the stream, creating a CBOR 32-bit Single-Precision Floating Point value.

The following code can be used to convert a C++ \tt double to \tt float if there's no loss of precision and append it, or instead append the \tt double.

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

See also: QCborStreamReader::isFloat(), QCborStreamReader::toFloat()

Definition at line 574 of file qcborstreamwriter.cpp.

◆ append() [6/19]

void QCborStreamWriter::append ( int i )

inline

Definition at line 74 of file qcborstreamwriter.h.

◆ append() [7/19]

void QCborStreamWriter::append ( QByteArrayView ba )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the byte array ba to the stream, creating a CBOR Byte String value.

QCborStreamWriter will attempt to write the entire string in one chunk.

The following example will load and append the contents of a file to the stream:

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

As the example shows, unlike JSON, CBOR requires no escaping for binary content.

Note: The overload taking a \l QByteArrayView has been present since Qt 6.10.

See also: appendByteString(), QCborStreamReader::isByteArray(), QCborStreamReader::readByteArray()

Definition at line 50 of file qcborstreamwriter.h.

◆ append() [8/19]

void QCborStreamWriter::append ( QCborKnownTags tag )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the CBOR tag tag to the stream, creating a CBOR Tag value.

All tags must be followed by another type which they provide meaning for.

In the following example, we append a CBOR Tag 1 (Unix time_t) and an integer representing the current time to the stream, obtained using the time() function:

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

See also: QCborStreamReader::isTag(), QCborStreamReader::toTag()

Definition at line 55 of file qcborstreamwriter.h.

◆ append() [9/19]

void QCborStreamWriter::append ( QCborNegativeInteger n )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the 64-bit negative value n to the CBOR stream.

QCborNegativeInteger is a 64-bit enum that holds the absolute value of the negative number we want to write. If n is zero, the value written will be equivalent to 2\sup{64} (that is, -18,446,744,073,709,551,616).

In the following example, we write the values -1, -2\sup{32} and INT64_MIN:

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

Note how this function can be used to encode numbers that cannot fit a standard computer's 64-bit signed integer like \l qint64. That is, if n is larger than {std::numeric_limits<qint64>::max()} or is 0, this will represent a negative number smaller than {std::numeric_limits<qint64>::min()}.

See also: QCborStreamReader::isNegativeInteger(), QCborStreamReader::toNegativeInteger()

Definition at line 394 of file qcborstreamwriter.cpp.

◆ append() [10/19]

void QCborStreamWriter::append ( QCborSimpleType st )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the CBOR simple type st to the stream, creating a CBOR Simple Type value.

In the following example, we write the simple type for Null as well as for type 32, which Qt has no support for.

writer.append(QCborSimpleType::Null);

writer.append(QCborSimpleType(32));

Note: Using Simple Types for which there is no specification can lead to validation errors by the remote receiver. In addition, simple type values 24 through 31 (inclusive) are reserved and must not be used.

See also: QCborStreamReader::isSimpleType(), QCborStreamReader::toSimpleType()

Definition at line 538 of file qcborstreamwriter.cpp.

◆ append() [11/19]

void QCborStreamWriter::append ( QCborTag tag )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the CBOR tag tag to the stream, creating a CBOR Tag value.

All tags must be followed by another type which they provide meaning for.

In the following example, we append a CBOR Tag 36 (Regular Expression) and a QRegularExpression's pattern to the stream:

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

See also: QCborStreamReader::isTag(), QCborStreamReader::toTag()

Definition at line 502 of file qcborstreamwriter.cpp.

◆ append() [12/19]

void QCborStreamWriter::append ( qfloat16 f )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the floating point number f to the stream, creating a CBOR 16-bit Half-Precision Floating Point value.

The following code can be used to convert a C++ \tt float to qfloat16 if there's no loss of precision and append it, or instead append the \tt float.

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

See also: QCborStreamReader::isFloat16(), QCborStreamReader::toFloat16()

Definition at line 556 of file qcborstreamwriter.cpp.

◆ append() [13/19]

void QCborStreamWriter::append ( qint64 i )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the 64-bit signed value i to the CBOR stream.

This will create either a CBOR Unsigned Integer or CBOR NegativeInteger value based on the sign of the parameter. In the following example, we write the values 0, -1, 2\sup{32} and INT64_MAX:

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

See also: QCborStreamReader::isInteger(), QCborStreamReader::toInteger()

Definition at line 370 of file qcborstreamwriter.cpp.

◆ append() [14/19]

void QCborStreamWriter::append ( QLatin1StringView str )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the Latin-1 string viewed by str to the stream, creating a CBOR Text String value.

QCborStreamWriter will attempt to write the entire string in one chunk.

The following example appends a simple Latin-1 string literal to the stream:

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

{Performance note}: CBOR requires that all Text Strings be encoded in UTF-8, so this function will iterate over the characters in the string to determine whether the contents are US-ASCII or not. If the string is found to contain characters outside of US-ASCII, it will allocate memory and convert to UTF-8. If this check is unnecessary, use appendTextString() instead or the overload taking a \l QUtf8StringView.

See also: QCborStreamReader::isString(), QCborStreamReader::readString()

Definition at line 455 of file qcborstreamwriter.cpp.

◆ append() [15/19]

void QCborStreamWriter::append ( QStringView str )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the text string str to the stream, creating a CBOR Text String value.

QCborStreamWriter will attempt to write the entire string in one chunk.

The following example writes an arbitrary QString to the stream:

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

See also: QCborStreamReader::isString(), QCborStreamReader::readString()

Definition at line 483 of file qcborstreamwriter.cpp.

◆ append() [16/19]

void QCborStreamWriter::append ( quint64 u )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends the 64-bit unsigned value u to the CBOR stream, creating a CBOR Unsigned Integer value.

In the following example, we write the values 0, 2\sup{32} and UINT64_MAX:

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

See also: QCborStreamReader::isUnsignedInteger(), QCborStreamReader::toUnsignedInteger()

Definition at line 353 of file qcborstreamwriter.cpp.

◆ append() [17/19]

void QCborStreamWriter::append ( QUtf8StringView str )

inline

Since: 6.10 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Appends the UTF-8 string viewed by str to the stream, creating a CBOR Text String value. QCborStreamWriter will attempt to write the entire string in one chunk.

See also: appendTextString(), QCborStreamReader::isString(), QCborStreamReader::readString()

Definition at line 53 of file qcborstreamwriter.h.

◆ append() [18/19]

void QCborStreamWriter::append ( std::nullptr_t )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Appends a CBOR Null value to the stream.

This function is equivalent to (and implemented as): The parameter is ignored.

writer.append(QCborSimpleType::Null);

See also: appendNull(), append(QCborSimpleType), QCborStreamReader::isNull()

Definition at line 57 of file qcborstreamwriter.h.

◆ append() [19/19]

void QCborStreamWriter::append ( uint u )

inline

Definition at line 75 of file qcborstreamwriter.h.

◆ appendByteString()

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

Appends len bytes of data starting from data to the stream, creating a CBOR Byte String value.

QCborStreamWriter will attempt to write the entire string in one chunk.

See also: append(), appendTextString(), QCborStreamReader::isByteArray(), QCborStreamReader::readByteArray()

Definition at line 612 of file qcborstreamwriter.cpp.

◆ appendNull()

void QCborStreamWriter::appendNull ( )

inline

Appends a CBOR Null value to the stream.

This function is equivalent to (and implemented as):

writer.append(QCborSimpleType::Null);

See also: append(std::nullptr_t), append(QCborSimpleType), QCborStreamReader::isNull()

Definition at line 69 of file qcborstreamwriter.h.

◆ appendTextString()

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

Appends len bytes of text starting from utf8 to the stream, creating a CBOR Text String value.

QCborStreamWriter will attempt to write the entire string in one chunk.

The string pointed to by utf8 is expected to be properly encoded UTF-8. QCborStreamWriter performs no validation that this is the case.

See also: append(QLatin1StringView), append(QStringView), QCborStreamReader::isString(), QCborStreamReader::readString()

Definition at line 628 of file qcborstreamwriter.cpp.

◆ appendUndefined()

void QCborStreamWriter::appendUndefined ( )

inline

Appends a CBOR Undefined value to the stream.

This function is equivalent to (and implemented as):

writer.append(QCborSimpleType::Undefined);

See also: append(QCborSimpleType), QCborStreamReader::isUndefined()

Definition at line 70 of file qcborstreamwriter.h.

◆ device()

QIODevice * QCborStreamWriter::device ( ) const

Returns the QIODevice that this QCborStreamWriter object is writing to.

The device must have previously been set with either the constructor or with setDevice().

If this object was created by writing to a QByteArray, this function will return an internal instance of QBuffer, which is owned by QCborStreamWriter.

See also: setDevice()

Definition at line 337 of file qcborstreamwriter.cpp.

◆ endArray()

bool QCborStreamWriter::endArray ( )

Terminates the array started by either overload of startArray() and returns true if the correct number of elements was added to the array.

This function must be called for every startArray() used.

A return of false indicates error in the application and an unrecoverable error in this stream. QCborStreamWriter also writes a warning using qWarning() if that happens.

Calling this function when the current container is not an array is also an error, though QCborStreamWriter cannot currently detect this condition.

See also: startArray(), startArray(quint64), endMap()

Definition at line 765 of file qcborstreamwriter.cpp.

◆ endMap()

bool QCborStreamWriter::endMap ( )

Terminates the map started by either overload of startMap() and returns true if the correct number of elements was added to the array.

This function must be called for every startMap() used.

A return of false indicates error in the application and an unrecoverable error in this stream. QCborStreamWriter also writes a warning using qWarning() if that happens.

Calling this function when the current container is not a map is also an error, though QCborStreamWriter cannot currently detect this condition.

See also: startMap(), startMap(quint64), endArray()

Definition at line 839 of file qcborstreamwriter.cpp.

◆ setDevice()

void QCborStreamWriter::setDevice ( QIODevice * device )

Replaces the device or byte array that this QCborStreamWriter object is writing to with device.

See also: device()

Definition at line 319 of file qcborstreamwriter.cpp.

◆ startArray() [1/2]

void QCborStreamWriter::startArray ( )

Starts a CBOR Array with indeterminate length in the CBOR stream.

Each startArray() call must be paired with one endArray() call and the current CBOR element extends until the end of the array.

The array created by this function has no explicit length. Instead, its length is implied by the elements contained in it. Note, however, that use of indeterminate-length arrays is not compliant with canonical CBOR encoding.

The following example appends elements from the list of strings passed as input:

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

See also: startArray(quint64), endArray(), startMap(), QCborStreamReader::isArray(), QCborStreamReader::isLengthKnown()

Definition at line 714 of file qcborstreamwriter.cpp.

◆ startArray() [2/2]

void QCborStreamWriter::startArray ( quint64 count )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Starts a CBOR Array with explicit length of count items in the CBOR stream.

Each startArray call must be paired with one endArray() call and the current CBOR element extends until the end of the array.

The array created by this function has an explicit length and therefore exactly count items must be added to the CBOR stream. Adding fewer or more items will result in failure during endArray() and the CBOR stream will be corrupt. However, explicit-length arrays are required by canonical CBOR encoding.

The following example appends all strings found in the \l QStringList passed as input:

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

{Size limitations}: The parameter to this function is quint64, which would seem to allow up to 2\sup{64}-1 elements in the array. However, both QCborStreamWriter and QCborStreamReader are currently limited to 2\sup{32}-2 items on 32-bit systems and 2\sup{64}-2 items on 64-bit ones. Also note that QCborArray is currently limited to 2\sup{27} elements on 32-bit platforms and 2\sup{59} elements on 64-bit ones.

See also: startArray(), endArray(), startMap(), QCborStreamReader::isArray(), QCborStreamReader::isLengthKnown()

Definition at line 746 of file qcborstreamwriter.cpp.

◆ startMap() [1/2]

void QCborStreamWriter::startMap ( )

Starts a CBOR Map with indeterminate length in the CBOR stream.

Each startMap() call must be paired with one endMap() call and the current CBOR element extends until the end of the map.

The map created by this function has no explicit length. Instead, its length is implied by the elements contained in it. Note, however, that use of indeterminate-length maps is not compliant with canonical CBOR encoding (canonical encoding also requires keys to be unique and in sorted order).

The following example appends elements from the list of int and string pairs passed as input:

    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();
    }

See also: startMap(quint64), endMap(), startArray(), QCborStreamReader::isMap(), QCborStreamReader::isLengthKnown()

Definition at line 788 of file qcborstreamwriter.cpp.

◆ startMap() [2/2]

void QCborStreamWriter::startMap ( quint64 count )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Starts a CBOR Map with explicit length of count items in the CBOR stream.

Each startMap call must be paired with one endMap() call and the current CBOR element extends until the end of the map.

The map created by this function has an explicit length and therefore exactly count pairs of items must be added to the CBOR stream. Adding fewer or more items will result in failure during endMap() and the CBOR stream will be corrupt. However, explicit-length map are required by canonical CBOR encoding.

The following example appends all strings found in the \l QMap passed as input:

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();
}

{Size limitations}: The parameter to this function is quint64, which would seem to allow up to 2\sup{64}-1 pairs in the map. However, both QCborStreamWriter and QCborStreamReader are currently limited to 2\sup{31}-1 items on 32-bit systems and 2\sup{63}-1 items on 64-bit ones. Also note that QCborMap is currently limited to 2\sup{26} elements on 32-bit platforms and 2\sup{58} on 64-bit ones.

See also: startMap(), endMap(), startArray(), QCborStreamReader::isMap(), QCborStreamReader::isLengthKnown()

Definition at line 820 of file qcborstreamwriter.cpp.

The documentation for this class was generated from the following files:

qtbase/src/corelib/serialization/qcborstreamwriter.h (cd4813a3c304a6d9d5d8096d91a8fc297818d624)
qtbase/src/corelib/serialization/qcborstreamwriter.cpp (cd4813a3c304a6d9d5d8096d91a8fc297818d624)

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ QCborStreamWriter() [1/2]

◆ QCborStreamWriter() [2/2]

◆ ~QCborStreamWriter()

Member Function Documentation

◆ append() [1/19]

◆ append() [2/19]

◆ append() [3/19]

◆ append() [4/19]

◆ append() [5/19]

◆ append() [6/19]

◆ append() [7/19]

◆ append() [8/19]

◆ append() [9/19]

◆ append() [10/19]

◆ append() [11/19]

◆ append() [12/19]

◆ append() [13/19]

◆ append() [14/19]

◆ append() [15/19]

◆ append() [16/19]

◆ append() [17/19]

◆ append() [18/19]

◆ append() [19/19]

◆ appendByteString()

◆ appendNull()

◆ appendTextString()

◆ appendUndefined()

◆ device()

◆ endArray()

◆ endMap()

◆ setDevice()

◆ startArray() [1/2]

◆ startArray() [2/2]

◆ startMap() [1/2]

◆ startMap() [2/2]