TStringList

TStringList maintains a list of strings.

Use a string list object to store and manipulate a list of strings.

TStringList implements the abstract properties and methods introduced by TStrings, and introduces new properties, events, and methods to:

• Sort the strings in the list
• Prohibit duplicate strings in sorted lists
• Respond to changes in the contents of the list
• Control whether strings are located, sorted, and identified as duplicates in a case-sensitive or case-insensitive manner

Properties:

Duplicates

property Duplicates: Boolean;

Description

(Read/Write)

Specifies whether duplicate strings can be added to sorted lists.

Set Duplicates to specify what should happen when an attempt is made to add a duplicate string to a sorted list.  The CaseSensitive property controls whether two strings are considered duplicates if they are identical except for differences in case.

The value of Duplicates should be one of the following:

• dupIgnore Ignore attempts to add duplicate strings to the list.
• dupError Raise an EStringListError exception when an attempt is made to add duplicate strings to the sorted list.
• dupAccept Permit duplicate strings in the sorted list.

Set Duplicates before adding any strings to the list.  Setting Duplicates to dupIgnore or dupError does nothing about duplicate strings that are already in the list.

Note: Duplicates does nothing if the list is not sorted.

---

Sorted

property Sorted: Boolean;

Description

(Read/Write)

Specifies whether the strings in the list should be automatically sorted.

Set Sorted to True to cause the strings in the list to be automatically sorted in ascending order. Set Sorted to False to allow strings to remain where they are inserted.  When Sorted is False, the strings in the list can be put in ascending order at any time by calling the Sort method.

When Sorted is True, do not use Insert to add strings to the list. Instead, use Add, which will insert the new strings in the appropriate position.  When Sorted is False, use Insert to add strings to an arbitrary position in the list, or Add to add strings to the end of the list.

Note: The CaseSensitive property controls whether the strings in the list are sorted based on a case-sensitive or case-insensitive comparison. The sort order takes into account the locale of the system on which the application is running.

---

Methods

Find

function Find(S: String; var Index: Integer): Boolean;

Description

Locates the index for a string in a sorted list and indicates whether a string with that value already exists in the list.

Use Find to obtain the index in a sorted list where the string S should be added.  If the string S, or a string that differs from S only in case when CaseSensitive is False, already exists in the list, Find returns True.  If the list does not contain a string that matches S, Find returns False.  The index where S should go is returned in the Index parameter.  The value of Index is zero-based, where the first string has the index 0, the second string has the index 1, and so on.

Note: Only use Find with sorted lists. For unsorted lists, use the IndexOf method instead.

---

Sort

procedure Sort;

Description

Sorts the strings in the list in ascending order.

Call Sort to sort the strings in a list that has the Sorted property set to False.  String lists with the Sorted property set to True are automatically sorted.

Note: Sort uses AnsiCompareStr to sort the strings when CaseSensitive is True and AnsiCompareText when CaseSensitive is False. To provide your own comparison operator instead, use the CustomSort method.

---