| 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 |
| AnsiString |
|
A data type that holds a string of AnsiChars |
| Array |
|
A data type holding indexable collections of data |
| String |
|
A data type that holds a string of characters |
| TList |
|
General purpose container of a list of objects |
|
|
|
| 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"
|
|