10.2. Methods

~ TStrings
Destructor.

Add
Add a string to the end of the list. The Add method returns the index of the new chain.

 virtual int __fastcall Add (const System:: AnsiString S); 

BeginUpdate and EndUpdate Should Always Be Used in conjunction with a try ... catch statement to Ensure That Is Called EndUpdate if an exception occurs. A block That Uses BeginUpdate and EndUpdate Typically looks like this:

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
ListBox1-> Items-> BeginUpdate ();
try {
ListBox1-> Items-> Clear ();
ListBox1-> Items-> Add ("Some foo");
ListBox1-> Items-> Add ("Some data");
ListBox1-> Items-> EndUpdate ();
}
catch (...){
ListBox1-> Items-> EndUpdate (); / / Executed events in case of an exception
throw;
}
} 

AddObject
Add a string to the list, and associates an object to the chain.

 virtual int __fastcall AddObject (const System:: AnsiString S, System:: TObject * AObject) 

Description

Call AddObject to add a string and Its associated object to the list. AddObject returns the index of the new string and object.

This code adds the string 'Orange' and a bitmap of an orange to an owner-draw list box:

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
TIcon * Icon;
Icon = new TIcon;
Icon-> LoadFromFile (Orange.es ");
ListBox1-> Items-> AddObject ("Orange", Icon);
} 

AddStrings
Add a group of strings to the list. For example, copy the contents of a memo in another.

 virtual void __fastcall AddStrings (TStrings * Strings); 

Description

Call AddStrings to add the strings from Another TStrings object to the list. If Both the source and destination objects associated support TStrings objects With their strings, references to the associated objects will Be added as well.

This code adds the list of strings Contained in ListBox1-> Items to the end of the ListBox2-> Items list of strings:

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
ListBox2-> Items-> AddStrings (ListBox1-> Items);
} 

Append
Add the string S to the list. The Append method is the same as Add, except that it does not return no par value.

 __fastcall void Append (const System:: AnsiString S); 

Description

Append Use When There Is No Need to know the index of the string after it has-been added, or with descendants of TStrings for the index returned Which is Not Meaningful.

For example, the memo Used by TStrings descendant objects use an index to determine WHERE to insert a string, the inserted string does But Not Necessarily end up as a single string in the list. Part of the inserted text May Become part of the previous string, and part broken off May Be Subsequent Into a string. The index returned by Add is Not Meaningful in this case.

Use Append Rather Than Add as a parameter for a function Requiring a TGetStrProc.

This code uses a button and a list box on a form. When the user clicks the button, the code appends a new string to a list box.

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
ListBox1-> Items-> Append ("New String");
} 

Assign
This method copies the strings contained in the list of TString object to another object. It overwrites the content.

 virtual void __fastcall Assign (TPersistent * Source); 

Description

Use Assign to September the value of the object from Another TStrings object. If Source is TStrings of type, the list is in September to the list of the source TStrings object, and if associated objects Are Supported, Any associated objects are copied from the Source as well.

Source If not is of type TStrings, the inherited Assign September will list the value of the object from That Supports Any TStrings in AssignTo STI method.

This example Consists of a memo and form with a listbox. When the button is clicked, the contents of the memo Are filled with the contents of the listbox.

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
Memo1-> Lines-> Assign (ListBox1-> Items);
} 

BeginUpdate
TStrings Enables the object to track when to the list of strings is Changing.

 void __fastcall BeginUpdate (void); 

Description

Automatically BeginUpdate Is Called By Any property or method That Changed the list of strings. Once the Changes are complete, the property or method calls EndUpdate. Before BeginUpdate Call Directly Modifying the strings in the list, and EndUpdate after. When Implementing Methods That properties or change the list in descendants of TStrings, call BeginUpdate Before The Changes are made, and EndUpdate When the Changes are complete.

Simply TStrings Keeps track of when to the list of strings is Being changed. Some descendants of TStrings use this information to Perform Certain actions, Such as telling a control to repaint, When Are updates complete.

BeginUpdate and EndUpdate Should Always Be Used in conjunction with a try ... catch statement to Ensure That Is Called EndUpdate if an exception occurs. A block That Uses BeginUpdate and EndUpdate Typically looks like this:

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
ListBox1-> Items-> BeginUpdate ();
try {
ListBox1-> Items-> Clear ();
ListBox1-> Items-> Add ("Some foo");
ListBox1-> Items-> Add ("Some data");
ListBox1-> Items-> EndUpdate ();
}
catch (...){
ListBox1-> Items-> EndUpdate (); / / Executed events in case of an exception
throw;
}
} 

Clear
Empty the list and the associated objects.

 virtual void __fastcall Clear (void) = 0; 

Description

Descendants of TStrings implemented Clear method to delete all the strings in the list, and Stock and to remove references to associated objects.

This example fills the list of a combo box with the set of available fonts When the user drops down the list. The list is Regenerated Every time the list is dropped down, so if the application adds or Remove fonts, the combo box stays current.

 __fastcall void Form1:: ComboBox1DropDown (TObject * Sender)
{
FontCombo-> Items-> BeginUpdate (), / / prevent Until repaints done
FontCombo-> Items-> Clear () / / empty the list of old values and Stock
FontCombo-> Sorted = true, / / make sure the font names sorted Are
FontCombo-> Items = Screen-> Fonts, / / add the current list of fonts
FontCombo-> Items-> EndUpdate (); / / reenable painting
} 

Delete
Deletes a string indicating the index list.

 virtual void __fastcall Delete (int Index) = 0; 

Description

Descendants of TStrings implemented Delete Specified method to remove a string from the list. If an object is associated with the string, the reference to the object is removed as well. Index Gives the position of the string, where, 0 is the first string, 1 is the second string, and so on.

This example uses a list box and a button on a form. When the form Appears, Are five items in the list box. When the user clicks the button, the second item in the list box is deleted:

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
ListBox1-> Items-> Delete (1);
} 

EndUpdate
TStrings Enables the object to keep track of when to the list of strings you have finished Changing.

 void __fastcall EndUpdate (void); 

Description

Automatically EndUpdate Is Called By Any property or method That Changed the list of strings. Before BeginUpdate Call Directly Modifying the strings in the list, and EndUpdate after. When Implementing Methods That properties or change the list in descendants of TStrings, call BeginUpdate Before The Changes are made, and EndUpdate When the Changes are complete.

Simply TStrings Keeps track of when to the list of strings is Being changed. Some descendants of TStrings use this information to Perform Certain actions, Such as telling a control to repaint, When Are updates complete.

Equals
Compare the list of channels on the list with other objects TStrins and returns true if the two lists are equal.

 __fastcall bool Equals (TStrings * Strings); 

Description

Call Equals to compare the two lists in TStrings objects. Equals compare only the strings, NOT Any references to associated objects. Equals returns true if the lists for objects TStrings Both Have the Same number of strings and the strings in Each list Are identical. Equals returns false if the lists Are Different in length, If They Contain Different Strings, or if the order of the strings in the two lists diff.

Exchange
Swaps the positions of two strings in the list.

 __fastcall virtual void Exchange (int index1, int index2); 

Description

Call Exchange to rearrange the strings in the list. The strings Are Specified by Their index values in the index1 and index2 parameters. Are zero-based indexes, so the first string in the list have an index value of 0, the second has an index value of 1, and so on.

Either if you have an associated string object, Exchange Change the position of the object as well.

GetText
Assign a text buffer and fills it with the Text property value.

 __fastcall virtual char * GetText (void); 

Description

GetText Call Allocated dynamically to Obtain a character buffer containing all of the strings in the list. Individual strings Are Separated by a carriage return and line feed. The caller is responsible for Freeing the returned value.

Example:

 String data;
M = Memo1-> Lines-> GetText (); / / Drop all lines separated by carriage return and line feed 

IndexOf
Return the position of a string in the list. The text must match the whole line.

 __fastcall virtual int IndexOf (const System:: AnsiString S);

if (Memo1-> Lines-> IndexOf ("Win.ini")> -1); 

Description

Call IndexOf to Obtain the position of the first Occurrence of the string S. IndexOf returns the 0-based index of the string. Thus, if S matches the first string in the list, IndexOf returns 0, if S is the second string, IndexOf returns 1, and so on. If the string is Not in the string list, IndexOf returns -1.

Note: If the string in the list Appears More Than Eleven, IndexOf returns the position of the first Occurrence.

This example uses a file list box, a directory list box, and a label on a form. When the user uses the directory list box to change directories, a message Appears and the color of the form if the changes file is AUTOEXEC.BAT file in the new directory. The code is Written in the OnChange event of the directory list box:

 void __fastcall TForm1:: DirectoryListBox1Change (TObject * Sender)
{
FileListBox1-> Directory = DirectoryListBox1-> Directory;
if (FileListBox1-> Items-> IndexOf ("AUTOEXEC.BAT")> -1) {
Color = clYellow;
Label1-> Caption = "You are in the root directory!"
}
} 

IndexOfName
Returns the position of the first string of the form name = value with the name especifífico.

 int __fastcall IndexOfName (const System:: AnsiString Name);

pos = Memo1-> Lines-> IndexOfName (Variable3 ") / / Returns the line number 

Description

Call IndexOfName to locate the first Occurrence of a string with the form Name = Value Where the name part is equal to the Name parameter. IndexOfName returns the 0-based index of the string. If no string in the Indicated list has the name, IndexOfName returns -1.

Strings of the form Name = Value Are Commonly found in. INI files. For example, Here Are A Few strings taken from a typical. INI file:

Displaygrid = 1

SnapToGrid = 1
GridSizeX = 8
GridSizeY = 8

The Strings That Make up the Params property of a database component (TDatabase) Have this format as well.

The Name that the string identifier is to the left of the equal sign (=), and the current Value of the Name identifier is on the right side. There Should Be no spaces present Before or after the equal sign.

Note: If There Is More Than One Portion string with a name matching the name parameter, IndexOfName returns the position of the first Such string.

Following the example merges the strings in the memo control strings Into Contained in the list box. If a string in the memo is of the form Name = Value and the Name también Contained in the list box, STI value Will Be Replaced by the list box's value.

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
int P, DI;
AnsiString S;
for (int i = 0; i <= ListBox1-> Items-> Count - 1; i + +) {
S = ListBox1-> Items-> Strings [i];
P = S. Pos ("=");
if (P> 1) {
DI = Memo1-> Lines-> IndexOfName (AnsiString (S. SubString (1, P - 1)));
if (ID> -1)
Memo1-> Lines-> Strings [DI] = S;
}
}
} 

IndexOfObject
Returns the index of the first string in the list associated with a Given object.

int __fastcall IndexOfObject (System:: TObject * AObject)

Description

Call IndexOfObject to locate the first string in the list associated with the object AObject. Specify the object you want to locate as the value of the parameter AObject. IndexOfObject returns the 0-based index of the string and object. If the object is Not Associated with Any of the strings, IndexOfObject returns -1.

The Following code is MyObject Determines if the first object in MyStringList.

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
if (ListBox1-> Items-> IndexOfObject (MyObject) == 0)
ShowMessage ("foo");
} 

Insert
Insert a string at a specific position.

 virtual void __fastcall Insert (int Index, const System:: AnsiString S) = 0;
Memo1-> Lines-> Insert (2, "Hello"); 

Description

Descendants of TStrings Implement an Insert method to add the string S to the list at the position Specified by Index. If Index is 0, the string is inserted at the Beginning of the list. If Index is 1, the string is put in the second position of the list, and so on.

All Methods That add strings to the list use the Insert method to add the string.

If the string has an associated object, use the method InsertObject instead.

InsertObject
Insert a string at a specific position in the list, and associates this with an object.

 void __fastcall InsertObject (int Index, const System:: AnsiString S, System:: TObject * AObject) 

Description

Call InsertObject to insert the string S Into the list at the position Identified by Index, and associate it with the object AObject. If Index is 0, the string is inserted at the Beginning of the list. If Index is 1, the string is put in the second position of the list, and so on.

The Following code inserts the components of Form1 Into the first position of the list of Memo1 Lines.

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
for (int i = 0; i <Form1-> ComponentCount-1, i + +)
Memo1-> Lines-> InsertObject (0, Form1-> Components [i] -> Name, this);
} 

LoadFromFile

Fill out the list of lines from a text file.

 virtual void __fastcall LoadFromFile (const System:: AnsiString FileName); 

Description

Call LoadFromFile to fill the list of the TStrings object from the file specified by FileName. Each line in the file, as Indicated by carriage return or linefeed characters, is appended as a string in the list.

This example uses a memo and a button on a form. When the button is clicked the memo is filled with the contents of the file.

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
Memo1-> Lines-> LoadFromFile (Unit1.cpp ");
} 

LoadFromStream
Fill out the list of lines of text read from the console.

 virtual void __fastcall LoadFromStream (TStream * Stream); 

Description

Call LoadFromStream to fill the list of the TStrings object from the stream Specified by Stream. The text read from the stream is parsed strings Into Separated by carriage return or linefeed characters. Thus, LoadFromStream reads the value of the Text property.

If the stream is a stream file, LoadFromStream does the Same thing as LoadFromFile, except the application Must create and destroy the file stream.

This example uses a memo and a button on a form. When the button is clicked the memo is filled with the contents of the file and Then to a new file saved.

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
Memo1-> Lines-> LoadFromStream (& TFileStream (Unit1.cpp "fmOpenRead));
Memo1-> Lines-> SaveToStream (& TFileStream (Unit2.cpp "fmOpenWrite));
} 

Move
Change the position of a string in the list.

 virtual void __fastcall Move (int CurIndex, int NewIndex)
Memo1-> Lines-> Move (2.4), / / Move the chain from position 2 to 4 

Description

Use Move to move the string at position CurIndex it so That Occupied the position NewIndex. The positions Are Specified as 0-based indexes. For example, the Following line of code moves the string in the first position to the last position.

 MyStringsObject-> Move (0, MyStringsObject-> Count - 1); 

If the string has an associated object, the object associated with the string Remains in STIs new position.

This example uses a list box and a button on a form. The list box contains items When the form appears. When the user clicks the button, the fifth item in the list box is Moved to the top of the list box:

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
ListBox1-> Items-> Move (4.0);
}
//------------------------------------------------ ---------------------------
void __fastcall TForm1:: FormCreate (TObject * Sender)
{
for (int i = 0; i <10; i + +)
ListBox1-> Items-> Append ("New String" + AnsiString (i));
} 

SaveToFile
Save the strings in the file list.

 virtual void __fastcall SaveToFile (const System:: AnsiString FileName); 

Description

Call SaveToFile to save the strings in the list to the file specified by FileName. Each string in the list is Written to a Separate line in the file.

This example uses a memo and a button on a form. When the button is clicked the memo is filled with the contents of the file and Then to a new file saved.

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
Memo1-> Lines-> LoadFromFile (Unit1.cpp ");
Memo1-> Lines-> SaveToFile (Unit2.cpp ");
} 

SaveToStream
Enter the Text property value in a Stream object.

 virtual void __fastcall SaveToStream (TStream * Stream); 

Description

Call SaveToStream to save the strings in the list to the stream Specified by the Stream parameter. SaveToStream writes the strings delimited by carriage return, line feed pairs. If the stream is a stream file, SaveToStream does the Same thing as SaveToFile, except the application Must create and destroy the file stream.

This example uses a memo and a button on a form. When the button is clicked the memo is filled with the contents of the file and Then to a new file saved.

 void __fastcall TForm1:: Button1Click (TObject * Sender)
{
Memo1-> Lines-> LoadFromStream (& TFileStream (Unit1.cpp "fmOpenRead));
Memo1-> Lines-> SaveToStream (& TFileStream (Unit2.cpp "fmOpenWrite));
} 

SetText
Start the list with the specified text content.

 __fastcall virtual void SetText (char * Text); 

Description

Call SetText to replace the list with the strings Specified by the Text parameter. SetText adds strings one at a time to the list, using the carriage returns or linefeed characters as delimiters in Text Indicating When to add a new string.

TStrings
Constructor. Creates a new TStrings.

 __fastcall TStrings (void): Classes:: TPersistent () {} 

Description

Do not create instances of TStrings. Methods TStrings Rely on pure virtual Methods That Must Be overridden in descendant objects.