DelphiBasics
TList
Type
General purpose container of a list of objects Classes unit
  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 you 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
 Download this web site as a Windows program.


 
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;

  // Free up the list
  myList.free;
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
  
 
 
Delphi Programming Neil Moffatt 2002 - 2014. All rights reserved.  |  Contact the author  |  Home Page