DelphiBasics
TStringList
Type
Holds a variable length list of strings Classes unit
type TStringList;
Description
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
 
Count property
Returns the number of strings in the list
 
Capacity property
Set or get the current capacity of the string list. You would manage this capacity for performance reasons.
 
Strings property
Get or update the string at a given index in the list (the first list item has index 0).
 
Note that the Strings property is the default property. This means that you can use it without specifying its name:
 
  myName := names.Strings[4];
 
is equivalent to :
 
  myName := names[4];
 
Text property
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 property
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 property
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 property
Used to enclose strings that have embedded blanks when using DelimitedText.
 
Delimiter property
Used to separate strings when using DelimitedText.
 
Names property
Strings in a string list can be treated as name/value pairs, as in the second code example. Each string must have no embedded blanks, and contain an embedded = sign (or whatever the current NameValueSeparator variable is).
 
This is a very useful concept. See the Value and ValueFromIndex properties, and the IndexOfName method.
 
Values property
Returns the value for a given name when using name/value pair strings (see above).
 
ValueFromIndex property
Returns the value by string index (starting at 0) when using name/value pairs.
 
CaseSensitive property
When true, Delphi treats strings as mixed case when perforing certain operations, such as Sort.
 
Duplicates property
This property may have one of the following TDuplicates enumeration values:
 
dupIgnore Ignore (discard) duplicates
dupAccept Allow duplicates
dupError Throw exception if duplicates

 
You should of course set this property to the desired value before adding strings.
 
Sorted property
When true all strings added will into a sorted sequence. When false, they are added at the end. See also the Sort method.
 
Objects property
Returns the object associated with the string at the given index, if present.
 
Add method
Will add the given string to the list, returning its allocated index position (starting with 0).
 
Append method
As Add but does not return the index value.
 
Insert method
Inserts a string at the given index position. Position 0 will force an insert at the start.
 
Delete method
Deletes the string at the given index.
 
Clear method
Deletes all strings from the list.
 
Move method
Moves a string from one index position to another, shifting other strings around as appropriate.
 
Exchange method
Swaps two strings in the list, as identified by their index positions.
 
IndexOf method
Gets the index position of the first string matching the given string. Or -1 if not found.
 
IndexOfName method
Gets the index position of the first name/value pair string where the name matches the given string. Or -1 if not found.
 
Find method
Same as IndexOf but used with sorted string lists.
 
Sort method
When Sorted is false, this will force a sort of the list.
 
AddStrings method
Adds the strings from another list into this one.
 
Assign method
Replaces the current list with the contents of another list.
 
LoadFromFile method
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 method
Will save a string list to a text file.
Related commands
AnsiStringA data type that holds a string of AnsiChars
ArrayA data type holding indexable collections of data
StringA data type that holds a string of characters
TListGeneral purpose container of a list of objects
 Download this web site as a Windows program.




 
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]

  // Free up the list object
  animals.Free;
end;
Show full unit code
  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;

  // Free up the list object
  names.Free;
end;
Show full unit code
  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]

  // Free up the list object
  cars.Free;
end;
Show full unit code
  Honda Jazz
  Ford Mondeo
  Jaguar "E-type"
 
Delphi Programming © Neil Moffatt . All rights reserved.  |  Home Page