QCborStreamWriter Class

Documentation des fonctions membres

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

Crée un objet QCborStreamWriter qui ajoutera le flux à ` data`. Tout le flux est immédiatement transféré vers le tableau d'octets, sans qu'il soit nécessaire de vider aucun tampon.

L'exemple suivant écrit un nombre dans un tableau d'octets, puis le renvoie.

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

QCborStreamWriter ne prend pas possession de ` data`.

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

Crée un objet QCborStreamWriter qui écrira le flux vers device. Le périphérique doit être ouvert avant le premier appel à la méthode append(). Ce constructeur peut être utilisé avec n'importe quelle classe dérivée de QIODevice, telle que QFile, QProcess ou QTcpSocket.

QCborStreamWriter ne dispose d'aucune mémoire tampon ; ainsi, chaque appel à ` append()` entraînera un ou plusieurs appels à la méthode ` write()` du périphérique.

L'exemple suivant écrit une carte vide dans un fichier :

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

QCborStreamWriter ne prend pas en charge la gestion de la mémoire de device.

Voir également device() et setDevice().

[delete] QCborStreamWriter::QCborStreamWriter(const QCborStreamWriter &)

Copie et construit une instance de ` QCborStreamWriter`. Cette fonction est supprimée.

[noexcept] QCborStreamWriter::~QCborStreamWriter()

Détruit cet objet ` QCborStreamWriter ` et libère toutes les ressources associées.

QCborStreamWriter N'effectue aucune vérification pour s'assurer que tous les éléments requis ont bien été écrits dans le flux avant la destruction de l'objet. Il incombe au programmeur de s'assurer que cela a bien été fait.

Ajoute le tableau d'octets ba au flux, créant ainsi une valeur de type « chaîne d'octets CBOR ». La méthode QCborStreamWriter tentera d'écrire la chaîne entière en un seul bloc.

L'exemple suivant charge et ajoute le contenu d'un fichier au flux :

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

Comme le montre l'exemple, contrairement au JSON, le CBOR ne nécessite aucun échappement pour le contenu binaire.

Voir également appendByteString(), QCborStreamReader::isByteArray() et QCborStreamReader::readByteArray().

void QCborStreamWriter::append(QCborKnownTags tag)

Ajoute la balise CBOR tag au flux, créant ainsi une valeur de balise CBOR. Toutes les balises doivent être suivies d'un autre type auquel elles donnent un sens.

Dans l'exemple suivant, nous ajoutons au flux une balise CBOR 1 (Unix time_t) et un entier représentant l'heure actuelle, obtenu à l'aide de la fonction time():

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

Voir également QCborStreamReader::isTag() et QCborStreamReader::toTag().

void QCborStreamWriter::append(QCborNegativeInteger n)

Ajoute la valeur négative sur 64 bits n au flux CBOR. QCborNegativeInteger est une énumération sur 64 bits qui contient la valeur absolue du nombre négatif que l'on souhaite écrire. Si n est égal à zéro, la valeur écrite sera équivalente à^2⁶⁴ (c'est-à-dire -18 446 744 073 709 551 616).

Dans l’exemple suivant, nous écrivons les valeurs -1,^-232 et INT64_MIN :

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

Notez comment cette fonction peut être utilisée pour encoder des nombres qui ne tiennent pas dans un entier signé 64 bits standard d’un ordinateur, comme qint64. Autrement dit, si n est supérieur à std::numeric_limits<qint64>::max() ou égal à 0, cela représentera un nombre négatif inférieur à std::numeric_limits<qint64>::min().

Voir également QCborStreamReader::isNegativeInteger() et QCborStreamReader::toNegativeInteger().

void QCborStreamWriter::append(QCborSimpleType st)

Ajoute le type simple CBOR « st » au flux, créant ainsi une valeur de type simple CBOR. Dans l'exemple suivant, nous écrivons le type simple correspondant à la valeur Null ainsi que celui correspondant au type 32, que Qt ne prend pas en charge.

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

Voir également QCborStreamReader::isSimpleType() et QCborStreamReader::toSimpleType().

void QCborStreamWriter::append(QCborTag tag)

Ajoute la balise CBOR « tag » au flux, créant ainsi une valeur de balise CBOR. Toutes les balises doivent être suivies d'un autre type auquel elles donnent un sens.

Dans l’exemple suivant, nous ajoutons une balise CBOR 36 (expression régulière) et le motif de l’ QRegularExpression au flux :

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

Voir également « QCborStreamReader::isTag() » et « QCborStreamReader::toTag() ».

void QCborStreamWriter::append(QLatin1StringView str)

Ajoute au flux la chaîne Latin-1 interprétée par la méthode « str », créant ainsi une valeur de type « CBOR Text String ». La méthode « QCborStreamWriter » tentera d'écrire la chaîne entière en un seul bloc.

L'exemple suivant ajoute une simple chaîne littérale au format Latin-1 au flux :

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

Remarque concernant les performances: CBOR exige que toutes les chaînes de texte soient encodées en UTF-8 ; cette fonction parcourt donc les caractères de la chaîne pour déterminer si son contenu est au format US-ASCII ou non. Si la chaîne contient des caractères hors de la norme US-ASCII, la fonction allouera de la mémoire et effectuera la conversion en UTF-8. Si cette vérification n’est pas nécessaire, utilisez plutôt appendTextString() ou la surcharge acceptant un argument de type QUtf8StringView.

Voir également QCborStreamReader::isString() et QCborStreamReader::readString().

void QCborStreamWriter::append(QStringView str)

Ajoute la chaîne de caractères str au flux, créant ainsi une valeur de type « Chaîne de caractères CBOR ». La méthode QCborStreamWriter tentera d'écrire la chaîne entière en un seul bloc.

L'exemple suivant écrit une chaîne de caractères arbitraire QString dans le flux :

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

Voir également QCborStreamReader::isString() et QCborStreamReader::readString().

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

Ajoute au flux la chaîne UTF-8 affichée par str, créant ainsi une valeur de type « Chaîne de texte CBOR ». La fonction QCborStreamWriter tentera d'écrire la chaîne entière en un seul bloc.

Cette fonction a été introduite dans Qt 6.10.

Voir également appendTextString(), QCborStreamReader::isString() et QCborStreamReader::readString().

void QCborStreamWriter::append(bool b)

Ajoute la valeur booléenne b au flux, créant ainsi soit une valeur CBOR False, soit une valeur CBOR True. Cette fonction est équivalente à (et implémentée comme) :

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

Voir également ` appendNull()`, ` appendUndefined()`, ` QCborStreamReader::isBool()` et ` QCborStreamReader::toBool()`.

void QCborStreamWriter::append(double d)

Ajoute le nombre à virgule flottante d au flux, créant ainsi une valeur CBOR à virgule flottante double précision de 64 bits. La fonction ` QCborStreamWriter ` ajoute toujours le nombre tel quel, sans vérifier s’il s’agit de la forme canonique d’une valeur NaN, d’un infini, d’un nombre dénormalisé ou s’il pourrait être écrit dans un format plus court.

Le code suivant effectue toutes ces vérifications, à l’exception de celle concernant les nombres dénormalisés, qui est censée être prise en compte directement par la FPU (unité de calcul en virgule flottante) du système ou par l’émulation de virgule flottante.

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

Déterminer si un nombre de type double peut être converti en un nombre entier sans perte de précision est laissé comme exercice au lecteur.

Voir également QCborStreamReader::isDouble() et QCborStreamReader::toDouble().

void QCborStreamWriter::append(float f)

Ajoute le nombre à virgule flottante f au flux, en créant une valeur CBOR à virgule flottante simple précision de 32 bits. Le code suivant permet de convertir un double C++ en float s’il n’y a pas de perte de précision et de l’ajouter au flux, ou bien d’ajouter directement double.

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

Voir également QCborStreamReader::isFloat() et QCborStreamReader::toFloat().

void QCborStreamWriter::append(qfloat16 f)

Ajoute le nombre à virgule flottante f au flux, en créant une valeur CBOR à virgule flottante de demi-précision sur 16 bits. Le code suivant permet de convertir une valeur C++ float en qfloat16 s’il n’y a pas de perte de précision, puis de l’ajouter au flux ; il est également possible d’ajouter directement la valeur float.

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

Voir également QCborStreamReader::isFloat16() et QCborStreamReader::toFloat16().

void QCborStreamWriter::append(qint64 i)

Ajoute la valeur signée sur 64 bits i au flux CBOR. Cela créera soit une valeur CBOR Unsigned Integer, soit une valeur CBOR NegativeInteger, en fonction du signe du paramètre. Dans l'exemple suivant, nous écrivons les valeurs 0, -1,²³² et INT64_MAX:

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

Voir également ` QCborStreamReader::isInteger()` et ` QCborStreamReader::toInteger()`.

void QCborStreamWriter::append(quint64 u)

Ajoute la valeur non signée 64 bits u au flux CBOR, créant ainsi une valeur entière non signée CBOR. Dans l'exemple suivant, nous écrivons les valeurs 0,²³² et UINT64_MAX:

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

Voir également QCborStreamReader::isUnsignedInteger() et QCborStreamReader::toUnsignedInteger().

void QCborStreamWriter::append(std::nullptr_t)

Ajoute une valeur CBOR nulle au flux. Cette fonction est équivalente à (et implémentée comme) : Le paramètre est ignoré.

writer.append(QCborSimpleType::Null);

Voir également appendNull(), append(QCborSimpleType) et QCborStreamReader::isNull().

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

Ajoute size octets de texte, à partir de str, au flux, créant ainsi une valeur de type « CBOR Text String ». QCborStreamWriter tentera d'écrire la chaîne entière en un seul bloc. Si size est égal à -1, cette fonction écrira strlen(\a str) octets.

La chaîne pointée par str doit être correctement encodée en UTF-8. QCborStreamWriter n’effectue aucune validation pour s’assurer que c’est le cas.

Voir également append(QLatin1StringView), append(QStringView), QCborStreamReader::isString() et QCborStreamReader::readString().

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

Ajoute len octets de données, à partir de l'adresse data, au flux, créant ainsi une valeur de type « chaîne d'octets CBOR ». La fonction QCborStreamWriter tentera d'écrire la chaîne entière en un seul bloc.

Voir également append(), appendTextString(), QCborStreamReader::isByteArray() et QCborStreamReader::readByteArray().

void QCborStreamWriter::appendNull()

Ajoute une valeur CBOR nulle au flux. Cette fonction est équivalente à (et implémentée comme) :

writer.append(QCborSimpleType::Null);

Voir également append(std::nullptr_t), append(QCborSimpleType) et QCborStreamReader::isNull().

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

Ajoute len octets de texte, à partir de utf8, au flux, créant ainsi une valeur de type « Chaîne de texte CBOR ». QCborStreamWriter tentera d'écrire la chaîne entière en un seul bloc.

La chaîne pointée par utf8 doit être correctement encodée en UTF-8. QCborStreamWriter n’effectue aucune validation pour s’assurer que c’est bien le cas.

Voir également append(QLatin1StringView), append(QStringView), QCborStreamReader::isString() et QCborStreamReader::readString().

void QCborStreamWriter::appendUndefined()

Ajoute une valeur CBOR « non définie » au flux. Cette fonction est équivalente à (et implémentée comme) :

writer.append(QCborSimpleType::Undefined);

Voir également append(QCborSimpleType) et QCborStreamReader::isUndefined().

QIODevice *QCborStreamWriter::device() const

Renvoie l'QIODevice sur lequel cet objet QCborStreamWriter effectue l'écriture. Le périphérique doit avoir été préalablement configuré soit via le constructeur, soit via la fonction setDevice().

Si cet objet a été créé en écrivant sur un QByteArray, cette fonction renvoie une instance interne de QBuffer, qui appartient à QCborStreamWriter.

Voir également setDevice().

bool QCborStreamWriter::endArray()

Mette fin au tableau créé par l'une ou l'autre des surcharges de la fonction ` startArray()` et renvoie `true` si le nombre correct d'éléments a été ajouté au tableau. Cette fonction doit être appelée pour chaque appel à ` startArray()`.

Une valeur de retour « false » indique une erreur dans l’application et une erreur irrémédiable dans ce flux. Dans ce cas, ` QCborStreamWriter ` génère également un avertissement via ` qWarning()`.

L’appel de cette fonction alors que le conteneur actuel n’est pas un tableau constitue également une erreur, bien qu’ QCborStreamWriter ne puisse actuellement pas détecter cette condition.

Voir également startArray(), startArray(quint64) et endMap().

bool QCborStreamWriter::endMap()

Mette fin au mappage lancé par l'une ou l'autre des surcharges de la fonction ` startMap()` et renvoie `true` si le nombre correct d'éléments a été ajouté au tableau. Cette fonction doit être appelée pour chaque appel à ` startMap()`.

Une valeur de retour `false` indique une erreur dans l’application et une erreur irrécupérable dans ce flux. ` QCborStreamWriter ` génère également un avertissement via ` qWarning()` si cela se produit.

L'appel de cette fonction lorsque le conteneur actuel n'est pas une carte constitue également une erreur, bien qu’ QCborStreamWriter ne puisse actuellement pas détecter cette condition.

Voir également startMap(), startMap(quint64) et endArray().

void QCborStreamWriter::setDevice(QIODevice *device)

Remplace le périphérique ou le tableau d'octets sur lequel cet objet ` QCborStreamWriter ` écrit par ` device`.

Voir aussi device().

void QCborStreamWriter::startArray()

Lance un tableau CBOR de longueur indéterminée dans le flux CBOR. Chaque appel à `startArray()` doit être associé à un appel à ` endArray()`, et l'élément CBOR actuel s'étend jusqu'à la fin du tableau.

Le tableau créé par cette fonction n’a pas de longueur explicite. Sa longueur est plutôt déterminée par les éléments qu’il contient. Notez toutefois que l’utilisation de tableaux de longueur indéterminée n’est pas conforme à l’encodage CBOR canonique.

L'exemple suivant ajoute des éléments provenant de la liste de chaînes de caractères transmise en entrée :

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

Voir également startArray(quint64), endArray(), startMap(), QCborStreamReader::isArray() et QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startArray(quint64 count)

Lance un tableau CBOR d’une longueur explicite de count éléments dans le flux CBOR. Chaque appel à startArray doit être associé à un appel à endArray() ; l’élément CBOR actuel s’étend alors jusqu’à la fin du tableau.

Le tableau créé par cette fonction a une longueur explicite ; par conséquent, exactement count éléments doivent être ajoutés au flux CBOR. L’ajout d’un nombre d’éléments inférieur ou supérieur entraînera un échec lors de l’appel à endArray() et le flux CBOR sera corrompu. Cependant, les tableaux à longueur explicite sont requis par le codage CBOR canonique.

L’exemple suivant ajoute toutes les chaînes présentes dans le tableau QStringList transmis en entrée :

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

Limites de taille: le paramètre de cette fonction est de type quint64, ce qui semblerait autoriser jusqu’à^264-1 éléments dans le tableau. Cependant, les fonctions QCborStreamWriter et QCborStreamReader sont actuellement limitées à^232-2 éléments sur les systèmes 32 bits et à^264-2 éléments sur les systèmes 64 bits. Notez également que la fonction QCborArray est actuellement limitée ಲ⁷ éléments sur les plateformes 32 bits et à²⁵⁹ éléments sur les plateformes 64 bits.

Voir également startArray(), endArray(), startMap(), QCborStreamReader::isArray() et QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startMap()

Lance une carte CBOR de longueur indéterminée dans le flux CBOR. Chaque appel à `startMap()` doit être associé à un appel à ` endMap()`, et l'élément CBOR courant s'étend jusqu'à la fin de la carte.

La carte créée par cette fonction n’a pas de longueur explicite. Sa longueur est plutôt déterminée implicitement par les éléments qu’elle contient. Notez toutefois que l’utilisation de cartes de longueur indéterminée n’est pas conforme à l’encodage canonique CBOR (l’encodage canonique exige également que les clés soient uniques et triées).

L'exemple suivant ajoute des éléments provenant de la liste de paires int et chaîne de caractères transmise en entrée :

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

Voir également startMap(quint64), endMap(), startArray(), QCborStreamReader::isMap() et QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startMap(quint64 count)

Lance une carte CBOR dont la longueur explicite est de count éléments dans le flux CBOR. Chaque appel à startMap doit être associé à un appel à endMap() ; l’élément CBOR actuel s’étend alors jusqu’à la fin de la carte.

La carte créée par cette fonction possède une longueur explicite ; par conséquent, exactement count paires d’éléments doivent être ajoutées au flux CBOR. L’ajout d’un nombre d’éléments inférieur ou supérieur entraînera un échec lors de l’appel à ` endMap()` et le flux CBOR sera corrompu. Cependant, les cartes à longueur explicite sont requises par l’encodage CBOR canonique.

L’exemple suivant ajoute toutes les chaînes présentes dans le tableau QMap transmis en entrée :

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

Limites de taille: le paramètre de cette fonction est de type quint64, ce qui semblerait autoriser jusqu’à^2⁶⁴-1 paires dans la carte. Cependant, les fonctions QCborStreamWriter et QCborStreamReader sont actuellement limitées à^2³¹-1 éléments sur les systèmes 32 bits et à^2⁶³-1 éléments sur les systèmes 64 bits. Notez également que QCborMap est actuellement limitée à^2²⁶ éléments sur les plateformes 32 bits et à^2⁵⁸ sur les plateformes 64 bits.

Voir également startMap(), endMap(), startArray(), QCborStreamReader::isMap() et QCborStreamReader::isLengthKnown().

[delete] QCborStreamWriter &QCborStreamWriter::operator=(const QCborStreamWriter &)

Copie et affecte « other » à cette instance de « QCborStreamWriter ». Cette fonction est supprimée.