Implements an associative, heterogeneous collection that maps strings to objects. More...

#include <jem/util/Dictionary.h>

Inheritance diagram for jem::util::Dictionary:

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

Ref< DictionaryEnumerator >	enumerate () const
	Returns an enumerator over this dictionary. More...

virtual Ref< DictionaryEnumerator >	getDictEnumerator () const =0
	Returns an enumerator over this dictionary. More...

virtual Ref< Enumerator >	getEnumerator () const
	Returns an enumerator over this dictionary. More...

virtual bool	contains (const String &key) const
	Checks whether this dictionary contains a specific key. More...

virtual Ref< Object >	get (const String &key) const
	Returns the object associated with a specific key. More...

virtual bool	find (Ref< Object > &value, const String &key) const =0
	Searches for an object associated with a specific key. More...

virtual void	insert (const String &key, const Ref< Object > &value)=0
	Inserts a key/value pair into this dictionary. More...

virtual void	erase (const String &key)=0
	Deletes a key/value pair from this dictionary. More...

virtual bool	add (const Ref< Object > &obj)
	Adds a key/value pair to this dictionary. More...

Public Member Functions inherited from jem::util::ObjectCollection
Ref< Enumerator >	enumerate () const
	Returns an enumerator over this collection. More...

virtual void	clear ()=0
	Deletes all objects from this collection. More...

virtual void	reserve (int n)
	Pre-allocates data structures for storing additional objects. More...

virtual void	trimToSize ()
	Deallocates non-used memory. More...

virtual int	capacity () const
	Returns the capacity of this collection. More...

virtual int	size () const =0
	Returns the number of objects in this collection. More...

Public Member Functions inherited from jem::Object
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 Class *	makeClass ()

static Class *	getType ()

Static Public Member Functions inherited from jem::util::ObjectCollection
static Class *	makeClass ()

static Class *	getType ()

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

Protected Member Functions
virtual	~Dictionary ()

void	readFrom_ (io::ObjectInput &in)
	Reads the contents of this dictionary from an object input stream. More...

void	writeTo_ (io::ObjectOutput &out) const
	Writes the contents of this dictionary to an object output stream. More...

void	clone_ (const Dictionary &rhs)
	Makes a deep copy of another dictionary. More...

Protected Member Functions inherited from jem::util::ObjectCollection
virtual	~ObjectCollection ()

void	clone_ (const ObjectCollection &rhs)
	Makes a deep copy of another collection. More...

void	readFrom_ (io::ObjectInput &in)
	Reads the contents of this collection from an object input stream. More...

void	writeTo_ (io::ObjectOutput &out) const
	Writes the contents of this collection to an object output stream. More...

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

	~Collectable ()
	Frees resources. More...

Protected Member Functions inherited from jem::util::Enumerable
virtual	~Enumerable ()

Protected Member Functions inherited from jem::Interface
virtual	~Interface ()
	Empty destructor. More...

Detailed Description

The abstract class Dictionary represents an associative, heterogeneous collection that maps keys of type String to values of type Object. All keys in a Dictionary are unique and each key maps to at most one value.

The Dictionary class provides functions for inserting key/value pairs; for retrieving a value associated with a specific key; and for iterating over all key/value pairs by means of a DictionaryEnumerator object. The order in which the enumerator iterates over the key/value pairs is called the order of a Dictionary.

Because the Dictionary class is derived from the ObjectCollection class, one can view a dictionary as regular, non-associative collection of objects that contain the key/value pairs. By default, key/value pairs are stored in objects of type ObjectPair, but a class derived from the Dictionary class is free to store the key/value pairs in objects of another type.

A Dictionary may not be structurally modified as long as one or more enumerators are pointing to it. In particular, you may not call any non-const member functions such as insert() and erase().

See also: Properties

Examples:: meshgen.cpp.

Constructor & Destructor Documentation

virtual jem::util::Dictionary::~Dictionary ( )

protectedvirtual

Member Function Documentation

static Class* jem::util::Dictionary::makeClass ( )

static

static Class* jem::util::Dictionary::getType ( )

static

virtual Class* jem::util::Dictionary::getClass ( ) const

virtual

Returns a pointer to the Class instance representing the runtime class of this object. If T denotes the runtime class of this object, then this function is equivalent with T::getType(). The pointer is valid during the entire lifetime of the program.

Returns: A pointer to the Class instance representing the runtime class of this object.

Reimplemented from jem::util::ObjectCollection.

Reimplemented in jem::util::HashDictionary.

Ref<DictionaryEnumerator> jem::util::Dictionary::enumerate ( ) const

Returns a DictionaryEnumerator that can be used to iterate over the key/value pairs in this dictionary. This function simply executes:

return getDictEnumerator();

Returns: A DictionaryEnumerator over this dictionary.

virtual Ref<DictionaryEnumerator> jem::util::Dictionary::getDictEnumerator ( ) const

pure virtual

Returns a DictionaryEnumerator that can be used to iterate over all key/value pairs in this dictionary. The enumerator points to the first key/value pair, or to the special end object if this dictionary is empty.

This dictionary may not be structurally modified as long as one or more enumerators are pointing to it.

Returns: A DictionaryEnumerator over this dictionary.

Implemented in jem::util::HashDictionary.

virtual Ref<Enumerator> jem::util::Dictionary::getEnumerator ( ) const

virtual

Returns an Enumerator that can be used to iterate over all key/value pairs in this dictionary.

The implementation of this function provided by the Dictionary class simply executes:

return getDictEnumerator();

Returns: An Enumerator over this dictionary.

Implements jem::util::ObjectCollection.

virtual bool jem::util::Dictionary::contains ( const String & key ) const

virtual

Returns true if this dictionary contains the key key, and false otherwise.

The implementation of this function provided by the Dictionary class is equivalent with:

Ref<Object> dummy;
return find ( dummy, key );

Parameters

key	- a key string.

Returns: true if this dictionary contains the key key, and false otherwise.

Reimplemented in jem::xutil::SnoopDictionary.

virtual Ref<Object> jem::util::Dictionary::get ( const String & key ) const

virtual

Returns a reference to the object that is associated with the key key. A NIL reference is returned if this dictionary does not contain the specified key.

The implementation of this function provided by the Dictionary class executes the following code:

Ref<Object> value;
if ( find( value, key ) ) {
  return value;
}
else {
  return NIL;
}

Note that if a dictionary may contain NIL objects, then you may have to call the function contains() if you want to be sure that the dictionary contains the specified key. In this case you are advised to use the function find() instead of get().

Parameters

key	- a key string.

Returns: A reference to the object associated with the specified key, or NIL if there is no such object.

virtual bool jem::util::Dictionary::find	(	Ref< Object > &	value,
		const String &	key
	)		const

pure virtual

Searches for the object that is associated with the key key. If the object is found, then its address is stored in the output parameter value and true is returned. Otherwise, false is returned and the output parameter value is not modified.

This function may not be called if an enumerator points to this dictionary.

Parameters

value	- a reference in which the address of the object to be found is stored.
key	- the key associated with the object to be found.

Returns: true if this dictionary contains the key key, and false otherwise.

Implemented in jem::util::HashDictionary, and jem::xutil::SnoopDictionary.

virtual void jem::util::Dictionary::insert	(	const String &	key,
		const Ref< Object > &	value
	)

pure virtual

Inserts a key/value pair in this dictionary. If this dictionary already contains the key key, then its associated value is replaced by the parameter value.

This function may not be called if an enumerator points to this dictionary.

Parameters

key	- a key string.
value	- the object associated with the key key.

Implemented in jem::util::HashDictionary, and jem::xutil::SnoopDictionary.

virtual void jem::util::Dictionary::erase ( const String & key )

pure virtual

Deletes the key key and its associated value from this dictionary. If this dictionary does not contain the specified key, then this function has no effect.

This function may not be called if an enumerator points to this dictionary.

Parameters

key	- the key to be deleted.

Implemented in jem::util::HashDictionary, and jem::xutil::SnoopDictionary.

virtual bool jem::util::Dictionary::add ( const Ref< Object > & obj )

virtual

Adds the key/value pair encapsulated by the object obj to this dictionary. The dynamic type of the object obj is not specified. The only requirement is that it should have the same type as the key/value objects returned by an enumerator over this dictionary. Thus, if lhs and rhs are two distinct dictionaries of the same type, then the following code should be legal.

Ref<Enumerator> e;
for ( e = rhs.enumerate(); ! e->atEnd(); e->toNext() ) {
  lhs.add ( e->get() );
}

The implementation of this function provided by the Dictionary class expects an object of type ObjectPair. The implementation is as follows:

if ( obj != NIL ) {
  
  Ref<ObjectPair> p = checkedCast<ObjectPair>( obj );
  
  insert ( toValue<String>( p->getFirst() ), p->getSecond() );
  
  return true;
}
else {
  return false;
}

This function may not be called if an enumerator points to this dictionary.

Parameters

obj	- the key/value pair to be added to this dictionary.

Returns: true if the key/value pair has been added, and false otherwise.

Implements jem::util::ObjectCollection.

void jem::util::Dictionary::readFrom_ ( io::ObjectInput & in )

protected

Clears this dictionary and then fills it with the key/value pairs that are read from the object input stream in. This function performs the same operation as the function writeTo_, but then in reverse.

You can use this function to implement the io::Serializable interface class.

Parameters

in	- an object input stream.

Exceptions

io::IOException	- if an I/O error occurs.
io::SerializationException	- if the input stream is corrupt.

void jem::util::Dictionary::writeTo_ ( io::ObjectOutput & out ) const

protected

Writes all objects in this dictionary to the object output stream out. This function essentially executes the following code:

Ref<DictionaryEnumerator> e;
out << size();
for ( e = enumerate(); ! e->atEnd(); e->toNext() ) {
  out << e->getKey ();
  out.encodeObject ( e->getValue() );
}

You can use this function to implement the io::Serializable interface class.

Parameters

out	- an object output stream.

Exceptions

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

void jem::util::Dictionary::clone_ ( const Dictionary & rhs )

protected

Copies the contents of the collection rhs into this collection. This function essentially executes:

Ref<DictionaryEnumerator>  e;
String                     key;
Ref<Object>                value;
clear   ();
reserve ( rhs.size() );
for ( e = rhs.enumerate(); ! e->atEnd(); e->toNext() )
{
  key   = e->getKey   ();
  value = e->getValue ();
  
  if ( value != NIL )
  {
    value = value->clone ();
  }
  
  insert ( key, value );
}

You can use this function to implement the Clonable interface class.

Parameters

rhs	- the dictionary to be copied.

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation