The Simons     Component Library

           

---

Collection Class Reference

#include <Collection.h>

Inheritance diagram for Collection:

List of all members.

---

Detailed Description

Collection: the abstract superclass of all collections of objects.

The Collection class is the root of the collections hierarchy, which includes the Sequence, Unordered and Sorted collections. It defines the interface for adding, counting and visiting the elements of a Collection. The semantics of adding an element varies in each subclass, and may be position-sensitive, value-sensitive or disregard duplicates. Counting returns the size of the Collection. Elements may be visited in one pass, by iterating over the Collection using an index in the range 0..n-1 where n is the size of the Collection. Element membership is tested in a single pass, by default, but this is reimplemented more efficiently in descendant classes. Comparison of two Collections and hashing on a Collection are abstract, defined in subclasses. These operations expect to return a result based on the values, and possibly also the ordering, of elements. All the elements of one Collection may be added to another, according to the semantics of adding.

Public Member Functions
	Collection ()
	Create an empty Collection.
virtual	~Collection ()
	Release a Collection.
virtual Void	readOn (ReaderID)
	Read this Collection on a Reader stream.
virtual Void	writeOn (WriterID) const
	Write this Object on a Writer stream.
virtual Natural	size () const
	Return the size of this Collection.
Boolean	empty () const
	Test if this Collection is empty.
virtual Boolean	has (ObjectID) const
	Test if this Collection contains a particular Object.
virtual ObjectID	item (Integer) const
	Select an Object contained in this Collection.
virtual Void	add (ObjectID)
	Add an Object to this Collection.
virtual Void	addAll (CollectionID)
	Add all the elements of another Collection to this Collection.
Protected Member Functions
	Collection (const Collection &)
	Copy another Collection.
Void	rangeExceeded (StringID, Integer) const
	Signal that this Collection has no element at this index.
Void	hasNoElements (StringID) const
	Signal that this Collection has no elements.
Void	hasNoElements (StringID, OutOfRangeID) const
	Signal that this Collection has no elements, after an out-of-range access.

---

Constructor & Destructor Documentation

Collection::Collection (  const Collection &  other  )  [protected]

Copy another Collection. This secret copy constructor is provided to ensure that copying a Collection faithfully copies the parent Object. Parameters: other  - the other Collection to copy. Returns: - a shallow copy of the Collection.

Collection::Collection (   )

Create an empty Collection. Returns: an empty Collection.

Collection::~Collection (   )  [virtual]

Release a Collection.

---

Member Function Documentation

Void Collection::add (  ObjectID  object  )  [virtual]

Add an Object to this Collection. All Collections support the addition of elements. Collections of unique elements will only permit an element to be inserted once. Elements may be inserted in sequential order, or in random order, according to the semantics of the Collection. This method is abstract in Collection, since different Collections add their elements in different ways. Parameters: object  - the Object to be added. Reimplemented in Bag, Map, Relation, Sequence, and Set.

Void Collection::addAll (  CollectionID  other  )  [virtual]

Add all the elements of another Collection to this Collection. All Collections support the inclusion of the elements of another Collection. Depending on the semantics of add(), this is equivalent to set union, bag union, sequence concatenation, or map union with override. By default, iterates over the other Collection using item(), up to the limit size() and uses add() to insert elements into this Collection. A subtype need only reimplement add() to alter the semantics of how elements are added to this Collection. This method allows a Collection of one type to add all the elements of another type of Collection, so is useful for converting between different types of Collection. It is safe to add all the elements of a Collection to itself. Parameters: other  - the other Collection. Reimplemented in String.

Boolean Collection::empty (   )  const

Test if this Collection is empty. Tests whether the size() of this Collection is zero, using suitable subclass implementations of size(). Returns: true if this Collection is empty, otherwise false.

Boolean Collection::has (  ObjectID  object  )  const [virtual]

Test if this Collection contains a particular Object. Searches this Collection for an element that is EQUAL to the object, under compare(). By default, iterates over this Collection in linear time using item(), up to the limit size(), returning as soon as the object is found. This method should be reimplemented in subtypes that support fast searching. Parameters: object  - the sought Object. Returns: true if this Collection contains the object, otherwise false. Reimplemented in Bag, Set, and String.

Void Collection::hasNoElements (  StringID  label, OutOfRangeID  cause )  const [protected]

Signal that this Collection has no elements, after an out-of-range access. Provided for convenience, to chain the two exceptions. Parameters: label  - the name of the method in which failure occurred. cause  - the OutOfRange exception which caused this failure.

Void Collection::hasNoElements (  StringID  label  )  const [protected]

Signal that this Collection has no elements. Provided for convenience, this method is inherited by all Collections and may be used to raise a NoElements exception to signal that an attempt was made to return an element from an empty Collection. Parameters: label  - the name of the method in which failure occurred.

ObjectID Collection::item (  Integer  index  )  const [virtual]

Select an Object contained in this Collection. All Collections support access to their elements, in some order, via an index. This is achieved efficiently, either through providing direct random access, or through internal memos that record positions inside Collections. Repeated access to the same element is guaranteed to be in constant time. Forward iteration using an incrementing index is also very efficient. This method is abstract in Collection, since different Collections access their elements in different ways. Parameters: index  - an index into this Collection. Returns: an Object in this Collection. Reimplemented in Bag, Sequence, and Set.

Void Collection::rangeExceeded (  StringID  label, Integer  index )  const [protected]

Signal that this Collection has no element at this index. Provided for convenience, this method is inherited by all Collections and may be used to raise an OutOfRange exception to signal that an attempt was made to access an element in this Collection at an out-of-range index. Parameters: label  - the name of the method in which failure occurred. index  - the bad index.

Void Collection::readOn (  ReaderID  in  )  [virtual]

Read this Collection on a Reader stream. The size of a Collection is encoded in the header processed by the Reader. This Collection determines its size from the Reader, then iterates for this number of times, using getField("item", anItem) to read each item, which it inserts using add(). Any subclass which expects to read its elements as a single block should reimplement this method. Parameters: in  - a Reader stream. Reimplemented from Object. Reimplemented in String.

Natural Collection::size (   )  const [virtual]

Return the size of this Collection. Counts the number of Object elements held in this Collection. This method is abstract in Collection, since different subclasses store their elements in different ways. Returns: the element count. Reimplemented in Bag, List, Set, String, and Vector.

Void Collection::writeOn (  WriterID  out  )  const [virtual]

Write this Object on a Writer stream. The size of a Collection is encoded in the header by the Writer. This Collection expects the Writer to write out its size, then iterates for this number of times, using putField("item", item(i)) to write each item individually. Any subclass which expects to write its elements as a single block should reimplement this method. Parameters: out  - a Writer stream. Reimplemented from Object. Reimplemented in String.

---

The documentation for this class was generated from the following files:

• Collection.h
• Collection.cc

---