SerializedItem Class Reference

Class to hold a serialized representation of an object. More...

#include <Workspace/DataExecution/Serialization/serializeditem.h>

Public Member Functions
	SerializedItem (const SerializedItem &sData)
	~SerializedItem ()
SerializedItem	addChild (const QString &tag)
SerializedItem	addChildCopy (const SerializedItem &item)
SerializedItem	addComment (const QString &comment)
void	clear ()
void	deepCopy (const SerializedItem &item)
SerializedItem	firstChild (const QString &tag=QString()) const
bool	getAttribute (const QString &key, bool &value) const
bool	getAttribute (const QString &key, double &value) const
bool	getAttribute (const QString &key, int &value) const
bool	getAttribute (const QString &key, QString &value) const
bool	getAttribute (const QString &key, QVariant &value) const
bool	getAttribute (const QString &key, unsigned &value) const
QStringList	getAttributeKeys () const
QString	getSubtreeAsString () const
QString	getSubtreeAsString (SerializedTreeIO &io) const
QString	getTagName () const
QString	getText () const
void	getText (QVariant &value) const
bool	hasAttribute (const QString &key) const
bool	hasAttributes () const
bool	hasChildren () const
bool	isEmpty (const QStringList &ignoredAttributes=QStringList()) const
bool	isNull () const
bool	isSameItem (const SerializedItem &item) const
bool	isSameTree (const SerializedItem &item) const
SerializedItem	nextSibling (const QString &=QString()) const
SerializedItem &	operator= (const SerializedItem &item)
SerializedItem	previousSibling (const QString &=QString()) const
void	removeAllChildren ()
void	removeAllChildren (const QString &tag)
void	removeAttribute (const QString &key)
void	removeChild (const SerializedItem &child)
void	setAttribute (const QString &key, bool value)
void	setAttribute (const QString &key, const char *value)
void	setAttribute (const QString &key, const QString &value)
void	setAttribute (const QString &key, double value)
void	setAttribute (const QString &key, int value)
void	setAttribute (const QString &key, unsigned value)
void	setTagName (const QString &tag)
void	setText (const QString &str)

Static Public Member Functions
static QString	getTagName (const QString &str)

Detailed Description

This class holds a hierarchical representation of serialized objects. Each object can have child objects and/or its own block of text, although it would be rare for an object to have both.

The SerializedItem class is actually just a handle into the underlying tree. There can be multiple handles to the same point in the underlying tree. Indeed, copying a SerializedItem object simply creates another handle to the same point in the tree, and modifying the data through one handle also changes the data for the other handles to that item.

From the preceding paragraph, it can be seen that copying a SerializedItem is cheap, since it is only a shallow copy (ie just a data handle is copied and not the data itself).

Constructor & Destructor Documentation

SerializedItem()

SerializedItem

(

const SerializedItem &

sData

)

Parameters

sData

An existing serialized data handle.

Constructs another handle to whatever data is a handle for.

~SerializedItem()

~SerializedItem

(

)

Member Function Documentation

addChild()

SerializedItem addChild

(

const QString &

tag

)

Parameters

tag

The name of the data item to create as a child of this one. Valid characters are upper and lowercase letters, numbers and underscores. The first character must be a letter. Spaces will be automatically converted to underscores. It should be explicitly noted that periods (.), colons (:) and slashes (/ and \) are not allowed.

Returns

A data handle to the new child, or a null object if tag contains invalid characters or this is a null SerializedItem.

Note

Any attempt to add a child to a null item will always fail.

addChildCopy()

SerializedItem addChildCopy

(

const SerializedItem &

item

)

Parameters

item	The item to copy and append as a child to this item.

Returns

A data handle to the new child copy, or a null object if either the current item is null or item is null.

The purpose of this function is to make a deep copy of item and append it as a child of this item. All of item's children will be included in the deep copy.

Note

Any attempt to add a child to a null item will always fail.

addComment()

SerializedItem addComment

(

const QString &

comment

)

clear()

void clear

(

)

deepCopy()

void deepCopy

(

const SerializedItem &

item

)

Parameters

item	The source item to copy.

The purpose of this function is to make a deep copy of item and make the current item that deep copy. The current item is first cleared by removing all its attributes, children and text. The attributes and text of item are then copied across along with deep copies of each child of item. If either this item or the item to be copied is null, then this item will be null when the function returns.

firstChild()

SerializedItem firstChild

(

const QString &

tag = QString()

)

const

Parameters

tag	The tag name to search for among the immediate children only.

Returns

The first child of this SerializedItem object with the name tag, or a null object if the object has no children or no tag by that name could be found. The caller can check for a null object by calling the returned object's isNull() function.

getAttribute() [1/6]

bool getAttribute	(	const QString &	key,
		bool &	value
	)		const

Parameters

key	The name of the attribute to retrieve.
value	Where to store the value of the attribute.

Returns

True if the key attribute was found and able to be stored in value. If it returns false, then value is left unchanged by this call.

If this is a null item, then this function will always fail since null items cannot have attributes.

getAttribute() [2/6]

bool getAttribute	(	const QString &	key,
		double &	value
	)		const

Parameters

key	The name of the attribute to retrieve.
value	Where to store the value of the attribute.

Returns

True if the key attribute was found and able to be stored in value. If it returns false, then value is left unchanged by this call.

If this is a null item, then this function will always fail since null items cannot have attributes.

getAttribute() [3/6]

bool getAttribute	(	const QString &	key,
		int &	value
	)		const

Parameters

key	The name of the attribute to retrieve.
value	Where to store the value of the attribute.

Returns

True if the key attribute was found and able to be stored in value. If it returns false, then value is left unchanged by this call.

If this is a null item, then this function will always fail since null items cannot have attributes.

getAttribute() [4/6]

bool getAttribute	(	const QString &	key,
		QString &	value
	)		const

Parameters

key	The name of the attribute to retrieve.
value	Where to store the value of the attribute.

Returns

True if the key attribute was found and able to be stored in value. If it returns false, then value is left unchanged by this call.

If this is a null item, then this function will always fail since null items cannot have attributes.

getAttribute() [5/6]

bool getAttribute	(	const QString &	key,
		QVariant &	value
	)		const

Parameters

key	The name of the attribute to retrieve.
value	Where to store the value of the attribute.

Returns

True if the key attribute was found and able to be stored in value. If it returns false, then value is left unchanged by this call.

If this is a null item, then this function will always fail since null items cannot have attributes.

getAttribute() [6/6]

bool getAttribute	(	const QString &	key,
		unsigned &	value
	)		const

Parameters

key	The name of the attribute to retrieve.
value	Where to store the value of the attribute.

Returns

True if the key attribute was found and able to be stored in value. If it returns false, then value is left unchanged by this call.

If this is a null item, then this function will always fail since null items cannot have attributes.

getAttributeKeys()

QStringList getAttributeKeys

(

)

const

Returns

A list containing all the attribute names that are set for this item. The ordering of the names returned is not defined, so no assumptions should be made about the order.

getSubtreeAsString() [1/2]

QString getSubtreeAsString

(

)

const

Returns

An XML representation of everything in the tree from this point down. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This function allows you to output part of a tree to a string as an XML fragment.

getSubtreeAsString() [2/2]

QString getSubtreeAsString

(

SerializedTreeIO &

io

)

const

Parameters

io	The input / output for the "to string" operation. Allows the calling code to request the string in different formats.

Returns

The subtree in a string representation corresponding to the IO type as controlled via the io parameter. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This function allows you to output part of a tree to a string as a string following the format of io.

getTagName() [1/2]

QString getTagName

(

)

const

Returns

The tag name associated with this object.

getTagName() [2/2]

QString getTagName ( const QString &  str )

static

Parameters

str	The string for which the equivalent tag name is needed.

Returns

The tag name equivalent of str.

All characters not in the allowable character set are converted to underscores. The allowable character set includes all letters (both upper and lower case), numbers and underscores. In addition, a tag must begin with a letter, so if str does not, the string "tag_" will be prepended. The one exception is that if str is empty, then the string "tag" will be returned.

getText() [1/2]

QString getText

(

)

const

Returns

The text data associated with this SerializedItem object. If there is no text data, an empty string will be returned.

The text data is usually only present for a SerializedItem object with no children. The leaf nodes of the underlying tree will store their data as text, which can be retrieved with this function.

See also

setText for details on allowable characters in the string returned.

getText() [2/2]

void getText

(

QVariant &

value

)

const

Parameters

value

The text data of this SerializedItem. If the text is a bool or numerical value, the correct QVariant type will be set for this parameter.

hasAttribute()

bool hasAttribute

(

const QString &

key

)

const

Returns

True if the item has an attribute named key.

hasAttributes()

bool hasAttributes

(

)

const

Returns

True if this item has any attributes defined.

hasChildren()

bool hasChildren

(

)

const

Returns

True if this item has any child items.

isEmpty()

bool isEmpty

(

const QStringList &

ignoredAttributes = QStringList()

)

const

Returns

True if this item has no attributes, no children and has an empty string for its text.

isNull()

bool isNull

(

)

const

Returns

True if this is a null object (ie is not associated with any data object).

A null SerializedItem object should only ever be encountered through a returned value from previousSibling(), nextSibling() or firstChild().

isSameItem()

bool isSameItem

(

const SerializedItem &

item

)

const

Parameters

item	The item to test.

Returns

True if item and this item refer to the same underlying data. If item and this item are different copies of data that happen to be otherwise identical, this function still returns false because the two items are distinct. The function is testing whether the two items refer to the same data, not whether the data they point to is equivalent.

isSameTree()

bool isSameTree

(

const SerializedItem &

item

)

const

Parameters

item	The item to test.

Returns

True if item and this item are part of the same SerializedTree.

nextSibling()

SerializedItem nextSibling

(

const QString &

tag = QString()

)

const

Parameters

tag	The tag name for the next sibling to return. If this is empty, then the next sibling will be returned regardless of its tag.

Returns

The next sibling to this SerializedItem object which has the specified tag name. If there is no such next sibling, a null object is returned. This can be tested by calling the returned object's isNull() function.

operator=()

SerializedItem & operator=

(

const SerializedItem &

item

)

Parameters

item	SerializedItem object to copy to this one.

Returns

This object.

The assignment operator makes a shallow copy of item, meaning that they point to the same thing in the serialized tree.

previousSibling()

SerializedItem previousSibling

(

const QString &

tag = QString()

)

const

Parameters

tag	The tag name for the previous sibling to return. If this is empty, then the previous sibling will be returned regardless of its tag.

Returns

The previous sibling to this SerializedItem object which has the specified tag name. If there is no such previous sibling, a null object is returned. This can be tested by calling the returned object's isNull() function.

removeAllChildren() [1/2]

void removeAllChildren

(

)

removeAllChildren() [2/2]

void removeAllChildren

(

const QString &

tag

)

removeAttribute()

void removeAttribute

(

const QString &

key

)

Parameters

key	The attribute to remove from the item. If no attribute with this name exists, this function has no effect.

removeChild()

void removeChild

(

const SerializedItem &

child

)

setAttribute() [1/6]

void setAttribute	(	const QString &	key,
		bool	value
	)

Parameters

key	The name of the attribute to set. If it does not yet exist for this data object, it will be created.
value	The value to assign to the named attribute.

Precondition

This must not be a null item (can be tested with the isNull() function).

setAttribute() [2/6]

void setAttribute	(	const QString &	key,
		const char *	value
	)

Parameters

key	The name of the attribute to set. If it does not yet exist for this data object, it will be created.
value	The value to assign to the named attribute.

Precondition

This must not be a null item (can be tested with the isNull() function).

This particular overload is needed because, according to the C++ standard, a pointer has an implicit conversion to bool. Therefore, if a const string is used for value and the const char* overload did not exist, it would erroneously call the bool overload instead of the String overload.

setAttribute() [3/6]

void setAttribute	(	const QString &	key,
		const QString &	value
	)

Parameters

key	The name of the attribute to set. If it does not yet exist for this data object, it will be created.
value	The value to assign to the named attribute.

Precondition

This must not be a null item (can be tested with the isNull() function).

setAttribute() [4/6]

void setAttribute	(	const QString &	key,
		double	value
	)

Parameters

key	The name of the attribute to set. If it does not yet exist for this data object, it will be created.
value	The value to assign to the named attribute.

Precondition

This must not be a null item (can be tested with the isNull() function).

setAttribute() [5/6]

void setAttribute	(	const QString &	key,
		int	value
	)

Parameters

key	The name of the attribute to set. If it does not yet exist for this data object, it will be created.
value	The value to assign to the named attribute.

Precondition

This must not be a null item (can be tested with the isNull() function).

setAttribute() [6/6]

void setAttribute	(	const QString &	key,
		unsigned	value
	)

Parameters

key	The name of the attribute to set. If it does not yet exist for this data object, it will be created.
value	The value to assign to the named attribute.

Precondition

This must not be a null item (can be tested with the isNull() function).

setTagName()

void setTagName

(

const QString &

tag

)

Parameters

tag	The tag name for this object.

This function should be used with care. A number of classes using SerializedItem objects rely on siblings having unique tag names. This condition is usually only checked when a child is added, so changing the tag name may result in such assumptions being violated. Callers of setTagName must ensure that they do not break any such assumptions before making the call.

setText()

void setText

(

const QString &

str

)

Parameters

str	A string holding the text data to associate with this SerializedItem object.

The text data is usually only present for a SerializedItem object with no children. The leaf nodes of the underlying tree will store their data as text using this function.

The string str should pretty much be able to contain anything in the normal character set. Internally, some characters will be encoded (such as the less-than (<) character), but these are re-converted back to their original form when getText is called.