Stores a (large) homogeneous set of objects. More...

Inheritance diagram for jive::util::ItemSet:

Public Types
typedef jem::String	String
	Represents a string type. More...

typedef jem::io::PrintWriter	Printer
	Represents a formatted output stream. More...

typedef jem::util::Dictionary	Dict
	Represents a dictionary. More...

typedef jem::util::Properties	Properties
	Represents a properties set. More...

Public Member Functions
virtual String	toString () const
	Returns a short textual description of this object. More...

virtual int	size () const
	Returns the size of this item set. More...

String	getName () const
	Returns the (descriptive) name of this item set. More...

virtual String	getTagName () const
	Returns an XML tag name for this item set. More...

virtual String	getItemName () const =0
	Returns the type name of an item. More...

virtual String	getItemsName () const
	Returns the plural of an item type name. More...

String	getContext () const
	Returns a context string. More...

virtual ItemMap *	getItemMap () const =0
	Returns the item map associated with this item set. More...

String	getItemPath (int itemID) const
	Returns an identification string for an item. More...

int	findItem (int itemID) const
	Returns the index of an item with a given ID. More...

int	getItemID (int iitem) const
	Returns the ID of the item with a given index. More...

virtual void	printTo (Printer &out) const
	Prints the contents of this item set. More...

void	store (const String &name, const Properties &globdat) const
	Stores this item set in a (global) data set. More...

Public Member Functions inherited from jem::Object
virtual Class *	getClass () const
	Returns the `Class` instance representing the runtime class of this object. More...

virtual long	hashValue () const
	Returns a hash value for this object. More...

virtual bool	equals (const Ref< Object > &obj) const
	Tests whether two objects are equal. More...

Ref< Object >	clone () const
	Returns a copy of this object. More...

Static Public Member Functions
static jem::Ref< ItemSet >	find (const String &name, const Properties &globdat)
	Searches for a named item set in a (global) data set. More...

static jem::Ref< ItemSet >	get (const String &name, const Properties &globdat, const String &context)
	Returns a named item set stored in a (global) data set. More...

static jem::Ref< Dict >	getAll (const Properties &globdat)
	Returns a dictionary containing all item sets in a (global) data set. More...

static StringVector	listAll (const Properties &globdat)
	Returns the names of all item sets stored in a (global) data set. More...

Static Public Member Functions inherited from jem::Object
static Class *	getType ()
	Returns the `Class` instance representing the `Object` class. More...

Public Attributes
jem::util::Event< int, Self & >	newSizeEvent
	Signals that the size of this item set has changed. More...

jem::util::Event< const IntVector &, Self & >	newOrderEvent
	Signals that the items have been re-ordered. More...

Protected Member Functions
	ItemSet (const String &name="")
	Constructs an item set with a given name. More...

virtual	~ItemSet ()

Protected Member Functions inherited from jem::Collectable
	Collectable ()
	Creates an empty `Collectable`. More...

	~Collectable ()
	Frees resources. More...

Protected Attributes
String	myName_
	The descriptive name of this item set. More...

Detailed Description

#include <jive/util/ItemSet.h>

An ItemSet encapsulates a homogeneous set of small objects that are referred to as items. Such an item can be viewed as a blob of data that has both an index and an ID associated with it. The index ranges from zero to the total number of items minus one, and the ID is an arbitrary integer that is unique for each item. The actual data stored in an item is determined by the type of the item set in which it is stored. For instance, an item in a PointSet (that is derived from ItemSet) encapsulates a double precision coordinate vector.

In addition to a set of items, an ItemSet has a name and a reference to a ItemMap object. The former is used mainly to create context strings for errors associated with the ItemSet, while the latter can be used to map item IDs to indices and the other way around.

See also: ItemMap

Examples:: DataParser.cpp.

Member Typedef Documentation

typedef jem::String jive::util::ItemSet::String

Represents a string type.

typedef jem::io::PrintWriter jive::util::ItemSet::Printer

Represents a formatted text output stream.

typedef jem::util::Dictionary jive::util::ItemSet::Dict

Represents a dictionary that maps strings to objects.

typedef jem::util::Properties jive::util::ItemSet::Properties

Represents a properties set.

Constructor & Destructor Documentation

jive::util::ItemSet::ItemSet ( const String & name = "" )

protected

Constructs an item set with name name.

Parameters

name	- the name of this item set.

Postcondition: this->getName() == name

virtual jive::util::ItemSet::~ItemSet ( )

protectedvirtual

Member Function Documentation

virtual String jive::util::ItemSet::toString ( ) const

virtual

Returns a short textual description of this object. The toString method of the class Object returns:

getClass()->getName() + "@" + String( hashValue() )

Returns: A String representing this object.

Reimplemented from jem::Object.

virtual int jive::util::ItemSet::size ( ) const

virtual

Returns the number of items in this set.

Returns: The number of items in this item set.

Reimplemented in jive::util::DummyItemSet, jive::util::StdGroupSet, jive::util::StdMemberSet, and jive::util::StdPointSet.

String jive::util::ItemSet::getName ( ) const

Returns the descriptive name of this item set.

Returns: The name of this item set.

virtual String jive::util::ItemSet::getTagName ( ) const

virtual

Returns a string that can be used as the name of an XML tag containing items of the same type as are stored in this item set. The implementation provided by the ItemSet class simply executes:

return jem::xml::makeTag ( getItemsName() );

Returns: An XML tag for this item set.

virtual String jive::util::ItemSet::getItemName ( ) const

pure virtual

Returns a string that can be used as the type name of an item in this set. For instance, if this item sets contains points, it could return the string "point".

The string returned by this function is mostly used to generate various types of output messagesm, including error messages.

Returns: A string denoting the type of items in this set.

Implemented in jive::util::DummyItemSet, jive::util::StdGroupSet, jive::util::StdMemberSet, jive::util::StdPointSet, jive::util::PointSet, jive::util::GroupSet, and jive::util::MemberSet.

virtual String jive::util::ItemSet::getItemsName ( ) const

virtual

Returns a string that can be used to describe multiple items in this set. In other words, it should return the plural of the name returned by the function getItemName().

The implementation of this function provided by the ItemSet class applies a few simple rules to construct a string that is the plural of the string returned by the getItemName() function.

Returns: A string that describes multiple items in this set.

String jive::util::ItemSet::getContext ( ) const

Returns a context string that can be used for displaying errors and other types of messages that are related to this item set. The returned string is typically passed as a context string to the constructor of an exception class.

Returns: A context string.

virtual ItemMap* jive::util::ItemSet::getItemMap ( ) const

pure virtual

Returns a pointer to the ItemMap object that is associated with this item set. The pointer is guaranteed to be non-null and to be valid throughout the lifetime of this item set.

Returns: A pointer to the ItemMap of this item set.

Implemented in jive::util::DummyItemSet, jive::util::StdGroupSet, jive::util::StdMemberSet, and jive::util::StdPointSet.

String jive::util::ItemSet::getItemPath ( int itemID ) const

Returns an identification string for the item with ID itemID. This string can be used to display messages related to that particular item.

The current implementation of this function simply returns:

String::format ( "%S[%d]", & myName_, itemID )

Parameters

itemID - an item ID.

Returns: An identification string for the item with ID itemID.

int jive::util::ItemSet::findItem ( int itemID ) const

Returns the index of the item with ID itemID, or a negative integer if there is no item in this set with that ID. The function simply executes:

return getItemMap()->findItem ( itemID )

Note that you can better use the ItemMap associated with this item set directly if you have to find many items. In this way you will reduce the number of virtual function calls and speed up your code.

Parameters

itemID - an item ID.

Returns: The index of the item with ID itemID, or a negative number.

int jive::util::ItemSet::getItemID ( int iitem ) const

Returns the ID of the item with index iitem. This function simple executes:

return getItemMap()->getItemID ( iitem )

Note that you can better use the ItemMap associated with this item set directly if you have to get the IDs of many items. In this way you will reduce the number of virtual function calls and speed up your code.

Parameters

iitem - a valid item index

Precondition: iitem >= 0 && iitem < size()

Returns: The ID of the item with index iitem.

virtual void jive::util::ItemSet::printTo ( Printer & out ) const

virtual

Writes the contents of this item set to the formatted output stream out. This function should not print the delimiting XML tags.

The implementation of this function provided by the ItemSet class prints the string returned by the function toString().

Parameters

out	- a formatted text output stream.

Exceptions

jem::io::IOException - if an I/O error occurs.

void jive::util::ItemSet::store	(	const String &	name,
		const Properties &	globdat
	)		const

Stores this item set as a property named name in the global data set globdat. This function also stores a reference to this item set in a special dictionary (stored in globdat) that can be accessed with the member function getAll().

Note that the name parameter is required because an item set is normally stored as a property with a shorter name than the full name of this item set that is returned by the member function getName().

Parameters

name	- the name of this item set in globdat.
globdat	- a (global) data set.

See also: Globdat

static jem::Ref<ItemSet> jive::util::ItemSet::find	(	const String &	name,
		const Properties &	globdat
	)

static

Searches for an item set named name in the global data set globdat. If found, a reference to the item set is returned, else NIL is returned.

Parameters

name	- the name of the item set to be found.
globdat	- a (global) data set.

Returns: The item set named name in globdat, or NIL if there is no such item set.

See also: store(), Globdat

static jem::Ref<ItemSet> jive::util::ItemSet::get	(	const String &	name,
		const Properties &	globdat,
		const String &	context
	)

static

Returns a reference to the item set named name in the global data set globdat. An exception is thrown if there is no such item set. The parameter context will be used as the context string for the exception.

Parameters

name	- the name of the item set to be retrieved.
globdat	- a (global) data set.
context	- an error context string.

Returns: The item set named name in globdat.

Exceptions

jem::IllegalInputException - if there is no item set named name in the data set globdat.

See also: find(), Globdat

static jem::Ref<Dict> jive::util::ItemSet::getAll ( const Properties & globdat )

static

Returns a dictionary containing all item sets in the global data set globdat. To be precise, the dictionary conains all item sets that have been stored in globdat by a call to the store() member function.

Parameters

globdat - a global data set.

Returns: A dictionary containing all item sets in globdat.

static StringVector jive::util::ItemSet::listAll ( const Properties & globdat )

static

Returns an array containing all the names of the item sets stored in the global data set globdat. Note that the array contains the names passed to the store() member function, and not the names returned by the getName() member function.

Member Data Documentation

jem::util::Event< int, Self& > jive::util::ItemSet::newSizeEvent

Signals that the size of this item set (that is, the number of items) has changed. The first event argument is the new size of this item set. The second event argument is a reference to this item set.

jem::util::Event< const IntVector&, Self& > jive::util::ItemSet::newOrderEvent

Signals that the items in this set have been re-ordered. The first event argument specifies how the items have been re-ordered. If this argument is denoted by iperm, then iperm[i] is the new index of the i-th item. If iperm[i] is a negative number, then the i-th item has been deleted. The second event argument is a reference to this item set.

Note that the item IDs do not change when the items are re-ordered.

String jive::util::ItemSet::myName_

protected

The string myName_ stores the descriptive name of this item set. It is initialized by the string passed to the constructor of the ItemSet class.

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation