OverviewA list is a data structure that stores a variable number of items of similar types. MacApp provides classes for creating and manipulating lists, allowing your application to use lists without having to implement the low-level details. MacApp's list classes and methods are shown in Figure 25-1.
Figure 25-1 List classes and methods
MacApp's list classes use a dynamic array model. Each item in a list has a unique index--you can access the items in a list by index or by standard list-traversal methods. The
TSortedListclass and its descendants can store only references to items that descend from the
TObjectclass. Other MacApp-defined list classes, such as
THandleList, store generic references that can be used to deal with a variety of developer-defined data types.
Iteration is a general-purpose mechanism for traversing the items in a list. MacApp provides the
CIteratorclass and many specialized subclasses that operate on various types of lists. Iteration classes can traverse the items in a list without knowing the exact details of the data structures involved.
Figure 25-2 shows MacApp's iteration classes and methods.
Figure 25-2 Iteration classes and methods
Working With Lists of ObjectsMacApp's
TListclasses provide extensive capabilities for working with lists of objects that descend from
TSortedListclass includes methods and fields for processing an ordered list in which each element is a reference to an object. The
TListclass is a subclass of
TSortedListthat doesn't sort the objects.
TListis used widely by MacApp, and it can be a valuable tool in your application as well.
- This section describes the
TListclasses, which refer to objects. The
THandleListprovide virtually identical operations on handles.
Creating a ListMacApp provides the
NewListroutine to create and initialize a new
TListobject. The convenience routine
NewAllocatedListlets you create a new
TListobject and at the same time specify the number of elements for which storage should be allocated. Each of these routines calls
Failureif the list cannot be allocated.
Adding an Object to a ListYou add an object to a
TListwith a method that inserts a reference to the specified object into the list. The insertion method calls
Failureif an attempt is made to insert the reference at an index that is out of range.
The following insertion methods are available:
MacApp's iteration mechanism, described beginning on page 576, allows you to iterate over a list correctly, even as items are added to the list.
AtPutmethod replaces the object reference at the specified position with a reference to the new object, without freeing the old object.
- For the
Insertmethod inserts the object reference at the end of the list. For the
TSortedListclass, the parent class of
Insertadds the object reference in sorted order, based on the list's
InsertBeforemethod inserts the object reference before the reference at the specified index. If the index is equal to 1, the object reference is inserted at the head of the list.
InsertFirstmethod inserts the object reference at the front of the list and makes its index equal to 1.
InsertLastmethod inserts the object reference at the end of the list.
Deleting an Object From a ListMacApp's list classes provide a number of methods for deleting an item from a list--not all are available in every list class:
MacApp's iteration mechanism, described beginning on page 576, allows list iteration to proceed correctly, even as items are deleted from the list.
AtDeletemethod deletes the object reference at the specified index position.
Deletemethod deletes the first reference to the object in the list. The object itself is not freed.
Deletedoes nothing if the object is not found in the list.
DeleteAllmethod deletes every element from the list, but does not free any of the objects.
- These methods delete a reference from the list--they do not free any memory occupied by the referred-to item itself. See the section "Freeing a List" (page 576) for more information on freeing a list and the items it references.
Finding an Object in a ListThe
TListclass provides a number of methods for finding an object in a list. You can find an object that is the same as another object, or find a specific object by its position in the list.
The following methods are available:
Atmethod returns the object reference at the specified index.
Firstmethod returns the first object reference in the list. It returns
NULLif the list is empty.
Lastmethod returns the last object reference in the list. It returns
NULLif the list is empty.
GetEqualItemNomethod uses the object's
CompareObjectmethod to test for equality. This allows object equality to be determined by the object. An "equal" object may be found, even though the object being looked for is not, in fact, identical to the one found.
GetIdentityItemNomethod uses the
operator==function to compare items in the list to the item being searched for. The
operator==function is overloaded in
TObject, where it calls the
IsEqualmethod, which does nothing in
TObject. As a result,
GetIdentityItemNodoes nothing unless you override the
- To use the
GetIdentityItemNomethod, you must override the
IsEqualmethod with a version that can identify equality between the items stored in your list.
Freeing a ListThe
TDynamicArray::Freemethod frees the memory occupied by a list itself but does not free the items referred to. You can call the
FreeAllmethod to free each of the objects in a list of object references (
TSortedListand descendants) or each of the handles in a list of handle references (
TSortedHandleListand descendants). The list itself becomes empty but is not freed. You can call the
FreeListmethod to free each object in the list and then free the list as well.
IterationIteration allows you to traverse an array or list and perform some operation on each element. MacApp provides the
CIteratorclass and several specialized subclasses for this purpose. For example, the
CArrayIteratorclass iterates through an array of indexed items, the
cMenuIteratorclass iterates through the menu handles in a menu list, the
CBehaviorIteratorclass iterates through the behaviors that are associated with an event handler, and the
CSubViewIteratorclass iterates through a list of subviews belonging to a view.
Each iterator class is defined for use with a specific kind of list (for example,
TSortedList) and can iterate correctly over the items in the list. This allows iteration to continue correctly, even as items are added to or deleted from a list. Iteration can be performed with both sorted and nonsorted lists and can be performed in either the forward or backward direction.
The most important base class for iterators is the
CArrayIteratorclass. Like several of its subclasses, the
CArrayIteratorclass provides multiple constructor methods for your convenience. The constructor methods of
CArrayIteratorcall the initialization method,
IArrayIterator, which sets the iterator's fields, including the following:
fCurrentIndexfield specifies the current index during iteration.
fDynamicArrayfield refers to the dynamic array for the list that is iterated through.
fHighBoundfield is the upper bound for forward iteration through the list.
fIterateForwardfield is set to
TRUEfor forward iteration through the list and to
FALSEfor backward iteration.
fLowBoundfield is the lower bound for backward iteration through the list.
CArrayIteratorclass also provides methods for inserting and deleting items in the list during iteration so that the iteration process is not invalidated by the change to the list. It includes the following methods:
DeleteElementAtmethod adjusts the iteration index to account for the deleted element.
InsertElementBeforemethod adjusts the iteration index to account for the added element.