QCborStreamWriter Class

Documentation des fonctions membres

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

Crée un objet QCborStreamWriter qui ajoutera le flux à data. Tous les flux sont transmis immédiatement au tableau d'octets, sans qu'il soit nécessaire de vider les tampons.

L'exemple suivant écrit un nombre dans un tableau d'octets et 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 sur device. Le périphérique doit être ouvert avant le premier appel à append(). Ce constructeur peut être utilisé avec n'importe quelle classe dérivée de QIODevice, comme QFile, QProcess ou QTcpSocket.

QCborStreamWriter n'a pas de mémoire tampon, de sorte que 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 possession de device.

Voir également device() et setDevice().

[noexcept] QCborStreamWriter::~QCborStreamWriter()

Détruit l'objet QCborStreamWriter et libère les ressources associées.

QCborStreamWriter n'effectue pas de contrôle d'erreur pour vérifier si tous les éléments requis ont été écrits dans le flux avant la destruction de l'objet. Il est de la responsabilité du programmeur de s'assurer que cela a été fait.

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 une signification.

Dans l'exemple suivant, nous ajoutons une balise CBOR 1 (Unix time_t) et un entier représentant l'heure actuelle au flux, 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 de 64 bits n au flux CBOR. QCborNegativeInteger est un enum de 64 bits qui contient la valeur absolue du nombre négatif que nous voulons écrire. Si n est zéro, la valeur écrite sera équivalente à²⁶⁴ (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 que cette fonction peut être utilisée pour coder des nombres qui ne peuvent pas correspondre à un entier signé de 64 bits d'un ordinateur standard comme qint64. En d'autres termes, si n est plus grand que std::numeric_limits<qint64>::max() ou vaut 0, cela représentera un nombre négatif plus petit que std::numeric_limits<qint64>::min().

Voir aussi 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 pour Null ainsi que pour le type 32, qui n'est pas pris en charge par Qt.

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

Voir aussi 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 une signification.

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

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

Voir aussi QCborStreamReader::isTag() et QCborStreamReader::toTag().

void QCborStreamWriter::append(QLatin1StringView str)

Ajoute la chaîne Latin-1 visualisée par str au flux, en créant une valeur de chaîne de texte CBOR. QCborStreamWriter tentera d'écrire la chaîne entière en un seul morceau.

L'exemple suivant ajoute une simple chaîne de caractères Latin-1 au flux :

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

Note sur les performances: CBOR exige que toutes les chaînes de texte soient codées en UTF-8. Cette fonction passe donc en revue les caractères de la chaîne pour déterminer si le contenu est US-ASCII ou non. Si la chaîne contient des caractères en dehors de US-ASCII, elle allouera de la mémoire et convertira en UTF-8. Si cette vérification n'est pas nécessaire, utilisez appendTextString() à la place ou la surcharge prenant un QUtf8StringView.

Voir aussi QCborStreamReader::isString() et QCborStreamReader::readString().

void QCborStreamWriter::append(QStringView str)

Ajoute la chaîne de texte str au flux, créant ainsi une valeur de chaîne de texte CBOR. QCborStreamWriter tentera d'écrire l'intégralité de la chaîne en un seul bloc.

L'exemple suivant écrit une valeur 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 la chaîne UTF-8 visualisée par str au flux, créant ainsi une chaîne de texte CBOR. QCborStreamWriter tentera d'écrire la chaîne entière en un seul morceau.

Cette fonction a été introduite dans Qt 6.10.

Voir aussi appendTextString(), QCborStreamReader::isString(), et QCborStreamReader::readString().

void QCborStreamWriter::append(bool b)

Ajoute la valeur booléenne b au flux, créant 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 aussi appendNull(), appendUndefined(), QCborStreamReader::isBool() et QCborStreamReader::toBool().

Ajoute le tableau d'octets ba au flux, créant ainsi une valeur de chaîne d'octets CBOR. QCborStreamWriter tente 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 à JSON, CBOR ne nécessite pas d'échappement pour le contenu binaire.

Voir aussi appendByteString(), QCborStreamReader::isByteArray(), et QCborStreamReader::readByteArray().

void QCborStreamWriter::append(double d)

Ajoute le nombre en virgule flottante d au flux, en créant une valeur CBOR 64 bits en virgule flottante double précision. QCborStreamWriter ajoute toujours le nombre tel quel, sans vérifier si le nombre est la forme canonique de NaN, un infini, s'il est dénormal ou s'il pourrait être écrit dans un format plus court.

Le code suivant effectue toutes ces vérifications, à l'exception de la vérification de la forme dénormale, qui devrait être prise en compte par le FPU du système ou par l'émulation de la virgule flottante directement.

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 double peut être converti en une intégrale sans perte de précision est laissé à l'appréciation du lecteur.

Voir aussi QCborStreamReader::isDouble() et QCborStreamReader::toDouble().

void QCborStreamWriter::append(float f)

Ajoute le nombre à virgule flottante f au flux, créant ainsi une valeur CBOR à virgule flottante 32 bits à précision unique. Le code suivant peut être utilisé pour convertir un C++ double en float s'il n'y a pas de perte de précision et l'ajouter, ou à la place ajouter le double.

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

Voir aussi QCborStreamReader::isFloat() et QCborStreamReader::toFloat().

void QCborStreamWriter::append(qfloat16 f)

Ajoute le nombre à virgule flottante f au flux, créant ainsi une valeur CBOR à virgule flottante de 16 bits en demi-précision. Le code suivant peut être utilisé pour convertir un C++ float en qfloat16 s'il n'y a pas de perte de précision et l'ajouter, ou à la place ajouter le float.

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

Voir aussi QCborStreamReader::isFloat16() et QCborStreamReader::toFloat16().

void QCborStreamWriter::append(qint64 i)

Ajoute la valeur signée de 64 bits i au flux CBOR. Cela créera une valeur CBOR Unsigned Integer ou 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 aussi QCborStreamReader::isInteger() et QCborStreamReader::toInteger().

void QCborStreamWriter::append(quint64 u)

Ajoute la valeur non signée de 64 bits u au flux CBOR, créant ainsi une valeur CBOR Unsigned Integer. 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 Null au flux. Cette fonction est équivalente à (et implémentée comme) : Le paramètre est ignoré.

writer.append(QCborSimpleType::Null);

Voir aussi 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 chaîne de texte CBOR. QCborStreamWriter tentera d'écrire la chaîne entière en un seul morceau. Si size vaut -1, cette fonction écrira strlen(\a str) octets.

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

Voir aussi 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 data au flux, créant une valeur de chaîne d'octets CBOR. QCborStreamWriter tentera d'écrire la chaîne entière en un seul morceau.

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

void QCborStreamWriter::appendNull()

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

writer.append(QCborSimpleType::Null);

Voir aussi 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 chaîne de texte CBOR. QCborStreamWriter tentera d'écrire la chaîne entière en un seul morceau.

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

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

void QCborStreamWriter::appendUndefined()

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

writer.append(QCborSimpleType::Undefined);

Voir aussi append(QCborSimpleType) et QCborStreamReader::isUndefined().

QIODevice *QCborStreamWriter::device() const

Renvoie l'adresse QIODevice sur laquelle cet objet QCborStreamWriter est en train d'écrire. Le périphérique doit avoir été préalablement défini soit par le constructeur, soit par setDevice().

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

Voir aussi setDevice().

bool QCborStreamWriter::endArray()

Termine le tableau commencé par l'une des surcharges de startArray() et renvoie vrai si le nombre correct d'éléments a été ajouté au tableau. Cette fonction doit être appelée pour chaque startArray() utilisée.

Un retour à false indique une erreur dans l'application et une erreur irrécupérable dans ce flux. QCborStreamWriter écrit également un avertissement en utilisant qWarning() si cela se produit.

L'appel à cette fonction lorsque le conteneur actuel n'est pas un tableau est également une erreur, bien que QCborStreamWriter ne puisse pas actuellement détecter cette condition.

Voir aussi startArray(), startArray(quint64) et endMap().

bool QCborStreamWriter::endMap()

Termine la carte lancée par l'une ou l'autre surcharge de startMap() et retourne vrai si le nombre correct d'éléments a été ajouté au tableau. Cette fonction doit être appelée pour chaque startMap() utilisé.

Un retour à false indique une erreur dans l'application et une erreur irrécupérable dans ce flux. QCborStreamWriter écrit également un avertissement en utilisant qWarning() si cela se produit.

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

Voir aussi 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()

Démarre 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. Au lieu de cela, sa longueur est impliquée par les éléments qu'il contient. Notez cependant que l'utilisation de tableaux de longueur indéterminée n'est pas conforme au codage CBOR canonique.

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

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

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

void QCborStreamWriter::startArray(quint64 count)

Démarre un tableau CBOR d'une longueur explicite de count éléments 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 a une longueur explicite et, par conséquent, exactement count éléments doivent être ajoutés au flux CBOR. L'ajout d'un nombre inférieur ou supérieur d'éléments entraînera un échec lors de l'appel à endArray() et le flux CBOR sera corrompu. Cependant, les tableaux de longueur explicite sont requis par le codage CBOR canonique.

L'exemple suivant ajoute toutes les chaînes de caractères trouvées dans le fichier QStringList passé en entrée :

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

Limitations de taille: Le paramètre de cette fonction est quint64, ce qui semble autoriser jusqu'à^264-1 éléments dans le tableau. Cependant, les sites QCborStreamWriter et QCborStreamReader sont actuellement limités à^232-2 éléments sur les systèmes 32 bits et à^264-2 éléments sur les systèmes 64 bits. Notez également que QCborArray est actuellement limité ಲ⁷ éléments sur les plates-formes 32 bits et à²⁵⁹ éléments sur les plates-formes 64 bits.

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

void QCborStreamWriter::startMap()

Démarre 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 actuel s'étend jusqu'à la fin de la carte.

La carte créée par cette fonction n'a pas de longueur explicite. Au lieu de cela, sa longueur est impliquée par les éléments qu'elle contient. Notez cependant que l'utilisation de cartes de longueur indéterminée n'est pas conforme au codage CBOR canonique (le codage canonique exige également que les clés soient uniques et triées).

L'exemple suivant ajoute des éléments à la liste des paires int et string passées 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 aussi startMap(quint64), endMap(), startArray(), QCborStreamReader::isMap() et QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startMap(quint64 count)

Démarre une carte CBOR avec une longueur explicite de count éléments dans le flux CBOR. Chaque appel à startMap doit être associé à un appel à endMap() et l'élément CBOR actuel s'étend jusqu'à la fin de la carte.

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

L'exemple suivant ajoute toutes les chaînes de caractères trouvées dans le fichier QMap passé 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();
}

Limitations de taille: Le paramètre de cette fonction est quint64, ce qui semble autoriser jusqu'à^264-1 paires dans la carte. Cependant, les sites QCborStreamWriter et QCborStreamReader sont actuellement limités à^231-1 éléments sur les systèmes 32 bits et à^263-1 éléments sur les systèmes 64 bits. Notez également que QCborMap est actuellement limité ಲ⁶ éléments sur les plates-formes 32 bits et à²⁵⁸ sur les plates-formes 64 bits.

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