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値をストリームに追加する。この関数は（と同じように実装された）等価である：

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

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

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

startMap()、startMap(quint64)、endArray()も参照の こと。

void QCborStreamWriter::setDevice(QIODevice *device)

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

device()も参照のこと 。

void QCborStreamWriter::startArray()

不定長のCBOR Arrayを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 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マップを開始する。各 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()も参照のこと 。