Data packing interfaces. More...

#include <data_stream.hh>

Inheritance diagram for COutByteStreamBasic< Data >:

Collaboration diagram for COutByteStreamBasic< Data >:

Public Types
typedef Data::__Buf	buffer_type

typedef Data::__Char	char_type

Public Member Functions

COutByteStreamBasic (size_t reserve=1024, bool net=kByteOrderDefault)

Constructor for COutByteStream/COutByteStreamStr, COutByteStreamVec. More...

COutByteStreamBasic (buffer_type &buf, bool net=kByteOrderDefault)

Constructor for COutByteStreamStrRef, COutByteStreamVecRef. More...

COutByteStreamBasic (char_type *buf, size_t sz, bool net=kByteOrderDefault)

Constructor for COutByteStreamBuf. More...

__Myt & bad (int code)

Set status. More...

ssize_t seek (size_t pos)

Set current pointer. More...

size_t cur () const

Get current pointer. More...

size_t size () const

Get byte size of data have been written, same as cur. More...

ssize_t skip (ssize_t off)

Skip some bytes. More...

ssize_t skip (ssize_t off, int fill)

Skip some bytes. More...

std::string toString () const

Get a readable description of this object. More...

bool finish ()

Export data for COutByteStreamStrRef, COutByteStreamVecRef. More...

template<typename SizeT >

bool finish (SizeT *sz)

Export data for COutByteStreamBuf, COutByteStreamStrRef, COutByteStreamVecRef. More...

bool finish (buffer_type &dst)

Export data for COutByteStream/COutByteStreamStr, COutByteStreamStrRef, COutByteStreamVec, COutByteStreamVecRef. More...

template<typename CharT >

bool finish (CharT *dst, size_t *sz)

Export data for COutByteStream/COutByteStreamStr, COutByteStreamStrRef, COutByteStreamVec, COutByteStreamVecRef, COutByteStreamBuf. More...

Pack primitive types

These functions write c to the underlying buffer, and extend it by sizeof c bytes, with appropriate byte order transformation.

Parameters

c	An integer to be packed

Returns: Reference to self

__Myt & operator<< (char c)

__Myt & operator<< (signed char c)

__Myt & operator<< (unsigned char c)

__Myt & operator<< (short c)

__Myt & operator<< (unsigned short c)

__Myt & operator<< (int c)

__Myt & operator<< (unsigned int c)

__Myt & operator<< (long c)

__Myt & operator<< (unsigned long c)

__Myt & operator<< (long long c)

__Myt & operator<< (unsigned long long c)

__Myt & operator<< (wchar_t c)

Pack compound types

__Myt & operator<< (const std::string &c)

Pack a string. More...

__Myt & operator<< (const std::wstring &c)

Pack a wide string. More...

template<class T , size_t N>

__Myt & operator<< (const T(&c)[N])

Pack an array. More...

Manipulators

These functions operates on different manipulators to achieve special purpose.

Please see the corresponding manipulator generators in Manip for more information.

Parameters

m	Manipulator object

Returns: Reference of self

template<class T >

__Myt & operator<< (const NS_IMPL::CManipulatorRawPtr< T > &m)

template<class T >

__Myt & operator<< (const NS_IMPL::CManipulatorRawCont< T > &m)

template<class ForwardIter >

__Myt & operator<< (const NS_IMPL::CManipulatorRawRange< ForwardIter > &m)

template<typename LenT , class T >

__Myt & operator<< (const NS_IMPL::CManipulatorArrayPtr< LenT, T > &m)

template<typename LenT , class T >

__Myt & operator<< (const NS_IMPL::CManipulatorArrayCont< LenT, T > &m)

template<typename LenT , class ForwardIter >

__Myt & operator<< (const NS_IMPL::CManipulatorArrayRange< LenT, ForwardIter > &m)

__Myt & operator<< (void(*m)(__MyBase &))

template<class T >

__Myt & operator<< (const NS_IMPL::CManipulatorValueByteOrder< T > &m)

__Myt & operator<< (const NS_IMPL::CManipulatorSeek &m)

__Myt & operator<< (const NS_IMPL::CManipulatorSkip &m)

__Myt & operator<< (const NS_IMPL::CManipulatorSkipFill &m)

template<typename T >

__Myt & operator<< (const NS_IMPL::CManipulatorSkipPtr< T > &m)

template<typename T >

__Myt & operator<< (const NS_IMPL::CManipulatorSkipPtrFill< T > &m)

template<class T >

__Myt & operator<< (const NS_IMPL::CManipulatorOffsetValue< T > &m)

template<class T >

__Myt & operator<< (const NS_IMPL::CManipulatorInsert< T > &m)

template<class T >

__Myt & operator<< (const NS_IMPL::CManipulatorProtobuf< T > &m)

template<typename T >

__Myt & operator<< (const NS_IMPL::CManipulatorVarint< T > &m)

__Myt & operator<< (const NS_IMPL::CManipulatorStubPush &m)

__Myt & operator<< (const NS_IMPL::CManipulatorStubPop &m)

__Myt & operator<< (const NS_IMPL::CManipulatorEnd< void, void > &m)

__Myt & operator<< (NS_IMPL::CManipulatorEnd< void, void >(*m)())

template<typename SizeT >

__Myt & operator<< (const NS_IMPL::CManipulatorEnd< SizeT *, void > &m)

__Myt & operator<< (const NS_IMPL::CManipulatorEnd< buffer_type, void > &m)

template<typename CharT >

__Myt & operator<< (const NS_IMPL::CManipulatorEnd< CharT *, size_t * > &m)

Detailed Description

template<class Data>
class COutByteStreamBasic< Data >

Data packing interfaces.

COutByteStreamBasic is for easy data packing/encoding/serialization. It manages data endianness automatically, so you don't need to call hton/ntoh family APIs manually. It also performs sufficient boundary checks so you won't end up with memory access violations.
COutByteStream supports a number of manipulators to operate on compound types and complex structures, which will make your code really concise and efficient.
The type of underlying byte buffer determines which variant of COutByteStreamBasic you may choose:

Internal std::string

COutByteStream (or COutByteStreamStr) uses internal std::string as the underlying byte buffer, which means you don't need to provide a byte buffer when constructing a COutByteStream object, instead you could indicate a byte size to the internal std::string object to reserve, so it might not need to expand (and copy data) later on.

External std::string

In the contrary, COutByteStreamStrRef needs an external std::string object to store data, provided in the constructor. COutByteStreamStrRef will hold a reference to the std::string object and manipulate it during the process of serialization/encoding. New data will append to the std::string object, so it's possible to deal with some legacy code and avoid performance loss.

Internal std::vector<char>

Similar to COutByteStream, COutByteStreamVec uses internal std::vector<char> as the underlying buffer. You can treat them quite the same, and the purpose of COutByteStreamVec is only for completion: some people prefer using std::vector<char> as a buffer.

External std::vector<char>

COutByteStreamVecRef needs an external std::vector<char> object to construct, just like COutByteStreamStrRef does. And every aspect is just the same for both of them, as described before.

External char array

COutByteStreamBuf is different from all above. It receives a char array as the underlying buffer, with fixed size, wrapped by CCharBuffer. It's impossible to expand the underlying buffer, and when it's full, all serialization operations will fail and status is set.
Here is an example use of COutByteStream:

COutByteStream out;   // using internal std::string as data buffer
// Following are the data we want to pack
uint32_t version;        // a 32-bit integer
string name;             // a string
vector<uint64_t> orders; // an array of 64-bit integers
// This is to receive the final data buffer.
std::string buf;
// Then we serialize all data in ONE line!
out << version << name << Manip::array(orders)
    << Manip::end(buf);  // And export the data to 'buf'

Other variants are similar, except for the constructors and Manip::end part.

Template Parameters

Data	Type of underlying byte buffer

Note: COutByteStreamBasic is not intended for direct use, try variants introduced above.

Constructor & Destructor Documentation

template<class Data >

COutByteStreamBasic< Data >::COutByteStreamBasic	(	size_t	reserve = `1024`,
		bool	net = `kByteOrderDefault`
	)

inlineexplicit

Constructor for COutByteStream/COutByteStreamStr, COutByteStreamVec.

Parameters

reserve	Byte size for the underlying buffer to reserve.
net	Byte order of the data in the underlying buffer: `true:` Net byte order, this is the default; `false:` Host byte order;

template<class Data >

COutByteStreamBasic< Data >::COutByteStreamBasic	(	buffer_type &	buf,
		bool	net = `kByteOrderDefault`
	)

inlineexplicit

Constructor for COutByteStreamStrRef, COutByteStreamVecRef.

Parameters

buf	Reference to external byte buffer
net	Byte order of the data in the underlying buffer: `true:` Net byte order, this is the default; `false:` Host byte order;

template<class Data >

COutByteStreamBasic< Data >::COutByteStreamBasic	(	char_type *	buf,
		size_t	sz,
		bool	net = `kByteOrderDefault`
	)

inline

Constructor for COutByteStreamBuf.

Parameters

buf	Pointer to external byte buffer
sz	Length of `buf`
net	Byte order of the data in the underlying buffer: `true:` Net byte order, this is the default; `false:` Host byte order;

Member Function Documentation

template<class Data >

__Myt& COutByteStreamBasic< Data >::bad ( int code )

inline

Set status.

If status is not 0, all packing operations will fail.

Parameters

code	`0`: Reset status. Otherwise: A number indicating error status.

Returns: Reference of self

template<class Data >

size_t COutByteStreamBasic< Data >::cur ( ) const

inline

Get current pointer.

Current pointer is the size of data that have been written to the underlying byte buffer. Every packing operation increases current pointer by the amount of data it writes.

Returns: Current pointer

See also: size

template<class Data >

bool COutByteStreamBasic< Data >::finish ( )

inline

Export data for COutByteStreamStrRef, COutByteStreamVecRef.

Although COutByteStreamStrRef and COutByteStreamVecRef use external byte buffer, it's still necessary to call this function or use Manip::end() explicitly, to do some finishing work, e.g. correcting the size of the byte buffer object.

Returns: true if succeeded; otherwise false

See also: Manip::end

template<class Data >

template<typename SizeT >

bool COutByteStreamBasic< Data >::finish ( SizeT * sz )

inline

Export data for COutByteStreamBuf, COutByteStreamStrRef, COutByteStreamVecRef.

This function does some finishing work, e.g. correcting the size of the underlying buffer, and return its real size to sz.
The returned size may be different to size(), in case that there were data already in the external buffer before serialization.

Template Parameters

SizeT An integer type

Parameters

[out] sz Pointer to an integer to receive the size of the data

Returns: true if succeeded; otherwise false

See also: Manip::end

template<class Data >

bool COutByteStreamBasic< Data >::finish ( buffer_type & dst )

inline

Export data for COutByteStream/COutByteStreamStr, COutByteStreamStrRef, COutByteStreamVec, COutByteStreamVecRef.

This function appends the underlying data to dst.
For COutByteStream and COutByteStreamVec, if dst is empty before exporting, swap will be used to avoid data copy.

Parameters

[out] dst A buffer to receive data

Returns: true if succeeded; otherwise false

See also: Manip::end

template<class Data >

template<typename CharT >

bool COutByteStreamBasic< Data >::finish	(	CharT *	dst,
		size_t *	sz
	)

inline

Export data for COutByteStream/COutByteStreamStr, COutByteStreamStrRef, COutByteStreamVec, COutByteStreamVecRef, COutByteStreamBuf.

This function copies the underlying data to a byte buffer pointed by dst, and returns the real size of data to sz.

Template Parameters

CharT Must be the same as the underlying character type, e.g. char

Parameters

[out]	dst	Pointer to a byte array to receive the data
[in,out]	sz	Pass in as the length of `dst`; pass out as the real size of exported data

Returns: true if succeeded; otherwise false

See also: Manip::end

template<class Data >

__Myt& COutByteStreamBasic< Data >::operator<< ( const std::string & c )

inline

Pack a string.

This function first writes a uint16_t equal to the length of c, then copy the whole string to the underlying buffer.

Parameters

c	A string to be packed

Returns: Reference to self

template<class Data >

__Myt& COutByteStreamBasic< Data >::operator<< ( const std::wstring & c )

inline

Pack a wide string.

This function first writes a uint16_t equal to the length of c, then copy the whole string to the underlying buffer.

Parameters

c	A wide string to be packed

Returns: Reference to self

template<class Data >

template<class T , size_t N>

__Myt& COutByteStreamBasic< Data >::operator<< ( const T(&) c[N] )

inline

Pack an array.

This function writes N elements directly (without leading length field) to the underlying buffer.
T must be a type supported by operator << of COutByteStreamBasic.

Template Parameters

T	Type of element in array
N	Number of elements in array

Parameters

c	An array to be packed

Returns: Reference to self

template<class Data >

ssize_t COutByteStreamBasic< Data >::seek ( size_t pos )

inline

Set current pointer.

If this function makes current pointer smaller, some data are erased; And if current pointer becomes larger, some room are reserved.

Parameters

pos	New current pointer

Returns

Negative: Operation failed, status will be set to a nonzero value;
Otherwise: New current pointer;

template<class Data >

size_t COutByteStreamBasic< Data >::size ( ) const

inline

Get byte size of data have been written, same as cur.

Returns: Byte size written data

See also: cur

template<class Data >

ssize_t COutByteStreamBasic< Data >::skip ( ssize_t off )

inline

Skip some bytes.

This function is equivalent to seek(cur() + off). If off > 0, some room are reserved; if off < 0, some data are erased.
The content of the underlying buffer will NOT be modified by this function.

Parameters

off	Size of bytes to skip.

Returns

Negative: Operation failed, status will be set to a nonzero value;
Otherwise: New current pointer;

template<class Data >

ssize_t COutByteStreamBasic< Data >::skip	(	ssize_t	off,
		int	fill
	)

inline

Skip some bytes.

This function is similar to seek(cur() + off). If off > 0, some room are reserved, and fill are used to fill in the room; if off < 0, some data are erased.

Parameters

off	Size of bytes to skip.
fill	Character to fill in the reserved room, if any

Returns

Negative: Operation failed, status will be set to a nonzero value;
Otherwise: New current pointer;

template<class Data >

std::string COutByteStreamBasic< Data >::toString ( ) const

inline

Get a readable description of this object.

Returns: A readable description of this object

The documentation for this class was generated from the following file:

data_stream.hh

Public Types

Public Member Functions

Detailed Description

template<class Data> class COutByteStreamBasic< Data >

Constructor & Destructor Documentation

Member Function Documentation

template<class Data>
class COutByteStreamBasic< Data >