Encapsulates a set of item indices. More...

Inheritance diagram for jive::util::ItemGroup:

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 int	size () const =0
	Returns the size of this item group. More...

virtual IntVector	getIDs () const
	Returns the IDs of the items in this group. More...

virtual IntVector	getIndices () const =0
	Returns the indices of the items in this group. More...

virtual ItemSet *	getItems () const =0
	Returns the item set containing the items in this group. More...

virtual bool	contains (int iitem) const
	Tests whether this group contains a given item index. More...

virtual void	filter (const IntVector &iitems) const
	Marks which item indices are not in this group. More...

int	findMembers (const IntVector &jitems, const IntVector &iitems) const
	Finds all item indices that are members of this group. More...

int	findNonMembers (const IntVector &jitems, const IntVector &iitems) const
	Finds all item indices that are not members of this group. More...

void	printTo (Printer &out) const
	Prints the contents of this group. More...

String	getTagName () const
	Returns an XML tag name for this group. More...

void	store (const String &name, const Properties &globdat) const
	Stores this item group 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 String	toString () const
	Returns a short textual description 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 IntVector	getUnion (const ItemGroup &first, const ItemGroup &second)
	Returns the union of two item groups. More...

static IntVector	getIntersection (const ItemGroup &first, const ItemGroup &second)
	Returns the intersection of two item groups. More...

static void	printGroup (Printer &out, const ItemSet &items, const IntVector &iitems)
	Prints the contents of a given set of item indices. More...

static void	printSome (Printer &out, const Dict &groups, const String &tag="")
	Prints all groups in a given dictionary. More...

static void	printAll (Printer &out, const Properties &globdat)
	Prints all item groups in a global data set. More...

static String	getTagName (const String &itemName)
	Returns an XML tag name for a group given an item type name. More...

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

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

static jem::Ref< Dict >	findFor (const jem::Ref< ItemSet > &items, const Properties &globdat)
	Searches for all groups associated with a given item set. More...

static jem::Ref< Dict >	getFor (const jem::Ref< ItemSet > &items, const Properties &globdat)
	Returns all groups associated with a given item 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 group has changed. More...

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

Protected Member Functions
virtual	~ItemGroup ()

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

	~Collectable ()
	Frees resources. More...

Detailed Description

#include <jive/util/ItemGroup.h>

An ItemGroup encapsulates a reference to an ItemSet and a set of indices referring to items in that set. Use the ItemGroup class to select groups of items in an ItemSet. Note that if you need to store and manipulate a (very) large number of item groups, you may be better off using the GroupSet class.

See also: GroupSet

Examples:: DataParser.cpp, and meshgen.cpp.

Member Typedef Documentation

typedef jem::String jive::util::ItemGroup::String

Represents a string type.

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

Represents a formatted text output stream.

typedef jem::util::Dictionary jive::util::ItemGroup::Dict

Represents a dictionary that maps strings to objects.

typedef jem::util::Properties jive::util::ItemGroup::Properties

Represents a properties set.

Constructor & Destructor Documentation

virtual jive::util::ItemGroup::~ItemGroup ( )

protectedvirtual

Member Function Documentation

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

pure virtual

Returns the number of item indices in this group.

Returns: The size of this group: this->getIndices().size()

Implemented in jive::util::ColoredItemGroup, jive::util::ArrayItemGroup, jive::fem::AutoBndGroup, jive::util::AllItemGroup, and jive::util::EmptyItemGroup.

virtual IntVector jive::util::ItemGroup::getIDs ( ) const

virtual

Returns the IDs of the items in this group. The implementation provided by the ItemGroup class simply executes:

IntVector  iitems  ( getIndices()  );
IntVector  itemIDs ( iitems.size() );
getItems()->getItemMap()->getItemIDs ( itemIDs, iitems );
return itemIDs;

Note that the returned array should not be modified as it may share its data with a private member of this ItemGroup object.

Returns: An array containing the IDs of the items in this group.

Reimplemented in jive::util::EmptyItemGroup.

virtual IntVector jive::util::ItemGroup::getIndices ( ) const

pure virtual

Returns an array containing the indices of the items in this group. The contents of the returned array should not be modified as the array may share its data with one of the private members of this ItemGroup object.

Returns: The indices of the items in this group.

Implemented in jive::util::ColoredItemGroup, jive::util::ArrayItemGroup, jive::fem::AutoBndGroup, jive::util::AllItemGroup, and jive::util::EmptyItemGroup.

virtual ItemSet* jive::util::ItemGroup::getItems ( ) const

pure virtual

Returns a pointer to the item set containing the items selected by this ItemGroup object. The pointer is guaranteed not to be NULL and to remain valid throughout the entire lifetime of this ItemGroup object.

Returns: A pointer to the item set referred to by this item group.

Implemented in jive::util::ColoredItemGroup, jive::util::ArrayItemGroup, jive::fem::AutoBndGroup, jive::util::AllItemGroup, and jive::util::EmptyItemGroup.

virtual bool jive::util::ItemGroup::contains ( int iitem ) const

virtual

Tests whether this item group contains the item index iitem. The implementation provided by the ItemGroup class simply searches the array returned by the getIndices() member function; derived classes are encouraged to provide a more efficient implementation.

Parameters

iitem - a valid item index.

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

Returns: true if this item group contains the index iitem, and false otherwise.

virtual void jive::util::ItemGroup::filter ( const IntVector & iitems ) const

virtual

Sets all item indices in the array iitems that are not in this group to a negative number. The item indices that are in this group are untouched. The default implementation provided by the ItemGroup class calls the contains() member function for each index in the array iitems.

Parameters

iitems - an array containing valid item indices.

Precondition: min(iitems) >= 0 && max(iitems) < getItems()->size()

int jive::util::ItemGroup::findMembers	(	const IntVector &	jitems,
		const IntVector &	iitems
	)		const

Fills the array jitems with the item indices in the array iitems that are members of this group. The integer returned by this function is the number of indices that have been copied from iitems to jitems. That is, if n denotes the return value, then jitems[slice(BEGIN,n)] contains all the copied indices.

The current implementation of this function copies all indices from iitems to jitems; then calls the filter() member function; and finally removes all negative indices from jitems.

Parameters

jitems	- an array to be filled with the indices in iitems that are members of this group.
iitems	- an array containing valid item indices.

Precondition: jitems.size() >= iitems.size() && min(iitems) >= 0 && max(iitems) < getItems()->size()

Returns: The number of indices that have been copied from iitems to jitems.

int jive::util::ItemGroup::findNonMembers	(	const IntVector &	jitems,
		const IntVector &	iitems
	)		const

Fills the array jitems with the item indices in the array iitems that not are members of this group. The integer returned by this function is the number of indices that have been copied from iitems to jitems.

Parameters

jitems	- an array to be filled with the indices in iitems that are not members of this group.
iitems	- an array containing valid item indices.

Precondition: jitems.size() >= iitems.size() && min(iitems) >= 0 && max(iitems) < getItems()->size()

Returns: The number of indices that have been copied from iitems to jitems.

See also: findMembers()

static IntVector jive::util::ItemGroup::getUnion	(	const ItemGroup &	first,
		const ItemGroup &	second
	)

static

Returns an array containing the item indices that are members of either the item group first and the item group second.

Parameters

first	- an item group.
second	- another item group referring to the same item set as first.

Precondition: first.getItems() == second.getItems()

Returns: An item index array containing the union of the groups first and second.

static IntVector jive::util::ItemGroup::getIntersection	(	const ItemGroup &	first,
		const ItemGroup &	second
	)

static

Returns an array containing the item indices that are members of both the item group first and the item group second.

Parameters

first	- an item group.
second	- another item group referring to the same item set as first.

Precondition: first.getItems() == second.getItems()

Returns: An item index array containing the intersection of the groups first and second.

void jive::util::ItemGroup::printTo ( Printer & out ) const

Writes the contents of this group to the formatted output stream out. This function simply executes:

printGroup ( out, *getItems(), getIndices() )

Parameters

out	- a formatted text output stream.

static void jive::util::ItemGroup::printGroup	(	Printer &	out,
		const ItemSet &	items,
		const IntVector &	iitems
	)

static

Writes the set of item indices in the array iitems to the formatted text output stream out. The parameter items is the set containing the items to which the indices in iitems refer. This function does not print any delimiting XML tags.

Parameters

out	- a formatted text output stream.
items	- an item set.
iitems	- an array containing valid item indices.

Precondition: min(iitems) >= 0 && max(iitems) < items.size()

See also: ItemGroupParser printSome(), printAll()

static void jive::util::ItemGroup::printSome	(	Printer &	out,
		const Dict &	groups,
		const String &	tag = `""`
	)

static

Writes all item groups in the dictionary groups to the formatted text output stream out. Each group is delimited by a pair of XML tags of which the name is tag. However, if tag is an empty string, the string returned by the member function getTagName() will be used as the name of the XML tags.

Note that this function will ignore all objects in the dictionary groups that are not derived from the ItemGroup class.

Parameters

out	- a formatted text output stream.
groups	- a dictionary containing a set of item groups.
tag	- the (optional) name of the XML tags enclosing each group.

See also: ItemGroupParser, printAll()

static void jive::util::ItemGroup::printAll	(	Printer &	out,
		const Properties &	globdat
	)

static

Writes all item groups stored in the global data set globdat to the formatted text output stream out. This function essentially calls the function ItemSet::listAll() to find the names of all item set in globdat, and then prints all item groups associated with each item set.

Parameters

out	- a formatted text output stream.
globdat	- a global data set.

See also: Globdat

String jive::util::ItemGroup::getTagName ( ) const

Returns a string that can be used as the name of an XML tag enclosing this item group. This function simply returns:

getTagName ( getItems()->getItemName() )

Returns: An XML tag for this item group.

static String jive::util::ItemGroup::getTagName ( const String & itemName )

static

Returns string that can be used as the name of an XML tag enclosing a group referring to items with type name itemName. The current implementation of this function returns:

jem::xml::makeTag( itemName ) + "Group"

Returns: An XML tag for an item group.

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

Stores this item group in the global data set globdat, using name as the name of this item group. This function has the same effect as:

Ref<Dict> groups = getFor ( getItems(), globdat );
dict->insert ( name, this );

Parameters

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

See also: Globdat

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

static

Searches for an item group named name in the global data set globdat. The parameter items is the item set that is associated with the item group to be found. This function has the same effect as:

Ref<Dict> findFor ( items, globdat );
if ( dict != NIL )
{
  return dynamicCast<ItemGroup> ( dict->get( name ) );
}
else
{
  return NIL;
}

Parameters

name	- the name of the item group to be found.
items	- the item set associated with the group to be found.
globdat	- a global data set.

Precondition: items != NIL

Returns: A reference to the searched item group, or NIL if that group does not exist in globdat.

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

static

Returns a reference to the item group named name that has been stored in the global data set globdat and that refers to the items in the set items. An exception is thrown if the group does not exist. The parameter context will be used as the context string for the exception.

Parameters

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

Precondition: items != NIL

Returns: A reference to the item group named \ a name.

Exceptions

jem::IllegalInputException - if the item group does not exist.

See also: find()

static jem::Ref<Dict> jive::util::ItemGroup::findFor	(	const jem::Ref< ItemSet > &	items,
		const Properties &	globdat
	)

static

Returns a reference to a dictionary that has been stored in the global data set globdat and that contains all groups referring to items in the set items. If there is no such dictionary, the value NIL is returned.

Parameters

items	- an item set.
globdat	- a global data set.

Precondition: items != NIL

Returns: A dictionary containing all groups referring to the item set items, or NIL.

See also: getFor()

static jem::Ref<Dict> jive::util::ItemGroup::getFor	(	const jem::Ref< ItemSet > &	items,
		const Properties &	globdat
	)

static

Returns a dictionary that has been stored in the global data set globdat and that contains all groups referring to items in the set items. If there is no such dictionary, a new one will be created and stored in globdat. The new dictionary will contain one AllItemGroup object named "all".

Parameters

items	- an item set.
globdat	- a global data set.

Precondition: items != NIL

Returns: A dictionary containing all groups referring to the item set items.

Member Data Documentation

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

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

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

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

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation