QCborStreamWriter Class

メンバ関数のドキュメント

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

data にストリームを追加する QCborStreamWriter オブジェクトを作成します。すべてのストリーミング処理は、バッファをフラッシュする必要なく、バイト配列に対して即座に行われます。

次の例では、バイト配列に数値を書き込んでから、それを返しています。

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

QCborStreamWriter は、data の所有権を取得しません。

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

device へストリームを書き込む QCborStreamWriter オブジェクトを作成します。最初のappend() を呼び出す前に、デバイスを開いておく必要があります。このコンストラクタは、QIODevice を継承する任意のクラス（QFile 、QProcess 、QTcpSocket など）で使用できます。

QCborStreamWriterにはバッファリング機能がないため、append()が呼び出されるたびに、デバイスのwrite()メソッドが1回以上呼び出されます。

次の例は、空のマップをファイルに書き込みます。

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

QCborStreamWriterはdevice の所有権を取得しません。

device() およびsetDevice()も参照してください 。

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

QCborStreamWriter のインスタンスをコピーして生成します。この関数は削除されています。

[noexcept] QCborStreamWriter::~QCborStreamWriter()

このQCborStreamWriter オブジェクトを破棄し、関連するリソースをすべて解放します。

QCborStreamWriter オブジェクトが破棄される前に、必要な項目がすべてストリームに書き込まれているかどうかを検証するエラーチェックは行われません。それが行われていることを確認するのは、プログラマーの責任です。

バイト配列ba をストリームに追加し、CBORバイト文字列値を作成します。QCborStreamWriter は、文字列全体を1つのチャンクで書き込もうとします。

次の例では、ファイルの内容を読み込んでストリームに追加します。

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

この例が示すように、JSONとは異なり、CBORではバイナリコンテンツのエスケープ処理は不要です。

関連項目： appendByteString()、QCborStreamReader::isByteArray()、QCborStreamReader::readByteArray()。

void QCborStreamWriter::append(QCborKnownTags tag)

CBORタグ「tag 」をストリームに追加し、CBORタグ値を作成します。すべてのタグの後には、そのタグが意味を与える別の型が続く必要があります。

次の例では、CBORタグ1（Unixtime_t ）と、time() 関数を使用して取得した現在の時刻を表す整数をストリームに追加しています。

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

QCborStreamReader::isTag() およびQCborStreamReader::toTag()も参照してください 。

void QCborStreamWriter::append(QCborNegativeInteger n)

64ビットの負の数n をCBORストリームに追加します。QCborNegativeIntegerは、書き込み対象の負の数の絶対値を保持する64ビットの列挙型です。 n が 0 の場合、書き込まれる値は^2⁶⁴（つまり -18,446,744,073,709,551,616）に相当します。

次の例では、-1、^-232、および INT64_MIN の値を書き込みます。

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

この関数を使用することで、qint64 のように、標準的なコンピュータの64ビット符号付き整数には収まらない数値をエンコードできる点に注意してください。つまり、n がstd::numeric_limits<qint64>::max() より大きいか、または0である場合、これはstd::numeric_limits<qint64>::min() より小さい負の数を表します。

QCborStreamReader::isNegativeInteger() およびQCborStreamReader::toNegativeInteger()も参照してください 。

void QCborStreamWriter::append(QCborSimpleType st)

CBOR単純型「st 」をストリームに追加し、CBOR単純型の値を作成します。以下の例では、Null および Qt XML がサポートしていない型 32 に対する単純型を記述しています。

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

QCborStreamReader::isSimpleType() およびQCborStreamReader::toSimpleType()も参照してください 。

void QCborStreamWriter::append(QCborTag tag)

CBORタグ「tag 」をストリームに追加し、CBORタグ値を作成します。すべてのタグの後には、そのタグが意味を与える別の型が続く必要があります。

次の例では、CBOR タグ 36（正規表現）と、QRegularExpression のパターンをストリームに追加しています。

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

QCborStreamReader::isTag() およびQCborStreamReader::toTag()も参照してください 。

void QCborStreamWriter::append(QLatin1StringView str)

str によって解釈された Latin-1 文字列をストリームに追加し、CBOR テキスト文字列値を作成します。QCborStreamWriter は、文字列全体を 1 つのチャンクで書き込もうとします。

次の例は、単純な Latin-1 文字列リテラルをストリームに追加するものです:

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

パフォーマンスに関する注意: CBOR では、すべてのテキスト文字列が UTF-8 でエンコードされていることが必須であるため、この関数は文字列内の各文字を順に処理し、その内容が US-ASCII であるかどうかを判定します。 文字列に US-ASCII 以外の文字が含まれていることが判明した場合、メモリを割り当てて UTF-8 に変換します。このチェックが不要な場合は、代わりに `appendTextString()` を使用するか、`QUtf8StringView` を引数とするオーバーロードを使用してください。

QCborStreamReader::isString() およびQCborStreamReader::readString()も参照してください 。

void QCborStreamWriter::append(QStringView str)

テキスト文字列「str 」をストリームに追加し、CBOR テキスト文字列値を作成します。QCborStreamWriter は、文字列全体を1つのチャンクとして書き込もうとします。

次の例は、任意のQString をストリームに書き込みます:

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

QCborStreamReader::isString() およびQCborStreamReader::readString()も参照してください 。

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

str で取得された UTF-8 文字列をストリームに追加し、CBOR テキスト文字列値を作成します。QCborStreamWriter は、文字列全体を 1 つのチャンクとして書き込もうとします。

この関数は Qt 6.10 で導入されました。

appendTextString()、QCborStreamReader::isString()、およびQCborStreamReader::readString()も参照してください 。

void QCborStreamWriter::append(bool b)

ブール値 `b ` をストリームに追加し、CBOR False 値または CBOR True 値のいずれかを作成します。この関数は、以下の式と同等であり（また、そのように実装されています）：

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

appendNull()、appendUndefined()、QCborStreamReader::isBool()、およびQCborStreamReader::toBool()も参照してください 。

void QCborStreamWriter::append(double d)

浮動小数点数 `d ` をストリームに追加し、CBOR 64ビット倍精度浮動小数点値を作成します。QCborStreamWriter は、常に数値をそのまま追加し、その数値が NaN や無限大の標準形であるか、非正規形であるか、あるいはより短い形式で記述できるかどうかについては一切チェックを行いません。

以下のコードは、非正規数に関するチェックを除き、これらすべてのチェックを実行します。非正規数に関するチェックは、システムの FPU または浮動小数点エミュレーションによって直接考慮されることが想定されています。

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

double型が精度を損なうことなく整数型に変換できるかどうかの判定は、読者の課題として残しておきます。

QCborStreamReader::isDouble() およびQCborStreamReader::toDouble()も参照してください 。

void QCborStreamWriter::append(float f)

浮動小数点数 `f ` をストリームに追加し、CBOR 32ビット単精度浮動小数点値を作成します。以下のコードを使用すると、精度の損失がない場合に C++ の `double ` を `float ` に変換して追加したり、代わりに `double` を追加したりすることができます。

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

QCborStreamReader::isFloat() およびQCborStreamReader::toFloat()も参照してください 。

void QCborStreamWriter::append(qfloat16 f)

浮動小数点数 `f ` をストリームに追加し、CBOR 16ビット半精度浮動小数点値を作成します。以下のコードを使用すると、精度の損失がない場合に C++ の `float ` を `qfloat16 ` に変換して追加したり、代わりに `float` を追加したりすることができます。

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

QCborStreamReader::isFloat16() およびQCborStreamReader::toFloat16()も参照してください 。

void QCborStreamWriter::append(qint64 i)

64ビットの符号付き値 `i ` を CBOR ストリームに追加します。これにより、パラメータの符号に基づいて、CBOR の符号なし整数または CBOR の負の整数の値が生成されます。次の例では、値 0、-1、²³²、および `INT64_MAX` を書き込みます。

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

QCborStreamReader::isInteger() およびQCborStreamReader::toInteger()も参照してください 。

void QCborStreamWriter::append(quint64 u)

64ビットの符号なし値 `u ` を CBOR ストリームに追加し、CBOR 符号なし整数値を作成します。次の例では、値 `0`、<sup>`232</sup>`、および `UINT64_MAX` を書き込みます：

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

QCborStreamReader::isUnsignedInteger() およびQCborStreamReader::toUnsignedInteger()も参照してください 。

void QCborStreamWriter::append(std::nullptr_t)

ストリームにCBORのNULL値を追加します。この関数は以下と同等であり（かつ以下として実装されています）：パラメータは無視されます。

writer.append(QCborSimpleType::Null);

appendNull()、append （QCborSimpleType）、およびQCborStreamReader::isNull()も参照してください 。

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

str から始まるsize バイトのテキストをストリームに追加し、CBOR テキスト文字列値を作成します。QCborStreamWriter は、文字列全体を 1 つのチャンクで書き込もうとします。size が -1 の場合、この関数はstrlen(\a str) バイトを書き込みます。

str が指す文字列は、適切にUTF-8エンコードされていることが想定されています。QCborStreamWriter は、これが満たされているかどうかを検証しません。

append(QLatin1StringView)、append(QStringView)、QCborStreamReader::isString()、およびQCborStreamReader::readString()も参照してください 。

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

data から始まるlen バイトのデータをストリームに追加し、CBOR バイト文字列値を作成します。QCborStreamWriter は、文字列全体を 1 つのチャンクで書き込もうとします。

append()、appendTextString()、QCborStreamReader::isByteArray()、およびQCborStreamReader::readByteArray()も参照してください 。

void QCborStreamWriter::appendNull()

ストリームに CBOR Null 値を追加します。この関数は、以下と同等であり（また、以下として実装されています）：

writer.append(QCborSimpleType::Null);

append （std::nullptr_t）、append （QCborSimpleType）、およびQCborStreamReader::isNull()も参照してください 。

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

utf8 から始まるlen バイトのテキストをストリームに追加し、CBOR テキスト文字列値を作成します。QCborStreamWriter は、文字列全体を 1 つのチャンクで書き込むよう試みます。

utf8 が指す文字列は、適切に UTF-8 エンコードされていることが想定されます。QCborStreamWriter は、これが満たされているかどうかを検証しません。

関連項目： append(QLatin1StringView)、append(QStringView)、QCborStreamReader::isString()、およびQCborStreamReader::readString()。

void QCborStreamWriter::appendUndefined()

ストリームにCBORの未定義値を追加します。この関数は、以下と同等であり（また、以下として実装されています）：

writer.append(QCborSimpleType::Undefined);

append （QCborSimpleType）およびQCborStreamReader::isUndefined()も参照してください 。

QIODevice *QCborStreamWriter::device() const

このQCborStreamWriter オブジェクトが書き込みを行っているQIODevice を返します。このデバイスは、コンストラクタまたはsetDevice()のいずれかによって、あらかじめ設定されている必要があります。

このオブジェクトがQByteArray への書き込みによって作成された場合、この関数はQCborStreamWriter が所有するQBuffer の内部インスタンスを返します。

setDevice()も参照してください 。

bool QCborStreamWriter::endArray()

startArray() のいずれかのオーバーロードによって開始された配列を終了させ、配列に正しい数の要素が追加された場合は true を返します。この関数は、startArray() が使用されるたびに呼び出す必要があります。

false が返された場合は、アプリケーションでエラーが発生し、このストリームで回復不可能なエラーが発生したことを示します。その場合、QCborStreamWriter はqWarning() を使用して警告を出力します。

現在のコンテナが配列でない場合にこの関数を呼び出すこともエラーとなりますが、QCborStreamWriter は現在この状態を検出できません。

startArray()、startArray(quint64)、およびendMap()も参照してください 。

bool QCborStreamWriter::endMap()

startMap() のいずれかのオーバーロードによって開始されたマップを終了させ、配列に正しい数の要素が追加された場合は true を返します。この関数は、startMap() が使用されるたびに呼び出す必要があります。

false が返された場合は、アプリケーションでエラーが発生し、このストリームで回復不可能なエラーが発生したことを示します。その場合、QCborStreamWriter はqWarning() を使用して警告を出力します。

現在のコンテナがマップでない場合にこの関数を呼び出すこともエラーとなりますが、QCborStreamWriter は現在この状態を検出することはできません。

startMap()、startMap(quint64)、およびendArray()も参照してください 。

void QCborStreamWriter::setDevice(QIODevice *device)

このQCborStreamWriter オブジェクトが書き込みを行っているデバイスまたはバイト配列を、device に置き換えます。

device()も参照してください 。

void QCborStreamWriter::startArray()

CBORストリーム内で、長さが不定のCBOR配列を開始します。startArray()の呼び出しは、それぞれ1回のendArray()の呼び出しと対になる必要があり、現在のCBOR要素は配列の末尾まで拡張されます。

この関数によって作成される配列には、明示的な長さはありません。その代わりに、配列に含まれる要素によって長さが暗黙的に決定されます。ただし、長さが不定の配列の使用は、標準的なCBORエンコーディングに準拠していないことに注意してください。

次の例は、入力として渡された文字列のリストから要素を追加します。

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

startArray(quint64)、endArray()、startMap()、QCborStreamReader::isArray()、およびQCborStreamReader::isLengthKnown()も参照してください 。

void QCborStreamWriter::startArray(quint64 count)

CBORストリーム内に、count 個の要素を持つ明示的な長さのCBOR配列を開始します。startArrayの呼び出しごとに、endArray()の呼び出しを1回行う必要があり、現在のCBOR要素は配列の末尾まで拡張されます。

この関数によって作成される配列は明示的な長さを持つため、CBORストリームには正確にcount 個の項目を追加する必要があります。これより少ない、または多い項目を追加すると、endArray()の実行中にエラーが発生し、CBORストリームが破損します。ただし、明示的な長さの配列は、標準的なCBORエンコーディングで必須とされています。

次の例では、入力として渡されたQStringList に含まれるすべての文字列を末尾に追加しています：

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

サイズ制限：この関数のパラメータはquint64であり、一見すると配列には^{最大264-1個の要素}を格納できるように思われます。しかし、現在、QCborStreamWriter およびQCborStreamReader の両関数は、^{32ビットシステムでは232-2個}、^64ビットシステム^{では264-2個の}項目に制限されています。 また、QCborArray は現在、32ビットプラットフォームでは²²⁷要素、64ビットプラットフォームでは²⁵⁹要素に制限されている点にも注意してください。

startArray()、endArray()、startMap()、QCborStreamReader::isArray()、およびQCborStreamReader::isLengthKnown()も参照してください 。

void QCborStreamWriter::startMap()

CBORストリーム内で、長さが不定のCBORマップを開始します。startMap()の呼び出しごとに、endMap()の呼び出しを1回行う必要があり、現在のCBOR要素はマップの末尾まで拡張されます。

この関数によって作成されるマップには、明示的な長さはありません。その代わりに、マップに含まれる要素によって長さが暗黙的に決定されます。ただし、長さが不定のマップの使用は、標準的なCBORエンコーディングには準拠していないことに注意してください（標準的なエンコーディングでは、キーが一意であり、ソートされた順序でなければならないことも要件となっています）。

次の例は、入力として渡された int と文字列のペアのリストから要素を追加します。

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

startMap （quint64）、endMap （）、startArray （）、QCborStreamReader::isMap （）、およびQCborStreamReader::isLengthKnown （）も参照してください 。

void QCborStreamWriter::startMap(quint64 count)

CBORストリーム内で、count 個の項目からなる明示的な長さのCBORマップを開始します。各startMap呼び出しには、1回のendMap()呼び出しを組み合わせる必要があり、現在のCBOR要素はマップの終わりまで拡張されます。

この関数によって作成されるマップには明示的な長さがあるため、CBORストリームには正確にcount 組の項目を追加する必要があります。これより少ない、または多い項目を追加すると、endMap()の実行中にエラーが発生し、CBORストリームが破損します。ただし、明示的な長さを持つマップは、標準的なCBORエンコーディングで必須とされています。

次の例では、入力として渡されたQMap に含まれるすべての文字列を末尾に追加しています：

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

サイズ制限：この関数のパラメータはquint64であるため、マップには^{最大2⁶⁴-1組の}ペアを格納できるように思われます。しかし、QCborStreamWriter およびQCborStreamReader は、現在、32ビットシステムでは^2³¹-1個、64ビットシステムでは^{2⁶³-1個の}項目に制限されています。 また、QCborMap は現在、32ビットプラットフォームでは²²⁶要素、64ビットプラットフォームでは^258要素に制限されている点にも注意してください。

startMap()、endMap()、startArray()、QCborStreamReader::isMap()、およびQCborStreamReader::isLengthKnown()も参照してください 。

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

other をこのQCborStreamWriter インスタンスにコピー代入します。この関数は削除されます。