QDataStream Class

成员函数文档

QDataStream::QDataStream()

构建一个不包含 I/O 设备的数据流。

另请参阅 setDevice()。

[explicit] QDataStream::QDataStream(QIODevice *d)

构建一个使用 I/O 设备d 的数据流。

另请参阅 setDevice() 和device()。

QDataStream::QDataStream(const QByteArray &a)

构建一个基于字节数组 `a` 的只读数据流。若需向字节数组写入数据，请使用 `QDataStream(QByteArray*, int)`。

由于QByteArray 不是QIODevice 的子类，因此系统会在内部创建一个QBuffer 来封装该字节数组。

QDataStream::QDataStream(QByteArray *a, QIODeviceBase::OpenMode mode)

构建一个对字节数组a 进行操作的数据流。mode 描述了该设备的使用方式。

此外，若您仅需从字节数组中读取数据，也可使用 QDataStream(constQByteArray &)。

由于QByteArray 并非QIODevice 的子类，因此系统会在内部创建一个QBuffer 来封装该字节数组。

[noexcept] QDataStream::~QDataStream()

销毁数据流。

该析构函数不会影响当前的 I/O 设备，除非该设备是正在处理构造函数中传入的 `QByteArray ` 的内部 I/O 设备（例如 `QBuffer`），在这种情况下，该内部 I/O 设备将被销毁。

void QDataStream::abortTransaction()

中止读取事务。

该函数通常用于在发生更高层协议错误或流同步丢失后丢弃事务。

如果在内部事务上调用此函数，则中止操作将委托给最外层的事务，并且随后启动的内部事务将被迫失败。

对于最外层事务，将丢弃恢复点以及流中任何内部复制的数据。不会影响流的当前读取位置。

将数据流的状态设置为

另请参阅 startTransaction()、commitTransaction() 和rollbackTransaction()。

bool QDataStream::atEnd() const

如果 I/O 设备已到达末尾（流或文件的末尾）或未设置 I/O 设备，则返回true ；否则返回false 。

另请参阅 QIODevice::atEnd()。

QDataStream::ByteOrder QDataStream::byteOrder() const

返回当前的字节序设置——BigEndian 或LittleEndian 之一。

另请参阅 setByteOrder()。

bool QDataStream::commitTransaction()

完成一次读取事务。如果事务期间未发生读取错误，则返回true ；否则返回false 。

如果在内部事务中调用此函数，提交操作将被推迟，直到最外层的 commitTransaction()、rollbackTransaction() 或abortTransaction() 调用发生时才执行。

否则，如果流状态表明已读到数据末尾之后，该函数将流数据恢复到调用startTransaction() 时的位置。 当出现这种情况时，您需要等待更多数据到达，之后再开始一个新的事务。如果数据流读取了损坏的数据，或者任何内部事务被中止，则该函数将中止当前事务。

另请参阅 startTransaction()、rollbackTransaction() 和abortTransaction()。

QIODevice *QDataStream::device() const

返回当前设置的 I/O 设备；如果当前未设置任何设备，则返回 `nullptr `。

另请参阅 setDevice()。

QDataStream::FloatingPointPrecision QDataStream::floatingPointPrecision() const

返回数据流的浮点精度。

另请参阅 FloatingPointPrecision 和setFloatingPointPrecision()。

[since 6.7] QDataStream &QDataStream::readBytes(char *&s, qint64 &l)

从流中读取缓冲区s ，并返回对该流的引用。

缓冲区s 使用new [] 分配。请使用delete [] 运算符将其销毁。

l 参数被设置为缓冲区的长度。如果读取的字符串为空，则l 被设置为 0，s 被设置为nullptr 。

序列化格式为：首先是长度指定符，随后是l 字节的数据。 如果版本小于 6.7 或元素个数小于 0xfffffffe (2^32 - 2)，则长度指定符为一个 quint32；否则，先有一个扩展值 0xfffffffe，后跟一个包含实际值的 quint64。 此外，对于支持 isNull() 的容器，其编码形式为一个所有位均设为 1 且不包含数据的单个 quint32。

该函数在 Qt 6.7 中引入。

另请参阅 readRawData() 和writeBytes()。

qint64 QDataStream::readRawData(char *s, qint64 len)

从流中最多读取len 字节数据到s ，并返回读取的字节数。如果发生错误，该函数返回 -1。

缓冲区s 必须预先分配。数据不会被解码。

另请参阅 readBytes()、QIODevice::read()，以及writeRawData()。

void QDataStream::resetStatus()

重置数据流的状态。

另请参阅 Status 、status() 以及setStatus()。

void QDataStream::rollbackTransaction()

回滚一个读取事务。

当在提交事务之前检测到未完成的读取时，通常使用此函数来回滚事务。

如果对内部事务调用此函数，回滚操作将委托给最外层的事务，并且随后启动的内部事务将被迫失败。

对于最外层事务，将流数据恢复到调用 `startTransaction()` 时的状态。如果数据流读取了损坏的数据，或者任何内层事务被中止，则此函数将中止该事务。

如果之前的流操作成功，则将数据流的状态设置为

另请参阅 startTransaction()、commitTransaction() 和abortTransaction()。

void QDataStream::setByteOrder(QDataStream::ByteOrder bo)

将序列化字节顺序设置为bo 。

bo 参数可以是QDataStream::BigEndian 或QDataStream::LittleEndian 。

默认设置为大端字节序。除非有特殊要求，否则建议保留此设置。

另请参阅 byteOrder()。

void QDataStream::setDevice(QIODevice *d)

void QDataStream::setDevice(QIODevice *d)

将 I/O 设备设置为d ，其中nullptr 可用于取消设置当前 I/O 设备。

另请参阅 device()。

void QDataStream::setFloatingPointPrecision(QDataStream::FloatingPointPrecision precision)

将数据流的浮点精度设置为precision 。如果浮点精度为DoublePrecision ，且数据流版本为Qt_4_6 或更高，则所有浮点数都将以64位精度进行读写。 如果浮点精度为SinglePrecision ，且版本为Qt_4_6 或更高，则所有浮点数都将以 32 位精度进行读写。

对于Qt_4_6 之前的版本，数据流中浮点数的精度取决于调用的流操作符。

默认值为DoublePrecision 。

请注意，此属性不会影响qfloat16 实例的序列化或反序列化。

另请参阅 floatingPointPrecision()。

void QDataStream::setStatus(QDataStream::Status status)

将数据流的状态设置为给定的status 。

在调用resetStatus() 之前，后续对 setStatus() 的调用将被忽略。

另请参阅 Status 、status() 和resetStatus()。

void QDataStream::setVersion(int v)

将数据序列化格式的版本号设置为v ，该值属于Version 枚举。

如果您使用的是 Qt 的当前版本，则无需设置版本号，但对于您自己的自定义二进制格式，我们建议您进行设置；请参阅“详细说明”中的Versioning 。

为了适应新功能，某些 Qt 类的数据流序列化格式在某些 Qt 版本中发生了变化。 如果您想读取由早期版本的 Qt XML 生成的数据，或者写入可被使用早期版本的 Qt XML 编译的程序读取的数据，请使用此函数来修改QDataStream 所使用的序列化格式。

Version 枚举为不同版本的 Qt 提供了符号常量。例如：

QDataStream out(&file);
out.setVersion(QDataStream::Qt_4_0);

另请参阅 version() 和Version 。

qint64 QDataStream::skipRawData(qint64 len)

从设备中跳过len 字节。返回实际跳过的字节数；若发生错误，则返回 -1。

这相当于对长度为len 的缓冲区调用readRawData()，并忽略该缓冲区。

另请参见 QIODevice::seek()。

void QDataStream::startTransaction()

在流上启动一个新的读取事务。

在读取操作序列中定义一个可恢复点。对于顺序设备，读取数据将在内部被复制，以便在读取不完整时进行恢复。对于随机访问设备，此函数会保存流的当前位置。调用commitTransaction()、rollbackTransaction() 或abortTransaction() 来结束当前事务。

一旦事务启动，后续对该函数的调用将使事务成为递归事务。内部事务作为最外层事务的代理（即向最外层事务报告读取操作的状态，从而使最外层事务能够恢复流的位置）。

当事务期间发生错误（包括内部事务失败）时，数据流的读取将暂停（所有后续读取操作均返回空值或零值），且后续的内部事务将强制失败。启动一个新的最外层事务可从该状态恢复。这种行为使得无需对每个读取操作单独进行错误检查。

另请参阅 commitTransaction()、rollbackTransaction() 和abortTransaction()。

QDataStream::Status QDataStream::status() const

返回数据流的状态。

另请参阅 Status 、setStatus() 以及resetStatus()。

int QDataStream::version() const

返回数据序列化格式的版本号。

另请参阅 setVersion() 和Version 。

QDataStream &QDataStream::writeBytes(const char *s, qint64 len)

将长度限定符 `len ` 和缓冲区 `s ` 写入流，并返回该流的引用。

len 将被序列化为一个 quint32 值和一个可选的 quint64 值，随后是来自s 的len 字节数据。请注意，数据未经过编码。

另请参阅 writeRawData() 和readBytes()。

qint64 QDataStream::writeRawData(const char *s, qint64 len)

将s 中的len 字节写入流中。返回实际写入的字节数；若发生错误，则返回 -1。数据未经过编码。

另请参阅 writeBytes()、QIODevice::write() 和readRawData()。

[explicit noexcept, since 6.10] QDataStream::operator bool() const

返回该流是否无错误（status() 返回Ok ）。

该函数在 Qt 6.10 中引入。

QDataStream &QDataStream::operator<<(qint8 i)

将一个带符号的字节（i ）写入流中，并返回该流的引用。

QDataStream &QDataStream::operator<<(bool i)

将布尔值i 写入流中。返回对该流的引用。

[since 6.0] QDataStream &QDataStream::operator<<(char16_t c)

将字符c 写入流中。返回对该流的引用

该函数在 Qt 6.0 中引入。

[since 6.0] QDataStream &QDataStream::operator<<(char32_t c)

将字符c 写入流中。返回对该流的引用

该函数在 Qt 6.0 中引入。

QDataStream &QDataStream::operator<<(const char *s)

将以“\0 ”结尾的字符串s 写入流，并返回该流的引用。

该字符串使用writeBytes() 进行序列化。

另请参阅 writeBytes() 和writeRawData()。

QDataStream &QDataStream::operator<<(double f)

将浮点数f 按标准IEEE 754格式写入流中。返回对该流的引用。

另请参阅 setFloatingPointPrecision()。

QDataStream &QDataStream::operator<<(float f)

将浮点数f 按标准IEEE 754格式写入流中。返回对该流的引用。

另请参阅 setFloatingPointPrecision()。

QDataStream &QDataStream::operator<<(qint16 i)

将一个有符号的 16 位整数（i ）写入流，并返回该流的引用。

QDataStream &QDataStream::operator<<(qint32 i)

将一个有符号的 32 位整数i 写入流，并返回该流的引用。

QDataStream &QDataStream::operator<<(qint64 i)

将一个有符号的 64 位整数（i ）写入流，并返回该流的引用。

QDataStream &QDataStream::operator<<(quint16 i)

将一个无符号 16 位整数i 写入流，并返回该流的引用。

QDataStream &QDataStream::operator<<(quint32 i)

将一个无符号整数i 作为32位无符号整数（quint32）写入流中。返回对该流的引用。

QDataStream &QDataStream::operator<<(quint64 i)

将一个无符号 64 位整数i 写入流，并返回该流的引用。

QDataStream &QDataStream::operator<<(quint8 i)

将一个无符号字节（i ）写入流，并返回该流的引用。

QDataStream &QDataStream::operator<<(std::nullptr_t ptr)

模拟将std::nullptr_t （ptr ）写入流，并返回该流的引用。该函数实际上并未向流中写入任何内容，因为std::nullptr_t 的值会被存储为0字节。

QDataStream &QDataStream::operator>>(bool &i)

从流中读取一个布尔值并将其赋值给i 。返回对该流的引用。

QDataStream &QDataStream::operator>>(qint8 &i)

从流中读取一个带符号的字节并将其赋值给i ，并返回对该流的引用。

QDataStream &QDataStream::operator>>(char *&s)

从流中读取字符串s ，并返回对该流的引用。

该字符串使用readBytes() 进行反序列化，其序列化格式为：首先是quint32 长度指定符，随后是相应数量字节的数据。生成的字符串始终以 '\0' 结尾。

字符串的内存空间通过 `new [] ` 分配——调用方必须使用 `delete []` 将其销毁。

另请参阅 readBytes() 和readRawData()。

[since 6.0] QDataStream &QDataStream::operator>>(char16_t &c)

从流中读取一个16位宽的字符到c 中，并返回该流的引用。

该函数在 Qt 6.0 中引入。

[since 6.0] QDataStream &QDataStream::operator>>(char32_t &c)

从流中读取一个32位宽的字符到c 中，并返回对该流的引用。

该函数在 Qt 6.0 中引入。

QDataStream &QDataStream::operator>>(double &f)

从流中读取一个浮点数并将其赋值给f ，采用标准IEEE 754格式。返回对该流的引用。

另请参阅 setFloatingPointPrecision()。

QDataStream &QDataStream::operator>>(float &f)

从流中读取一个浮点数并将其赋值给f ，采用标准IEEE 754格式。返回对该流的引用。

另请参阅 setFloatingPointPrecision()。

QDataStream &QDataStream::operator>>(qint16 &i)

从流中读取一个有符号的 16 位整数并将其赋值给 `i`，并返回该流的引用。

QDataStream &QDataStream::operator>>(qint32 &i)

从流中读取一个有符号的 32 位整数并将其赋值给 `i`，并返回对该流的引用。

QDataStream &QDataStream::operator>>(qint64 &i)

从流中读取一个有符号的 64 位整数并将其赋值给 `i`，并返回对该流的引用。

QDataStream &QDataStream::operator>>(quint16 &i)

从流中读取一个无符号 16 位整数并将其赋值给 `i`，并返回对该流的引用。

QDataStream &QDataStream::operator>>(quint32 &i)

从流中读取一个无符号 32 位整数并将其赋值给 `i`，并返回对该流的引用。

QDataStream &QDataStream::operator>>(quint64 &i)

从流中读取一个无符号 64 位整数，将其赋值给 `i`，并返回该流的引用。

QDataStream &QDataStream::operator>>(quint8 &i)

从流中读取一个无符号字节到i 中，并返回对该流的引用。

QDataStream &QDataStream::operator>>(std::nullptr_t &ptr)

模拟从流中读取std::nullptr_t 并将其写入ptr ，并返回对该流的引用。该函数实际上并未从流中读取任何内容，因为std::nullptr_t 的值被存储为0字节。