OrderedCltn--Ordered Collection of Object Pointers

Class OrderedCltn implements a variable-length array of pointers to objects. Object pointers are indexed originating at 0, with index range checking. The member function add() appends objects to the end of the array at index size().

CONSTRUCTORS

OrderedCltn(unsigned capacity =DEFAULT_CAPACITY): Constructs an empty OrderedCltn that can hold up to capacity objects. An
NIHCL_ALLOCSIZE error is raised if capacity is not greater than 0. If an attempt is made to add more than capacity objects to an OrderedCltn, reSize() is called to increase its capacity.

ADDING OBJECTS

virtual Object* add(Object& ob)
virtual Object* addLast(Object& ob): Add the object ob to the end of this OrderedCltn and return a pointer to ob.
virtual Object* addAfter(const Object& ob, Object& newob)
virtual Object* addBefore(const Object& ob, Object& newob): Finds the first object in this OrderedCltn that is isEqual() to ob, inserts newob before or after it, and returns a pointer to newob. If no object equal to ob is found, an NIHCL_OBNOTFOUND error is raised. Since the addition of an object pointer at any position other than at the end of an OrderedCltn causes the pointers above it to be moved up, applications using large OrderedCltns that require many insertions will perform those operations more efficiently with a LinkedList.
virtual Object* addAllLast(const OrderedCltn& cltn): Adds the objects in the OrderedCltn cltn to the end of this OrderedCltn and returns a pointer to cltn.
virtual Collection& addContentsTo(Collection& cltn) const: Adds all of the objects in this OrderedCltn to cltn and returns a pointer to cltn.
virtual void atAllPut(Object& ob): Replaces all object pointers in this OrderedCltn with pointers to object ob.
virtual void replaceFrom(int start, int stop, const SeqCltn& replacement, int startAt=0): Replaces the sequence of object pointers at index start through stop in this OrderedCltn with those in SeqCltn replacement starting at index startAt.

REMOVING OBJECTS

virtual Object* remove(const Object& ob): Removes the first occurrence of an object that is isEqual() to ob from this OrderedCltn and returns a pointer to the removed object. If no equal object is found nil is returned. The remove() function shifts object pointers to fill the array position of the removed object, if necessary.
virtual void removeAll(): Removes all the objects from this OrderedCltn.
virtual Object* removeId(const Object& ob): Removes the first occurrence of the object ob from this OrderedCltn and returns a pointer to ob. Returns nil if ob is not found. The removeId() function shifts object pointers to fill the array position of the removed object, if necessary.
virtual Object* removeLast(): Removes the last object from this OrderedCltn and returns a pointer to it. If this OrderedCltn is empty, an NIHCL_CLTNEMPTY error results.

SEARCHING

virtual Object* after(const Object& ob) const
virtual Object* before(const Object& ob) const: Finds the first object in this OrderedCltn that is isEqual() to ob and returns a pointer to the object after/before it. If the equal object is the last/first in this OrderedCltn, nil is returned. If no object equal to ob is found, an NIHCL_OBNOTFOUND error results.
virtual unsigned hash() const: Returns a number that classes such as Set can use as a hash table probe. Class OrderedCltn implements hash() by exclusinve ORing the results of applying hash() to all objects in an OrderedCltn.
virtual int indexOf(const Object& ob) const: Returns the index of the pointer to the first object that is isEqual() to ob in this OrderedCltn. If no object is found, -1 is returned.
virtual int indexOfSubCollection(const SeqCltn& cltn, int start =0) const: Returns the index of the pointer to the first object of the sequence of objects that is isEqual() to cltn. The search for an equal sequence begins at offset start in this OrderedCltn. If no equal sequence is found, -1 is returned.
virtual unsigned occurrencesOf(const Object& ob) const: Returns a count of the number of objects in this OrderedCltn that are isEqual() to ob.

RELATIONAL OPERATORS

bool operator==(const OrderedCltn&) const
bool operator!=(const OrderedCltn&) const: Return YES if the left OrderedCltn operand is equal to (or not equal to) the right OrderedCltn operand.

TESTING ORDEREDCLTNS

virtual bool isEmpty() const: Returns YES if this OrderedCltn contains no objects.

COPYING ORDEREDCLTNS

virtual void deepenShallowCopy(): Converts this shallow copy to a deep copy by applying deepCopy() to all the object pointers, replacing each pointer with a pointer to its copy.

INDEXING ORDEREDCLTNS

Object*& operator[](int i)
const Object *const& operator[](int i) const
virtual Object*& at(int i)
virtual const Object *const& at(int i) const: Return a reference to the pointer to the ith object in this OrderedCltn. Zero-origin index is used--object pointers are indexed from 0 to size()-1. These functions perform a range check on the index i and raise an NIHCL_INDEXRANGE error if i is out of bounds.
virtual Object* first() const
virtual Object* last() const: Returns a pointer to the first or last object in this OrderedCltn. If this OrderedCltn is empty, an NIHCL_CLTNEMPTY exception results.

ORDEREDCLTN CAPACITY AND SIZE

virtual unsigned capacity() const: Returns the number of objects that this OrderedCltn can hold before it will need to be expanded.
virtual unsigned size() const: Returns the number of objects in this OrderedCltn.
virtual void reSize(unsigned newSize): Changes the capacity of this OrderedCltn to newSize. If newSize is less than or equal to size(), then the capacity is not changed.

COMBINING ORDEREDCLTNS

OrderedCltn operator&(const SeqCltn& cltn) const: Returns an OrderedCltn that is the result of adding all of the objects in cltn to the end of this OrderedCltn.
void operator&=(const SeqCltn& cltn): Replaces this OrderedCltn with the result of adding all of the objects in cltn to the end of this OrderedCltn.

SORTING ORDEREDCLTNS

virtual void sort(): Sorts the objects in this OrderedCltn into ascending order. Object order is determined by applying compare().

PROTECTED MEMBERS

Add/Remove at Index

Object* addAtIndex(int i, Object& ob): Inserts a pointer to ob at the ith index position in this OrderedCltn and returns a pointer to ob. The object pointers originally at index positions i through size()-1 are shifted up one position.
Object* removeAtIndex(int i): Removes the object pointer at index i from this OrderedCltn and returns the removed object pointer. The object pointers originally at index positions i +1 through size()-1 are shifted down one position.

Object I/O

virtual void storer(OIOofd& fd) const
virtual void storer(OIOout& strm) const: Apply storeOn() to each of the objects contained in this OrderedCltn to store them on fd or strm.

EXCEPTIONS RAISED

NIHCL_CLTNEMPTY, NIHCL_OBNOTFOUND

Go to the previous, next section.