Tekkotsu: LoadSave Class Reference

Generally, for triggering serialization of a LoadSave subclass, all you need to know is to call saveFile() / saveBuffer() in order to have the class serialize itself, and loadFile() / loadBuffer() in order to reload the data.

When saveFile() is called, it checks that it can open the specified file, and then calls saveFileStream() with the open file. This will then check getBinSize(), create a buffer of that size, and call saveBuffer() to do the actual work of serialization into that buffer. If saveBuffer is successful, saveFileStream() copies the buffer out to the file, and then finally, saveFile() will close the file.

This means when writing a class which requires serialization, you need only define 3 functions: loadBuffer(), saveBuffer(), and getBinSize(). If you are saving directly into a file and need the highest possible performance, overriding loadFileStream and saveFileStream and reimplementing the serialization operations into the file stream can save a buffer copy. Usually this is not a performance issue, but the interface is there if you need it.

The recommended style for using LoadSave in classes with multiple levels of inheritance is to have each subclass first call the superclass's implementation (e.g. of loadBuffer/saveBuffer), and then save their own data afterward. This compartmentalizes the data access and makes it easy to maintain - the code that serializes is right in with the code that defines the structure. If you change one, it's easy to see where to change the other. And protection between levels of inheritance is retained. (This is why I say it's highly flexible/maintainable, but poor readability since the serialization is all broken up.)

I also recommend putting a little string header at the beginning of each class's info via saveCreator() and checkCreator(). This will allow polymorphism when loading files (you can look at the string and create the appropriate type) but also is handy for checking field alignment... it's a lot easier to tell how much you're offset within a string than to do the same with a stream of binary values. Further, you can use the string as version information if you want to be backward compatible in future versions of your code.

LoadSave provides a series of encode() and decode() functions for all the primitive types. This will handle copying the value into the buffer or file, and can provide platform independence through byte swapping if needed (there's a compiler flag you can set for platforms that have the opposite byte order, although this should be autodetected from the system headers). Most of these are pretty straightfoward - an int is just 4 bytes and so on.

However, there's one caveat that I want to make sure to point out if you have to write parsing code in say, Java. Strings are encoded by first storing an int to hold the string's length, then the string itself, and then a null character. This adds 5 bytes to the length of any string, but makes loading the files much easier/faster - you can call string library functions directly on the buffer if it's already in memory since the string is null terminated, or can allocate memory to hold the string with one pass from a file because you'll know the size of the string before you get to it.

Of course, the string serialization format is transparent if you just stick to using LoadSave's encode/decode functions to parse it.

Definition at line 90 of file LoadSave.h.


Public Member Functions
Constructors/Destructors
	LoadSave ()
	constructor
virtual	~LoadSave ()
	destructor
Buffer Operations
virtual unsigned int	getBinSize () const =0
	Calculates space needed to save - if you can't precisely add up the size, just make sure to overestimate and things will still work.
virtual unsigned int	loadBuffer (const char buf[], unsigned int len)=0
	Load from a saved buffer in memory.
virtual unsigned int	saveBuffer (char buf[], unsigned int len) const =0
	Save to a given buffer in memory.
File Operations
These are called to load and save to files
virtual unsigned int	loadFile (const char *filename)
	initiate opening of the specified file and loading/saving of all appropriate information.
virtual unsigned int	saveFile (const char *filename) const
	initiate opening of the specified file and loading/saving of all appropriate information.
virtual unsigned int	loadFileStream (FILE *f)
	Used recursively on member objects once a file is already open - DON'T CLOSE the file in your overridden functions.
virtual unsigned int	saveFileStream (FILE *f) const
	Used recursively on member objects once a file is already open - DON'T CLOSE the file in your overridden functions.
virtual unsigned int	LoadFile (const char *filename) ATTR_deprecated
	deprecated, use loadFile() instead (refactored to standardize capitalization style)
virtual unsigned int	SaveFile (const char *filename) const ATTR_deprecated
	deprecated, use saveFile() instead (refactored to standardize capitalization style)
Creator Utilities
virtual unsigned int	creatorSize (const char creator[]) const
	Returns size of the creator code.
virtual unsigned int	checkCreator (const char *creator, const char buf[], unsigned int len, bool isLoading=true) const throw ()
	Compares the creator code in the buffer to the one given.
virtual bool	checkCreatorInc (const char creator, const char &buf, unsigned int &len, bool isLoading=true) const throw ()
	Compares the creator code in the buffer to the one given, increments buf and decrements len if it matches.
virtual void	checkCreatorIncT (const char creator, const char &buf, unsigned int &len, bool isLoading=true) const throw (std::runtime_error)
	Compares the creator code in the buffer to the one given, increments buf and decrements len if it matches, throws std::runtime_error if it doesn't match.
virtual unsigned int	checkCreator (const char creator, FILE f, bool isLoading=true) const throw ()
	Compares the creator code in the file to the one given, will attempt to reset the file position if fails (so you can check for one of several types).
virtual unsigned int	saveCreator (const char *creator, char buf[], unsigned int len) const throw ()
	Saves a creator code to a buffer.
virtual bool	saveCreatorInc (const char creator, char &buf, unsigned int &len) const throw ()
	Saves a creator code to a buffer, increments buf and decrements len by the amount used.
virtual void	saveCreatorIncT (const char creator, char &buf, unsigned int &len) const throw (std::runtime_error)
	Saves a creator code to a buffer, increments buf and decrements len by the amount used.
virtual unsigned int	saveCreator (const char creator, FILE f) const throw ()
	Saves a creator code directly to a file.
Static Public Member Functions
static bool	checkInc (int res, const char *&buf, unsigned int &len) throw ()
	Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ) If res is 0, returns false.
static bool	checkInc (int res, const char &buf, unsigned int &len, const char msg,...) __attribute__((format(printf throw ()
	Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ) If res is 0, displays the specified message on stderr and returns false.
static bool static bool	checkInc (int res, char *&buf, unsigned int &len) throw ()
	Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ). If res is 0, returns false.
static bool	checkInc (int res, char &buf, unsigned int &len, const char msg,...) __attribute__((format(printf throw ()
	Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ). If res is 0, displays the specified message on stderr and returns false.
static bool static void	checkIncT (int res, const char &buf, unsigned int &len, const char msg="LoadSave::check underflow",...) __attribute__((format(printf throw (std::length_error)
	Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ) If res is 0, throws a std::length_error with the specified message.
static bool static void static void	checkIncT (int res, char &buf, unsigned int &len, const char msg="LoadSave::check underflow",...) __attribute__((format(printf throw (std::length_error)
	Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ). If res is 0, throws a std::length_error with the specified message.
template<class T>
static bool static void static void static bool	encodeInc (const T &value, char *&buf, unsigned int &cap) throw ()
	Encodes value into the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, returns false.
template<class T>
static bool	encodeInc (const T &value, char &buf, unsigned int &cap, const char msg,...) __attribute__((format(printf throw ()
	Encodes value into the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, displays the specified message on stderr and returns false.
template<class T>
static bool static bool	decodeInc (T &value, const char *&buf, unsigned int &cap) throw ()
	Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, returns false.
template<class T>
static bool	decodeInc (T &value, const char &buf, unsigned int &cap, const char msg,...) __attribute__((format(printf throw ()
	Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, displays the specified message on stderr and returns false.
template<class T>
static bool static bool	decodeInc (T &value, char *&buf, unsigned int &cap) throw ()
	Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, returns false.
template<class T>
static bool	decodeInc (T &value, char &buf, unsigned int &cap, const char msg,...) __attribute__((format(printf throw ()
	Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, displays the specified message on stderr and returns false.
template<class T>
static bool static void	encodeIncT (const T &value, char &buf, unsigned int &cap, const char msg="LoadSave::encode overflow",...) __attribute__((format(printf throw (std::length_error)
	Encodes value into the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, throws a std::length_error with the specified message.
template<class T>
static bool static void static void	decodeIncT (T &value, const char &buf, unsigned int &cap, const char msg="LoadSave::decode underflow",...) __attribute__((format(printf throw (std::length_error)
	Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, throws a std::length_error with the specified message.
template<class T>
static bool static void static void static void	decodeIncT (T &value, char &buf, unsigned int &cap, const char msg="LoadSave::decode underflow",...) __attribute__((format(printf throw (std::length_error)
	Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, throws a std::length_error with the specified message.
static bool static void static void static void static bool	chkAdvance (int res, const char *buf, unsigned int len, const char *msg,...) ATTR_deprecated __attribute__((format(printf
	deprecated, use checkInc() instead (provides less error-prone interface (NULL not allowed), mixes better with other new *Inc varients)
Methods to detect the size member fields
static unsigned int	getSerializedSize (const LoadSave &x) throw ()
	returns the serialized size of the argument
static unsigned int	getSerializedSize (const std::string &x) throw ()
	returns the serialized size of the argument
static unsigned int	getSerializedSize (const char *x) throw ()
	returns the serialized size of the argument
static unsigned int	getSerializedSize (const void *) throw ()
	returns the serialized size of the argument
static unsigned int	getSerializedSize (const bool &) throw ()
	returns the serialized size of the argument
template<class T>
static unsigned int	getSerializedSize (const T &x) throw ()
	returns the serialized size of the argument
template<class T>
static unsigned int	getSerializedSize () throw ()
	this version lets you get the theoretical size of a type, but beware it will throw invalid_argument if you pass a string type! (can't tell the size of the string without an actual instance...)
Encode/Decode Utils
encode/decode cross-platform compatable (byte order consistancy)
static unsigned int	encode (const LoadSave &x, char buf[], unsigned int cap)
	encode or decode with byte order consistancy
static unsigned int	decode (LoadSave &x, const char buf[], unsigned int cap)
	encode or decode with byte order consistancy
static unsigned int	encode (const LoadSave &x, FILE *f)
	encode or decode with byte order consistancy
static unsigned int	decode (LoadSave &x, FILE *f)
	encode or decode with byte order consistancy
static unsigned int	encode (const double x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (double &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const double x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (double &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const float x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (float &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const float x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (float &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const long long x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (long long &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const long long x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (long long &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const unsigned long long x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (unsigned long long &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const unsigned long long x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (unsigned long long &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const long x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (long &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const long x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (long &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const unsigned long x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (unsigned long &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const unsigned long x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (unsigned long &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const int x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (int &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const int x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (int &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const unsigned int x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (unsigned int &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const unsigned int x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (unsigned int &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const short x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (short &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const short x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (short &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const unsigned short x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (unsigned short &x, const char buf[], unsigned int cap)
	encode or decode with byte order consistancy
static unsigned int	encode (const unsigned short x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (unsigned short &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const std::string &x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (std::string &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const std::string &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (std::string &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const char *x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (char *&x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const char x, FILE f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (char &x, FILE f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const char x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (char &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const char x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (char &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const unsigned char x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (unsigned char &x, const char buf[], unsigned int cap)
	encode or decode with byte order consistancy
static unsigned int	encode (const unsigned char x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (unsigned char &x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const bool x, char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (bool &x, const char buf[], unsigned int cap) throw ()
	encode or decode with byte order consistancy
static unsigned int	encode (const bool x, FILE *f) throw ()
	encode or decode with byte order consistancy
static unsigned int	decode (bool &x, FILE *f) throw ()
	encode or decode with byte order consistancy
Static Public Attributes
static const unsigned int	stringpad = sizeof(unsigned int)+1
	This is the amount of extra space needed to store a string (int for len of string plus 1 for.
Static Protected Member Functions
template<class T>
static void	byteswap (T &dstc, const T &srcc) throw ()
	templated function to swap byte ordering, should allow compiler to unroll the loop; warning don't use this if src==dst!!!

Member Function Documentation

unsigned int LoadSave::checkCreator	(	const char *	creator,
		FILE *	f,
		bool	isLoading = `true`
	)			const throw () `[virtual]`

Compares the creator code in the file to the one given, will attempt to reset the file position if fails (so you can check for one of several types).

Parameters:

	creator	what the creator should be
	f	the file pointer to check
	isLoading	set this to true if you want to output a warning if it doesn't match

Returns:: the number of bytes consumed by the creator code, or 0 if it didn't match

Definition at line 34 of file LoadSave.cc.

unsigned int LoadSave::checkCreator	(	const char *	creator,
		const char	buf[],
		unsigned int	len,
		bool	isLoading = `true`
	)			const throw () `[virtual]`

Compares the creator code in the buffer to the one given.

Parameters:

	creator	what the creator should be
	buf	the buffer to check
	len	the size remaining in the buffer
	isLoading	set this to true if you want to output a warning if it doesn't match

Returns:: the number of bytes used by the creator, or 0 if it didn't match

Definition at line 9 of file LoadSave.cc.

Referenced by RemoteRouter::forwardEvent(), LookoutIREvent::loadBinaryBuffer(), and LookoutPointAtEvent::loadBinaryBuffer().

bool LoadSave::checkCreatorInc	(	const char *	creator,
		const char *&	buf,
		unsigned int &	len,
		bool	isLoading = `true`
	)			const throw () `[virtual]`

Compares the creator code in the buffer to the one given, increments buf and decrements len if it matches.

Parameters:

	creator	what the creator should be
	buf	the buffer to check
	len	the size remaining in the buffer
	isLoading	set this to true if you want to output a warning if it doesn't match

Returns:: true if it matched, false otherwise

Definition at line 20 of file LoadSave.cc.

Referenced by VisionObjectEvent::loadBinaryBuffer(), TimerEvent::loadBinaryBuffer(), TextMsgEvent::loadBinaryBuffer(), PitchEvent::loadBinaryBuffer(), LocomotionEvent::loadBinaryBuffer(), EventBase::loadBinaryBuffer(), WalkMC::loadBuffer(), SegmentedColorGenerator::loadBuffer(), and FilterBankGenerator::loadBuffer().

void LoadSave::checkCreatorIncT	(	const char *	creator,
		const char *&	buf,
		unsigned int &	len,
		bool	isLoading = `true`
	)			const throw (std::runtime_error) `[virtual]`

Compares the creator code in the buffer to the one given, increments buf and decrements len if it matches, throws std::runtime_error if it doesn't match.

Parameters:

	creator	what the creator should be
	buf	the buffer to check
	len	the size remaining in the buffer
	isLoading	set this to true if you want to output a warning if it doesn't match

Definition at line 24 of file LoadSave.cc.

bool LoadSave::checkInc	(	int	res,
		char *&	buf,
		unsigned int &	len,
		const char *	msg,
			...
	)			throw () `[inline, static]`

Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ). If res is 0, displays the specified message on stderr and returns false.

Doesn't have to be used with encode/decode, also handy with snprintf, sscanf type operations using n

Parameters:

	res	number of bytes used, or 0 if error
	buf	pointer to current position in buffer, will be incremented by res bytes
	len	number of bytes remain between current place and end of buffer, will be decremented by res bytes
	msg	Error to display if res is less than or equal to zero

Returns:: true if everything worked, false otherwise

Definition at line 567 of file LoadSave.h.

bool LoadSave::checkInc	(	int	res,
		char *&	buf,
		unsigned int &	len
	)			throw () `[inline, static]`

Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ). If res is 0, returns false.

Doesn't have to be used with encode/decode, also handy with snprintf, sscanf type operations using n

Parameters:

	res	number of bytes used, or 0 if error
	buf	pointer to current position in buffer, will be incremented by res bytes
	len	number of bytes remain between current place and end of buffer, will be decremented by res bytes

Returns:: true if everything worked, false otherwise

Definition at line 559 of file LoadSave.h.

bool LoadSave::checkInc	(	int	res,
		const char *&	buf,
		unsigned int &	len,
		const char *	msg,
			...
	)			throw () `[inline, static]`

Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ) If res is 0, displays the specified message on stderr and returns false.

Doesn't have to be used with encode/decode, also handy with snprintf, sscanf type operations using n

Parameters:

	res	number of bytes used, or 0 if error
	buf	pointer to current position in buffer, will be incremented by res bytes
	len	number of bytes remain between current place and end of buffer, will be decremented by res bytes
	msg	Error to display if res is less than or equal to zero

Returns:: true if everything worked, false otherwise

Definition at line 545 of file LoadSave.h.

bool LoadSave::checkInc	(	int	res,
		const char *&	buf,
		unsigned int &	len
	)			throw () `[inline, static]`

Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ) If res is 0, returns false.

Doesn't have to be used with encode/decode, also handy with snprintf, sscanf type operations using n

Parameters:

	res	number of bytes used, or 0 if error
	buf	pointer to current position in buffer, will be incremented by res bytes
	len	number of bytes remain between current place and end of buffer, will be decremented by res bytes

Returns:: true if everything worked, false otherwise

Definition at line 537 of file LoadSave.h.

Referenced by checkInc(), chkAdvance(), RemoteRouter::forwardEvent(), VisionObjectEvent::loadBinaryBuffer(), TimerEvent::loadBinaryBuffer(), TextMsgEvent::loadBinaryBuffer(), PitchEvent::loadBinaryBuffer(), LocomotionEvent::loadBinaryBuffer(), WaypointEngine< MAX_WAY >::loadBuffer(), SegmentedColorGenerator::loadBuffer(), RLEGenerator::loadBuffer(), RegionGenerator::loadBuffer(), RawCameraGenerator::loadBuffer(), PostureEngine::loadBuffer(), MotionSequenceEngine::loadBuffer(), JPEGGenerator::loadBuffer(), InterleavedYUVGenerator::loadBuffer(), VisionObjectEvent::saveBinaryBuffer(), TimerEvent::saveBinaryBuffer(), TextMsgEvent::saveBinaryBuffer(), PitchEvent::saveBinaryBuffer(), LocomotionEvent::saveBinaryBuffer(), WaypointEngine< MAX_WAY >::saveBuffer(), SegmentedColorGenerator::saveBuffer(), RLEGenerator::saveBuffer(), RegionGenerator::saveBuffer(), RawCameraGenerator::saveBuffer(), PostureEngine::saveBuffer(), PNGGenerator::saveBuffer(), MotionSequenceEngine::saveBuffer(), JPEGGenerator::saveBuffer(), InterleavedYUVGenerator::saveBuffer(), RawCamBehavior::writeColor(), RegionCamBehavior::writeRegions(), SegCamBehavior::writeRLE(), SegCamBehavior::writeSeg(), and RawCamBehavior::writeSingleChannel().

void LoadSave::checkIncT	(	int	res,
		char *&	buf,
		unsigned int &	len,
		const char *	msg = `"LoadSave::check underflow"`,
			...
	)			throw (std::length_error) `[inline, static]`

Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ). If res is 0, throws a std::length_error with the specified message.

Doesn't have to be used with encode/decode, also handy with snprintf, sscanf type operations using n

Parameters:

	res	number of bytes used, or 0 if error
	buf	pointer to current position in buffer, will be incremented by res bytes
	len	number of bytes remain between current place and end of buffer, will be decremented by res bytes
	msg	Error message to throw in the std::length_error if res is less than or equal to zero

Definition at line 601 of file LoadSave.h.

void LoadSave::checkIncT	(	int	res,
		const char *&	buf,
		unsigned int &	len,
		const char *	msg = `"LoadSave::check underflow"`,
			...
	)			throw (std::length_error) `[inline, static]`

Handy for checking results from functions which manipulate a buffer (see also encodeInc()/decodeInc() ) If res is 0, throws a std::length_error with the specified message.

Doesn't have to be used with encode/decode, also handy with snprintf, sscanf type operations using n

Parameters:

	res	number of bytes used, or 0 if error
	buf	pointer to current position in buffer, will be incremented by res bytes
	len	number of bytes remain between current place and end of buffer, will be decremented by res bytes
	msg	Error message to throw in the std::length_error if res is less than or equal to zero

Definition at line 581 of file LoadSave.h.

virtual unsigned int LoadSave::creatorSize ( const char creator[] ) const [inline, virtual]

Returns size of the creator code.

Parameters:

creator

a string to use for the creator

Returns:: the size to leave for the creator code

Definition at line 289 of file LoadSave.h.

Referenced by WalkMC::getBinSize(), VisionObjectEvent::getBinSize(), TimerEvent::getBinSize(), TextMsgEvent::getBinSize(), SegmentedColorGenerator::getBinSize(), PitchEvent::getBinSize(), LookoutIREvent::getBinSize(), LookoutPointAtEvent::getBinSize(), LocomotionEvent::getBinSize(), FilterBankGenerator::getBinSize(), and EventBase::getBinSize().

template<class T>

bool LoadSave::decodeInc	(	T &	value,
		char *&	buf,
		unsigned int &	cap,
		const char *	msg,
			...
	)			throw () `[inline, static]`

Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, displays the specified message on stderr and returns false.

Parameters:

	value	the value to decode into, must be a primitive or a LoadSave subclass (i.e. a value for which decode() is defined)
	buf	pointer to current position in buffer, will be incremented by the serialized size of value
	cap	number of bytes remain between current place and end of buffer, will be decremented by the serialized size of value
	msg	Error to display if buf did not have enough capacity

Returns:: true if everything worked, false otherwise

Definition at line 691 of file LoadSave.h.

template<class T>

bool LoadSave::decodeInc	(	T &	value,
		char *&	buf,
		unsigned int &	cap
	)			throw () `[inline, static]`

Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, returns false.

Parameters:

	value	the value to decode into, must be a primitive or a LoadSave subclass (i.e. a value for which decode() is defined)
	buf	pointer to current position in buffer, will be incremented by the serialized size of value
	cap	number of bytes remain between current place and end of buffer, will be decremented by the serialized size of value

Returns:: true if everything worked, false otherwise

Definition at line 676 of file LoadSave.h.

template<class T>

bool LoadSave::decodeInc	(	T &	value,
		const char *&	buf,
		unsigned int &	cap,
		const char *	msg,
			...
	)			throw () `[inline, static]`

Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, displays the specified message on stderr and returns false.

Parameters:

	value	the value to decode into, must be a primitive or a LoadSave subclass (i.e. a value for which decode() is defined)
	buf	pointer to current position in buffer, will be incremented by the serialized size of value
	cap	number of bytes remain between current place and end of buffer, will be decremented by the serialized size of value
	msg	Error to display if buf did not have enough capacity

Returns:: true if everything worked, false otherwise

Definition at line 664 of file LoadSave.h.

template<class T>

bool LoadSave::decodeInc	(	T &	value,
		const char *&	buf,
		unsigned int &	cap
	)			throw () `[inline, static]`

Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, returns false.

Parameters:

	value	the value to decode into, must be a primitive or a LoadSave subclass (i.e. a value for which decode() is defined)
	buf	pointer to current position in buffer, will be incremented by the serialized size of value
	cap	number of bytes remain between current place and end of buffer, will be decremented by the serialized size of value

Returns:: true if everything worked, false otherwise

Definition at line 649 of file LoadSave.h.

Referenced by SegmentedColorGenerator::decodeColorsInc(), decodeInc(), VisionObjectEvent::loadBinaryBuffer(), TimerEvent::loadBinaryBuffer(), TextMsgEvent::loadBinaryBuffer(), PitchEvent::loadBinaryBuffer(), LocomotionEvent::loadBinaryBuffer(), EventBase::loadBinaryBuffer(), WalkMC::loadBuffer(), RLEGenerator::loadBuffer(), RegionGenerator::loadBuffer(), RawCameraGenerator::loadBuffer(), PNGGenerator::loadBuffer(), JPEGGenerator::loadBuffer(), InterleavedYUVGenerator::loadBuffer(), and FilterBankGenerator::loadBuffer().

template<class T>

void LoadSave::decodeIncT	(	T &	value,
		char *&	buf,
		unsigned int &	cap,
		const char *	msg = `"LoadSave::decode underflow"`,
			...
	)			throw (std::length_error) `[inline, static]`

Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, throws a std::length_error with the specified message.

Parameters:

	value	the value to decode into, must be a primitive or a LoadSave subclass (i.e. a value for which decode() is defined)
	buf	pointer to current position in buffer, will be incremented by the serialized size of value
	cap	number of bytes remain between current place and end of buffer, will be decremented by the serialized size of value
	msg	Error to display if buf did not have enough capacity

Definition at line 762 of file LoadSave.h.

template<class T>

void LoadSave::decodeIncT	(	T &	value,
		const char *&	buf,
		unsigned int &	cap,
		const char *	msg = `"LoadSave::decode underflow"`,
			...
	)			throw (std::length_error) `[inline, static]`

Decodes value from the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, throws a std::length_error with the specified message.

Parameters:

	value	the value to decode into, must be a primitive or a LoadSave subclass (i.e. a value for which decode() is defined)
	buf	pointer to current position in buffer, will be incremented by the serialized size of value
	cap	number of bytes remain between current place and end of buffer, will be decremented by the serialized size of value
	msg	Error to display if buf did not have enough capacity

Definition at line 733 of file LoadSave.h.

template<class T>

bool LoadSave::encodeInc	(	const T &	value,
		char *&	buf,
		unsigned int &	cap,
		const char *	msg,
			...
	)			throw () `[inline, static]`

Encodes value into the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, displays the specified message on stderr and returns false.

Parameters:

	value	the value to encode, must be a primitive or a LoadSave subclass (i.e. a value for which encode() is defined)
	buf	pointer to current position in buffer, will be incremented by the serialized size of value
	cap	number of bytes remain between current place and end of buffer, will be decremented by the serialized size of value
	msg	Error to display if buf did not have enough capacity

Returns:: true if everything worked, false otherwise

Definition at line 637 of file LoadSave.h.

template<class T>

bool LoadSave::encodeInc	(	const T &	value,
		char *&	buf,
		unsigned int &	cap
	)			throw () `[inline, static]`

Encodes value into the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, returns false.

Parameters:

	value	the value to encode, must be a primitive or a LoadSave subclass (i.e. a value for which encode() is defined)
	buf	pointer to current position in buffer, will be incremented by the serialized size of value
	cap	number of bytes remain between current place and end of buffer, will be decremented by the serialized size of value

Returns:: true if everything worked, false otherwise

Definition at line 622 of file LoadSave.h.

Referenced by SegmentedColorGenerator::encodeColorsInc(), encodeInc(), SegCamBehavior::openPacket(), RegionCamBehavior::openPacket(), RawCamBehavior::openPacket(), WorldStateSerializerBehavior::processEvent(), VisionObjectEvent::saveBinaryBuffer(), TimerEvent::saveBinaryBuffer(), TextMsgEvent::saveBinaryBuffer(), PitchEvent::saveBinaryBuffer(), LocomotionEvent::saveBinaryBuffer(), EventBase::saveBinaryBuffer(), WalkMC::saveBuffer(), RLEGenerator::saveBuffer(), RegionGenerator::saveBuffer(), RawCameraGenerator::saveBuffer(), PNGGenerator::saveBuffer(), JPEGGenerator::saveBuffer(), InterleavedYUVGenerator::saveBuffer(), FilterBankGenerator::saveBuffer(), and RawCamBehavior::writeColor().

template<class T>

void LoadSave::encodeIncT	(	const T &	value,
		char *&	buf,
		unsigned int &	cap,
		const char *	msg = `"LoadSave::encode overflow"`,
			...
	)			throw (std::length_error) `[inline, static]`

Encodes value into the buffer and if successful, increments the the buffer position and decrements the capacity. If unsuccessful, throws a std::length_error with the specified message.

Parameters:

	value	the value to encode, must be a primitive or a LoadSave subclass (i.e. a value for which encode() is defined)
	buf	pointer to current position in buffer, will be incremented by the serialized size of value
	cap	number of bytes remain between current place and end of buffer, will be decremented by the serialized size of value
	msg	Error to display if buf did not have enough capacity

Definition at line 704 of file LoadSave.h.

virtual unsigned int LoadSave::getBinSize ( ) const [pure virtual]

Calculates space needed to save - if you can't precisely add up the size, just make sure to overestimate and things will still work.

getBinSize is used for reserving buffers during serialization, but does not necessarily determine the actual size of what is written -- the return value of saveBuffer() specifies that after the data actually has been written. If getBinSize overestimates, the extra memory allocation is only temporary, no extra filler bytes are actually stored.

Returns:: number of bytes read/written, 0 if error (or empty)

Implemented in EventBase, LocomotionEvent, LookoutPointAtEvent, LookoutIREvent, PitchEvent, TextMsgEvent, TimerEvent, VisionObjectEvent, MotionSequenceEngine, PostureEngine, WalkMC, WaypointEngine< MAX_WAY >, XMLLoadSave, BufferedImageGenerator, CDTGenerator, FilterBankGenerator, InterleavedYUVGenerator, JPEGGenerator, PNGGenerator, RawCameraGenerator, RegionGenerator, RLEGenerator, and SegmentedColorGenerator.

Referenced by saveFileStream().

virtual unsigned int LoadSave::loadBuffer	(	const char	buf[],
		unsigned int	len
	)			`[pure virtual]`

Load from a saved buffer in memory.

Parameters:

	buf	pointer to the memory where you should begin loading
	len	length of buf available (this isn't necessarily all yours, there might be other things following your data)

Returns:: the number of bytes actually used

Implemented in EventBase, MotionSequenceEngine, PostureEngine, PostureMC, WalkMC, WaypointEngine< MAX_WAY >, Config, XMLLoadSave, BufferedImageGenerator, CDTGenerator, FilterBankGenerator, InterleavedYUVGenerator, JPEGGenerator, PNGGenerator, RawCameraGenerator, RegionGenerator, RLEGenerator, and SegmentedColorGenerator.

Referenced by decode(), and loadFileStream().

unsigned int LoadSave::loadFile ( const char * filename ) [virtual]

initiate opening of the specified file and loading/saving of all appropriate information.

Parameters:

filename

the file to load/save

Returns:: number of bytes read/written, 0 if error (or empty)

Reimplemented in EventBase, WalkMC, WaypointEngine< MAX_WAY >, Config, and XMLLoadSave.

Definition at line 74 of file LoadSave.cc.

Referenced by WaypointEngine< MAX_WAY >::loadFile(), WalkMC::loadFile(), PostureEngine::loadFile(), MotionSequenceEngine::loadFile(), LoadFile(), and EventBase::loadFile().

unsigned int LoadSave::loadFileStream ( FILE * f ) [virtual]

Used recursively on member objects once a file is already open - DON'T CLOSE the file in your overridden functions.

Parameters:

a pointer to the file to load

Returns:: number of bytes read, 0 if error (or empty)

Reimplemented in EventBase, Config, and XMLLoadSave.

Definition at line 111 of file LoadSave.cc.

Referenced by decode(), loadFile(), and EventBase::loadFileStream().

virtual unsigned int LoadSave::saveBuffer	(	char	buf[],
		unsigned int	len
	)			const `[pure virtual]`

Save to a given buffer in memory.

Parameters:

	buf	pointer to the memory where you should begin writing
	len	length of buf available. (this isn't necessarily all yours, constrain yourself to what you returned in getBinSize() )

Returns:: the number of bytes actually used

Implemented in EventBase, MotionSequenceEngine, PostureEngine, WalkMC, WaypointEngine< MAX_WAY >, XMLLoadSave, BufferedImageGenerator, CDTGenerator, FilterBankGenerator, InterleavedYUVGenerator, JPEGGenerator, PNGGenerator, RawCameraGenerator, RegionGenerator, RLEGenerator, and SegmentedColorGenerator.

Referenced by saveFileStream().

unsigned int LoadSave::saveCreator	(	const char *	creator,
		FILE *	f
	)			const throw () `[virtual]`

Saves a creator code directly to a file.

Parameters:

	creator	the string to use for the creator code
	f	the file to save the code into

Returns:: the number of bytes consumed

Definition at line 70 of file LoadSave.cc.

unsigned int LoadSave::saveCreator	(	const char *	creator,
		char	buf[],
		unsigned int	len
	)			const throw () `[virtual]`

Saves a creator code to a buffer.

Parameters:

	creator	the string to use for the creator code
	buf	the buffer to save the code into
	len	the space available in the buffer

Returns:: the number of bytes consumed

Definition at line 54 of file LoadSave.cc.

Referenced by LookoutIREvent::saveBinaryBuffer(), and LookoutPointAtEvent::saveBinaryBuffer().

bool LoadSave::saveCreatorInc	(	const char *	creator,
		char *&	buf,
		unsigned int &	len
	)			const throw () `[virtual]`

Saves a creator code to a buffer, increments buf and decrements len by the amount used.

Parameters:

	creator	the string to use for the creator code
	buf	the buffer to save the code into
	len	the space available in the buffer

Returns:: true if successful, false otherwise

Definition at line 57 of file LoadSave.cc.

Referenced by VisionObjectEvent::saveBinaryBuffer(), TimerEvent::saveBinaryBuffer(), TextMsgEvent::saveBinaryBuffer(), PitchEvent::saveBinaryBuffer(), LocomotionEvent::saveBinaryBuffer(), EventBase::saveBinaryBuffer(), WalkMC::saveBuffer(), SegmentedColorGenerator::saveBuffer(), and FilterBankGenerator::saveBuffer().

void LoadSave::saveCreatorIncT	(	const char *	creator,
		char *&	buf,
		unsigned int &	len
	)			const throw (std::runtime_error) `[virtual]`

Saves a creator code to a buffer, increments buf and decrements len by the amount used.

Parameters:

	creator	the string to use for the creator code
	buf	the buffer to save the code into
	len	the space available in the buffer

Definition at line 61 of file LoadSave.cc.

unsigned int LoadSave::saveFile ( const char * filename ) const [virtual]

initiate opening of the specified file and loading/saving of all appropriate information.

Parameters:

filename

the file to load/save

Returns:: number of bytes read/written, 0 if error (or empty)

Reimplemented in EventBase, WalkMC, WaypointEngine< MAX_WAY >, and XMLLoadSave.

Definition at line 92 of file LoadSave.cc.

Referenced by WaypointEngine< MAX_WAY >::saveFile(), WalkMC::saveFile(), PostureEngine::saveFile(), MotionSequenceEngine::saveFile(), SaveFile(), and EventBase::saveFile().

unsigned int LoadSave::saveFileStream ( FILE * f ) const [virtual]

Used recursively on member objects once a file is already open - DON'T CLOSE the file in your overridden functions.

Parameters:

a pointer to the file to save

Returns:: number of bytes written, 0 if error (or empty)

Reimplemented in EventBase, XMLLoadSave, BufferedImageGenerator, and RawCameraGenerator.

Definition at line 138 of file LoadSave.cc.

Referenced by encode(), saveFile(), and EventBase::saveFileStream().

LoadSave Class Reference

Detailed Description

Public Member Functions

Static Public Member Functions

Static Public Attributes

Static Protected Member Functions

Member Function Documentation

Member Data Documentation