index previous next




file name: listbase.hpp, listbase.cpp
classification: simulation
contents: abstract class ACObjectList
use: provide a basic class for storing arbitrary data with arbitrary key (no duplicates, optimized for sequential access)


global items used:


member types:

 class CObjectElement: stores a (void) pointer to the data and a (void) pointer to its key


member variables:

 INT32 allocSize_: the number of additional elements that are allocated if the array is expanded.
default: parameter aSize of the ctor

 CObjectElement *array_: a pointer to the beginning of the sorted array. Every entry is stored in an object of type CObjectElement.
default and reset value: a newly created array with allocSize elements.

 INT32 current_: contains the index of the currently accessed entry. That may also be a free entry (in that case, the current pointer is said to be invalid).
default and reset value: 0

 INT32 firstFree_: contains the index of the first free entry in the array.
default and reset value: 0

 INT32 size_: the current size of the array.
default and reset value: allocSize


member functions:

 ACObjectList (INT32 aSize = ArrayAllocationSize): The data is stored in an array, so aSize is the number of array entries that are allocated or freed whenever the array is expanded or shrinked. The ctor allocates an array of storage objects (type CObjectElement) with that number of entries. allocSize stores the aSize value.

 virtual ~ACObjectList (): destructor, pure virtual
Since a destructor is always called, even if it is pure virtual, the array that is created in the ctor is deleted here. Deleting the array deletes the storage objects of type CObjectElement, but does not free the memory used for the data and key. So all entries should be deleted before the list class is destroyed.

 void AllocateMemory(): Allocates a new array that is allocSize elements bigger than the current array. The data is copied to the new array, and the old array is discarded.

 INT32 AllocationSize() const: Returns the additional size used for expansion or contraction of the array.

 EBool BeginOfList () const: Returns True if the current pointer, which always contains the index of the data that was accessed last, is at the beginning of the list, False if it is not at the beginning or if the array is empty.

 virtual int Compare (void *key1, void* key2) const: pure virtual
The function should return -1 if key1 < key2, 0 if key1 = key2, and +1 if key1 > key2. Derived classes must define this function and cast the key parameters to their correct type.

 int CompareToCurrent (void *key) const: The function behaves like a call to Compare() with key1=key and key2=GetCurrentKey(). Again, current must contain a valid index, otherwise an assert will fail.

 EBool CurrentIsValid () const: The function returns True if current contains the index of an occupied slot, False if it does not.

 virtual void DeleteKey (void *key): pure virtual
The function should free the memory of the key structure. This function is called whenever an object is removed. Derived classes must define the function, cast the key parameter to its correct type and delete it.

 EBool Empty() const: returns True if the array is empty, False if objects are stored.

 EBool EndOfList () const: Returns True if the current pointer is at the end of the list, False if it is not at the end or if the array is empty.

 void* Find (void *key): Searches for an entry with the given key. The function uses CompareKey() to move in the array. If the list is not empty, it first checks if current is valid. If it is, the element current points to is checked. If the key does not match the search key, it checks the neighbours of current. If their keys do not match either, or if current was invalid in the first place, binary search is used to find the element. If it is found, the pointer to the data is returned and current contains its index. If it is not found, NULL is returned and current contains the index where the element should be inserted (if the element is to be appended, current is now invalid!).

 void FreeMemory(): Allocates a new array that is allocSize elements smaller than the current array (if that would result in a non-positive size, an assert fails). The data is copied to the new array, and the old array is discarded. All data must fit into the new array. If that is not the case, an assert will fail.

 void* GetCurrent () const: Returns the pointer to the data entry of the element pointed to by current. current must contain a valid index, otherwise an assert will fail.

 void* GetCurrentKey () const: The function returns the pointer to the key of the element pointed to by current. current must contain a valid index, otherwise an assert will fail.

 void* GetCurrentObject () const: Returns a pointer to the data element that is currently being accessed or NULL, if no element is being accessed.

 void* GetCurrentObjectKey () const: Returns a pointer to the key of the element that is currently being accessed or NULL, if no element is being accessed.

 void* GetFirst (): Returns the pointer to the first data entry in the array, or NULL if the array is empty. If the list is not empty, current is set to the index of the first element.

 void* GetLast (): Returns the pointer to the last data entry in the array, or NULL if the array is empty. If the list is not empty, current is set to the index of the last element.

 void* GetNext (): If current is valid, ie., if it contains the index of an array entry that is occupied (data is stored there), the function returns the pointer of the next data entry in the array. It returns NULL if the array is empty, if the end of the array is reached or if current does not point to an occupied slot. If this next element exists, current is incremented accordingly.

 void* GetPrev (): If current is valid, the function returns the pointer to the previous data entry in the array. It returns NULL if the array is empty, if the beginning of the array has been reached or if current is not valid. If this previous element exists, current is decremented accordingly.

 EBool Insert (void *object, void *key): Inserts a new element into the sorted array. If either the object or the key pointer are NULL, False is returned and nothing happens. Otherwise, the list is searched for an entry with the given key. If one is found, again False is returned (so you may not store entries with duplicate keys). If no element with this key was found, the data pointer and key are stored in the array and True is returned. If the last free entry in the array was used, a new array with more elements (allocSize entries more than in last array) is allocated and all entries are copied from the old array to the new one.

 void InsertAtCurrent (void *object, void *key): Inserts the new data at the index specified by current. Shifts the rest of the array one element to the right. If current is not valid or if the array does not contain any free elements, an assert fails. If the array is full after the new data is inserted, a bigger array is allocated using AllocateMemory().

 INT32 Occupied() const: Returns the number of array elements that are currently in use.

 void* Remove (void *key): Removes the data entry with the given key, ie., it searches for the element, and if the element is found, the array slot is freed, the memory used for the key is deleted calling DeleteKey() and the pointer to the data entry is returned. If key is NULL or if the data was not found, NULL is returned. If more than allocSize+1 entries are free, a new array with fewer entries (allocSize entries less than in last array) is allocated and all entries are copied from the old array to the new one.

 void RemoveAtCurrent (): The element pointed to by current is freed, ie., its key is deleted and all elements after the current one are shifted one place to the left. Store the data pointer before calling this function, or it will be lost. If current is no valid index, an assert fails. If more than allocSize+1 elements are unused, a smaller array is allocated by FreeMemory().

 INT32 Size() const: Returns the current size of the array (ie., the number of array elements).

 void UpdateArray(): Allocates a new array (the new size is taken from the private member size), and copies the occupied part of the old array to the new one. The old array is deleted, and the internal array pointer is set to the new array. Note that the pointer is set to the new array *after* the old array has been deleted, so concurrent access should not be allowed. The new array must be big enough to hold the occupied part of the old array, otherwise an assert will fail.


last modified: Fri Feb 5 18:56:26 1999