Класс 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 (старший байт первым). Изменение его на little-endian нарушает портативность (если читатель также не переключается на little-endian). Мы рекомендуем сохранить это значение, если у вас нет особых требований.

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

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

Аналогичная пара функций — readBytes() и writeBytes(). Они отличаются от своих необработанных аналогов следующим образом: 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(), чтобы завершить текущую транзакцию.

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

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

Эта функция была добавлена в 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 с завершающим нулём в поток и возвращает ссылку на поток.

Строка сериализуется с помощью 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 с завершением '\0' из потока и возвращает ссылку на поток.

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