QCborStreamWriter Class

Dokumentation der Mitgliedsfunktionen

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

Erzeugt ein QCborStreamWriter-Objekt, das den Stream an data anhängt. Das gesamte Streaming erfolgt sofort in das Byte-Array, ohne dass ein Flushing der Puffer erforderlich ist.

Das folgende Beispiel schreibt eine Zahl in ein Byte-Array und gibt sie dann zurück.

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

QCborStreamWriter übernimmt nicht den Besitz von data.

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

Erzeugt ein QCborStreamWriter-Objekt, das den Stream auf device schreibt. Das Gerät muss vor dem ersten Aufruf von append() geöffnet werden. Dieser Konstruktor kann mit jeder Klasse verwendet werden, die von QIODevice abgeleitet ist, wie z. B. QFile, QProcess oder QTcpSocket.

QCborStreamWriter hat keine Pufferung, so dass jeder append()-Aufruf zu einem oder mehreren Aufrufen der write()-Methode des Geräts führt.

Das folgende Beispiel schreibt eine leere Map in eine Datei:

   QFile f("output", QIODevice::WriteOnly);
   QCborStreamWriter writer(&f);
   writer.startMap(0);
   writer.endMap();

QCborStreamWriter übernimmt nicht das Eigentum an device.

Siehe auch device() und setDevice().

[noexcept] QCborStreamWriter::~QCborStreamWriter()

Zerstört dieses QCborStreamWriter Objekt und gibt alle zugehörigen Ressourcen frei.

QCborStreamWriter führt keine Fehlerprüfung durch, um festzustellen, ob alle erforderlichen Elemente in den Stream geschrieben wurden, bevor das Objekt zerstört wurde. Es liegt in der Verantwortung des Programmierers, sicherzustellen, dass dies geschehen ist.

void QCborStreamWriter::append(QCborKnownTags tag)

Dies ist eine überladene Funktion.

Hängt das CBOR-Tag tag an den Datenstrom an und erzeugt einen CBOR-Tag-Wert. Alle Tags müssen von einem anderen Typ gefolgt werden, für den sie eine Bedeutung haben.

Im folgenden Beispiel wird ein CBOR-Tag 1 (Unix time_t) und eine Ganzzahl, die die aktuelle Zeit darstellt, an den Stream angehängt, die mit der Funktion time() ermittelt wurde:

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

Siehe auch QCborStreamReader::isTag() und QCborStreamReader::toTag().

void QCborStreamWriter::append(QCborNegativeInteger n)

Dies ist eine überladene Funktion.

Hängt den negativen 64-Bit-Wert n an den CBOR-Stream an. QCborNegativeInteger ist ein 64-Bit-Enum, das den absoluten Wert der negativen Zahl enthält, die wir schreiben wollen. Wenn n gleich Null ist, entspricht der geschriebene Wert²⁶⁴ (d. h. -18.446.744.073.709.551.616).

Im folgenden Beispiel schreiben wir die Werte -1, ^-232 und INT64_MIN:

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

Beachten Sie, wie diese Funktion verwendet werden kann, um Zahlen zu kodieren, die nicht in die vorzeichenbehaftete 64-Bit-Ganzzahl eines Standardcomputers wie qint64 passen. Das heißt, wenn n größer als std::numeric_limits<qint64>::max() oder gleich 0 ist, stellt dies eine negative Zahl dar, die kleiner als std::numeric_limits<qint64>::min() ist.

Siehe auch QCborStreamReader::isNegativeInteger() und QCborStreamReader::toNegativeInteger().

void QCborStreamWriter::append(QCborSimpleType st)

Dies ist eine überladene Funktion.

Hängt den CBOR Simple Type st an den Stream an und erzeugt einen CBOR Simple Type Wert. Im folgenden Beispiel schreiben wir den Simple Type für Null sowie für den Typ 32, für den Qt keine Unterstützung bietet.

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

Siehe auch QCborStreamReader::isSimpleType() und QCborStreamReader::toSimpleType().

void QCborStreamWriter::append(QCborTag tag)

Dies ist eine überladene Funktion.

Hängt das CBOR-Tag tag an den Datenstrom an und erzeugt einen CBOR-Tag-Wert. Alle Tags müssen von einem anderen Typ gefolgt werden, für den sie eine Bedeutung haben.

Im folgenden Beispiel wird ein CBOR-Tag 36 (Regulärer Ausdruck) und ein QRegularExpression's-Muster an den Stream angehängt:

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

Siehe auch QCborStreamReader::isTag() und QCborStreamReader::toTag().

void QCborStreamWriter::append(QLatin1StringView str)

Dies ist eine überladene Funktion.

Hängt die von str betrachtete Latin-1-Zeichenkette an den Stream an und erzeugt einen CBOR-Text-String-Wert. QCborStreamWriter versucht, die gesamte Zeichenkette in einem Stück zu schreiben.

Das folgende Beispiel fügt ein einfaches Latin-1-String-Literal an den Stream an:

   writer.append("Hello, World"_L1);

Hinweis zur Leistung: CBOR verlangt, dass alle Text-Strings in UTF-8 kodiert sind. Daher durchläuft diese Funktion die Zeichen im String, um festzustellen, ob der Inhalt US-ASCII ist oder nicht. Wird festgestellt, dass die Zeichenkette Zeichen außerhalb von US-ASCII enthält, wird Speicher zugewiesen und in UTF-8 konvertiert. Wenn diese Prüfung unnötig ist, verwenden Sie stattdessen appendTextString().

Siehe auch QCborStreamReader::isString() und QCborStreamReader::readString().

void QCborStreamWriter::append(QStringView str)

Dies ist eine überladene Funktion.

Hängt die Zeichenkette str an den Stream an und erzeugt einen CBOR-Textstring-Wert. QCborStreamWriter versucht, die gesamte Zeichenkette in einem Stück zu schreiben.

Das folgende Beispiel schreibt eine beliebige QString in den Stream:

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

Siehe auch QCborStreamReader::isString() und QCborStreamReader::readString().

void QCborStreamWriter::append(bool b)

Dies ist eine überladene Funktion.

Hängt den booleschen Wert b an den Stream an und erzeugt entweder einen CBOR False Wert oder einen CBOR True Wert. Diese Funktion ist äquivalent zu (und implementiert als):

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

Siehe auch appendNull(), appendUndefined(), QCborStreamReader::isBool(), und QCborStreamReader::toBool().

void QCborStreamWriter::append(const QByteArray &ba)

Dies ist eine überladene Funktion.

Hängt das Byte-Array ba an den Stream an und erzeugt einen CBOR Byte String Wert. QCborStreamWriter versucht, den gesamten String in einem Stück zu schreiben.

Im folgenden Beispiel wird der Inhalt einer Datei geladen und an den Stream angehängt:

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

Wie das Beispiel zeigt, erfordert CBOR im Gegensatz zu JSON kein Escaping für binäre Inhalte.

Siehe auch appendByteString(), QCborStreamReader::isByteArray(), und QCborStreamReader::readByteArray().

void QCborStreamWriter::append(double d)

Dies ist eine überladene Funktion.

Hängt die Fließkommazahl d an den Stream an und erzeugt einen CBOR 64-Bit Double-Precision Floating Point Wert. QCborStreamWriter hängt die Zahl immer so an, wie sie ist, ohne zu prüfen, ob die Zahl die kanonische Form für NaN, eine Unendlichkeit ist, ob sie denormal ist oder ob sie in einem kürzeren Format geschrieben werden könnte.

Der folgende Code führt alle diese Prüfungen durch, mit Ausnahme der Prüfung auf Denormalität, die von der System-FPU oder der Fließkomma-Emulation direkt berücksichtigt werden sollte.

   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 = f;
           if (f16 == f)
               writer.append(f16);
           else
               writer.append(f);
       } else {
           writer.append(d);
       }
   }

Die Feststellung, ob ein Double ohne Präzisionsverlust in ein Integral umgewandelt werden kann, bleibt dem Leser als Übung überlassen.

Siehe auch QCborStreamReader::isDouble() und QCborStreamReader::toDouble().

void QCborStreamWriter::append(float f)

Dies ist eine überladene Funktion.

Hängt die Fließkommazahl f an den Stream an und erzeugt einen CBOR 32-Bit Single-Precision Floating Point Wert. Der folgende Code kann verwendet werden, um eine C++-Zahl double in float zu konvertieren, wenn es keinen Präzisionsverlust gibt, und diese anzufügen, oder stattdessen double anzuhängen.

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

Siehe auch QCborStreamReader::isFloat() und QCborStreamReader::toFloat().

void QCborStreamWriter::append(qfloat16 f)

Dies ist eine überladene Funktion.

Hängt die Fließkommazahl f an den Stream an und erzeugt einen CBOR 16-Bit Half-Precision Floating Point Wert. Der folgende Code kann verwendet werden, um eine C++-Zahl float in qfloat16 umzuwandeln, wenn es keinen Präzisionsverlust gibt, und diese anzufügen, oder stattdessen float anzuhängen.

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

Siehe auch QCborStreamReader::isFloat16() und QCborStreamReader::toFloat16().

void QCborStreamWriter::append(qint64 i)

Dies ist eine überladene Funktion.

Hängt den vorzeichenbehafteten 64-Bit-Wert i an den CBOR-Stream an. Dadurch wird je nach Vorzeichen des Parameters entweder ein CBOR Unsigned Integer oder CBOR NegativeInteger Wert erzeugt. Im folgenden Beispiel schreiben wir die Werte 0, -1,²³² und INT64_MAX:

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

Siehe auch QCborStreamReader::isInteger() und QCborStreamReader::toInteger().

void QCborStreamWriter::append(quint64 u)

Dies ist eine überladene Funktion.

Hängt den vorzeichenlosen 64-Bit-Wert u an den CBOR-Stream an und erzeugt einen CBOR Unsigned Integer-Wert. Im folgenden Beispiel schreiben wir die Werte 0,²³² und UINT64_MAX:

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

Siehe auch QCborStreamReader::isUnsignedInteger() und QCborStreamReader::toUnsignedInteger().

void QCborStreamWriter::append(std::nullptr_t)

Dies ist eine überladene Funktion.

Hängt einen CBOR-Null-Wert an den Stream an. Diese Funktion ist äquivalent zu (und implementiert als): Der Parameter wird ignoriert.

   writer.append(QCborSimpleType::Null);

Siehe auch appendNull(), append(QCborSimpleType), und QCborStreamReader::isNull().

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

Dies ist eine überladene Funktion.

Hängt size Bytes Text ab str an den Stream an und erzeugt einen CBOR Text String Wert. QCborStreamWriter versucht, den gesamten String in einem Stück zu schreiben. Wenn size -1 ist, schreibt diese Funktion strlen(\a str) Bytes.

Es wird erwartet, dass die Zeichenkette, auf die str verweist, ordnungsgemäß in UTF-8 kodiert ist. QCborStreamWriter führt keine Überprüfung durch, ob dies der Fall ist.

Anders als die QLatin1StringView Überladung von append() ist diese Funktion nicht auf 2 GB begrenzt. Beachten Sie jedoch, dass weder QCborStreamReader noch QCborValue das Lesen von CBOR-Streams mit Textstrings größer als 2 GB unterstützen.

Siehe auch append(QLatin1StringView), append(QStringView), QCborStreamReader::isString(), und QCborStreamReader::readString().

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

Hängt len Bytes von Daten ab data an den Stream an und erzeugt einen CBOR Byte String-Wert. QCborStreamWriter versucht, den gesamten String in einem Stück zu schreiben.

Anders als die QByteArray Überladung von append() ist diese Funktion nicht durch die Größenbeschränkungen von QByteArray begrenzt. Beachten Sie jedoch, dass weder QCborStreamReader::readByteArray() noch QCborValue das Lesen von CBOR-Streams mit Byte-Arrays größer als 2 GB unterstützen.

Siehe auch append(), appendTextString(), QCborStreamReader::isByteArray(), und QCborStreamReader::readByteArray().

void QCborStreamWriter::appendNull()

Hängt einen CBOR-Nullwert an den Stream an. Diese Funktion ist äquivalent zu (und implementiert als):

   writer.append(QCborSimpleType::Null);

Siehe auch append(std::nullptr_t), append(QCborSimpleType), und QCborStreamReader::isNull().

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

Hängt len Bytes Text ab utf8 an den Stream an und erzeugt einen CBOR Text String Wert. QCborStreamWriter versucht, den gesamten String in einem Chunk zu schreiben.

Es wird erwartet, dass die Zeichenkette, auf die utf8 verweist, korrekt in UTF-8 kodiert ist. QCborStreamWriter führt keine Überprüfung durch, ob dies der Fall ist.

Anders als die QLatin1StringView Überladung von append() ist diese Funktion nicht auf 2 GB begrenzt. Beachten Sie jedoch, dass weder QCborStreamReader::readString() noch QCborValue das Lesen von CBOR-Streams mit Textstrings größer als 2 GB unterstützen.

Siehe auch append(QLatin1StringView), append(QStringView), QCborStreamReader::isString(), und QCborStreamReader::readString().

void QCborStreamWriter::appendUndefined()

Hängt einen CBOR Undefined Wert an den Stream an. Diese Funktion ist äquivalent zu (und implementiert als):

   writer.append(QCborSimpleType::Undefined);

Siehe auch append(QCborSimpleType) und QCborStreamReader::isUndefined().

QIODevice *QCborStreamWriter::device() const

Gibt das QIODevice zurück, auf das dieses QCborStreamWriter Objekt schreibt. Das Gerät muss zuvor entweder mit dem Konstruktor oder mit setDevice() gesetzt worden sein.

Wenn dieses Objekt durch Schreiben auf ein QByteArray erstellt wurde, gibt diese Funktion eine interne Instanz von QBuffer zurück, die QCborStreamWriter gehört.

Siehe auch setDevice().

bool QCborStreamWriter::endArray()

Beendet das Array, das durch eine der beiden Überladungen von startArray() gestartet wurde, und gibt true zurück, wenn dem Array die richtige Anzahl von Elementen hinzugefügt wurde. Diese Funktion muss für jede verwendete startArray() aufgerufen werden.

Ein Rückgabewert von false deutet auf einen Fehler in der Anwendung und einen nicht behebbaren Fehler in diesem Stream hin. QCborStreamWriter schreibt auch eine Warnung mit qWarning(), wenn dies geschieht.

Der Aufruf dieser Funktion, wenn der aktuelle Container kein Array ist, ist ebenfalls ein Fehler, obwohl QCborStreamWriter diesen Zustand derzeit nicht erkennen kann.

Siehe auch startArray(), startArray(quint64), und endMap().

bool QCborStreamWriter::endMap()

Beendet die Map, die durch eine der beiden Überladungen von startMap() gestartet wurde, und gibt true zurück, wenn dem Array die richtige Anzahl von Elementen hinzugefügt wurde. Diese Funktion muss für jede verwendete startMap() aufgerufen werden.

Ein Rückgabewert von false deutet auf einen Fehler in der Anwendung und einen nicht behebbaren Fehler in diesem Stream hin. QCborStreamWriter schreibt auch eine Warnung mit qWarning(), wenn dies geschieht.

Der Aufruf dieser Funktion, wenn der aktuelle Container keine Karte ist, ist ebenfalls ein Fehler, obwohl QCborStreamWriter diesen Zustand derzeit nicht erkennen kann.

Siehe auch startMap(), startMap(quint64), und endArray().

void QCborStreamWriter::setDevice(QIODevice *device)

Ersetzt das Gerät oder Byte-Array, in das dieses QCborStreamWriter Objekt schreibt, durch device.

Siehe auch device().

void QCborStreamWriter::startArray()

Startet ein CBOR-Array mit unbestimmter Länge im CBOR-Stream. Jeder startArray()-Aufruf muss mit einem endArray()-Aufruf gepaart sein und das aktuelle CBOR-Element reicht bis zum Ende des Arrays.

Das von dieser Funktion erzeugte Array hat keine explizite Länge. Stattdessen wird seine Länge durch die darin enthaltenen Elemente impliziert. Beachten Sie jedoch, dass die Verwendung von Arrays mit unbestimmter Länge nicht mit der kanonischen CBOR-Kodierung konform ist.

Das folgende Beispiel fügt Elemente aus der Liste der als Eingabe übergebenen Zeichenketten an:

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

Siehe auch startArray(quint64), endArray(), startMap(), QCborStreamReader::isArray(), und QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startArray(quint64 count)

Dies ist eine überladene Funktion.

Startet ein CBOR Array mit expliziter Länge von count Elementen im CBOR Stream. Jeder startArray-Aufruf muss mit einem endArray()-Aufruf gepaart sein und das aktuelle CBOR-Element reicht bis zum Ende des Arrays.

Das von dieser Funktion erstellte Array hat eine eindeutige Länge und daher müssen genau count Elemente zum CBOR-Stream hinzugefügt werden. Das Hinzufügen von weniger oder mehr Elementen führt zu einem Fehler bei endArray() und der CBOR-Stream wird beschädigt. Arrays mit expliziter Länge sind jedoch für die kanonische CBOR-Kodierung erforderlich.

Das folgende Beispiel fügt alle Zeichenketten an, die in der als Eingabe übergebenen QStringList gefunden wurden:

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

Größenbeschränkungen: Der Parameter für diese Funktion ist quint64, was anscheinend bis zu^264-1 Elemente im Array erlaubt. Allerdings sind sowohl QCborStreamWriter als auch QCborStreamReader auf 32-Bit-Systemen auf^232-2 Elemente und auf 64-Bit-Systemen auf^264-2 Elemente beschränkt. Beachten Sie auch, dass QCborArray derzeit auf 32-Bit-Plattformen auf²²⁷ Elemente und auf 64-Bit-Plattformen auf²⁵⁹ Elemente beschränkt ist.

Siehe auch startArray(), endArray(), startMap(), QCborStreamReader::isArray(), und QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startMap()

Startet eine CBOR-Map mit unbestimmter Länge im CBOR-Stream. Jeder startMap()-Aufruf muss mit einem endMap()-Aufruf gepaart sein und das aktuelle CBOR-Element erstreckt sich bis zum Ende der Map.

Die mit dieser Funktion erstellte Map hat keine explizite Länge. Stattdessen wird ihre Länge durch die in ihr enthaltenen Elemente impliziert. Beachten Sie jedoch, dass die Verwendung von Maps mit unbestimmter Länge nicht mit der kanonischen CBOR-Kodierung konform ist (die kanonische Kodierung verlangt auch, dass die Schlüssel eindeutig und in sortierter Reihenfolge sind).

Das folgende Beispiel fügt Elemente aus der Liste der als Eingabe übergebenen int- und string-Paare an:

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

Siehe auch startMap(quint64), endMap(), startArray(), QCborStreamReader::isMap(), und QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startMap(quint64 count)

Dies ist eine überladene Funktion.

Startet eine CBOR Map mit expliziter Länge von count Elementen im CBOR Stream. Jeder startMap-Aufruf muss mit einem endMap()-Aufruf gepaart sein und das aktuelle CBOR-Element erstreckt sich bis zum Ende der Map.

Die mit dieser Funktion erstellte Map hat eine eindeutige Länge und daher müssen genau count Paare von Elementen zum CBOR-Stream hinzugefügt werden. Das Hinzufügen von weniger oder mehr Elementen führt zu einem Fehler bei endMap() und der CBOR-Stream wird beschädigt. Für die kanonische CBOR-Kodierung ist jedoch eine Zuordnung mit expliziter Länge erforderlich.

Das folgende Beispiel fügt alle Zeichenketten an, die in der als Eingabe übergebenen QMap gefunden wurden:

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

Größenbeschränkungen: Der Parameter für diese Funktion ist quint64, was anscheinend bis zu^264-1 Paare in der Map zulässt. Allerdings sind sowohl QCborStreamWriter als auch QCborStreamReader derzeit auf^231-1 Elemente auf 32-Bit-Systemen und^263-1 Elemente auf 64-Bit-Systemen beschränkt. Beachten Sie auch, dass QCborMap derzeit auf 32-Bit-Plattformen auf²²⁶ Elemente und auf 64-Bit-Plattformen auf²⁵⁸ Elemente beschränkt ist.

Siehe auch startMap(), endMap(), startArray(), QCborStreamReader::isMap(), und QCborStreamReader::isLengthKnown().