Represents an heterogeneous collection of objects. More...

#include <jem/util/ObjectCollection.h>

Inheritance diagram for jem::util::ObjectCollection:

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

Ref< Enumerator >	enumerate () const
	Returns an enumerator over this collection. More...

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

virtual bool	add (const Ref< Object > &obj)=0
	Adds an object to 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::Object
static Class *	getType ()
	Returns the `Class` instance representing the `Object` class. More...

Protected Member Functions
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 ObjectCollection represents an heterogeneous collection of objects of type Object. It provides functions for adding objects, for removing objects, for iterating over all objects, and for memory management. It is the superclass of various types of collections, including associative collections and ordered collections.

As the ObjectCollection inherits the interface class Enumerable, you can iterate over all objects in a collection by means of an Enumerator object. An ObjectCollection may not be structurally modified while one or more enumerators are pointing to it. In particular, you may not call any non-const member functions such as add() and clear(). All classes in jem that implement these functions will immediately throw an exception if you try to do so.

If you need to store and manipulate a homogeneous collection of objects, you are probably better off with a template class such as the class Flex.

Constructor & Destructor Documentation

virtual jem::util::ObjectCollection::~ObjectCollection ( )

protectedvirtual

Member Function Documentation

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

static

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

static

virtual Class* jem::util::ObjectCollection::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::Object.

Reimplemented in jem::util::HashDictionary, and jem::util::Dictionary.

Ref<Enumerator> jem::util::ObjectCollection::enumerate ( ) const

Returns an Enumerator that can be used to iterate over all objects in this collection. This function simply executes:

return this->getEnumerator ();

This function is not virtual so that it can be overriden by derived classes with a version that returns a special enumerator object. The Dictionary class, for instance, overrides this function with a version that returns a DictionaryEnumerator instead of an Enumerator.

Returns: An Enumerator over all objects in this collection.

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

pure virtual

Returns an Enumerator that can be used to iterate over all objects in this collection. This object collection may not be structurally modified as long as one or more enumerators are pointing to it.

Implements jem::util::Enumerable.

Implemented in jem::util::Dictionary, jem::util::ObjectMap, and jem::util::ObjectSequence.

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

pure virtual

Requests that the object obj is added to this collection. This function returns true if the object has been added, and false otherwise. An implementation of this function does not have to add the object if it is already present in this collection and if all objects in this collection should be unique.

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

Parameters

obj	- the object to be added.

Returns: true if the object has been added to this collection, and false otherwise.

Implemented in jem::util::Dictionary, jem::util::ObjectList, jem::util::ObjectSequence, and jem::util::ObjectMap.

virtual void jem::util::ObjectCollection::clear ( )

pure virtual

Deletes all objects from this collection.

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

Postcondition: this->size() == 0

Implemented in jem::util::ObjectList, jem::util::HashDictionary, jem::util::ObjectSequence, jem::xutil::SnoopDictionary, jem::util::ObjectHashMap, and jem::util::WeakHashMap.

virtual void jem::util::ObjectCollection::reserve ( int n )

virtual

Notifies this collection that it should pre-allocate data structures for storing additional objects. The input parameter n specifies the total number of objects that will be stored in this collection. This function may speed up subsequent calls to the member function add().

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

The implementation of this function provided by the ObjectCollection class does nothing.

Parameters

n	- the total number of objects to be stored in this collection.

Precondition: n >= 0

See also: trimToSize(), capacity()

Reimplemented in jem::util::HashDictionary.

virtual void jem::util::ObjectCollection::trimToSize ( )

virtual

Notifies this collection that it should deallocate non-used memory. Call this function after you have added all objects to this collection.

For efficiency reasons, an ObjectCollection may allocate extra memory each time that an object is added and no more free space is left in its internal data structures. This means that the ObjectCollection may use more memory than is actually needed to store all objects. This member function informs the ObjectCollection that no more new objects will be added and that it should shrink its data structures as much as possible.

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

See also: reserve(), capacity()

Reimplemented in jem::util::HashDictionary, jem::util::ObjectList, jem::xutil::SnoopDictionary, jem::util::ObjectHashMap, and jem::util::WeakHashMap.

virtual int jem::util::ObjectCollection::capacity ( ) const

virtual

Returns the number of objects that this collection can contain without having to expand its internal data structures. This number is called the capacity of this collection.

The implementation of this function provided by the ObjectCollection class simply returns size().

Returns: The capacity of this collection.

Reimplemented in jem::util::HashDictionary, jem::util::ObjectList, jem::xutil::SnoopDictionary, jem::util::ObjectHashMap, and jem::util::WeakHashMap.

virtual int jem::util::ObjectCollection::size ( ) const

pure virtual

Returns the number of objects in this collection.

Returns: The number of objects in this collection.

Implemented in jem::util::HashDictionary, jem::util::ObjectList, jem::xutil::SnoopDictionary, jem::util::ObjectHashMap, and jem::util::WeakHashMap.

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

protected

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

Ref<Enumerator>  e;
Ref<Object>      obj;
clear   ();
reserve ( rhs.size() );
for ( e = rhs.enumerate(); ! e->atEnd(); e->toNext() )
{
  obj = e->get ();
  
  if ( obj != NIL )
  {
    obj = obj->clone ();
  }
  add ( obj );
}

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

Parameters

rhs	- the object collection to be copied.

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

protected

Clears this collection and then fills it with the objects 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::ObjectCollection::writeTo_ ( io::ObjectOutput & out ) const

protected

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

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

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.

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation