type TList;
Description
The TList class is a very useful general purpose list container.
It differs from arrays in that it provides richer functionality.
In particular, TList objects can be sorted. This sorting can be by any criteria use choose. For example, the list may contain a set of objects that have string and number fields. You could sort the list by string, number, both, ascending or descending as you wish. And resort by other criteria later.
The sample code shows such a sort.
The key properties and methods are listed below.
Capacity property
Used to set the size (number object pointers) of the list. By presetting to a sensible value, multiple memory reallocations can be avoided.
Count property
The number of items (pointers) in the list. Can be read or written to. If the size is reduced as a result of a Count value change, items at the end of the list are removed.
Items property
Allows access to the items in the list. For example, myList.Items[2]; returns the 3rd item in the list. This is the default property, so the above can be simplified to myList[2];.
List property
Returns the items in an array.
Add method
Add an item to the list. Gets added at the end.
Assign method
Replaces the list with the contents of another list.
Clear method
Removes all list items, setting the Count to 0.
Delete method
Removes an item from the list by its list position.
Remove method
Removes an item from the list by its object pointer.
Exchange method
Swaps the positions of two items
Move method
Moves an item to a new list position
Insert method
Inserts a new item into the list at a given index position.
First method
Gets the first item in the list
Last method
Gets the last item in the list
Sort method
Sorts the list by your specified criteria. The list sorting is carried out internally in TList, but each item pair compare invokes the function you name to this method.
IndexOf method
Gives the list position of a specified object in the list.
Notes
You can add Nil pointers to the list. Delphi will add Nil pointers when you set the Count property higher than the current number of items in the list.
Related commands
TStringList Holds a variable length list of strings
Array A data type holding indexable collections of data
Example code : Creating, furnishing, sorting, and tinkering with a list
unit Unit1;
interface
uses
Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
Dialogs, StdCtrls;
type
// The customer class definition
TCustomer = class
private
// The data fields of this new class
CustomerName : String;
CustomerNumber : Integer;
public
// Properties to read these data values
property Name : String
read CustomerName;
property Number : Integer
read CustomerNumber;
// Constructor
constructor Create(const CustomerName : String;
const CustomerNumber : Integer);
end;
// The form class definition
TForm1 = class(TForm)
procedure FormCreate(Sender: TObject);
private
// The TList object we use in this code
myList : TList;
// Method to show the contents of our list object
procedure ShowListContents;
public
end;
var
Form1: TForm1;
implementation
{$R *.dfm}
// Customer constructor
// --------------------------------------------------------------------------
constructor TCustomer.Create(const CustomerName : String;
const CustomerNumber : Integer);
begin
// Save the passed parameters
self.CustomerName := CustomerName;
self.CustomerNumber := CustomerNumber;
end;
// TList sort routine : compare customers by name
// --------------------------------------------------------------------------
// The returned integer has the following value :
//
// > 0 : (positive) Item1 is less than Item2
// 0 : Item1 is equal to Item2
// < 0 : (negative) Item1 is greater than Item2
function compareByName(Item1 : Pointer; Item2 : Pointer) : Integer;
var
customer1, customer2 : TCustomer;
begin
// We start by viewing the object pointers as TCustomer objects
customer1 := TCustomer(Item1);
customer2 := TCustomer(Item2);
// Now compare by string
if customer1.Name > customer2.Name
then Result := 1
else if customer1.Name = customer2.Name
then Result := 0
else Result := -1;
end;
// A routine to display the contents of our list
// --------------------------------------------------------------------------
procedure TForm1.ShowListContents;
var
i : Integer;
begin
// And redisplay the list
for i := 0 to myList.Count-1 do
begin
ShowMessage(TCustomer(myList[i]).Name+' is customer number '+
IntToStr(TCustomer(myList[i]).Number));
end;
end;
// Form constructor
// --------------------------------------------------------------------------
procedure TForm1.FormCreate(Sender: TObject);
var
customer : TCustomer;
begin
// Create the TList object to hold a set of customer objects
myList := TList.Create;
// Create some customer objects and add to our object list
customer := TCustomer.Create('Neil Moffatt', 123);
myList.Add(customer);
customer := TCustomer.Create('Bill Gates', 64);
myList.Add(customer);
// We can add the object without assigning to an intermediate variable
myList.Add(TCustomer.Create('Henry Cooper', 999));
myList.Add(TCustomer.Create('Alan Sugar', 2));
// Now display the list
ShowListContents;
// We will now sort the list into name sequence and redisplay
myList.Sort(compareByName);
// And redisplay the list
ShowListContents;
// Now do some object inserts and deletes
// Note that indices start at 0
myList.Insert(2, TCustomer.Create('Added as item 3', 33));
myList.Delete(4);
// And redisplay the list
ShowListContents;
end;
end.
Show full unit code
Neil Moffatt is customer number 123
Bill Gates is customer number 64
Henry Cooper is customer number 999
Alan Sugar is customer number 2
Alan Sugar is customer number 2
Bill Gates is customer number 64
Henry Cooper is customer number 999
Neil Moffatt is customer number 123
Alan Sugar is customer number 2
Bill Gates is customer number 64
Added as item 3 is customer number 33
Henry Cooper is customer number 999