QCborStreamWriter Class

成员函数文档

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

创建一个 QCborStreamWriter 对象，该对象将流追加到 `data` 中。所有流数据都会立即写入字节数组，无需刷新任何缓冲区。

以下示例将一个数字写入字节数组，然后返回该数组。

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

QCborStreamWriter 不会获取data 的所有权。

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

创建一个 QCborStreamWriter 对象，该对象将流写入device 。在首次调用append() 之前，必须先打开该设备。此构造函数可与任何继承自QIODevice 的类配合使用，例如QFile 、QProcess 或QTcpSocket 。

由于 QCborStreamWriter 不支持缓冲，因此每次调用append() 都会触发一次或多次对设备write() 方法的调用。

以下示例将一个空映射写入文件：

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 将尝试一次性写入整个字符串。

以下示例将加载文件内容并将其追加到流中：

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 为零，则写入的值将等同于²⁶⁴（即 -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())));

请注意，该函数可用于编码无法容纳在标准计算机 64 位有符号整数范围内的数值，例如qint64 。也就是说，如果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）的简单类型，以及类型 32 的简单类型——Qt 不支持该类型。

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 将尝试将整个字符串一次性写入。

以下示例将一个简单的 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 将尝试一次性将整个字符串写入。

以下示例将任意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 将尝试将整个字符串一次性写入。

该函数在 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、²³²和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 空值追加到流中。此函数等同于（且实现方式为）：该参数将被忽略。

writer.append(QCborSimpleType::Null);

另请参阅 appendNull()、append(QCborSimpleType) 以及QCborStreamReader::isNull()。

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

将从str 开始的size 字节文本追加到流中，并生成一个 CBOR 文本字符串值。QCborStreamWriter 将尝试将整个字符串作为单个数据块写入。如果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 将尝试一次性写入整个字符串。

另请参阅 append()、appendTextString()、QCborStreamReader::isByteArray() 和QCborStreamReader::readByteArray()。

void QCborStreamWriter::appendNull()

将一个 CBOR 空值追加到流中。该函数等同于（且实现方式与）以下内容：

writer.append(QCborSimpleType::Null);

另请参见 append(std::nullptr_t)、append(QCborSimpleType) 以及QCborStreamReader::isNull()。

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

将从utf8 开始的len 字节文本追加到流中，从而创建一个 CBOR 文本字符串值。QCborStreamWriter 将尝试将整个字符串作为单个数据块写入。

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() 都必须与一次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() 调用配对，且当前 CBOR 元素将延伸至数组末尾。

此函数创建的数组具有显式长度，因此必须向 CBOR 流中添加恰好count 个元素。若添加的元素数量少于或多于此数，将在调用endArray() 时导致失败，且 CBOR 流将遭到破坏。然而，显式长度数组是规范 CBOR 编码所必需的。

以下示例将作为输入传递的QStringList 中找到的所有字符串追加到CBOR流中：

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

大小限制：该函数的参数为 quint64，这似乎意味着数组中最多可包含^2⁶⁴-1 个元素。然而，目前在 32 位系统上，QCborStreamWriter 和QCborStreamReader 均限制为^2³²-2 个项目；在 64 位系统上则限制为^2⁶⁴-2 个项目。 另请注意，QCborArray 目前在 32 位平台上最多支持²²⁷个元素，在 64 位平台上最多支持²⁵⁹个元素。

另请参阅 startArray()、endArray()、startMap()、QCborStreamReader::isArray() 和QCborStreamReader::isLengthKnown()。

void QCborStreamWriter::startMap()

在 CBOR 流中启动一个长度未定的 CBOR 映射。每次调用 startMap() 都必须与一次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 映射。每次调用 startMap 时，必须配合一次endMap() 调用，且当前 CBOR 元素将一直延伸至该映射的末尾。

由该函数创建的映射具有显式长度，因此必须向 CBOR 流中添加恰好count 对的项目。添加的项目数量少于或多于此数将导致endMap() 调用失败，并且 CBOR 流将遭到破坏。然而，规范的 CBOR 编码要求使用显式长度的映射。

以下示例将作为输入传递的QMap 中找到的所有字符串追加到CBOR流中：

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 位平台上的限制为²⁵⁸个元素。

另请参阅 startMap()、endMap()、startArray()、QCborStreamReader::isMap() 以及QCborStreamReader::isLengthKnown()。

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

将other 复制并赋值给此QCborStreamWriter 实例。该函数已被删除。