Класс PIChunkStream

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

#include <pichunkstream.h>

Классы
struct	Chunk
	Вложенный шаблонный структура для данных чанка Подробнее...
struct	ChunkConst
	Вложенный шаблонный структура для константных данных чанка Подробнее...

Открытые типы
enum	Version { Version_1 , Version_2 = 2 }
	Версия хранения данных. Подробнее...

Открытые члены
	PIChunkStream (const PIByteArray &data)
	Создает поток на чтение из "data".
	PIChunkStream (PIByteArray *data=0, Version v=Version_2)
	Создает поток на чтение или запись из/в "data", или пустой поток на запись если "data" = 0.
	PIChunkStream (Version v)
	Создает пустой поток на запись с версией "v".
	~PIChunkStream ()
	Деструктор
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() после инициализации. Возвращает если ли данные для чтения.
void	setSource (const PIByteArray &data)
	Устанавливает исходный буфер для чтения из "data".
void	setSource (PIByteArray *data)
	Устанавливает исходный буфер для чтения или записи из/в "data", или пустой поток на запись если "data" = 0.
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".
template<typename T>
void	get (T &v) const
	Записывает значение последнего прочитанного чанка в "v".
template<typename T>
const PIChunkStream &	get (int id, T &v) const
	Записывает значение чанка с ID "id" в "v".
template<typename T>
PIChunkStream &	set (int id, const T &v)
	Заменяет значение чанка с ID "id" на "v".

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

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

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

PIChunkStream обеспечивает бинарный поток с разметкой для чтения и записи структурированных данных-чанков с ID.

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

Этот класс предоставляет очень удобный механизм для сохранения и извлечения значений в/из 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	Вторая, более оптимизированная версия

Методы

chunk()

template<typename T>

ChunkConst< T > PIChunkStream::chunk ( int id, const T & data )

inlinestatic

Возвращает чанк с ID "id" и значением "data" для записи в поток

См. также

chunk()

add()

template<typename T>

PIChunkStream & PIChunkStream::add ( int id, const T & data )

inline

Добавляет в этот поток чанк с ID "id" и значением "data".

См. также

chunk()

extract()

template<typename T>

bool PIChunkStream::extract ( PIBinaryStream< T > & stream, bool read_all = false )

inline

Извлекает PIByteArray из "stream" и инициализирует им поток. Если указан "read_all", то вызывает readAll() после инициализации. Возвращает если ли данные для чтения.

Заметки

Перед использованием методов getData() или get() следует вызвать readAll()

read()

int PIChunkStream::read

(

)

Читает один чанк из потока и возвращает его ID.

Читает следующий чанк из потока и сохраняет его ID для последующих вызовов getData() или get()

readAll()

void PIChunkStream::readAll

(

)

Читает все чанки из потока. Данный метод лишь индексирует данные

Эта функция индексирует входные данные для возможности случайного доступа через getData(int id) и get(int id, T & v)

getID()

int PIChunkStream::getID ( )

inline

Возвращает ID последнего прочитанного чанка

Возвращает ID последнего чанка, прочитанного методом read()

getData() [1/2]

template<typename T>

T PIChunkStream::getData ( ) const

inline

Возвращает значение последнего прочитанного чанка

Заметки

Сначала вызовите read() для чтения чанка перед использованием этого метода

getData() [2/2]

template<typename T>

T PIChunkStream::getData ( int id ) const

inline

Возвращает значение чанка с ID "id".

Заметки

Необходимо вызвать readAll() перед использованием этого метода!

get() [1/2]

template<typename T>

void PIChunkStream::get ( T & v ) const

inline

Записывает значение последнего прочитанного чанка в "v".

Заметки

Сначала вызовите read() для чтения чанка перед использованием этого метода

get() [2/2]

template<typename T>

const PIChunkStream & PIChunkStream::get ( int id, T & v ) const

inline

Записывает значение чанка с ID "id" в "v".

Заметки

Необходимо вызвать readAll() перед использованием этого метода!

set()

template<typename T>

PIChunkStream & PIChunkStream::set ( int id, const T & v )

inline

Заменяет значение чанка с ID "id" на "v".

Заметки

Необходимо вызвать readAll() перед использованием этого метода!