PIChunkStream Class Reference

Class for binary de/serialization. More...

#include <pichunkstream.h>

Classes
struct	Chunk
	Nested template struct for chunk data. More...
struct	ChunkConst
	Nested template struct for constant chunk data. More...

Public Types
enum	Version { Version_1 , Version_2 = 2 }
	Version of data packing. More...

Public Member Functions
	PIChunkStream (const PIByteArray &data)
	Constructs stream for read from "data".
	PIChunkStream (PIByteArray *data=0, Version v=Version_2)
	Constructs stream for read or write to/from "data", or empty stream for write if "data" = 0.
	PIChunkStream (Version v)
	Constructs empty stream for write with version "v".
	~PIChunkStream ()
	Destructor.
template<typename T >
PIChunkStream &	add (int id, const T &data)
	Add to this stream chunk with ID "id" and value "data". More...
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. More...
void	setSource (const PIByteArray &data)
	Sets source buffer for read from "data".
void	setSource (PIByteArray *data)
	Sets source buffer for read or write to/from "data", or empty stream for write if "data" = 0.
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 ()
	Reads one chunk from stream and returns its ID. More...
void	readAll ()
	Read all chunks from stream. This function just index input data. More...
int	getID ()
	Returns last read chunk ID. More...
template<typename T >
T	getData () const
	Returns value of last read chunk. More...
template<typename T >
T	getData (int id) const
	Returns value of chunk with ID "id". More...
template<typename T >
void	get (T &v) const
	Places value of last read chunk into "v". More...
template<typename T >
const PIChunkStream &	get (int id, T &v) const
	Places value of chunk with ID "id" into "v". More...
template<typename T >
PIChunkStream &	set (int id, const T &v)
	Replaces value of chunk with ID "id" to "v". More...

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. More...

Detailed Description

Class for binary de/serialization.

PIChunkStream provides a binary markup serialization stream that allows reading and writing structured data chunks with IDs.

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

Member Function Documentation

chunk()

template<typename T >

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

inlinestatic

Returns chunk with ID "id" and value "data" for write to stream.

See also

chunk()

add()

template<typename T >

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

inline

Add to this stream chunk with ID "id" and value "data".

See also

chunk()

extract()

template<typename T >

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

inline

Extract PIByteArray from "stream" and set it current stream. If "read_all" then call readAll() after extract. Returns if has data to read.

Note

You should call readAll() before using getData() or get() methods

read()

int PIChunkStream::read

(

)

Reads one chunk from stream and returns its ID.

Reads the next chunk from the stream and stores its ID for subsequent getData() or get() calls

readAll()

void PIChunkStream::readAll

(

)

Read all chunks from stream. This function just index input data.

This function indexes input data to allow random access via getData(int id) and get(int id, T & v)

getID()

int PIChunkStream::getID ( )

inline

Returns last read chunk ID.

Returns the ID of the last chunk read by read() method

getData() [1/2]

template<typename T >

T PIChunkStream::getData ( ) const

inline

Returns value of last read chunk.

Note

Call read() first to read a chunk before using this method

getData() [2/2]

template<typename T >

T PIChunkStream::getData ( int  id ) const

inline

Returns value of chunk with ID "id".

Note

You should call readAll() before using this function!

get() [1/2]

template<typename T >

void PIChunkStream::get ( T &  v ) const

inline

Places value of last read chunk into "v".

Note

Call read() first to read a chunk before using this method

get() [2/2]

template<typename T >

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

inline

Places value of chunk with ID "id" into "v".

Note

You should call readAll() before using this function!

set()

template<typename T >

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

inline

Replaces value of chunk with ID "id" to "v".

Note

You should call readAll() before using this function!