TList Overview

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.

Table 5-1 Overview of the TList class

Add Function

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.

Figure 5-1 Adding an item (4) to the end of a TList object, i.e., List.Add(Item4)

Clear Procedure

procedure Clear

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.

Delete Procedure

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.

Figure 5-2 Deleting an item (2) from a TList object, i.e., List.Delete(2)

Exchange Procedure

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.

Figure 5-3 Exchanging items 3 and 5 in a TList object, i.e., List.Exchange(2, 4)

Expand Function

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.

First Function

function First: Pointer

The First method returns the first item in the list, that is, Items[0]. It raises an EListError exception if the list is empty.

IndexOf Function

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.

Insert Procedure

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.

Figure 5-4 Inserting an item (4) at index 2 of a TList object, i.e., List.Insert(2, Item4)

Last Function

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.

Move Procedure

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.

Figure 5-5 Moving item 2 to index 4 in a TList object, i.e., List.Move(2, 4)

Pack Procedure

procedure Pack

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

Remove Function

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.

Capacity Property

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.

Count Property

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).

Items Property

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.

List Property

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.

• Tempest Software
  • Secrets of Delphi 2
    • Chapter 5 Dynamic Arrays: The TList Class
      • Dynamic Arrays with TList
      • TList Overview
      • Using the TList Class
      • Limitations of the TList Class
      • A Better TList Class
      • Summary

Copyright © 1996 Waite Group Press