|
TStringList maintains a list of strings. Use a string list object to store and manipulate a list of strings.
In some examples we assume a string list has been created and is named "list".
TStringList list = TStringList.Create;
Usually you create a list inside a try ... finally block like this:
TStringList list = TStringList.Create;
try
list.Add("Line 1");
...
finally
list.Free;
end;
Properties
property string CommaText;
Use CommaText to get or set all the strings in the list using a single comma-delimited string.
Ex.
list.CommaText = "String1, String 2, String 3";
"list" will contain the 3 strings:
--------
String1
String2
String3
--------
property int Count;
Get the number of strings in the list.
Ex. int nr = list.Count;
property TEncoding DefaultEncoding;
Default encoding is used when no encoding is specified in a call to LoadFromStream or LoadFromFile, or the encoding cannot be detected.
TEncoding = (encAnsi, encUTF8, encUnicode)
Ex. list.DefaultEncoding = encUTF8;
property TDuplicates Duplicates;
Specifies whether duplicate strings can be added to sorted lists.
TDuplicates =
dupIgnore // Ignore duplicates. Do not add the string if a duplicate is found
dupError // Raise an exception when a duplicate string is added
dupAccept // Accept duplicates and add any new string
Ex.
list.Sorted = true;
list.Duplicates = dupIgnore;
property string Names[int Index];
Get or set the name part of a string given as a name value pair. Names and values are separated by "=". E.g. "Name=Value".
Ex.
list.Add("Name 1=Value 1");
list.Add("Name 2=Value 2");
string name = list.Names[0]; // name now contain the string "Name 1"
property bool Sorted;
Indicate if the list should be automatically sorted. All new strings added to the list are inserted in the correct position.
property string Strings[int Index];
Get or set a string in the list. The list start at zero and the last string is at index "list.Count - 1".
You don't have to use the "Strings" property to access strings. You can simply use "list[Index]".
Ex.
list.Add("Line 1");
list.Add("Line 2");
string s1 = list.Strings[0];
string s2 = list[1];
property string Text;
Use "Text" to get or set all the strings in the list. Each line is separated by a line feed.
Ex.
list.Text = "Line 1\r\nLine 2";
property string Values[string s];
Get or set the value part of a string given as a name value pair. Names and values are separated by "=". E.g. "Name=Value".
Ex.
list.Add("Name 1=Value 1");
list.Add("Name 2=Value 2");
string value = list.Values["Name 1"]; // value now contain the string "Value 1"
Methods
function int Add(String s);
Adds a new string to the list.
Ex.
list.Add("Some text...");
string s = "Hello!";
list.Add(s);
procedure Clear;
Removes all strings from the list.
constructor Create;
Create the list object.
Ex.
TStringList list = TStringList.Create;
procedure Delete(int Index);
Removes the string specified by the Index parameter.
function bool Find(string s, int &index);
Locates the index for a string in a sorted list and indicates whether a string with that value already exists in the list.
Ex.
int inx;
list.Sort;
if (list.Find("Line 1", inx) == true) {
ShowMessage("Line 1 was found in the list at index: " + IntToStr(inx));
}
procedure Free;
Destroys an object and frees its associated memory, if necessary.
function int IndexOf(string s);
Returns the position of a string in the list. IndexOf returns the 0-based index of the string.
The list does not have to be sorted, like the "Find" method.
function int IndexOfName(string Name);
Returns the position of the first name-value pair with the specified name.
Name-value pairs are separated by "=". E.g. list.Add("Name 1=Value 1");
Ex.
list.Add("Name 1=Value 1");
list.Add("Name 2=Value 2");
int n = list.IndexOf("Name 2"); // n = 1. The list is zero based and starts at 0.
procedure Insert(int Index, string S);
Inserts a string to the list at the position specified by Index.
Ex.
list.Add("Line 2");
list.Add("Line 3");
list.Insert(0, "Line 1");
procedure LoadFromFile(string FileName);
Fills the list with the lines of text in a specified file. Use this to load a text file into a string list.
Ex.
list.LoadFromFile("C:\MyFolder\MyText.txt");
procedure LoadFromFileEx(string FileName, TEncoding encoding);
Load a text file into the string list using the given text encoding.
Valid encodings are encAnsi, encUTF8, encUnicode.
Ex.
list.LoadFromFileEx("C:\MyFolder\MyText.txt", encUTF8);
procedure LoadFromStream(TStream Stream);
Load the text from a given stream object.
procedure LoadFromStreamEx(TStream Stream, TEncoding encoding);
Load the text from a given stream object and use the given encoding.
procedure Move(int CurIndex, int NewIndex);
Changes the position of a string in the list. Use Move to move the string at position CurIndex so that it occupies the position NewIndex. The positions are specified as 0-based indexes.
Ex.
list.Move(0, list.Count-1); // Move the first item to the end
procedure SaveToFile(string FileName);
Save the strings in the list to the specified file.
Ex.
list.SaveToFile("C:\MyFolder\MyText.txt");
procedure SaveToFileEx(string FileName, TEncoding encoding);
Save the strings in the list to the specified file, using the given encoding.
Ex.
To save the text in an UTF8 encoded text file use:
list.SaveToFileEx("C:\MyFolder\MyText.txt", encUTF8);
procedure SaveToStream(TStream Stream);
Saves the strings in the list to the specified stream.
procedure SaveToStreamEx(TStream Stream, TEncoding encoding);
Saves the strings in the list to the specified file stream using the given encoding.
procedure Sort;
Sorts the strings in the list in ascending order.
|
