PIChunkStream Class Reference

Class for binary de/serialization. More...

#include <pichunkstream.h>

Public Types
enum	Version { Version_1 , Version_2 = 2 }
	Version of data packing. Read-access PIChunkStream automatic detect version, but write-access PIChunkStream by default write in new version, be careful! More...

Public Member Functions
	PIChunkStream (const PIByteArray &data)
	Contructs stream for read from "data".
	PIChunkStream (PIByteArray *data=0, Version v=Version_2)
	Contructs stream for read or write to/from "data", or empty stream for write if "data" = 0.
	PIChunkStream (Version v)
	Contructs empty stream for write with version "v".
template<typename T >
PIChunkStream &	add (int id, const T &data)
	Add to this stream chunk with ID "id" and value "data".
template<typename T >
bool	extract (PIBinaryStream< T > &stream, bool read_all=false)
	Extract PIByteArray from "stream" and set it current stream. If "read_all" then call readAll() after extract. Returns if has data to read.
PIByteArray	data () const
	Returns internal buffer with written data.
bool	atEnd () const
	Returns if there is end of stream.
Version	version () const
	Returns stream version.
int	read ()
	Read one chunk from stream and returns its ID.
void	readAll ()
	Read all chunks from stream. This function just index input data.
int	getID ()
	Returns last readed chunk ID.
template<typename T >
T	getData () const
	Returns value of last readed chunk.
template<typename T >
T	getData (int id) const
	Returns value of chunk with ID "id". You should call readAll() before using this function!
template<typename T >
void	get (T &v) const
	Place value of last readed chunk into "v".
template<typename T >
const PIChunkStream &	get (int id, T &v) const
	Place value of chunk with ID "id" into "v". You should call readAll() before using this function!
template<typename T >
PIChunkStream &	set (int id, const T &v)
	Replace value of chunk with ID "id" to "v". You should call readAll() before using this function!

Static Public Member Functions
template<typename T >
static ChunkConst< T >	chunk (int id, const T &data)
	Returns chunk with ID "id" and value "data" for write to stream.

Detailed Description

Class for binary de/serialization.

Synopsis

This class provides very handly mechanism to store and restore values to and from PIByteArray. The main advantage of using this class is that your binary data become independent from order and collection of your values.

Mechanism

PIChunkStream works with items called "chunk". Chunk is an ID, size and any value that can be stored and restored to/from PIChunkStream with stream operators << and >>.

To construct PIChunkStream for writing data use any non-default constructor. Empty constructor creates internal buffer that can be accessed by function data(). Non-empty constructor works with given byte array.

To read chunks from byte array use function read() that returns ID of readed chunk. Then you can get value of this chunk with functions getData() or get(), but you should definitely know type of this value. You can read from byte array while atEnd() if false.

Examples

Using simple operator and cascade serialization: Prepare your structs to work with 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;
}

Old-style writing to 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 ...

Fastest reading from 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;

And next code show how to serialize your struct with 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;
}

... and deserialize:

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;
}

Member Enumeration Documentation

Version

enum PIChunkStream::Version

Version of data packing. Read-access PIChunkStream automatic detect version, but write-access PIChunkStream by default write in new version, be careful!

Enumerator
Version_1	First, old version
Version_2	Second, more optimized version