String-Based Collections

Introduction

A list is a series of items of the same category and considered as an entity. By default, a list is made of a single type of items easily identified, but an advanced list is made of objects that are of the same type although each object can be made of sub-objects. The first concern of a list is the composition of its members.

The members of a list could be simple text fields. A list can be structured as a tree made of words or groups of words. Another list could be made of graphics or pictures only. A list can also combine graphics and text. A list does not have to be made of items uniformly aligned.

A list does not necessarily display its items all at once. For example, the items of a list view are usually configured to change their display mode. Such is the case for the right pane of Windows Explorer. Another category of list of this kind is implemented for a multiple-choice question exam or text where only one question as a member of the list of questions.

There are various reasons for using lists. Lists provide a uniform way of displaying a group of similar items to the user. Depending on how it is configured, a certain list could be used to display a simple list of items to the user; this could serve to provide static information to the user. A popular type of list is available on database applications. These lists allow the user to select items from one list to create a new one.

When creating a list, you will decide how you would like users to interact with that part of your application, how they can use the list, what they can do and what they should be prevented from doing. The less interaction users have with a list, the least difficult it is to create. Depending on your intentions, you will need to provide just as much usefulness as possible to the user.

Many controls use lists as their main part. The primary and the most regularly used class to create a list is the TStrings class. The TStrings class is derived from TPersistent. The TStrings class is used to provide most of the list-based controls with the properties and methods they need for their functionality. Because of this, such controls are equipped to take advantage of all (or most) properties of this class.

Since the TStrings class does not lead to a specific Windows control, the control that needs it has to call it. Put it in reverse order, the TStrings class is declared in each class that needs to create a list based on a TStrings class. For this reason, it is free to be named anyway a class wants it. In some controls, it is named Lines. In other cases, it is called Items. Sometimes, the TStrings variable is called Cells.

To implement a list based on the TStrings class from any of these objects, call the TStrings property which in turn would give access to its properties and methods.

The operations performed using the TStrings class consist of creating a list of items, inserting new ones, deleting others, counting the items, changing their positions, or switching the items to another list.

The primary operation you as the programmer will perform on a new list is to fill it with some strings. At design time, this is usually easy to do because most list-based controls use the String List Editor. To open it, access the Object Inspector for the control, click Items and click its ellipsis button:

To create each item, type it on its line and press Enter. After creating the strings, click OK. To let you programmatically create a new item, the TStrings class provides a method named Add. Its syntax is:

virtual int __fastcall Add(System::UnicodeString Source);

This function takes one argument as an UnicodeString and adds it to the end of the target list. If the list is empty, the Add() method would initiate the list with the new item. The Source argument could be a locally defined string. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::ButtonClicked(TObject *Sender)
{
    Something->Lines->Add(L"C++Builder is fun!!!");
}
//---------------------------------------------------------------------------

You can also use a string held by another control. In this case you would call the control field that holds the string. For example, the following would add the content of the Edit1 edit box, or the Text property of the Edit control, to the list of a control:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    Something->Items->Add(Edit1->Text);
}
//---------------------------------------------------------------------------

You can also use the name of a string variable to add its value to a TStrings variable:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    UnicodeString Address = L"4812 Lockwood Drive #D12";
    Something->Items->Add(Address);
}
//---------------------------------------------------------------------------

The items of a TStrings list are usually text-based although they can also be of different kinds of objects. When the items are made of strings, sometimes you will need to convert them to a single text. To assist you with this operation, the TStrings class provides the GetText() method whose syntax is:

virtual wchar_t * __fastcall GetText(void);

When this method is called by a TStrings variable, it returns a null-terminated wide string that represents all of the items of the text.

To assign a C-based string to a TStrings list of strings, use the SetText() method. Its syntax is:

virtual void __fastcall SetText(wchar_t * Text);

This method takes one argument as a wide C-string and converts it to TStrings. You can use these two methods to transfer a list of strings from one object to another. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnGetTextClick(TObject *Sender)
{
    wchar_t *WholeList = Memorandum->Lines->GetText();
    Resume->Lines->SetText(WholeList);
}
//---------------------------------------------------------------------------

Even if the controls are of different kinds, you can use the same transaction. For example, the following event transfers the contents of a list-based control to a multiple line-based control:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnTransToLBXClick(TObject *Sender)
{
    char *wholeList = listControl->Items->GetText();
    someList->Lines->SetText(wholeList);
}
//---------------------------------------------------------------------------

Instead of using the GetText() and the SetText() methods separately, the TStrings class provides a property named Text that is a combination of those two methods:

__property System::UnicodeString Text = {read=GetTextStr,write=SetTextStr};

When you use the Text property to perform a transfer, the compiler scans the list of items. At the end of each item, the compiler adds a carriage return (this is equivalent to the Enter key) and adds the next string to the next line. This allows the compiler to create a UnicodeString made of all of the strings. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm2::btnTransferClick(TObject *Sender)
{
    Memorandum->Lines->Add(someListControl->Items->Text);
    Edit1->Text = someListControl->Items->Text;
    Label1->Caption = someListControl->Items->Text;
}
//---------------------------------------------------------------------------

At any time you can find out how many items compose a list of strings. This is information is held by the read-only Count property of the TStrings class:

__property int Count = {read=GetCount};

Not only does this property provide an integral count of the members of the list but also you can use it when scanning the list using a for loop. The fundamental way of using the Count property is to get the number of items of a list. In the following example, when the user clicks the Count button, the number of strings in the ControlGroup control displays in the Count edit box:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnCountClick(TObject *Sender)
{
    edtCount->Text = ControlGroup->Items->Count;
}
//---------------------------------------------------------------------------

The capacity of a list if the number of items that the list can possibly hold. To support this, the TStrings list provides a property named Capacity:

__property int Capacity = {read=GetCapacity,write=SetCapacity};

The main role of the TStrings::Capacity property is to deal with memory allocation especially when writing a component that uses a list of items.

The TStrings class allows you to save its list of strings. This can be done by calling the SaveToFile() method. It is provided in two versions whose syntaxes are:

virtual void __fastcall SaveToFile(System::UnicodeString FileName);
virtual void __fastcall SaveToFile(System::UnicodeString FileName,
 				   Sysutils::TEncoding * Encoding);

The first version takes a UnicodeString as argument. This argument specifies the default name of the file being saved by the user. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnSaveClick(TObject *Sender)
{
    SomeControl->Items->SaveToFile(L"Example.txt");
}
//---------------------------------------------------------------------------

The second version also takes as argument the name of the file, which is the first argument. The second argument specifies the type of encoding scheme that will be used. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
   Memorandom->Lines->Add(L"A Soho, dans Londres, il y avait un étrange "
			  L"club pour dépravés de luxe avides de sensations "
			  L"insolites. Mais lorsque Mac Bolan découvrit le "
			  L"Vieux Charles mort, brûlé vif et attaché à un "
			  L"chevalet, il comprit qu'il allait être obligé "
			  L"de le venger.");
    Memorandom->Lines->SaveToFile("Example.txt", TEncoding::UTF8);
}
//---------------------------------------------------------------------------

If you had saved a list of strings that are stored in a file, the TStrings class makes it possible to open it. This is done using a method named LoadFromFile() that is overloaded with two versions. Their syntaxes are:

virtual void __fastcall LoadFromFile(System::UnicodeString FileName);
virtual void __fastcall LoadFromFile(System::UnicodeString FileName,
                                     Sysutils::TEncoding * Encoding);

The first version takes a UnicodeString as argument. This is the name of the file. If you want to open a file whose path you know, you can provide this path as the argument. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    Memorandom->Lines->LoadFromFile("Example.txt");
}
//---------------------------------------------------------------------------

The second version of the method allows you to specify what encoding scheme the file is using or what encoding should be applied when analyzing the characters in the list. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    Memorandom->Lines->LoadFromFile("Example.txt", TEncoding::UTF8);
}
//---------------------------------------------------------------------------

In some cases, you can fill a list of a control from the strings of another list. This is mainly performed using the AddStrings() method whose syntax is:

virtual void __fastcall AddStrings(Classes::TStrings * Strings);

The argument provided to this string must be a valid list of strings. Therefore, you should make sure that the list originates from another list-based control or from another valid source. The Str argument could come from a known control. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnTransferFileClick(TObject *Sender)
{
    SomeControl->Items->AddStrings(memorandum->Lines);
}
//---------------------------------------------------------------------------

We saw that the TStrings::Add() method adds a new string to the end of the list and it returns the position of the newly added item. If you are not interested in that position, you can use the TStrings:: Append() method. Its syntax is:

void __fastcall Append(System::UnicodeString S);

For a text-based control, the only thing you want to know is whether the item was added to the list. This makes the TStrings:: Append() method useful. This method also takes one argument as the UnicodeString to be added. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    Something->Items->Append(L"The magazine is on the table");
}
//---------------------------------------------------------------------------

Since the TStrings class is a descendent of TPersistent, you can also use the Assign() method to assign a list of strings to an appropriate control. The syntax of the Assign() method is:

void __fastcall Assign(TPersistent* Source);

Here is an example of calling it:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnTransferFileClick(TObject *Sender)
{
    SomeControl->Items->Assign(Memorandum->Lines);
}
//---------------------------------------------------------------------------

When you call the Add() method of a TStrings variable to add a new item, if the operation was successful, the method returns the position of the new item. The position is zero-based. If Source was set as the first item of the list, its position would be 0. If it were added as the 2nd item of the list, it would assume position 1, etc. If you need to, you can find out the position the argument is occupying after being added. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::ButtonClicked(TObject *Sender)
{
    UnicodeString Address = L"4812 Lockwood Drive #D12";
    int Success = Something->Items->Add(Address);

    if( Success != -1)
        ShowMessage(Address + L" was added at position " +
                    UnicodeString(Success + 1));
}
//---------------------------------------------------------------------------

To let you know the index of an existing item, the TStrings class provides the IndexOf() method. Its syntax is:

virtual int __fastcall IndexOf(System::UnicodeString Source);

To use this function, provide the string you are looking for. This string is a UnicodeString object. If the string exists in the list, the IndexOf() method returns its position. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnFindClick(TObject *Sender)
{
    Network->Items->IndexOf("Printer");
}
//---------------------------------------------------------------------------

If the IndexOf() method finds that the Source string exists in the target list, it returns the position of Source. You can then use this information as you see fit. For example you can insert a new string on top of the found string. Here is example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnInsertClick(TObject *Sender)
{
    int found = Network->Items->IndexOf("Printer");

    if( Found )
        Network->Items->Insert(found, "Digital Camera");
}
//---------------------------------------------------------------------------

While the Add() and the Append() methods are used to add a string to the end of a list, the Insert() method allows you to add a string to a position of your choice in the target list. The syntax of the Insert() method is:

virtual void __fastcall Insert(int Index, System::UnicodeString Source);

This function needs two pieces of information. The Index argument specifies the intended position to insert the item. The positions are zero-based. If you want to add the new item on top of the list, set the Index to 0, for the second place, set the Index to 1, etc. The string to be added is the Source argument. Here is an example that inserts the "Easy Listening" string to the 3rd position on a list:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    SomeControl->Items->Insert(2, L"Easy Listening");
}
//---------------------------------------------------------------------------

The Index value applies whether the list is sorted or not. If you would like to add a new string to a sorted list and insert it to the right alphabetical sequence, use the Add() or the Append() methods.

Another type of operation you will perform in a list is to retrieve the text of a particular string in the group. This usually happens when you want to transfer an item to another control or display a message about the item. The Strings property allows you to get an item based on its position in the list:

__property System::UnicodeString Strings = {read=Get,write=Put};

This property is an array that represents the items of the list. To locate a string, use the square brackets to specify its position. Because the list is zero-based, the first item is 0 and would be represented by Strings[0], the second is 1 and would be called with Strings[1], etc.

For the following example, when the user clicks a control that holds a list, regardless of the item selected, a label on the form would retrieve the third item of the list, provided the list has at least 3 items:

//---------------------------------------------------------------------------
void __fastcall TForm1::ListControlClick(TObject *Sender)
{
    Label1->Caption = SomeControl->Items->Strings[2];
}
//---------------------------------------------------------------------------

One of the most effective ways to use the Strings property is to find out the item that the user would have selected in a list and act accordingly. In the following example, when the user selects a control from a group control, the caption of the button selected displays on a label:

//---------------------------------------------------------------------------
void __fastcall TForm1::controlGroupClick(TObject *Sender)
{
    // Find the position of the item selected
    int ItemPos = ControlGroup->ItemIndex;
    // Get the text of the item selected
    String strSelected = ControlGroup->Items->Strings[ItemPos];
    // Using a label, display a message associated with the item selected
    Label1->Caption = L"You selected " + strSelected;
}
//---------------------------------------------------------------------------

One of the most regular reasons for this operation is to make sure that a string is not duplicated and added to a list that already has the Source argument. In the following example, when the user types a string in an edit box and clicks somewhere else (that is, when the Edit control looses focus), the compiler checks to see if the string in the edit box already exists in the list. If the list of the control does not have the string in the edit box, then this string is added to the list:

//---------------------------------------------------------------------------
void __fastcall TForm1::edtLaptopExit(TObject *Sender)
{
    UnicodeString Laptop = edtLaptop->Text;
    int Exists = Network->Items->IndexOf(Laptop);

    if( Exists == -1 )
        Network->Items->Append(Laptop);
}
//---------------------------------------------------------------------------

Some operating system configuration files contain lines with the = symbol as part of a string. There is no strict rule on what those files are or what they do. The company or the person who creates such a file also decides what the file is used for and when. For example, a music program would use such a file to configure the keyboard keys as related to the associated software. A communication program could use another type of those files as a list or table of ports. Programmers have to deal with those files for various reasons. Some of those files have strings made of three parts: Left=Right. The value called Right has to be assigned to the value on the left. Sometimes the Left value is called a Key; sometimes it is called a Name. The value on the right of equal is also called a Value. Therefore, a string on this file would have the form Name=Value. Some of these files have the .INI extension but can perfectly have any extension the programmer wanted.

Depending on how the file is structured, programmers have to find a certain key or name in the list. The TStrings class is equipped with a function that helps with this operation. The method is the IndexOfName() and its syntax is:

virtual int __fastcall IndexOfName(System::UnicodeString Name);

This method takes a UnicodeString as argument. The compiler scans the list looking for a string that uses the formula Name=Value. If the left part of a string matches the Name argument, the IndexOfName() method returns the first position where such a string was found. The following form box is equipped with an edit box and a list. To add a new key to the list of keys, the user types the key in the edit box and clicks the Add Key button (the Edit control is named edtNewKey, the list control is named lstConfigure, the button is named btnAddKey, the bottom Edit control is named edtFound):

Here is an example of implementing the IndexOfName() method from the OnClick event of the Add Key button:

//---------------------------------------------------------------------------

#include <vcl.h>
#pragma hdrstop

#include "Unit1.h"
//---------------------------------------------------------------------------
#pragma package(smart_init)
#pragma resource "*.dfm"
TForm1 *Form1;
//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
	: TForm(Owner)
{
}
//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    lstConfigure->Lines->LoadFromFile(L"C:\\Exercise\\Example.ini");
}
//---------------------------------------------------------------------------
void __fastcall TForm1::btnAddKeyClick(TObject *Sender)
{
    UnicodeString NewKey = edtNewKey->Text;
    int LookFor = lstConfigure->Lines->IndexOfName(L"ALLOW_LOCKDOWN_MEDIA");

    if(LookFor == -1)
		lstConfigure->Lines->Append(NewKey);
    else
		edtFound->Text = LookFor;
}
//---------------------------------------------------------------------------

When the user clicks the Add Key button, the Name part, which is the string on the left of the = symbol of the edit box, is checked for each string in the list. If no name matches the Name part of the edit box, the new key is added to the list. If that Name part is already in the list, the bottom edit box displays the position of the first string that contains Name.

Probably the best way to do this, "Live", is to retrieve the Name part from the string that the user has typed in the top edit box. The following code would accomplish that:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnAddKeyClick(TObject *Sender)
{
    // Get the content of the edit box
    UnicodeString NewKey = edtNewKey->Text;
    // Find the position of the first occurrence in the edit box int
    int EqualPos = NewKey.Pos(L"=");
    // Create a string from the beginning to the first occurrence of =
    UnicodeString NamePart = NewKey.Delete(EqualPos, NewKey.Length());
    // Find out if the Name part of the key is already in the list
    int LookFor = lstConfigure->Lines->IndexOfName(NamePart);
    // if it is not, add the new key to the file
    if(LookFor == -1)
        lstConfigure->Lines->Append(edtNewKey->Text);
}
//---------------------------------------------------------------------------

Depending on how the list is structured, you can ask the compiler to retrieve the name part of a string provided its position. This operation is performed using the Names property:

__property System::UnicodeString Names = {read=GetName};

This property is an array of the strings of this type of file. When needed, you can ask the compiler to give you the name part of a certain line. For example, to retrieve the name part of the 5th line, you could write Names[4]. If the item at that position does not have = as part of the string, the compiler would consider that the line is not a valid IndexOfName string and would avoid it. In the following example, the 2nd line of lstConfigure is examined. If that line is a valid IndexOfName, its Name part displays in the Found At edit box:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnGetNameClick(TObject *Sender)
{
    edtFound->Text = lstConfigure->Lines->Names[1];
}
//---------------------------------------------------------------------------

By contrast, to retrieve the Value part of an IndexOfName string, use the Values property. This also is an array of the valid = strings of the list. It uses the following syntax:

__property System::UnicodeString Values = {read=GetValue,write=SetValue};

This time, you must (or should) provide the string you are looking for as if it were the position of the string. This string, which is a UnicodeString object, should be the Name part of a string you are looking for. The compiler would scan the list of strings looking for valid IndexOfName strings. If it finds a string that encloses an = symbol, then the compiler would check its Name part. If this Name matches the NamePart of the Values property, then it would return the Value. This is useful if you want to know whether a certain key has already been defined in the file.

When providing the NamePart as the string to look for, make sure you do not include = as part of the string

Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnGetValueClick(TObject *Sender)
{
    edtFound->Text = lstConfigure->Lines->Values[L"Directory"];
}
//---------------------------------------------------------------------------

If you have two lists and want to compare them, use the Equals() method whose syntax is:

bool __fastcall Equals(TStrings* Strings);

This function requires a TStrings list of strings. The conversion is performed on two fronts. First, both lists should have the same number of strings. If both lists have different number of items, the function returns false. If they have the same number of strings, then the compiler examines the strings one line at a time, for each list. If two strings of the same position are not the same, the function returns false. This means that even if both lists have the same strings, the comparison can still render negative. Here is an example of implementing this method:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnCompareListsClick(TObject *Sender)
{
    if( !firstList->Items->Equals(secondList->Items) )
        ShowMessage(L"Both lists are not the same\n"
                    L"You should synchronize them before exiting");
}
//---------------------------------------------------------------------------

Another usefulness of items of a list is to switch their positions as related to each other. The primary method used to swap items is the Move() method. Its syntax is:

virtual void __fastcall Move(int CurIndex, int NewIndex);

This function takes two strings. The first string is considered for its position. When executing, the function moves the first item from the CurrentPos position to the position specified by NewPos. The following event would move the 2nd item of a list-based control to the 5th position:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnMoveClick(TObject *Sender)
{
    SomeListControl->Items->Move(1, 4);
}
//---------------------------------------------------------------------------

After the move, the item at CurrentPos is moved to NewPos. If the item is moved just one position, all of the items whose positions are between CurrentPos and NewPos are affected. If the item moved up, the items that were above it would be moved down. The opposite occurs if the item has moved down.

While the Move() method is used to move an item from one position to another, the Exchange() method is used to switch two items. Its syntax is:

virtual void __fastcall Exchange(int Index1, int Index2);

The compiler takes the item at Index1, moves it to Index2, takes the item that was at Index2 and moves it to Index1. In the following example, the items at the 4th and the 1st positions are switched:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnExchangeClick(TObject *Sender)
{
    SomeControl->Items->Exchange(3, 0);
}
//---------------------------------------------------------------------------

As you can see, this transfer is not properly interpreted by the Edit control because this control does not have a multiple line capability.

Another technique used to most effectively transfer a list from a strictly list-based control is to use the CommaText property:

__property System::UnicodeString CommaText = {read=GetCommaText,write=SetCommaText};

When called to use this property, the compiler would scan the list of items. If an item is a one-word string, the compiler would write a comma "," on its right and start adding the next item. If the item is a string made of more than one word, to delimit it, the compiler would enclose it with double-quotes.

In the following example, when the user clicks the Transfer button, the list of items from the first control is transferred to two other controls using the CommaText property:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnTransferClick(TObject *Sender)
{
    Memorandum->Lines->Add(ListControl->Items->CommaText);
    Edit1->Text = ListControl->Items->CommaText;
}
//---------------------------------------------------------------------------

Besides adding, appending, or inserting, you can delete an item from a list. This is performed using the Delete() method whose syntax is:

virtual void __fastcall Delete(int Index);

To delete an item, the Delete() method needs to know its position. Once again, the list is zero-based: the 1st item is at position 0, the 2nd at 1, etc. If the Index argument points to an item that does not exist, for example either you set it to a value greater than the number of items or all items have been deleted, nothing would happen (no error would be thrown). In the following example, the 3rd item of a combo box is deleted:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnDeleteClick(TObject *Sender)
{
    Network->Items->Delete(2);
}
//---------------------------------------------------------------------------

To (effectively) use the Delete() method, you should supply the position of the item you want to delete. Sometimes such a position would be invalid. The best thing to do is to first inquire whether the item you want to delete exists in the list. For this and many other reasons, you can ask the compiler to check the existence of a certain item in a list.

You can also look for Source in a target list and delete it if it exists. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnDeleteClick(TObject *Sender)
{
    int found = Network->Items->IndexOf("Printer");

    if( found )
        Network->Items->Delete(found);
}
//---------------------------------------------------------------------------

If you decide to dismiss a whole list, use the Clear() method. Its syntax is:

virtual void __fastcall Clear(void);

Unlike the Delete() method, the Clear() function completely empties the list of items. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnEmptyTheListClick(TObject *Sender)
{
    Memorandum->Lines->Clear();
}
//---------------------------------------------------------------------------