Класс QDataStream

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

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

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

Публичные типы

Публичные функции

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

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

Например, 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 подобные операторы потока, проверьте раздел Связанные внеклассовые члены на странице документации класса.

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

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

enum QDataStream::ByteOrder

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

enum QDataStream::FloatingPointPrecision

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

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

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

enum QDataStream::Status

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

enum QDataStream::Version

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

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

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

QDataStream::QDataStream()

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

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

QDataStream::QDataStream(QIODevice *d)

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

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

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

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

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

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

QDataStream::QDataStream(const QByteArray &a)

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

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

QDataStream::~QDataStream()

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

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

bool QDataStream::atEnd() const

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

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

ByteOrder QDataStream::byteOrder() const

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

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

QIODevice *QDataStream::device() const

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

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

FloatingPointPrecision QDataStream::floatingPointPrecision() const

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

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

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

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

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

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

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

Формат сериализации — это сначала 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::setByteOrder(ByteOrder bo)

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

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

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

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

void QDataStream::setDevice(QIODevice *d)

void QDataStream::setDevice(QIODevice *d)

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

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

void QDataStream::setFloatingPointPrecision(FloatingPointPrecision precision)

Устанавливает точность чисел с плавающей запятой для потока данных на precision. Если точность чисел с плавающей запятой — DoublePrecision, а версия потока данных — Qt_4_6 или выше, все числа с плавающей запятой будут записаны и считаны с точностью 64 бита. Если точность чисел с плавающей запятой — SinglePrecision, а версия — Qt_4_6 или выше, все числа с плавающей запятой будут записаны и считаны с точностью 32 бита.

Для версий до Qt_4_6 точность чисел с плавающей запятой в потоке данных зависит от используемого оператора потока.

По умолчанию используется DoublePrecision.

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

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

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

void QDataStream::setStatus(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().

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<<(bool i)

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

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

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

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