Класс QDataStream

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

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

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

Общедоступные типы

Общедоступные функции

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

Поток данных — это двоичный поток закодированной информации, который полностью независим от операционной системы, процессора или порядка байтов хост-компьютера. Например, поток данных, записанный ПК под управлением 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. Это гарантирует, что вы получите целые числа нужного размера и избавит вас от проблем с компилятором и платформой.

Например, строка 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(). Они отличаются от своих сырых аналогов следующим образом: readBytes() считывает quint32, который принимается как длина считываемых данных, затем это количество байтов считывается в предварительно выделенный char *; writeBytes() записывает quint32, содержащую длину данных, за которым следуют сами данные. Обратите внимание, что любое кодирование/декодирование данных (кроме quint32 длины) должно выполняться вами.

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

Классы контейнеров Qt также могут быть сериализованы в QDataStream. К ним относятся QList, QLinkedList, QVector, 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, QIODevice::OpenMode mode)

Создаёт поток данных, работающий с массивом байтов, a. Значение mode определяет способ использования устройства.

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

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

QDataStream::QDataStream(QIODevice *d)

Создаёт поток данных, использующий устройство ввода/вывода d.

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

QDataStream::QDataStream()

Создаёт поток данных без устройства ввода/вывода.

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

QDataStream::~QDataStream()

Удаляет поток данных.

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

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().

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

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

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

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

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.

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

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

См. также 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 и игнорированию буфера.

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

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

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 в поток и возвращает ссылку на поток.

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

Это перегруженная функция.

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

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

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

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

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 в поток и возвращает ссылку на поток.

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

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

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 и возвращает ссылку на поток.

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

Это перегруженная функция.

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

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

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

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

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().