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.