ObjectDictionary Class Reference

Holds a named set of DataObject instances, previosuly DataAnalysis::DataCollection. More...

#include <Workspace/DataExecution/DataObjects/objectdictionary.h>

Inheritance diagram for ObjectDictionary:

Classes
struct	Accessor

Public Types
using	const_iterator = Application::IndexBasedIterator< ObjectDictionary, true, value_type, size_type, difference_type, Accessor< true > >
using	difference_type = long
using	iterator = Application::IndexBasedIterator< ObjectDictionary, false, value_type, size_type, difference_type, Accessor< false > >
using	size_type = int
using	value_type = DataObject

Public Member Functions
	ObjectDictionary ()
	ObjectDictionary (const ObjectDictionary &data)
	~ObjectDictionary () override
DataExecution::DataObject &	addItem (const DataExecution::DataFactory &factory, const QString &name, const QString &description, bool ensureHasData=true)
template<typename T >
T &	addItem (const QString &name, const QString &description="")
DataExecution::DataObject &	addItemCopy (const DataExecution::DataObject &obj, const QString &name, const QString &description="")
template<typename T >
DataExecution::DataObject &	addItemCopy (const T &obj, const QString &name, const QString &description="")
template<typename T >
DataExecution::DataObject &	addItemPtr (T *ptr, const QString &name, bool takeOwnership, const QString &description="")
iterator	begin ()
const_iterator	begin () const
bool	canSerialize () const override
void	clear ()
int	count () const
iterator	end ()
const_iterator	end () const
template<typename T >
ObjectDictionary *	findParent (const T &child)
template<typename T >
const ObjectDictionary *	findParent (const T &child) const
QString	getCollectionIdentifier () const
QString	getDescription (const QString &name) const
const QString &	getDescription (int index) const
DataExecution::DataObject *	getItem (const QString &name)
template<typename T >
T *	getItem (const QString &name)
const DataExecution::DataObject *	getItem (const QString &name) const
template<typename T >
const T *	getItem (const QString &name) const
DataExecution::DataObject *	getItem (int index)
const DataExecution::DataObject *	getItem (int index) const
QStringList	getItemDescriptions () const
int	getItemIndex (const DataExecution::DataObject &obj) const
int	getItemIndex (const QString &name) const
template<typename T >
int	getItemIndex (const T &item) const
QStringList	getItemNames () const
const QString &	getName (int index) const
QString	getNamePath (const DataExecution::DataObject &obj) const
QStringList	getNames () const
bool	hasName (const QString &name) const
bool	load (const DataExecution::SerializedItem &item) override
ObjectDictionary &	operator= (const ObjectDictionary &data)
void	removeItem (const QString &name)
bool	renameItem (const QString &oldName, const QString &newName)
bool	save (DataExecution::SerializedItem &item) const override
void	setCollectionIdentifier (const QString &identifier)
void	setDescription (const QString &name, const QString &description)
Public Member Functions inherited from Serialize
virtual	~Serialize ()=default
virtual bool	canSerialize () const =0
virtual bool	load (const SerializedItem &item)=0
virtual bool	save (SerializedItem &item) const =0

Static Public Member Functions
static bool	fromQVariant (const QVariant &v, DataExecution::ObjectDictionary *&data, bool deepConvert, bool &ownsData)

Detailed Description

A ObjectDictionary is able to hold a named set of mixed data types. Any data type that the Workspace knows about (ie any data type with an associated DataFactory) can be added to a dictionary. Each item added must be given a name that is unique among all items in the collection and this name cannot be changed after it is set. Each item can have a description, and there are no requirements on the description itself (it can even be left blank). The description can be changed, although normally it will be set when the item is first created and left alone after that.

Items can only be added by the templated addItem() function. This ensures that the data type is specified on a robust way. Items can only be removed by calling removeItem() and removal is always based on the name.

The dictionary owns the data it holds. Do not attempt to take ownership of any item's data. You can access the data using the templated getItem() function if you know what data type to expect, or else use the non-templated getItem() function and query the data object returned to ascertain the data type.

A ObjectDictionary can have an identifier (a string) that may be useful when dealing with a collection of collections.

Member Typedef Documentation

const_iterator

using const_iterator = Application::IndexBasedIterator<ObjectDictionary, true, value_type, size_type, difference_type, Accessor<true> >

difference_type

using difference_type = long

iterator

using iterator = Application::IndexBasedIterator<ObjectDictionary, false, value_type, size_type, difference_type, Accessor<false> >

size_type

using size_type = int

value_type

using value_type = DataObject

Constructor & Destructor Documentation

ObjectDictionary() [1/2]

ObjectDictionary

(

)

Creates an empty dictionary.

ObjectDictionary() [2/2]

ObjectDictionary

(

const ObjectDictionary &

data

)

Parameters

data	An existing dictionary to be copied.

This constructor creates a deep copy of data. The data objects held in data are cloned if they support cloning. For those objects that don't support cloning, a new object is created but it will not be a clone or copy of the corresponding object in data.

~ObjectDictionary()

~ObjectDictionary ( )

override

Destroys all data held in the collection.

Member Function Documentation

addItem() [1/2]

DataObject & addItem	(	const DataExecution::DataFactory &	factory,
		const QString &	name,
		const QString &	description,
		bool	ensureHasData = true
	)

Parameters

factory	The factory of the data type for this item.
name	The name of the item to add. It should not already exist in the collection. If it does, then the existing item must have the same factory as the one being specified here. In this case, the existing data object will be returned. Unlike some other member functions, name cannot be a name path (see getItem() for more information on name paths).
description	The description for this particular item. It can be empty, but normally it would contain something useful since it will often be shown to the user in widgets, plots, etc.
ensureHasData	Ensure the object create has valid data allocated. If set to false clients should ensure they set the data manually in the returned DataObject before using any other methods on this instance.

Returns

The data object for the new item. The collection retains ownership of this object and the caller should not attempt to manipulate the DataObject but rather operate only on the actual data it holds. The DataObject returned is guaranteed to return true for calling its hasData() function.

See also

hasName(), getItem()

addItem() [2/2]

T & addItem ( const QString &  name, const QString &  description = ""  )

inline

addItemCopy() [1/2]

DataExecution::DataObject & addItemCopy	(	const DataExecution::DataObject &	obj,
		const QString &	name,
		const QString &	description = ""
	)

Parameters

obj	The data object to clone from for this item.
name	The name of the item to add. It should not already exist in the collection. If it does, then the existing item must have the same factory as the one being specified here. In this case, the existing data object will be returned. Unlike some other member functions, name cannot be a name path (see getItem() for more information on name paths).
description	The description for this particular item. It can be empty, but normally it would contain something useful since it will often be shown to the user in widgets, plots, etc.

Returns

The data object for the new item. The collection retains ownership of this object and the caller should not attempt to manipulate the DataObject but rather operate only on the actual data it holds. The DataObject returned is guaranteed to return true for calling its hasData() function.

See also

hasName(), getItem()

addItemCopy() [2/2]

DataExecution::DataObject & addItemCopy ( const T &  obj, const QString &  name, const QString &  description = ""  )

inline

addItemPtr()

DataExecution::DataObject & addItemPtr ( T *  ptr, const QString &  name, bool  takeOwnership, const QString &  description = ""  )

inline

begin() [1/2]

iterator begin ( )

inline

begin() [2/2]

const_iterator begin ( ) const

inline

canSerialize()

bool canSerialize ( ) const

overridevirtual

Returns

True if this object can be serialized.

For objects that can be serialized, the save and load functions will be used to do the serialization. If this function returns false, both load() and save() must also return false.

Implements Serialize.

clear()

void clear

(

)

Discards all data held by the collection, leaving it with no contents.

count()

int count

(

)

const

Returns

The number of items in the collection.

Note

The count is not recursive - it does not include the counts of any collections included within this collection.

end() [1/2]

iterator end ( )

inline

end() [2/2]

const_iterator end ( ) const

inline

findParent() [1/2]

ObjectDictionary * findParent ( const T &  child )

inline

findParent() [2/2]

const ObjectDictionary * findParent ( const T &  child ) const

inline

fromQVariant()

bool fromQVariant ( const QVariant &  v, DataExecution::ObjectDictionary *&  data, bool  deepConvert, bool &  ownsData  )

static

getCollectionIdentifier()

QString getCollectionIdentifier

(

)

const

Returns a string (set by calling setCollectionIdentifier()) that can be used to identify the collection. This is useful when dealing with a collection of collections.

getDescription() [1/2]

QString getDescription

(

const QString &

name

)

const

Parameters

name	The name of the item whose description is to be retrieved.

Returns

The description of the specified item or an empty string if name is not in the collection.

getDescription() [2/2]

const QString & getDescription

(

int

index

)

const

getItem() [1/6]

DataObject * getItem

(

const QString &

name

)

Parameters

name	The name of the item to search for in the collection. This can also be a name path, with forward slashes as the separator. The name path then refers to sub-collections below this one, nested as far as the name path requires.

Returns

A pointer to the item's data object if the specified name exists, or a null pointer if the name was not in the collection (or the name path in name was not valid).

Warning

The collection retains ownership of the object and the caller should not attempt to manipulate the DataObject other than to work out what factory it belongs to and to access the underlying data held by the DataObject. If a non-null result is returned, it can be assumed that the result of calling its hasData() member function will be true.

getItem() [2/6]

T * getItem ( const QString &  name )

inline

getItem() [3/6]

const DataObject * getItem

(

const QString &

name

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getItem() [4/6]

const T * getItem ( const QString &  name ) const

inline

getItem() [5/6]

DataExecution::DataObject * getItem

(

int

index

)

getItem() [6/6]

const DataExecution::DataObject * getItem

(

int

index

)

const

getItemDescriptions()

QStringList getItemDescriptions

(

)

const

Returns

A list of descriptions for the immediate items held by the data collection. The list will be in the order that items were added to the collection.

getItemIndex() [1/3]

int getItemIndex

(

const DataExecution::DataObject &

obj

)

const

Parameters

obj	The data object to search for in the collection.

Returns

The index of the item in the collection if it exists, -1 if it doesn't.

getItemIndex() [2/3]

int getItemIndex

(

const QString &

name

)

const

Parameters

name	The name of the item to search for in the collection.

Returns

The index of the item in the collection if it exists, -1 if it doesn't.

getItemIndex() [3/3]

int getItemIndex ( const T &  item ) const

inline

getItemNames()

QStringList getItemNames

(

)

const

Returns

A list of names for the immediate items held by the data collection. The list will be in the order that items were added to the collection.

getName()

const QString & getName

(

int

index

)

const

getNamePath()

QString getNamePath

(

const DataExecution::DataObject &

obj

)

const

getNames()

QStringList getNames

(

)

const

Returns

A list of the names held by the dictionary. Names will be in the order in which they were added to the collection.

hasName()

bool hasName

(

const QString &

name

)

const

Parameters

name	A name to search for in the collection. It can also be a name path with forward slashes as the separator.

Returns

True if the specified name exists in the collection. Note that if name is a name path, then this function will return true if that name path could be found.

See also

getItem()

load()

bool load ( const DataExecution::SerializedItem &  item )

overridevirtual

Parameters

item	Supplies the state to be loaded into this object.

This function will load the state of this object from item. For many object types, this is most easily implemented in terms of the object's input operator (>>).

It would be reasonable for subclass implementations to assume that the data provided in item is in the same form as would have been saved from a call to save.

Returns

If the state of the object could not be loaded, the function returns false. A return value of true implies that the object state was successfully loaded. If canSerialize() returns false, this function must do nothing except return false as well.

Implements Serialize.

operator=()

ObjectDictionary & operator=

(

const ObjectDictionary &

data

)

Parameters

data	An existing dictionary to be copied.

The assignment operator behaves exactly the same way as the copy constructor. It creates a deep copy of data and the data objects held in data are cloned if they support cloning. For those objects that don't support cloning, a new object is created but it will not be a clone or copy of the corresponding object in data.

removeItem()

void removeItem

(

const QString &

name

)

Parameters

name	The name of the item to remove. It cannot be a name path, but it can refer to a sub-collection (in which case the entire sub-collection is removed just like any other data type would be).

If the specified name is not found in the collection, this function does nothing. otherwise it deletes the data associated with the specified name and removes it from the collection.

renameItem()

bool renameItem	(	const QString &	oldName,
		const QString &	newName
	)

Parameters

oldName	The local name of the item to rename (not recursive)
newName	The new name of the item

Renames an item in the ObjectDictionary without copying the underlying data.

Returns

true if the item was renamed successfully, false if it either didn't exist or if an item with the same name already exists.

save()

bool save ( DataExecution::SerializedItem &  item ) const

overridevirtual

Parameters

item	Where to save the state of this object.

This function will serialise the object by saving it to item. For most object types, this is most easily implemented in terms of the object's output operator (<<).

It is allowable for an object to only serialize part of itself. This would be useful if the data it represents has a set of defaults and only those values different to the defaults need to be serialized. Such an implementation then needs to be careful how it handles the complimentary load member function.

Returns

If an object could not be serialised or if the underlying object type does not support serialisation, this function should return false. A return value of true implies that the object was successfully saved to item. If canSerialize() returns false, this function must do nothing except return false as well.

Implements Serialize.

setCollectionIdentifier()

void setCollectionIdentifier

(

const QString &

identifier

)

Parameters

identifier

The string to be used to identify the collection Set a string on the collection that can be used to identify it. This is useful when dealing with a collection of collections.

setDescription()

void setDescription	(	const QString &	name,
		const QString &	description
	)

Parameters

name	The name of the item whose description should be set.
description	The new description to use for name.

If no item with the specified name exists in the collection, this function has no effect.