TStringList

TStringList is a utility class type. It is extremely useful for many kinds of list processing. Items in a string list may be inserted, moved and sorted.

The list can be built string by string, or loaded from a comma separated big string, or even from a text file.

TStringList is derived from TStrings. Whilst you can use TStrings, it is not recommended since it is incomplete - some of the methods are abstract. TStringList implements these abstract methods (Clear, Delete and Insert). We'll cover the main properties and methods of TStringList, including those derived from TStrings

Property or Method Description
Count Returns the number of strings in the list.
Strings Get or update the string at a given index in the list (the first list item has index 0).
Text Set or get the list via a big string. This string will have each string terminated with a carriage return and line feed combination (CRLF). Useful for loading from a visual object that can hold multiple lines of text.
CommaText Get or set the list via a big string. This string will have the list strings separated by commas. This is useful for loading from a text spreadsheet export. When getting, if a string contains embedded spaces, it will be enclosed in double quote marks.
DelimitedText Get or set the list via a big string. This string will have the list strings separated by the Delimiter value (default is a comma). Strings containing embedded blanks must be enclosed in the QuoteChar (default is ").
QuoteChar Used to enclose strings that have embedded blanks when using DelimitedText.
Delimiter Used to separate strings when using DelimitedText.
Sorted When true all strings added will into a sorted sequence. When false, they are added at the end. See also the Sort method.
Add Will add the given string to the list, returning its allocated index position (starting with 0).
Append As Add but does not return the index value.
Insert Inserts a string at the given index position. Position 0 will force an insert at the start.
Delete Deletes the string at the given index.
Clear Deletes all strings from the list.
Move Moves a string from one index position to another, shifting other strings around as appropriate.
Exchange Swaps two strings in the list, as identified by their index positions.
IndexOf Gets the index position of the first string matching the given string. Or -1 if not found.
Sort When Sorted is false, this will force a sort of the list.
AddStrings Adds the strings from another list into this one.
LoadFromFile Very useful indeed - loads a string list from a text file. Each text line (as terminated by CRLF - see DelimitedText) becomes a list string.
SaveToFile Will save a string list to a text file.

Example code : A simple example

var
  animals : TStringList;            // Define our string list variable
  i       : Integer;
begin
  // Define a string list object, and point our variable at it
  animals := TStringList.Create;

  // Now add some names to our list
  animals.Add('Cat');
  animals.Add('Mouse');
  animals.Add('Giraffe');

  // Now display these animals
  for i := 0 to animals.Count-1 do
    ShowMessage(animals[i]);  // animals[i] equates to animals.Strings[i]
end;

Output

Cat
   Mouse
   Giraffe

Example code : Using name-value strings

var
  names  : TStringList;            // Define our string list variable
  ageStr : String;
  i      : Integer;
begin
  // Define a string list object, and point our variable at it
  names := TStringList.Create;

  // Now add some names to our list
  names.CommaText := 'Neil=45, Brian=63, Jim=22';

  // And now find Brian's age
  ageStr := names.Values['Brian'];

  // Display this value
  ShowMessage('Brians age = '+ageStr);

  // Now display all name and age pair values
  for i := 0 to names.Count-1 do
  begin
    ShowMessage(names.Names[i]+' is '+names.ValueFromIndex[i]);
  end;
end;

Output

Brians age is 63
   Neil is 45
   Brian is 63
   Jim is 22

Example code : Using DelimitedText, Delimiter and QuoteChar

var
  cars : TStringList;            // Define our string list variable
  i    : Integer;
begin
  // Define a string list object, and point our variable at it
  cars := TStringList.Create;

  // Now add some cars to our list - using the DelimitedText property
  // with overriden control variables
  cars.Delimiter := ' ';        // Each list item will be blank separated
  cars.QuoteChar := '|';        // And each item will be quoted with |'s
  cars.DelimitedText := '|Honda Jazz| |Ford Mondeo| |Jaguar "E-type"|';

  // Now display these cars
  for i := 0 to cars.Count-1 do
    ShowMessage(cars[i]);       // cars[i] equates to cars.Strings[i]
end;

Output

Honda Jazz
   Ford Mondeo
   Jaguar "E-type"
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License