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() を最初に呼び出す前に、デバイスをオープンする必要があります。このコンストラクタは、QFile 、QProcess 、QTcpSocket など、QIODevice から派生するすべてのクラスで使用できます。

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

以下の例では、空のマップをファイルに書き込んでいる：

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

QCborStreamWriter はdevice の所有権を持ちません。

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

[noexcept] QCborStreamWriter::~QCborStreamWriter()

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

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

void QCborStreamWriter::append(QCborKnownTags tag)

これはオーバーロードされた関数である。

CBORタグtag をストリームに追加し、CBORタグ値を作成する。すべてのタグの後には、そのタグが意味を持つ別の型が続かなければならない。

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

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

QCborStreamReader::isTag() およびQCborStreamReader::toTag()も参照 。

void QCborStreamWriter::append(QCborNegativeInteger n)

これはオーバーロードされた関数です。

CBORストリームに64ビットの負の値n を追加します。QCborNegativeIntegerは64ビット列挙型で、書き込みたい負の数の絶対値を保持します。nがゼロの場合、書き込まれる値は^264に相当する（つまり、-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がサポートしていない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 Text String 値を作成します。QCborStreamWriter は、文字列全体を 1 チャンクで書き込もうとします。

次の例は、単純な Latin-1 文字列リテラルをストリームに追加します：

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

性能上の注意：CBORはすべての文字列がUTF-8でエンコードされることを要求しているので、この関数は文字列内の文字を繰り返し処理して、その内容がUS-ASCIIかどうかを判断します。文字列がUS-ASCII以外の文字を含んでいることが判明した場合、メモリを確保してUTF-8に変換します。このチェックが不要な場合は、代わりにappendTextString() を使用する。

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()も参照 。

void QCborStreamWriter::append(bool b)

これはオーバーロードされた関数です。

ブール値b をストリームに追加し、CBOR False値またはCBOR True値を作成します。この関数は、CBOR False 値または CBOR True 値をストリームに追加します：

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

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

void QCborStreamWriter::append(const QByteArray &ba)

これはオーバーロードされた関数である。

バイト配列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(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 = 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 = f;
       if (qIsNaN(f) || f16 == f)
           writer.append(f16);
       else
           writer.append(f);
   }

QCborStreamReader::isFloat16() およびQCborStreamReader::toFloat16()も参照の こと。

void QCborStreamWriter::append(qint64 i)

これはオーバーロードされた関数です。

CBORストリームに64ビット符号付き値i を追加します。これは、パラメータの符号に基づいてCBOR Unsigned IntegerまたはCBOR NegativeInteger値を作成します。以下の例では、値 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)

これはオーバーロードされた関数です。

CBORストリームに64ビット符号なし値u を追加し、CBOR符号なし整数値を作成します。以下の例では、値 0、²³²、および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値をストリームに追加します。この関数は、CBOR Null 値をストリームに追加します：パラメータは無視されます。

   writer.append(QCborSimpleType::Null);

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

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

これはオーバーロードされた関数です。

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

str が指す文字列は、適切にエンコードされたUTF-8であることが期待される。QCborStreamWriter は、それが正しいかどうかの検証は行わない。

append()のQLatin1StringView オーバーロードとは異なり、この関数は2GBに制限されない。ただし、QCborStreamReader もQCborValue も、2 GB を超えるテキスト文字列を含む CBOR ストリームの読み込みには対応していないことに注意。

append(QLatin1StringView),append(QStringView),QCborStreamReader::isString(),QCborStreamReader::readString()も参照 。

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

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

append() のQByteArray オーバーロードとは異なり、この関数はQByteArray のサイズ制限に制限されない。ただし、QCborStreamReader::readByteArray() もQCborValue も、2 GBを超えるバイト配列を持つCBORストリームの読み込みには対応していない。

append()、appendTextString()、QCborStreamReader::isByteArray()、QCborStreamReader::readByteArray()も参照 。

void QCborStreamWriter::appendNull()

CBOR Null値をストリームに追加します。この関数は、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 Text String 値を作成します。QCborStreamWriter は、文字列全体を 1 チャンクで書き込もうとします。

utf8 が指す文字列は、適切にエンコードされたUTF-8であることが期待される。QCborStreamWriter は、それが正しいかどうかの検証は行わない。

append() のQLatin1StringView オーバーロードとは異なり、この関数は 2GB に制限されない。ただし、QCborStreamReader::readString() もQCborValue も、2 GB を超えるテキスト文字列を含む CBOR ストリームの読み込みには対応していないことに注意。

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() のいずれかのオーバーロードによって開始されたマップを終了し、正しい要素数が配列に追加された場合に真を返す。この関数は、startMap() が使用されるたびに呼び出されなければならない。

falseが返された場合は、アプリケーションにエラーがあり、このストリー ムに回復不可能なエラーが発生したことを示す。QCborStreamWriter 、このようなエ ラーが発生した場合は、qWarning （）を使用して警告も記述する。

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

startMap （）、startMap （quint64）、endArray （）も参照 。

void QCborStreamWriter::setDevice(QIODevice *device)

このQCborStreamWriter オブジェクトが書き込んでいるデバイスまたはバイト配列をdevice に置き換える。

device()も参照 。

void QCborStreamWriter::startArray()

CBORストリームに長さ不定のCBOR Arrayを開始する。各 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 Arrayを開始する。各 startArray 呼び出しは、1 つのendArray() 呼び出しと対になっていなければならず、現在の 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 Mapを開始する。各 startMap() 呼び出しは、1 つのendMap() 呼び出しと対になっていなければならず、現在の 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 Mapを開始する。各 startMap 呼び出しは、1つのendMap() 呼び出しと対になっていなければならず、現在の CBOR 要素はマップの終わりまで拡張される。

この関数によって作成されたマップは明示的な長さを持つため、count のペアのアイテムが CBORストリームに追加されなければならない。これより少なかったり多かったりする項目を追加すると、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であり、マップに^264-1ペアまで許容するように見える。しかし、QCborStreamWriter とQCborStreamReader は現在、32ビットシステムでは^231-1項目、64ビットシステムでは^263-1項目に制限されている。また、QCborMap は現在、32ビットプラットフォームでは²²⁶要素、64ビットプラットフォームでは²⁵⁸要素に制限されていることに注意してください。

startMap(),endMap(),startArray(),QCborStreamReader::isMap(),QCborStreamReader::isLengthKnown()も参照のこと 。