pj::ContainerNode Class Reference

#include <persistent.hpp>

Public Member Functions
bool	hasUnread () const
string	unreadName () const throw (Error)
int	readInt (const string &name="") const throw (Error)
float	readNumber (const string &name="") const throw (Error)
bool	readBool (const string &name="") const throw (Error)
string	readString (const string &name="") const throw (Error)
StringVector	readStringVector (const string &name="") const throw (Error)
void	readObject (PersistentObject &obj) const throw (Error)
ContainerNode	readContainer (const string &name="") const throw (Error)
ContainerNode	readArray (const string &name="") const throw (Error)
void	writeNumber (const string &name, float num) throw (Error)
void	writeInt (const string &name, int num) throw (Error)
void	writeBool (const string &name, bool value) throw (Error)
void	writeString (const string &name, const string &value) throw (Error)
void	writeStringVector (const string &name, const StringVector &arr) throw (Error)
void	writeObject (const PersistentObject &obj) throw (Error)
ContainerNode	writeNewContainer (const string &name) throw (Error)
ContainerNode	writeNewArray (const string &name) throw (Error)

Data Fields
container_node_op *	op
container_node_internal_data	data

Detailed Description

A container node is a placeholder for storing other data elements, which could be boolean, number, string, array of strings, or another container. Each data in the container is basically a name/value pair, with a type internally associated with it so that written data can be read in the correct type. Data is read and written serially, hence the order of reading must be the same as the order of writing.

Application can read data from it by using the various read methods, and write data to it using the various write methods. Alternatively, it may be more convenient to use the provided macros below to read and write the data, because these macros set the name automatically:

• NODE_READ_BOOL(node,item)
• NODE_READ_UNSIGNED(node,item)
• NODE_READ_INT(node,item)
• NODE_READ_FLOAT(node,item)
• NODE_READ_NUM_T(node,type,item)
• NODE_READ_STRING(node,item)
• NODE_READ_STRINGV(node,item)
• NODE_READ_OBJ(node,item)
• NODE_WRITE_BOOL(node,item)
• NODE_WRITE_UNSIGNED(node,item)
• NODE_WRITE_INT(node,item)
• NODE_WRITE_FLOAT(node,item)
• NODE_WRITE_NUM_T(node,type,item)
• NODE_WRITE_STRING(node,item)
• NODE_WRITE_STRINGV(node,item)
• NODE_WRITE_OBJ(node,item)

Implementation notes:

The ContainerNode class is subclass-able, but not in the usual C++ way. With the usual C++ inheritance, some methods will be made pure virtual and must be implemented by the actual class. However, doing so will require dynamic instantiation of the ContainerNode class, which means we will need to pass around the class as pointer, for example as the return value of readContainer() and writeNewContainer() methods. Then we will need to establish who needs or how to delete these objects, or use shared pointer mechanism, each of which is considered too inconvenient or complicated for the purpose.

So hence we use C style "inheritance", where the methods are declared in container_node_op and the data in container_node_internal_data structures. An implementation of ContainerNode class will need to set up these members with values that makes sense to itself. The methods in container_node_op contains the pointer to the actual implementation of the operation, which would be specific according to the format of the document. The methods in this ContainerNode class are just thin wrappers which call the implementation in the container_node_op structure.

Member Function Documentation

hasUnread()

bool pj::ContainerNode::hasUnread

(

)

const

Determine if there is unread element. If yes, then app can use one of the readXxx() functions to read it.

unreadName()

string pj::ContainerNode::unreadName	(		)	const
throw	(	Error
	)

Get the name of the next unread element.

readInt()

int pj::ContainerNode::readInt	(	const string &	name = ""	)	const
throw	(	Error
	)

Read an integer value from the document and return the value. This will throw Error if the current element is not a number. The read position will be advanced to the next element.

Parameters

name	If specified, then the function will check if the name of the next element matches the specified name and throw Error if it doesn't match.

Returns

The value.

readNumber()

float pj::ContainerNode::readNumber	(	const string &	name = ""	)	const
throw	(	Error
	)

Read a number value from the document and return the value. This will throw Error if the current element is not a number. The read position will be advanced to the next element.

Parameters

name	If specified, then the function will check if the name of the next element matches the specified name and throw Error if it doesn't match.

Returns

The value.

readBool()

bool pj::ContainerNode::readBool	(	const string &	name = ""	)	const
throw	(	Error
	)

Read a boolean value from the container and return the value. This will throw Error if the current element is not a boolean. The read position will be advanced to the next element.

Parameters

name	If specified, then the function will check if the name of the next element matches the specified name and throw Error if it doesn't match.

Returns

The value.

readString()

string pj::ContainerNode::readString	(	const string &	name = ""	)	const
throw	(	Error
	)

Read a string value from the container and return the value. This will throw Error if the current element is not a string. The read position will be advanced to the next element.

Parameters

name	If specified, then the function will check if the name of the next element matches the specified name and throw Error if it doesn't match.

Returns

The value.

readStringVector()

StringVector pj::ContainerNode::readStringVector	(	const string &	name = ""	)	const
throw	(	Error
	)

Read a string array from the container. This will throw Error if the current element is not a string array. The read position will be advanced to the next element.

Parameters

name	If specified, then the function will check if the name of the next element matches the specified name and throw Error if it doesn't match.

Returns

The value.

readObject()

void pj::ContainerNode::readObject	(	PersistentObject &	obj	)	const
throw	(	Error
	)

Read the specified object from the container. This is equal to calling PersistentObject.readObject(ContainerNode);

Parameters

obj	The object to read.

readContainer()

ContainerNode pj::ContainerNode::readContainer	(	const string &	name = ""	)	const
throw	(	Error
	)

Read a container from the container. This will throw Error if the current element is not a container. The read position will be advanced to the next element.

Parameters

name	If specified, then the function will check if the name of the next element matches the specified name and throw Error if it doesn't match.

Returns

Container object.

readArray()

ContainerNode pj::ContainerNode::readArray	(	const string &	name = ""	)	const
throw	(	Error
	)

Read array container from the container. This will throw Error if the current element is not an array. The read position will be advanced to the next element.

Parameters

name	If specified, then the function will check if the name of the next element matches the specified name and throw Error if it doesn't match.

Returns

Container object.

writeNumber()

void pj::ContainerNode::writeNumber	(	const string &	name,
		float	num
	)
throw	(	Error
	)

Write a number value to the container.

Parameters

name	The name for the value in the container.
num	The value to be written.

writeInt()

void pj::ContainerNode::writeInt	(	const string &	name,
		int	num
	)
throw	(	Error
	)

Write a number value to the container.

Parameters

name	The name for the value in the container.
num	The value to be written.

writeBool()

void pj::ContainerNode::writeBool	(	const string &	name,
		bool	value
	)
throw	(	Error
	)

Write a boolean value to the container.

Parameters

name	The name for the value in the container.
value	The value to be written.

writeString()

void pj::ContainerNode::writeString	(	const string &	name,
		const string &	value
	)
throw	(	Error
	)

Write a string value to the container.

Parameters

name	The name for the value in the container.
value	The value to be written.

writeStringVector()

void pj::ContainerNode::writeStringVector	(	const string &	name,
		const StringVector &	arr
	)
throw	(	Error
	)

Write string vector to the container.

Parameters

name	The name for the value in the container.
arr	The vector to be written.

writeObject()

void pj::ContainerNode::writeObject	(	const PersistentObject &	obj	)
throw	(	Error
	)

Write an object to the container. This is equal to calling PersistentObject.writeObject(ContainerNode);

Parameters

obj	The object to be written

writeNewContainer()

ContainerNode pj::ContainerNode::writeNewContainer	(	const string &	name	)
throw	(	Error
	)

Create and write an empty Object node that can be used as parent for subsequent write operations.

Parameters

name	The name for the new container in the container.

Returns

A sub-container.

writeNewArray()

ContainerNode pj::ContainerNode::writeNewArray	(	const string &	name	)
throw	(	Error
	)

Create and write an empty array node that can be used as parent for subsequent write operations.

Parameters

name	The name for the array.

Returns

A sub-container.

Field Documentation

op

container_node_op* pj::ContainerNode::op

Method table.

data

container_node_internal_data pj::ContainerNode::data

Internal data

---

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

• persistent.hpp