Класс QDataStream

Класс QDataStream обеспечивает сериализацию двоичных данных в QIODevice. Подробнее...

• Список всех членов, включая наследуемые

Примечание: Все функции в этом классе являются повторно входящими.

Открытые типы

Открытые функции

Связанные нечлены

Подробное описание

Поток данных — это двоичный поток закодированной информации, который на 100% независим от операционной системы, процессора или порядка байтов хост-компьютера. Например, поток данных, записанный ПК под управлением Windows, может быть прочитан Sun SPARC, работающим под Solaris.

Вы также можете использовать поток данных для чтения/записи незакодированных двоичных данных. Если вам нужен поток ввода для «парсинга», см. QTextStream.

Класс QDataStream реализует сериализацию основных типов данных C++, таких как char, short, int, char *, и т. д. Сериализация более сложных данных выполняется путём разбиения данных на примитивные единицы.

Поток данных тесно взаимодействует с QIODevice. QIODevice представляет собой среду ввода/вывода, из которой можно читать данные и в которую можно записывать данные. Примером устройства ввода/вывода является класс QFile.

Пример (запись двоичных данных в поток):

QFile file("file.dat");
file.open(QIODevice::WriteOnly);
QDataStream out(&file);   // we will serialize the data into the file
out << QString("the answer is");   // serialize a string
out << (qint32)42;        // serialize an integer

Пример (чтение двоичных данных из потока):

QFile file("file.dat");
file.open(QIODevice::ReadOnly);
QDataStream in(&file);    // read the data serialized from the file
QString str;
qint32 a;
in >> str >> a;           // extract "the answer is" and 42

Каждый элемент, записанный в поток, записывается в предопределённом двоичном формате, который зависит от типа элемента. Поддерживаемые типы Qt включают QBrush, QColor, QDateTime, QFont, QPixmap, QString, QVariant и многие другие. Полный список всех типов Qt, поддерживающих потоковую передачу данных, см. в Сериализация типов данных Qt.

Для целых чисел лучше всегда преобразовывать их в тип Qt для записи и читать обратно в тот же тип Qt. Это гарантирует, что вы получите целые числа нужного размера и защитит вас от различий в компиляторах и платформах.

Перечисления могут быть сериализованы через QDataStream без необходимости вручную определять операторы потоковой передачи. Классы перечислений сериализуются с использованием объявленного размера.

Например, char * строка записывается как 32-битовое целое число, равное длине строки, включая байт '\0', за которым следуют все символы строки, включая байт '\0'. При чтении char * строки сначала считываются 4 байта для создания 32-битового значения длины, а затем столько символов для char * строки, включая завершающий символ '\0'.

Начальное устройство ввода/вывода обычно устанавливается в конструкторе, но может быть изменено с помощью setDevice(). Если вы достигли конца данных (или если устройство ввода/вывода не задано), atEnd() вернёт true.

Версии

Двоичный формат QDataStream эволюционировал с Qt 1.0 и, вероятно, будет продолжать эволюционировать, отражая изменения в Qt. При вводе или выводе сложных типов очень важно убедиться, что используется та же версия потока (version()), что и для чтения и записи. Если вам нужна как обратная, так и прямая совместимость, вы можете закодировать номер версии в приложении:

stream.setVersion(QDataStream::Qt_4_0);

Если вы создаёте новый двоичный формат данных, такой как формат файла для документов, созданных вашим приложением, вы можете использовать QDataStream для записи данных в переносимый формат. Как правило, вы записываете заголовок с магической строкой и номером версии, чтобы дать себе возможность для расширения в будущем. Например:

QFile file("file.xxx");
file.open(QIODevice::WriteOnly);
QDataStream out(&file);

// Write a header with a "magic number" and a version
out << (quint32)0xA0B0C0D0;
out << (qint32)123;

out.setVersion(QDataStream::Qt_4_0);

// Write the data
out << lots_of_interesting_data;

Затем прочтите его с помощью:

QFile file("file.xxx");
file.open(QIODevice::ReadOnly);
QDataStream in(&file);

// Read and check the header
quint32 magic;
in >> magic;
if (magic != 0xA0B0C0D0)
    return XXX_BAD_FILE_FORMAT;

// Read the version
qint32 version;
in >> version;
if (version < 100)
    return XXX_BAD_FILE_TOO_OLD;
if (version > 123)
    return XXX_BAD_FILE_TOO_NEW;

if (version <= 110)
    in.setVersion(QDataStream::Qt_3_2);
else
    in.setVersion(QDataStream::Qt_4_0);

// Read the data
in >> lots_of_interesting_data;
if (version >= 120)
    in >> data_new_in_XXX_version_1_2;
in >> other_interesting_data;

Вы можете выбрать порядок байтов, который будет использоваться при сериализации данных. По умолчанию используется порядок байтов big endian (MSB первый). Изменение его на little endian нарушит переносимость (если читатель также не изменит порядок байтов на little endian). Мы рекомендуем сохранять этот параметр, если у вас нет особых требований.

Чтение и запись сырых двоичных данных

Возможно, вам потребуется напрямую читать/записывать собственные сырые двоичные данные в/из потока данных. Данные могут быть считаны из потока в предварительно выделенный char * с помощью readRawData(). Аналогично, данные могут быть записаны в поток с помощью writeRawData(). Обратите внимание, что любую кодировку/декодировку данных необходимо выполнить самостоятельно.

Аналогичная пара функций — readBytes() и writeBytes(). Эти функции отличаются от своих аналогов raw следующим образом: readBytes() считывает quint32, которая рассматривается как длина считываемых данных, затем столько байтов считывается в предварительно выделенный char *; writeBytes() записывает quint32, содержащую длину данных, за которой следуют данные. Обратите внимание, что любую кодировку/декодировку данных (кроме quint32 длины) необходимо выполнить самостоятельно.

Чтение и запись коллекций Qt

Классы контейнеров Qt также могут быть сериализованы в QDataStream. К ним относятся QList, QSet, QHash и QMap. Операторы потока объявлены как нечлены классов.

Чтение и запись других классов Qt

Помимо перегруженных операторов потока, документированных здесь, любые классы Qt, которые вы можете захотеть сериализовать в QDataStream, будут иметь соответствующие операторы потока, объявленные как нечлены класса:

    QDataStream &operator<<(QDataStream &, const QXxx &);
    QDataStream &operator>>(QDataStream &, QXxx &);

Например, вот операторы потока, объявленные как нечлены класса QImage:

    QDataStream & operator<< (QDataStream& stream, const QImage& image);
    QDataStream & operator>> (QDataStream& stream, QImage& image);

Чтобы узнать, есть ли у вашего любимого класса Qt аналогичные операторы потока, проверьте раздел «Связанные нечлены» на странице документации класса.

Использование транзакций чтения

Когда поток данных работает с асинхронным устройством, фрагменты данных могут прибывать в произвольные моменты времени. Класс QDataStream реализует механизм транзакций, который обеспечивает возможность атомарного чтения данных с помощью серии операторов потока. Например, вы можете обрабатывать неполные чтения из сокета, используя транзакцию в слоте, подключённом к сигналу readyRead():

in.startTransaction();
QString str;
qint32 a;
in >> str >> a; // try to read packet atomically

if (!in.commitTransaction())
    return;     // wait for more data

Если не получен полный пакет, этот код восстанавливает поток в начальную позицию, после чего вам нужно подождать, пока прибудут дополнительные данные.

См. также QTextStream и QVariant.

Документация по типам членов

Перечисление QDataStream::ByteOrder

Порядок байтов, используемый для чтения/записи данных.

Перечисление QDataStream::FloatingPointPrecision

Точность чисел с плавающей точкой, используемых для чтения/записи данных. Это повлияет только в том случае, если версия потока данных — Qt_4_6 или выше.

Предупреждение: Точность чисел с плавающей точкой должна быть установлена в том же значении для объекта, который записывает, и для объекта, который читает поток данных.

См. также setFloatingPointPrecision() и floatingPointPrecision().

Перечисление QDataStream::Status

Это перечисление описывает текущее состояние потока данных.

Перечисление QDataStream::Version

Это перечисление предоставляет символические синонимы для номеров версий формата сериализации данных.

См. также setVersion() и version().

Документация по членам-функциям

QDataStream::QDataStream(const QByteArray &a)

Создает потоковый объект для чтения, который работает с массивом байтов a. Используйте QDataStream(QByteArray*, int), если вы хотите писать в массив байтов.

Так как QByteArray не является подклассом QIODevice, внутри создается QBuffer для обертывания массива байтов.

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

Создает потоковый объект, который работает с массивом байтов a. Параметр mode описывает, как будет использоваться устройство.

В качестве альтернативы, вы можете использовать QDataStream(const QByteArray &), если вам нужно только читать из массива байтов.

Так как QByteArray не является подклассом QIODevice, внутри создается QBuffer для обертывания массива байтов.

QDataStream::QDataStream(QIODevice *d)

Создает потоковый объект, который использует устройство ввода-вывода d.

См. также setDevice() и device().

QDataStream::QDataStream()

Создает потоковый объект без устройства ввода-вывода.

См. также setDevice().

QDataStream::~QDataStream()

Удаляет потоковый объект.

Деструктор не повлияет на текущее устройство ввода-вывода, за исключением случаев, когда это внутреннее устройство ввода-вывода (например, QBuffer), обрабатывающее QByteArray, переданный в конструктор. В этом случае внутреннее устройство ввода-вывода уничтожается.

[since 5.7] void QDataStream::abortTransaction()

Прерывает операцию чтения.

Эта функция обычно используется для отбрасывания операции чтения после ошибок протокола высокого уровня или потери синхронизации потока.

Если вызов происходит во внутренней транзакции, прерывание делегируется внешней транзакции, а запущенные внутренние транзакции принудительно завершаются ошибкой.

Для внешней транзакции отбрасывается точка восстановления и любые внутренние дублированные данные потока. Не влияет на текущую позицию чтения потока.

Устанавливает состояние потока данных в

Эта функция была добавлена в Qt 5.7.

См. также startTransaction(), commitTransaction(), и rollbackTransaction().

bool QDataStream::atEnd() const

Возвращает true , если устройство ввода-вывода достигло конечной позиции (конец потока или файла) или если устройство ввода-вывода не задано; в противном случае возвращает false.

См. также QIODevice::atEnd().

QDataStream::ByteOrder QDataStream::byteOrder() const

Возвращает текущую установку порядка байтов — либо BigEndian, либо LittleEndian.

См. также setByteOrder().

[since 5.7] bool QDataStream::commitTransaction()

Завершает операцию чтения. Возвращает true , если во время транзакции не произошло ошибок чтения; в противном случае возвращает false.

Если вызов происходит во внутренней транзакции, завершение откладывается до вызова outermost commitTransaction(), rollbackTransaction() или abortTransaction().

В противном случае, если состояние потока указывает на чтение за пределами данных, эта функция восстанавливает данные потока до момента вызова startTransaction(). В этой ситуации вам нужно дождаться прихода дополнительных данных, после чего запустить новую транзакцию. Если поток данных прочитал поврежденные данные или любая из внутренних транзакций была прервана, эта функция прерывает транзакцию.

Эта функция была добавлена в Qt 5.7.

См. также startTransaction(), rollbackTransaction(), и abortTransaction().

QIODevice *QDataStream::device() const

Возвращает текущее устройство ввода-вывода, или nullptr , если устройство не установлено.

См. также setDevice().

QDataStream::FloatingPointPrecision QDataStream::floatingPointPrecision() const

Возвращает точность с плавающей запятой потока данных.

См. также FloatingPointPrecision и setFloatingPointPrecision().

QDataStream &QDataStream::readBytes(char *&s, uint &l)

Считывает буфер s из потока и возвращает ссылку на поток.

Буфер s выделяется с помощью new []. Удалите его с помощью оператора delete [].

Параметр l устанавливается в длину буфера. Если считанная строка пустая, l устанавливается в 0, а s устанавливается в nullptr.

Формат сериализации — это спецификатор длины quint32 сначала, затем l байтов данных.

См. также readRawData() и writeBytes().

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

Считывает не более len байтов из потока в s и возвращает количество считанных байтов. Если произошла ошибка, эта функция возвращает -1.

Буфер s должен быть предварительно выделен. Данные не декодируются.

См. также readBytes(), QIODevice::read() и writeRawData().

void QDataStream::resetStatus()

Сбрасывает состояние потока данных.

См. также Status, status() и setStatus().

[since 5.7] void QDataStream::rollbackTransaction()

Откатывает транзакцию чтения.

Эта функция обычно используется для отката транзакции, когда неполное чтение было обнаружено до подтверждения транзакции.

Если вызвана для внутренней транзакции, откат делегируется самой внешней транзакции, и все последующие начатые внутренние транзакции вынуждены завершиться ошибкой.

Для самой внешней транзакции восстанавливает данные потока до момента вызова startTransaction(). Если поток данных прочитал поврежденные данные или любая из внутренних транзакций была прервана, эта функция прерывает транзакцию.

Если предыдущие операции с потоком были успешны, устанавливает состояние потока данных в

Эта функция была добавлена в Qt 5.7.

См. также startTransaction(), commitTransaction() и abortTransaction().

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

Устанавливает порядок байтов сериализации на bo.

Параметр bo может быть QDataStream::BigEndian или QDataStream::LittleEndian.

По умолчанию используется big endian. Рекомендуется не изменять это значение, если нет особых требований.

См. также byteOrder().

void QDataStream::setDevice(QIODevice *d)

void QDataStream::setDevice(QIODevice *d)

Устанавливает устройство ввода-вывода на d, которое может быть nullptr для отмены текущего устройства ввода-вывода.

См. также 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.

Последующие вызовы setStatus() игнорируются до тех пор, пока не будет вызван resetStatus().

См. также Status, status() и resetStatus().

void QDataStream::setVersion(int v)

Устанавливает номер версии формата сериализации данных на v, значение перечисления Version.

Вам не обязательно устанавливать версию, если вы используете текущую версию Qt, но для собственных пользовательских двоичных форматов рекомендуется это делать; см. Versioning в подробном описании.

Для поддержки новых возможностей формат сериализации потока данных некоторых классов Qt изменился в некоторых версиях Qt. Если вы хотите прочитать данные, созданные более ранней версией Qt, или записать данные, которые может прочитать программа, скомпилированная с более ранней версией Qt, используйте эту функцию для изменения формата сериализации, используемого QDataStream.

Перечисление Version предоставляет символические константы для различных версий Qt. Например:

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

См. также version() и Version.

int QDataStream::skipRawData(int len)

Пропускает len байтов из устройства. Возвращает количество фактически пропущенных байтов или -1 при ошибке.

Это эквивалентно вызову readRawData() для буфера длиной len и игнорированию буфера.

См. также QIODevice::seek().

[since 5.7] void QDataStream::startTransaction()

Начинает новую транзакцию чтения в потоке.

Определяет точку восстановления в последовательности операций чтения. Для последовательных устройств данные чтения будут дублироваться внутри для восстановления в случае неполных чтений. Для устройств с произвольным доступом эта функция сохраняет текущую позицию потока. Вызовите commitTransaction(), rollbackTransaction() или abortTransaction() для завершения текущей транзакции.

После начала транзакции последующие вызовы этой функции сделают транзакцию рекурсивной. Внутренние транзакции действуют как агенты самой внешней транзакции (то есть сообщают о состоянии операций чтения самой внешней транзакции, которая может восстановить позицию потока).

Примечание: Восстановление до момента вызова вложенного startTransaction() не поддерживается.

При возникновении ошибки во время транзакции (включая сбой внутренней транзакции), чтение из потока приостанавливается (все последующие операции чтения возвращают пустые/нулевые значения), и последующие внутренние транзакции вынуждены завершиться ошибкой. Начало новой самой внешней транзакции восстанавливает состояние. Это поведение делает ненужной отдельную проверку ошибок для каждой операции чтения.

Эта функция была добавлена в Qt 5.7.

См. также commitTransaction(), rollbackTransaction() и abortTransaction().

QDataStream::Status QDataStream::status() const

Возвращает состояние потока данных.

См. также Status, setStatus() и resetStatus().

int QDataStream::version() const

Возвращает номер версии формата сериализации данных.

См. также setVersion() и Version.

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

Записывает спецификатор длины len и буфер s в поток и возвращает ссылку на поток.

len сериализуется как quint32, за которым следуют len байтов из s. Обратите внимание, что данные не кодируются.

См. также writeRawData() и readBytes().

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

Записывает len байтов из s в поток. Возвращает количество фактически записанных байтов или -1 при ошибке. Данные не кодируются.

См. также writeBytes(), QIODevice::write() и readRawData().

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

Записывает знаковое байтовое значение i в поток и возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает беззнаковое байтовое значение i в поток и возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает знаковое 16-битное целое число i в поток и возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает беззнаковое 16-битное целое число i в поток и возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает знаковое 32-битное целое число i в поток и возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает беззнаковое целое число i в поток как 32-битное беззнаковое целое число (quint32). Возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает знаковое 64-битное целое число i в поток и возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает беззнаковое 64-битное целое число i в поток и возвращает ссылку на поток.

[since 5.9] QDataStream &QDataStream::operator<<(std::nullptr_t ptr)

Это перегруженный метод.

Эмулирует запись значения std::nullptr_t, ptr, в поток и возвращает ссылку на поток. Данный метод не записывает ничего в поток, так как значения std::nullptr_t хранятся как 0 байты.

Этот метод был добавлен в Qt 5.9.

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

Записывает булевое значение i в поток. Возвращает ссылку на поток.

[since 5.9] QDataStream &QDataStream::operator<<(qfloat16 f)

Это перегруженный метод.

Записывает число с плавающей точкой f в поток в стандартном формате IEEE 754. Возвращает ссылку на поток.

Этот метод был добавлен в Qt 5.9.

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

Это перегруженный метод.

Записывает число с плавающей точкой f в поток в стандартном формате IEEE 754. Возвращает ссылку на поток.

См. также setFloatingPointPrecision().

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

Это перегруженный метод.

Записывает число с плавающей точкой f в поток в стандартном формате IEEE 754. Возвращает ссылку на поток.

См. также setFloatingPointPrecision().

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

Это перегруженный метод.

Записывает строку s с завершением '\0' в поток и возвращает ссылку на поток.

Строка сериализуется с использованием writeBytes().

См. также writeBytes() и writeRawData().

[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>>(qint8 &i)

Считывает знаковое байтовое значение из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Считывает беззнаковое байтовое значение из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Считывает знаковое 16-битное целое число из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Считывает беззнаковое 16-битное целое число из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Считывает знаковое 32-битное целое число из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Считывает беззнаковое 32-битное целое число из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Считывает знаковое 64-битное целое число из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Считывает беззнаковое 64-битное целое число из потока в i и возвращает ссылку на поток.

[since 5.9] QDataStream &QDataStream::operator>>(std::nullptr_t &ptr)

Это перегруженный метод.

Эмулирует считывание значения std::nullptr_t из потока в ptr и возвращает ссылку на поток. Данный метод не считывает ничего из потока, так как значения std::nullptr_t хранятся как 0 байты.

Этот метод был добавлен в Qt 5.9.

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

Считывает булевое значение из потока в i. Возвращает ссылку на поток.

[since 5.9] QDataStream &QDataStream::operator>>(qfloat16 &f)

Это перегруженный метод.

Считывает число с плавающей точкой из потока в f в стандартном формате IEEE 754. Возвращает ссылку на поток.

Этот метод был добавлен в Qt 5.9.

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

Это перегруженный метод.

Считывает число с плавающей точкой из потока в f, используя стандартный формат IEEE 754. Возвращает ссылку на поток.

См. также setFloatingPointPrecision().

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

Это перегруженный метод.

Считывает число с плавающей точкой из потока в f, используя стандартный формат IEEE 754. Возвращает ссылку на поток.

См. также setFloatingPointPrecision().

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

Это перегруженный метод.

Считывает завершающуюся нулём строку s из потока и возвращает ссылку на поток.

Строка десериализуется с помощью readBytes().

Память для строки выделяется с помощью 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.