Класс PIChunkStream

Класс для бинарной де/сериализации. Подробнее...

#include <pichunkstream.h>

Открытые типы
enum	Version { Version_1 , Version_2 = 2 }
	Версия хранения данных. PIChunkStream на чтение автоматически определяет версию, но для записи использует по умолчанию новую, осторожно! Подробнее...

Открытые члены
	PIChunkStream (const PIByteArray &data)
	Создает поток на чтение из "data".
	PIChunkStream (PIByteArray *data=0, Version v=Version_2)
	Создает поток на чтение или запись из/в "data", или пустой поток на запись если "data" = 0.
	PIChunkStream (Version v)
	Создает пустой поток на запись с версией "v".
template<typename T >
PIChunkStream &	add (int id, const T &data)
	Добавляет в этот поток чанк с ID "id" и значением "data".
template<typename T >
bool	extract (PIBinaryStream< T > &stream, bool read_all=false)
	Извлекает PIByteArray из "stream" и инициализирует им поток. Если указан "read_all", то вызывает readAll() после инициализации. Возвращает если ли данные для чтения.
PIByteArray	data () const
	Возвращает внутренний буфер с записанными данными
bool	atEnd () const
	Возвращает достигнут ли конец потока
Version	version () const
	Возвращает версию потока
int	read ()
	Читает один чанк из потока и возвращает его ID.
void	readAll ()
	Читает все чанки из потока. Данный метод лишь индексирует данные
int	getID ()
	Возвращает ID последнего прочитанного чанка
template<typename T >
T	getData () const
	Возвращает значение последнего прочитанного чанка
template<typename T >
T	getData (int id) const
	Возвращает значение чанка с ID "id". Необходимо вызвать readAll() перед использованием этого метода!
template<typename T >
void	get (T &v) const
	Записывает значение последнего прочитанного чанка в "v".
template<typename T >
const PIChunkStream &	get (int id, T &v) const
	Записывает значение чанка с ID "id" в "v". Необходимо вызвать readAll() перед использованием этого метода!
template<typename T >
PIChunkStream &	set (int id, const T &v)
	Заменяет значение чанка с ID "id" на "v". Необходимо вызвать readAll() перед использованием этого метода!

Открытые статические члены
template<typename T >
static ChunkConst< T >	chunk (int id, const T &data)
	Возвращает чанк с ID "id" и значением "data" для записи в поток

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

Класс для бинарной де/сериализации.

Краткий обзор

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

Механизм

PIChunkStream работает с элементами под названием "чанк". Чанк имеет ID, размер и значение, и может быть записан или прочитан в/из PIChunkStream с помощью операторов << и >>.

Для создания потока на запись используется любой не-умолчальный конструктор. Пустой конструктор создает внутренний буфер, который можно получить с помощью метода data(). Непустой конструктор работает с переданным байтовым массивом.

Для чтения чанков из байтового массива используется метод read(), который возвращает ID прочитанного чанка. Получить значение этого чанка далее можно с помощью методов getData() или get(), но тип значения должен быть известен. Читать из потока можно пока метод atEnd() возвращает ложь.

Пример

Использование простого оператора и каскадная сериализация:

Подготовка своей структуры для работы с PIChunkStream:

// Your struct
struct S {
    int i;
    float f;
    PIString s;
};
 
// Operators
PIByteArray & operator<<(PIByteArray & b, const S & s) {
    b << s.i << s.f << s.s;
    return b;
}
PIByteArray & operator>>(PIByteArray & b, S & s) {
    b >> s.i >> s.f >> s.s;
    return b;
}

Старый стиль использования PIChunkStream:

// Write chunk stream
S s;
s.i = 99;
s.f = 0.01;
s.s = "SSS";
PIVector<float> f;
f << -1. << 2.5 << 11.;
// write some data to empty stream
PIChunkStream cs;
cs << cs.chunk(1, int(10)) << cs.chunk(2, PIString("text")) << cs.chunk(4, f) << cs.chunk(3, s);
// now you can take cs.data() and send or place it somewhere ...

Самое быстрое чтение из PIChunkStream:

// create stream for read, cs from upper code
PIByteArray ba(cs.data());
PIChunkStream cs2(ba);
int i(0);
PIString str;
S s;
PIVector<float> f;
// read from stream
while (!cs2.atEnd()) {
    switch (cs2.read()) {
    case 1: i = cs2.getData<int>(); break;
    case 2: str = cs2.getData<PIString>(); break;
    case 3: s = cs2.getData<S>(); break;
    case 4: f = cs2.getData<PIVector<float>>(); break;
    }
}
piCout << i << str << f << s.i << s.f << s.s;

Следующий код показывает, как сериализовать свою структуру в PIChunkStream:

PIByteArray & operator<<(PIByteArray & s, const S & value) {
    PIChunkStream cs;
    cs.add(1, value.i).add(2, value.f).add(3, value.s);
    s << cs.data();
    return s;
}

... и десериализовать:

PIByteArray & operator>>(PIByteArray & s, S & value) {
    PIChunkStream cs;
    if (!cs.extract(s)) return s;
    cs.readAll();
    cs.get(1, value.i).get(2, value.f).get(3, value.s);
    return s;
}

Перечисления

Version

enum PIChunkStream::Version

Версия хранения данных. PIChunkStream на чтение автоматически определяет версию, но для записи использует по умолчанию новую, осторожно!

Элементы перечислений
Version_1	Первая, старая версия
Version_2	Вторая, более оптимизированная версия