You can find documentation for all the methods and properties of the TList class in Delphi's online help files. The help files are not always accurate, so Table 5-1 presents an overview of the TList class. Following the table are more complete descriptions of the methods and properties.
|Method or Property||Description|
|function Add(Item: Pointer): Integer||Adds Item to the end of the list.|
|procedure Clear||Deletes all items from the list.|
|procedure Delete(Index: Integer)||Deletes the item at the given Index.|
|procedure Exchange(Index1, Index2)||Swaps the items at Index1 and Index2.|
|function Expand: TList||Increases the size of the list.|
|function First: Pointer||Returns Items.|
|function IndexOf(Item: Pointer): Integer||Returns the index of the first item to match Item.|
|procedure Insert(Index: Integer; Item: Pointer)||Inserts the item at position Index.|
|function Last: Pointer||Returns Items[Count-1].|
|procedure Move(CurIndex, NewIndex: Integer)||Moves the item at CurIndex to NewIndex.|
|procedure Pack||Deletes all nil items.|
|function Remove(Item: Pointer): Integer||Deletes the first item that matches Item.|
|property Capacity: Integer||Sets or gets the number of available slots where list items can be stored.|
|property Count: Integer||Sets or gets the number of items in the list.|
|property Items[Index: Integer]: Pointer; default||Sets or gets the item at position Index.|
|property List: PPointerList||Returns a pointer to the array where TList stores its items.|
function Add(Item: Pointer): Integer
The Add method appends Item to the end of the list, expanding the capacity of the list if needed. It returns the index of the newly added item. If the list is full and cannot grow any more, then an EListError exception is raised. Figure 5-1 demonstrates how an item is added to a list.
The Clear method deletes all items from the list, and sets the Capacity to zero. Calling Clear is faster than calling Delete for every item. Also, calling Delete does not change the Capacity, just the Count.
procedure Delete(Index: Integer)
The Delete method deletes the item at the given Index, reducing Count by one and shifting over every item at higher indexes. It raises an EListError exception if the Index is invalid. Figure 5-2 demonstrates deleting an item from a list.
procedure Exchange(Index1, Index2: Integer)
The Exchange method swaps the items at Index1 and Index2. It raises an EListError exception if either index is invalid. The list size and capacity are unchanged. Figure 5-3 demonstrates the exchange of list items.
function Expand: TList
The Expand method increases the size of the list to make sure there is room for at least one more item. It returns Self. Delphi always calls Expand before inserting or appending an item to the list.
function First: Pointer
The First method returns the first item in the list, that is, Items. It raises an EListError exception if the list is empty.
function IndexOf(Item: Pointer): Integer
The IndexOf method returns the index of the first item to match Item, or -1 if the Item cannot be found. The list is searched linearly from index 0 to index Count-1, looking for a pointer value that is equal to Item. If you want to dereference the pointer and compare the contents of the memory being pointed to, you must write your own loop.
procedure Insert(Index: Integer; Item: Pointer)
The Insert method inserts Item at position Index, shifting the rest of the list right by one position to make room. The capacity of the list is expanded, if needed. If Index = Count, then Item is appended to the end of the list. If Index > Count, then an EListError exception is raised. Figure 5-4 demonstrates how an item is inserted into a list.
function Last: Pointer
The Last method returns the last item in the list, namely, Items[Count-1]. It raises an EListError exception if the list is empty.
procedure Move(CurIndex, NewIndex: Integer)
The Move method moves the item at CurIndex to NewIndex, shifting the indexes of other items as needed. Figure 5-5 demonstrates how items are moved in a list.
The Pack procedure deletes all nil items. If there are many nil items, Pack is slow and inefficient because it deletes the nil items one at a time. Figure 5-6 demonstrates how a list is packed. When you delete items from the list, they are removed from the list, without leaving nil values behind. So, unless you explicitly insert nil items and then later want to delete them, there is little purpose in calling Pack.
Figure 5-6 Packing nil items in a TList object, i.e., List.Pack
function Remove(Item: Pointer): Integer
The Remove method deletes the first item that matches Item and returns the index from which it was deleted. It returns -1 if Item is not found.
property Capacity: Integer
The Capacity property is a read-write property that sets or gets the maximum number of items that can be added to the list. If you set Capacity < Count or > MaxListSize, then an EListError exception is raised. In Delphi 2.0, MaxListSize is 134,217,727 (MaxInt div 16); in Delphi 1.0, MaxListSize is 16380. Changing the Capacity does not affect the Count.
property Count: Integer
The Count property is a read-write property that sets or gets the number of items in the list. If you increase the Count, the extra items are initialized to nil. If you set the Count > Capacity, the list grows to accommodate the new items. If you set Count > MaxListSize, an EListError exception is raised. You can also decrease Count, which is like deleting items from the end of the list (but is more efficient).
property Items[Index: Integer]: Pointer; default
The Items property is a read-write property that gets or sets the item at position Index. It raises an EListError exception if Index is < 0 or Count.
property List: PPointerList
The List property is read-only and returns a pointer to the actual array where TList stores its items. The PPointerList type is an array of Pointer.
Copyright © 1996 Waite Group Press