Manip Namespace Reference

Manipulators for stream interface APIs. More...

Functions
template<class T >
NS_IMPL::CManipulatorProtobuf< T >	protobuf (T &msg, size_t size=size_t(-1))
	Pack/unpack Protocol Buffers messages. More...
template<typename T >
NS_IMPL::CManipulatorVarint< const T >	varint (const T &val)
	Pack integer using Base 128 Varints encoding. More...
template<typename T >
NS_IMPL::CManipulatorVarint< T >	varint (T &val)
	Unpack integer using Base 128 Varints encoding. More...
NS_IMPL::CManipulatorStubPush	stub (size_t sz)
	Set up a stub. More...
NS_IMPL::CManipulatorStubPop	stub_pop (bool align=false, bool check=false)
	Demolish the top most stub. More...
CToString &	boolalpha (CToString &tos)
CToString &	noboolalpha (CToString &tos)
NS_IMPL::CToStringWidth	setw (int w)
NS_IMPL::CToStringFill	fill (char c)
CToString &	left (CToString &tos)
CToString &	right (CToString &tos)
NS_IMPL::CToStringBase	setbase (int base)
CToString &	dec (CToString &tos)
CToString &	hex (CToString &tos)
CToString &	oct (CToString &tos)
CToString &	bin (CToString &tos)
CToString &	showbase (CToString &tos)
CToString &	noshowbase (CToString &tos)
CToString &	autocase (CToString &tos)
CToString &	uppercase (CToString &tos)
CToString &	nouppercase (CToString &tos)
CToString &	showpos (CToString &tos)
CToString &	noshowpos (CToString &tos)
CToString &	endl (CToString &tos)
CToString &	ends (CToString &tos)
Mapip::raw
Pack/unpack a range of elements, without leading size field. Mapip::raw is convenient for pack/unpack fixed number of elements, like an array, a string of characters, or a container. Array Sample code for CInByteStream: CInByteStream in(buf, sz); int c[5]; // an array to receive unpacked results in >> Mapip::raw(c); // unpack 5 integers // This is equivalent to: // for(int i = 0;i < 5;++i) // in >> c[i]; Sample code for COutByteStreamBasic: COutByteStream out; int c[5]; // an array to pack out << Mapip::raw(c); // pack 5 integers // This is equivalent to: // for(int i = 0;i < 5;++i) // out << c[i]; If size of array cannot be deduced automatically, a parameter must be provided. Sample code for CInByteStream: CInByteStream in(buf, sz); int * c = new int[sz]; // an array to receive unpacked results in >> Mapip::raw(c, sz); // unpack 'sz' integers // This is equivalent to: // for(int i = 0;i < sz;++i) // in >> c[i]; Sample code for COutByteStreamBasic: COutByteStream out; int * c = new int[sz]; // an array to pack out << Mapip::raw(c, sz); // pack 'sz' integers // This is equivalent to: // for(int i = 0;i < sz;++i) // out << c[i]; Containers Most STL containers are well supported, e.g. vector, list, deque, set/multiset, map/multimap, etc. Sample code for CInByteStream: CInByteStream in(buf, sz); vector<int> c; // a container to receive unpacked results in >> Mapip::raw(c, sz); // unpack 'sz' integers, and append them to 'c' // This is equivalent to: // for(int i = 0, v;i < sz;++i){ // in >> v; // c.insert(c.end(), v); // } Sample code for COutByteStreamBasic: COutByteStream out; vector<int> c; // an vector to pack out << Mapip::raw(c); // pack all elements in 'c' // This is equivalent to: // for(int i = 0;i < c.size();++i) // out << c[i]; String A C-style string is essentially an array of characters. Sample code for CInByteStream: CInByteStream in(buf, sz); char * c = new char[sz]; // an array of chars to receive unpacked results in >> Mapip::raw(c, sz); // unpack 'sz' chars // This is equivalent to: // for(int i = 0;i < sz;++i) // in >> c[i]; Sample code for COutByteStreamBasic: COutByteStream out; const char * c = "abcde"; // a C-style string to pack out << Mapip::raw(c, strlen(c)); // pack a C-style string // This is equivalent to: // for(int i = 0;i < strlen(c);++i) // out << c[i]; An std::string is a container of characters. Sample code for CInByteStream: CInByteStream in(buf, sz); string c; // an object to receive unpacked data in >> Mapip::raw(c, len); // unpack 'len' bytes of data, and append them to 'c' // This is equivalent to: // for(int i = 0;i < len;++i){ // char v; // in >> v; // c.push_back(v); // } Sample code for COutByteStreamBasic: COutByteStream out; string c = "abcde"; // a string to pack out << Mapip::raw(c); // pack the string // This is equivalent to: // for(int i = 0;i < c.size();++i) // out << c[i]; Iterator range Sometimes you only have a begin and an end iterators to do the packing/unpacking. A size_t * parameter might be provided to retrieve the number of elements actually packed/unpacked. If it doesn't matter, just ignore it. Sample code for CInByteStream: CInByteStream in(buf, sz); list<int> c; list<int>::iterator first = c.begin(); // start iterator list<int>::iterator last = c.end(); // end iterator size_t sz; in >> Mapip::raw(first, last, &sz); // unpack certain integers to range [first, last), and // store the number of elements unpaced in 'sz' // This is equivalent to: // for(list<int>::iterator it = first;it != last;++it) // in >> *it; Sample code for COutByteStreamBasic: COutByteStream out; list<int> c; list<int>::const_iterator first = c.begin(); // start iterator list<int>::const_iterator last = c.end(); // end iterator out << Mapip::raw(first, last); // pack certain integers from range [first, last), not // interested in the number of elements packed // This is equivalent to: // for(list<int>::const_iterator it = first;it != last;++it) // out << *it;
template<class T , size_t N>
NS_IMPL::CManipulatorRawPtr< T >	raw (T(&c)[N])
template<class T >
NS_IMPL::CManipulatorRawPtr< T >	raw (T *c, size_t sz)
template<class T >
NS_IMPL::CManipulatorRawPtr< T >	raw (std::vector< T > &c, size_t sz)
template<class T >
NS_IMPL::CManipulatorRawPtr< const T >	raw (const std::vector< T > &c, size_t *sz=NULL)
template<typename Char >
NS_IMPL::CManipulatorRawPtr< Char >	raw (std::basic_string< Char > &c, size_t len)
template<typename Char >
NS_IMPL::CManipulatorRawPtr< const Char >	raw (const std::basic_string< Char > &c, size_t *sz=NULL)
template<class ForwardIter >
NS_IMPL::CManipulatorRawRange< ForwardIter >	raw (ForwardIter first, ForwardIter last, size_t *sz=NULL)
template<class T >
NS_IMPL::CManipulatorRawCont< T >	raw (T &c, size_t sz)
template<class T >
NS_IMPL::CManipulatorRawCont< const T >	raw (const T &c, size_t *sz=NULL)
Mapip::array
Pack/unpack a range of elements, with leading size field. Mapip::array is convenient for pack/unpack a number of elements, like an array, a string of characters, or a container. It is very similar to Manip::raw, except that a size field (the number elements) is packed/unpacked first before the elements. By default, the type of leading size field is uint16_t, unless you specify it explicitly. Array Sample code for CInByteStream: CInByteStream in(buf, sz); int c[10]; // an array to receive unpacked results uint8_t sz; // an integer to retrieve the number of elements actually unpacked in >> Mapip::array(c, &sz); // firstly unpack an uint8_t to 'sz' as the number of following // elements, then unpack 'sz' integers to 'c' // This is equivalent to: // in >> sz; // for(int i = 0;i < sz;++i) // in >> c[i]; Note that if sz is larger than the size c can hold, the whole operation fails with status of in set to non-zero. Sample code for COutByteStreamBasic: COutByteStream out; int c[5]; // an array to pack out << Mapip::array<uint16_t>(c); // pack a uint16_t equals to 5, then pack 5 integers // This is equivalent to: // out << uint16_t(5); // for(int i = 0;i < 5;++i) // out << c[i]; Note that you must specify the type of leading size. If size of array cannot be deduced automatically, a parameter must be provided. Sample code for CInByteStream: CInByteStream in(buf, sz); int * c = new int[sz]; // an array to receive unpacked results uint16_t real_sz; // an integer to retrieve the number of elements actually unpacked in >> Mapip::array(c, sz, &real_sz);// firstly unpack a uin16_t to 'real_sz' as the number of // following elements, then unpack 'real_sz' integers // This is equivalent to: // in >> real_sz; // for(int i = 0;i < real_sz;++i) // in >> c[i]; Note that if real_sz is larger than sz, the whole operation fails with status of in is set to non-zero. Sample code for COutByteStreamBasic: COutByteStream out; int * c = new int[sz]; // an array to pack out << Mapip::array<uint16_t>(c, sz); // pack a uint16_t equals to 'sz' first, then pack // 'sz' integers // This is equivalent to: // out << uint16_t(sz); // for(int i = 0;i < sz;++i) // out << c[i]; Note that you must specify the type of leading size. Containers Most STL containers are well supported, e.g. vector, list, deque, set/multiset, map/multimap, etc. Sample code for CInByteStream: CInByteStream in(buf, sz); vector<int> c; // a container to receive unpacked results in >> Mapip::array(c); // firstly unpack a uint16_t as the number of following elements, // then unpack that number of integers, and append them to 'c' // This is equivalent to: // uint16_t sz; // in >> sz; // for(int i = 0, v;i < sz;++i){ // in >> v; // c.insert(c.end(), v); // } If the leading size is not uint16_t, you can specify it like this: in >> Mapip::array<uint8_t>(c); // firstly unpack a uint8_t as the number of following // elements, then unpack that number of integers, and // append them to 'c' If there is a limitation of elements, an additional parameter may be provided, and the leading size has the same type as the second parameter: uint32_t max_sz = 100; in >> Mapip::array(c, max_sz); // firstly unpack a uint32_t as the number of following // elements, then unpack that number of integers, and // append them to 'c' If the leading size unpacked is larger than max_sz, the operation fails and status of in is set to non-zero. Sample code for COutByteStreamBasic: COutByteStream out; vector<int> c; // an vector to pack out << Mapip::array(c); // firstly pack a uint16_t equals to 'c.size()', then pack all // elements in 'c' // This is equivalent to: // out << uint16_t(c.size()); // for(int i = 0;i < c.size();++i) // out << c[i]; Note that you can specify the type of leading size like this: out << Mapip::array<uint8_t>(c); // firstly pack a uint8_t equals to 'c.size()', then pack //all elements in 'c' String A C-style string is essentially an array of characters. Sample code for CInByteStream: CInByteStream in(buf, sz); char * c = new char[sz]; // an array of chars to receive unpacked results uint16_t real_sz; // an integer to retrieve the number characters actually unpacked in >> Mapip::array(c, sz, &real_sz); // firstly unpack a uint16_t to 'real_sz' as the // number of following characters, then unpack // 'real_sz' characters to 'c' // This is equivalent to: // in >> real_sz; // for(int i = 0;i < real_sz;++i) // in >> c[i]; If real_sz is larger than sz, this operation fails and status of in is set to non-zero. Sample code for COutByteStreamBasic: COutByteStream out; const char * c = "abcde"; // a C-style string to pack out << Mapip::array<uint8_t>(c, strlen(c)); // firstly pack a uint8_t equals to // 'strlen(c)', then pack the content of 'c' // This is equivalent to: // out << uint8_t(strlen(c)); // for(int i = 0;i < strlen(c);++i) // out << c[i]; Note that the type of leading size must be provided. An std::string is a container of characters. Sample code for CInByteStream: CInByteStream in(buf, sz); string c; // an object to receive unpacked data in >> Mapip::array(c); // firstly unpack a uint16_t as the number of following characters, // then unpack that number of bytes of data, and append them to 'c' // This is equivalent to: // uint16_t sz; // in >> sz; // for(int i = 0;i < sz;++i){ // char v; // in >> v; // c.push_back(v); // } You can specify the type of leading size like this: in >> Mapip::array<uint8_t>(c); // firstly unpack a uint8_t as the number of following // characters, then unpack that number of bytes of data, // and append them to 'c' If there is a limitation of bytes to unpack, an additional parameter may be provided, and the type of leading size is the same as the second parameter: uint8_t max_sz = 100; in >> Mapip::array(c, max_sz); // firstly unpack a uint8_t as the number of following // characters, then unpack that number of bytes of data, // and append them to 'c' If the leading size unpacked is larger than max_sz, the operation fails and status of in is set to non-zero. Sample code for COutByteStreamBasic: COutByteStream out; string c = "abcde"; // a string to pack out << Mapip::array(c); // firstly pack a uint16_t equals to 'c.size()', then pack the // content of 'c' // This is equivalent to: // out << uint16_t(c.size()); // for(int i = 0;i < c.size();++i) // out << c[i]; If the type of leading size isn't uint16_t, you can specify it like this: out << Mapip::array<uint8_t>(c); // firstly pack a uint8_t equals to 'c.size()', then pack // the content of 'c' Iterator range (pack only) Sometimes you only have a begin and an end iterators to do the packing. Sample code for COutByteStreamBasic: COutByteStream out; list<int> c; list<int>::const_iterator first = c.begin(); // start iterator list<int>::const_iterator last = c.end(); // end iterator out << Mapip::array<uint16_t>(first, last);// firstly pack a uint16_t equals to the number of // elements in range [first, last), then pack all // integers the range // This is equivalent to: // out << uint16_t(distance(first, last)); // for(list<int>::const_iterator it = first;it != last;++it) // out << *it; An additional integer parameter could be provided to retrieve the number of elements packed, and it will have the same type of the leading size: uint8_t sz; out << Mapip::array(first, last, &sz); // firstly pack a uint8_t equals to the number of // elements in range [first, last), then pack all // integers in the range
template<typename LenT , class T , size_t N>
NS_IMPL::CManipulatorArrayPtr< LenT, T >	array (T(&c)[N], LenT *real_sz)
template<typename LenT , class T , size_t N>
NS_IMPL::CManipulatorArrayPtr< LenT, const T >	array (const T(&c)[N])
template<typename LenT , class T >
NS_IMPL::CManipulatorArrayPtr< LenT, T >	array (T *c, size_t sz, LenT *real_sz)
template<typename LenT , class T >
NS_IMPL::CManipulatorArrayPtr< LenT, const T >	array (const T *c, size_t sz)
template<typename LenT , class T >
NS_IMPL::CManipulatorArrayCont< LenT, T >	array (T &c, LenT max_size=0)
template<typename LenT , class T >
NS_IMPL::CManipulatorArrayCont< LenT, const T >	array (const T &c)
template<class T >
NS_IMPL::CManipulatorArrayCont< uint16_t, T >	array (T &c, uint16_t max_size=0)
template<class T >
NS_IMPL::CManipulatorArrayCont< uint16_t, const T >	array (const T &c)
template<typename LenT , class ForwardIter >
NS_IMPL::CManipulatorArrayRange< LenT, ForwardIter >	array (ForwardIter first, ForwardIter last, LenT *sz=NULL)
Byte order
APIs for changing CInByteStream / COutByteStreamBasic object's byte order, both permanently and temporarily. Change byte order permanently. Sample code: CInByteStream in(buf, sz); COutByteStream out; // Set the underlying data buffer as Net Byte Order (Big Endian). in >> Mapip::net_order; out << Manip::net_order; // Set the underlying data buffer as Host Byte Order. in >> Mapip::host_order; out << Manip::host_order; // Set the underlying data buffer as Little Endian. in >> Mapip::little_endian; out << Manip::little_endian; // Set the underlying data buffer as Big Endian (Net Byte Order). in >> Mapip::big_endian; out << Manip::big_endian; Change byte order temporarily. Set byte order and pack/unpack data, then restore old byte order. Sample code: CInByteStream in(buf, sz); COutByteStream out; int val = 10; in >> Mapip::net_order_value(val); // unpack an integer using Net Byte Order, despite // the actual byte order of 'in' out << Mapip::net_order_value(val); // pack an integer using Net Byte Order, dspite the // actual byte order of 'out' in >> Mapip::host_order_value(val); // unpack an integer using Host Byte Order, despite // the actual byte order of 'in' out << Mapip::host_order_value(val); // pack an integer using Host Byte Order, dspite the // actual byte order of 'out' in >> Mapip::little_endian_value(val); // unpack an integer using Little Endian, despite // the actual byte order of 'in' out << Mapip::little_endian_value(val); // pack an integer using Little Endian, dspite the // actual byte order of 'out' in >> Mapip::big_endian_value(val); // unpack an integer using Big Endian, despite the // actual byte order of 'in' out << Mapip::big_endian_value(val); // pack an integer using Big Endian, dspite the actual // byte order of 'out'
void	net_order (NS_IMPL::CDataStreamBase &ds)
void	host_order (NS_IMPL::CDataStreamBase &ds)
void	little_endian (NS_IMPL::CDataStreamBase &ds)
void	big_endian (NS_IMPL::CDataStreamBase &ds)
template<class T >
NS_IMPL::CManipulatorValueByteOrder< T >	net_order_value (T &val)
template<class T >
NS_IMPL::CManipulatorValueByteOrder< const T >	net_order_value (const T &val)
template<class T >
NS_IMPL::CManipulatorValueByteOrder< T >	host_order_value (T &val)
template<class T >
NS_IMPL::CManipulatorValueByteOrder< const T >	host_order_value (const T &val)
template<class T >
NS_IMPL::CManipulatorValueByteOrder< T >	little_endian_value (T &val)
template<class T >
NS_IMPL::CManipulatorValueByteOrder< const T >	little_endian_value (const T &val)
template<class T >
NS_IMPL::CManipulatorValueByteOrder< T >	big_endian_value (T &val)
template<class T >
NS_IMPL::CManipulatorValueByteOrder< const T >	big_endian_value (const T &val)
Current position
APIs for changing current position, both permanently and temporarily. Change current postion permanently Sample code: CInByteStream in(buf, sz); COutByteStream out; // Set current position absolutely in >> Mapip::seek(10); // Same as in.seek(10) out << Mapip::seek(10); // Same as out.seek(10) // Move current position relatively in >> Mapip::skip(10); // Same as in.skip(10) out << Mapip::skip(10); // Same as out.skip(10) uint32_t off = -10; in >> Mapip::skip(&off); // Same as in.skip(off) out << Mapip::skip(&off); // Same as out.skip(off) // Fill while moving int fill = 'a'; in >> Mapip::skip(10, fill); // Same as in.skip(10, fill) out << Mapip::skip(10, fill); // Same as out.skip(10, fill) uint32_t off = -10; in >> Mapip::skip(&off, fill); // Same as in.skip(off, fill) out << Mapip::skip(&off, fill); // Same as out.skip(off, fill) Change current postion temporarily Move current position and pack/unpack data, then restore old current position. Sample code: CInByteStream in(buf, sz); COutByteStream out; int val = 100; // Unpack data from an absolute position in >> Mapip::offset_value(10, val); // This is equivalent to: // size_t old = in.cur(); // in.seek(10); // in >> val; // in.seek(old); // Pack data to an absolute position out << Mapip::offset_value(10, val); // This is equivalent to: // size_t old = out.cur(); // out.seek(10); // out << val; // out.seek(old); Insert data (pack only) Sometimes you need to insert a value to a particular position in already packed data, which means all existing data after that position need to move forward, to make room for the value. This operation could be complex without Manip::insert. Sample code: COutByteStream out; int val = 100; out << Mapip::insert(10, val); // pack 'val' at absolute position 10. Any existing data // after this position will move forward by 'sizeof val' // bytes to make room for 'val'
NS_IMPL::CManipulatorSeek	seek (size_t pos)
NS_IMPL::CManipulatorSkip	skip (ssize_t off)
NS_IMPL::CManipulatorSkipFill	skip (ssize_t off, int fill)
template<typename T >
NS_IMPL::CManipulatorSkipPtr< T >	skip (T *off)
template<typename T >
NS_IMPL::CManipulatorSkipPtrFill< T >	skip (T *off, int fill)
template<class T >
NS_IMPL::CManipulatorOffsetValue< T >	offset_value (size_t pos, T &val)
template<class T >
NS_IMPL::CManipulatorOffsetValue< const T >	offset_value (size_t pos, const T &val)
template<class T >
NS_IMPL::CManipulatorInsert< T >	insert (size_t pos, const T &val)
Manip::end
End packing/unpacking operations. When all packing/unpacking operations finish, it's a good practice to announce an end explicitly. For unpacking operations (CInByteStream), left data size will be checked. If it's not zero, status of CInByteStream object will be set to non-zero. Because usually some left data means you have missed something, or there is a misunderstanding about the protocol. For packing operations (COutByteStreamBasic), it's always necessary to end. Because the underlying data buffer (whether it's internal or external) may have reserved some room for performance, so an adjustment is critical to correct its size. Besides, it will call corresponding COutByteStreamBasic::finish to export data. Note Ending operation will clear all stubs, without any alignments or checks. See also COutByteStreamBasic::finish
NS_IMPL::CManipulatorEnd< void, void >	end ()
	End operations for CInByteStream, COutByteStreamStrRef, COutByteStreamVecRef. More...
template<typename SizeT >
NS_IMPL::CManipulatorEnd< SizeT *, void >	end (SizeT *sz)
	End operations for COutByteStreamBuf, COutByteStreamStrRef, COutByteStreamVecRef. More...
template<class BufT >
NS_IMPL::CManipulatorEnd< BufT, void >	end (BufT &buf)
	End operations for COutByteStream / COutByteStreamStr, COutByteStreamStrRef, COutByteStreamVec, COutByteStreamVecRef. More...
template<typename CharT >
NS_IMPL::CManipulatorEnd< CharT *, size_t * >	end (CharT *buf, size_t *sz)
	End operations for COutByteStream / COutByteStreamStr, COutByteStreamStrRef, COutByteStreamVec, COutByteStreamVecRef, COutByteStreamBuf. More...

Detailed Description

Manipulators for stream interface APIs.

Function Documentation

NS_IMPL::CManipulatorEnd<void, void> Manip::end ( )

inline

End operations for CInByteStream, COutByteStreamStrRef, COutByteStreamVecRef.

Sample code for CInByteStream:

CInByteStream in(buf, 8);
uint32_t val;

in >> val;               // unpack a 4-byte integer
// in >> Manip::end;     // FAIL! There are 4 bytes left

in >> val;               // unpack another 4-byte integer
in >> Manip::end;        // Fine, no left data

Sample code for COutByteStreamBasic:

string buf;
COutByteStreamStrRef out(buf);   // 'buf' is the underlying buffer for 'out'

out << uint32_t(100);        // pack a 4-byte integer,
// assert(buf.size() == 4);  // ERROR! buf.size() >= 4

out << Manip::end;           // adjust buf.size()
assert(buf.size() == 4);     // Correct

template<typename SizeT >

NS_IMPL::CManipulatorEnd<SizeT *, void> Manip::end ( SizeT *  sz )

inline

End operations for COutByteStreamBuf, COutByteStreamStrRef, COutByteStreamVecRef.

This manipulator will also store the byte size of underlying data buffer in sz.
Sample code:

char * buf = new char[10];
COutByteStreamBuf out(buf, 10);  // 'buf' is the underlying buffer for 'out'

out << uint32_t(100);        // pack a 4-byte integer,

size_t sz;
out << Manip::end(&sz);      // set correct size to 'sz'
assert(sz == 4);             // Correct

Template Parameters

SizeT

Type of an integer

Parameters

[out]

sz

Pointer to an integer to receive the size of actual data

template<class BufT >

NS_IMPL::CManipulatorEnd<BufT, void> Manip::end ( BufT &  buf )

inline

End operations for COutByteStream / COutByteStreamStr, COutByteStreamStrRef, COutByteStreamVec, COutByteStreamVecRef.

This manipulator will also export data to buf. If it's not empty, new data will append to it.
Sample code:

COutByteStream out;

out << uint32_t(100);    // pack a 4-byte integer

string buf;
out << Manip::end(buf);  // export data to 'buf'
assert(buf.size() == 4); // Correct

Note

Data copy is avoided whenever possible, e.g. buf is empty and the underlying buffer is internal (COutByteStream / COutByteStreamStr and COutByteStreamVec).

Template Parameters

BufT	Must be the same as the underlying buffer type, e.g. std::string for COutByteStream / COutByteStreamStr, COutByteStreamStrRef, or std::vector<char> for COutByteStreamVec, COutByteStreamVecRef

Parameters

[out]

buf

A buffer to receive data

template<typename CharT >

NS_IMPL::CManipulatorEnd<CharT *, size_t *> Manip::end ( CharT *  buf, size_t *  sz  )

inline

End operations for COutByteStream / COutByteStreamStr, COutByteStreamStrRef, COutByteStreamVec, COutByteStreamVecRef, COutByteStreamBuf.

Sample code;

COutByteStream out;

out << uint32_t(100);    // pack a 4-byte integer

char * buf = new char[10];
size_t sz = 10;

out << Manip::end(buf, &sz); // export data to 'buf'
assert(sz == 4);             // Correct

Template Parameters

CharT

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

Parameters

[out]	buf	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

template<class T >

NS_IMPL::CManipulatorProtobuf<T> Manip::protobuf ( T &  msg, size_t  size = size_t(-1)  )

inline

Pack/unpack Protocol Buffers messages.

This manipulator makes protobuf messages easily cooperative with other data formats. Packing/unpacking a protobuf message is as simple as for an integer. Boundary checks are automatically done, data pointers are efficiently handled.
Sample code for CInByteStream:

CInByteStream in(buf, sz);

AnyMessage msg;  // any protobuf message object

in >> Manip::protobuf(msg);  // unpack 'msg' from all left data of 'in'

By default, Manip::protobuf will use all left data of in to initialize protobuf message object, which means the message should be the last value of in.
But if that's not the case, you must provide a size parameter to limit the reading:

in >> Manip::protobuf(msg, 50);  // unpack 'msg' from 50 bytes of data of 'in'

Note

In both cases Manip::protobuf will try to use all data available to initialize the message. If data size is incorrect, no matter smaller or larger than actually needed, this operation will fail and status of in will be set to non-zero.

Sample code for COutByteStreamBasic:

COutByteStream out;

AnyMessage msg;  // any protobuf message object

out << Manip::protobuf(msg); // pack 'msg'

Template Parameters

T	Any subclass of google::protobuf::MessageLite

Parameters

[in,out]	msg	A message object
[in]	size	Size of bytes read when unpacking msg

NS_IMPL::CManipulatorStubPush Manip::stub ( size_t  sz )

inline

Set up a stub.

Any packing/unpacking operation cannot go beyond the stub, or it fails with status set to non-zero.
Stubs can stack, the top most one is currently in effect. After popping up it, the next top one takes effect immediately, until there is no stubs.
A common use of stubs is to create a robust hierarchical data structure in which errors in one part never affect other parts. Besides, additional boundary checks make defects harder to hide.
When creating a stub, you need provide offset of the stub, sz, relative to current pointer, i.e. the position of the stub is cur() + sz.
Sample code for CInByteStream:

CInByteStream in(buf, sz);
uint32_t val;

in >> Manip::stub(4);    // Set up a stub at (in.cur() + 4)
in >> val;               // Fine, unpack a 4-byte integer
in >> val;               // FAIL! Can NOT go beyond the stub

Sample code for COutByteStreamBasic:

COutByteStream out;

out << Mapip::stub(4);   // Set up a stub at (out.cur() + 4)
out << uint32_t(100);    // Fine, pack a 4-byte integer
out << 'a';              // FAIL! Can NOT go beyong the stub

Parameters

sz	Offset of the stub, relative to current pointer

NS_IMPL::CManipulatorStubPop Manip::stub_pop ( bool  align = false, bool  check = false  )

inline

Demolish the top most stub.

This manipulator demolishes current stub, check and align current pointer if needed. The next top stub will take effect, until there is no stubs any more.
Sample code for CInByteStream:

CInByteStream in(buf, sz);
uint32_t val;

in >> Manip::stub(4);    // Set up a stub at (in.cur() + 4)
in >> val;               // Fine, unpack a 4-byte integer

in >> Mapip::stub_pop()  // Remove the stub
in >> val;               // Fine, unpack another 4-byte integer

Sample code for COutByteStreamBasic:

COutByteStream out;

out << Mapip::stub(4);   // Set up a stub at (out.cur() + 4)
out << uint32_t(100);    // Fine, pack a 4-byte integer

out << Manip::stub_pop();// remove the stub
out << 'a';              // Fine, pack a char

Parameters

align	true: Align current pointer to the position of removed stub. This is useful when you want to ignore any data in a sub-structure. false: Do not change current pointer.
check	true: Assert if current pointer equals to the position of removed stub. If failed, status will be set to non-zero. This is useful when you cannot tolerate any errors in the sub-structure. false: Do not check.

template<typename T >

NS_IMPL::CManipulatorVarint<const T> Manip::varint ( const T &  val )

inline

Pack integer using Base 128 Varints encoding.

Varint encoding is compact, byte order independent, and efficient. This manipulator makes it super easy to take advantage of it, and supports all primitive integer types, from char to wchar_t to long long.
Sample Code:

COutByteStream out;

out << Manip::varint(1000);  // pack number '1000' using Base 128 Varints encoding

Template Parameters

T	An integer type

Parameters

val	An integer

template<typename T >

NS_IMPL::CManipulatorVarint<T> Manip::varint ( T &  val )

inline

Unpack integer using Base 128 Varints encoding.

Sample Code:

CInByteStream in(buf, sz);
int val;

in >> Manip::varint(val);  // unpack an integer to 'val' using Base 128 Varints encoding

Template Parameters

T	An integer type

Parameters

[out]

val

An integer to receive the result