Strings¶

Qualified name: delphifmx.Strings

class Strings¶

Bases: Persistent

TStrings is the base class for objects that represent a list of strings. Derive a class from TStrings to store and manipulate a list of strings. TStrings contains abstract or, in C++ terminology, pure virtual methods and should not be directly instantiated. Descendants of TStrings can represent several individual strings, such as the individual lines that appear in a list box. Some objects use descendants of TStrings to represent one long body of text so that it can be manipulated in smaller chunks. TStrings introduces many properties and methods to:

Add or delete strings at specified positions in the list. Rearrange the strings in the list. Access the string at a particular location. Read the strings from or write the strings to a file or stream. Associate an object with each string in the list. Store and retrieve strings as name-value pairs. For an explanation of name-value pairs, refer to the NameValueSeparator property.

Methods

`Add`	Adds a string to the TStrings object and returns the index position
`AddObject`	Adds a string and an associated Delphi object to the Strings and returns the index position
`AddPair`	Adds name-value pairs to the list of strings using fluent-style coding.
`AddStrings`	Adds the specified strings (and objects) to the current TStrings object.
`Append`	Adds a string to the list.
`BeginUpdate`	Enables the TStrings object to track when the list of strings is changing.
`Clear`	Clears all strings from a TStrings (and the associated objects
`Contains`
`ContainsName`
`ContainsObject`
`Delete`	Deletes the string at Index i (and the associated object
`EndUpdate`	Enables the TStrings object to keep track of when the list of strings has finished changing.
`Equals`	Compares the list of strings to the list from another TStrings object and returns true if the two lists match.
`Exchange`	Swaps the position of two strings in the list.
`GetEnumerator`	Returns a TStrings enumerator.
`GetText`	Allocates a text buffer and fills it with the value of the Text property.
`IndexOf`	Returns the Index of a string s or -1 if not found
`IndexOfName`	Returns the position of the first name-value pair with the specified name.
`IndexOfObject`	Returns the index of the first string in the list associated with a given object.
`Insert`	Introduces abstract (Delphi) or pure virtual (C++) method to insert a string at a specified position.
`InsertObject`	Inserts a string into the list at the specified position, and associates it with an object.
`LoadFromFile`	Fills the list with the lines of text in a specified file.
`LoadFromStream`	Fills the list with lines of text read from a stream.
`Move`	Changes the position of a string in the list.
`SaveToFile`	Saves the strings in the list to the specified file.
`SaveToStream`	Writes the value of the Text property to the Stream stream.
`SetStrings`	Sets the strings from another TStrings object to the list of strings.
`SetText`	Sets the Text property.
`ToObjectArray`	Returns the TObject array associated with Strings.
`ToStringArray`	Converts a TStrings descendant to a string array.

Attributes

`Capacity`	Indicates the number of strings the TStrings object can hold.
`ClassName`	Returns the TObject.ClassName
`CommaText`	Lists the strings in the TStrings object in a single comma-delimited string.
`Count`	Introduces an abstract property to represent the number of strings in the list.
`DefaultEncoding`	The default encoding for the current object.
`DelimitedText`	Represents all the strings in the TStrings object as a single delimited string.
`Delimiter`	Specifies the delimiter used by the DelimitedText property.
`Encoding`	Character encoding determined during reading from a stream or file.
`IsEmpty`	bool:
`KeyNames`	str:
`LineBreak`	Defines line-break characters.
`NameValueSeparator`	Indicates the character used to separate names from values.
`Names`	str:
`Objects`	Represents a set of objects that are associated one with each of the strings in the Strings property.
`Options`	Controls a set of boolean properties of TStrings.
`QuoteChar`	Specifies the quote character used by the DelimitedText property.
`StrictDelimiter`	Determines how the Delimiter property is used.
`Strings`	str:
`StringsAdapter`	Implements an IStringsAdapter interface for the TStrings object.
`Text`	Lists the strings in the TStrings object as a single string with the individual strings delimited by carriage returns and line feeds.
`TrailingLineBreak`	Determines whether to add a line Break after the last line of the Text property or not.
`Updating`	Indicates whether or not the list of strings is in the middle of an update.
`UseLocale`	Determines the implementation that the list of strings must use for string comparison.
`ValueFromIndex`	str:
`Values`	str:
`WriteBOM`	Will cause SaveToStream and SaveToFile to write a BOM.

Add(s)¶: Adds a string to the TStrings object and returns the index position

AddObject(s, delphiobject)¶: Adds a string and an associated Delphi object to the Strings and returns the index position

AddPair(Name: str, Value: str) → Strings¶: Adds name-value pairs to the list of strings using fluent-style coding. AddPair adds name-value pairs using the current NameValueSeparator. You can also use AddPair to add name-value pairs and the corresponding AObject. TStrings returns a reference to the string list, allowing to populate the list using the fluent-style coding. Adds name-value pairs to the list of strings using fluent-style coding. AddPair adds name-value pairs using the current NameValueSeparator. You can also use AddPair to add name-value pairs and the corresponding AObject. TStrings returns a reference to the string list, allowing to populate the list using the fluent-style coding.

AddStrings(Strings: Strings) → None¶: Adds the specified strings (and objects) to the current TStrings object. AddStrings, with the Strings parameter of the TStrings type, appends strings and associated objects from the Strings object at the end of the string list in the current TStrings object. AddStrings with the Strings parameter representing the array of strings, appends strings from Strings array at the end of the string list in the current TStrings object. AddStrings, with two parameters, appends strings from Strings array at the end of the string list in the current TStrings object and associates references to objects from Objects with their strings (having the same numbers in Strings and Objects arrays). If the number of strings in Strings is not equal to the number of objects in Objects, then an exception is raised. Adds the specified strings (and objects) to the current TStrings object. AddStrings, with the Strings parameter of the TStrings type, appends strings and associated objects from the Strings object at the end of the string list in the current TStrings object. AddStrings with the Strings parameter representing the array of strings, appends strings from Strings array at the end of the string list in the current TStrings object. AddStrings, with two parameters, appends strings from Strings array at the end of the string list in the current TStrings object and associates references to objects from Objects with their strings (having the same numbers in Strings and Objects arrays). If the number of strings in Strings is not equal to the number of objects in Objects, then an exception is raised. Adds the specified strings (and objects) to the current TStrings object. AddStrings, with the Strings parameter of the TStrings type, appends strings and associated objects from the Strings object at the end of the string list in the current TStrings object. AddStrings with the Strings parameter representing the array of strings, appends strings from Strings array at the end of the string list in the current TStrings object. AddStrings, with two parameters, appends strings from Strings array at the end of the string list in the current TStrings object and associates references to objects from Objects with their strings (having the same numbers in Strings and Objects arrays). If the number of strings in Strings is not equal to the number of objects in Objects, then an exception is raised.

Append(S: str) → None¶: Adds a string to the list. Append is the same as the Add method, except that it does not return a value. Use Append when there is no need to know the index of the string after it has been added, or with descendants of TStrings for which the index returned is not meaningful. For example, the TStrings descendant used by memo objects uses an index to determine where to insert a string, but the inserted string does 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 may be broken off into a subsequent 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.

BeginUpdate()¶: Enables the TStrings object to track when the list of strings is changing.

Capacity¶: Indicates the number of strings the TStrings object can hold.

Clear()¶: Clears all strings from a TStrings (and the associated objects

CommaText¶

Lists the strings in the TStrings object in a single comma-delimited string. Use CommaText to get or set all the strings in the TStrings object in a single comma-delimited string. The single comma-delimited string format is also known as the system data format (SDF). When retrieving CommaText, any string in the list that include spaces, commas or double quotes will be contained in double quotes, and any double quotes in a string will be repeated. For example, if the list contains the following strings:

Stri,ng1 Stri”ng2 String 3 String4

CommaText will return:

“Stri,ng1”,”Stri””ng2”,”String 3”,String4

When assigning CommaText, the value is parsed as SDF formatted text. For SDF format, strings are separated by commas or spaces, and optionally enclosed in double quotes. Double quote marks that are part of the string are repeated to distinguish them from the quotes that surround the string. Spaces and commas that are not contained within double quote marks are delimiters. Two commas next to each other will indicate an empty string, but spaces that appear next to another delimiter are ignored. For example, suppose CommaText is set to:

“Stri,ng 1”,”Stri””ng 2”,String 3,String4

The list will then contain:

Stri,ng 1 Stri”ng 2 String 3 String4

Note: CommaText is the same as the DelimitedText property with a delimiter of ‘,’ and a quote character of ‘”’. Including a trailing comma in the source string causes a blank item to be included in the string list. For example, if CommaText is set to

“String1,String2,String3, “

the string list will contain

String1 String2 String3 <Blank>

Type:: str

Contains(S: str) → bool¶

ContainsName(Name: str) → bool¶

ContainsObject(AObject: Object) → bool¶

Count¶

Introduces an abstract property to represent the number of strings in the list. Descendants of TStrings implement a Count property to indicate the number of strings in the list. Use the Count property when iterating over all the strings in the list, or when trying to locate the position of a string relative to the last string in the list.

Type:: int

DefaultEncoding¶

The default encoding for the current object. DefaultEncoding is used when the nil encoding is specified in a call to LoadFromStream or SaveToStream. By default, DefaultEncoding is set to Default. The user can change DefaultEncoding if another default encoding is desired for LoadFromStream or SaveToStream.

Type:: Encoding

Delete(i)¶: Deletes the string at Index i (and the associated object

DelimitedText¶

Represents all the strings in the TStrings object as a single delimited string. Use DelimitedText to get or set all the strings in the TStrings object in a single string, separated by the character specified by the Delimiter property. When retrieving DelimitedText, any string in the list that includes spaces or the delimiter and quotation marks characters specified in the Delimiter and QuoteChar properties will be surrounded (before and after) by the quotation mark character (QuoteChar). In addition, any QuoteChar character contained in an individual string will be repeated. When retrieving DelimitedText, the resulting value delimits individual strings in two ways: each string is surrounded (before and after) by the quotation marks character specified by the QuoteChar property. In addition, individual strings are separated by the character specified by the Delimiter property. When assigning DelimitedText, individual strings must be separated using Delimiter marks, and optionally enclosed in QuoteChar characters. When assigning DelimitedText, the value is parsed as SDF formatted text. For SDF format, strings are separated by Delimiter characters or spaces, and optionally enclosed in QuoteChar characters. QuoteChar marks that are part of the string are repeated to distinguish them from the QuoteChar characters that surround the string. Spaces and Delimiter characters that are not contained within QuoteChar marks are delimiters. Two Delimiter characters next to each other will indicate an empty string, but spaces that appear next to another Delimiter character are ignored. If StrictDelimiter is set to False, the space character is also interpreted as a delimiter, regardless of the value of Delimiter. This is not true when the space character occurs between quotation marks.

Note: CommaText is the same as the DelimitedText property when Delimiter is ‘,’ and QuoteChar is ‘”’. Including a trailing Delimiter in the source string causes a blank item to be included in the string list.

Type:: str

Delimiter¶

Specifies the delimiter used by the DelimitedText property. Use Delimiter to get or set the delimiter used by the DelimitedText property. DelimitedText represents all of the strings in the TStrings object as a single string, with individual strings separated by the character that is the value of Delimiter. The default delimiter is represented by comma (,).

Type:: unicodechr(str)

Encoding¶

Character encoding determined during reading from a stream or file. Encoding is a read-only property that contains the value of the character encoding detected when the LoadFromStream or LoadFromFile methods are called. If a file or stream does not contain a BOM (the encoding value cannot be detected) then Encoding is set to the value specified in the DefaultEncoding property. Encoding is used in the SaveToStream and SaveToFile methods.

Type:: Encoding

EndUpdate()¶: Enables the TStrings object to keep track of when the list of strings has finished changing.

Equals(Strings: Strings) → bool¶

Compares the list of strings to the list from another TStrings object and returns true if the two lists match. Call Equals to compare the lists in two TStrings objects. Equals compares only the strings, not any references to associated objects. Equals returns true if the lists for both TStrings objects have the same number of strings and the strings in each list match. 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 differ.

Note: The Equals method uses an overridden Get method to perform the compare, thus it does not provide a context-insensitive option.

Exchange(Index1: int, Index2: int) → None¶: Swaps the position of two strings in the list. Call Exchange to rearrange the strings in the list. The strings are specified by their index values in the Index1 and Index2 parameters. Indexes are zero-based, so the first string in the list has an index value of 0, the second has an index value of 1, and so on. If either string has an associated object, Exchange changes the position of the object as well.

GetEnumerator()¶: Returns a TStrings enumerator. GetEnumerator returns a TStringsEnumerator reference, which enumerates the strings in a TStrings object. To process all these strings, call the TStringsEnumerator GetCurrent method within a While MoveNext do loop.

GetText()¶: Allocates a text buffer and fills it with the value of the Text property. Call GetText to obtain a dynamically allocated character buffer containing all of the strings in the list. Individual strings are separated by a carriage return (#13) on the OS X operating system, or by a carriage return and a line feed (#13#10) on Windows operating systems. The caller is responsible for freeing the returned value using the StrDispose procedure.

IndexOf(s)¶: Returns the Index of a string s or -1 if not found

IndexOfName(Name: str) → int¶

Returns the position of the first name-value pair with the specified name. Call IndexOfName to locate the first occurrence of a name-value pair where the name part is equal to the Name parameter or differs only in case. IndexOfName returns the 0-based index of the string. If no string in the list has the indicated name, IndexOfName returns -1.

Note: If there is more than one name-value pair with a name portion matching the Name parameter, IndexOfName returns the position of the first such string.

IndexOfObject(AObject: Object) → int¶: Returns the index of the first string in the list associated with a given object. 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 AObject parameter. 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.

Insert(Index: int, S: str) → None¶: Introduces abstract (Delphi) or pure virtual (C++) method to insert a string at a specified position. 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 InsertObject method instead.

InsertObject(Index: int, S: str, AObject: Object) → None¶: Inserts a string into the list at the specified position, and associates it with an object. 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.

IsEmpty¶: bool:

KeyNames¶: str:

LineBreak¶

Defines line-break characters. The LineBreak property is used internally in TStrings to set the string terminator characters. Set or read the LineBreak property to determine the string terminator characters in multistring output operations. For example, the GetText method returns a long string containing all TStrings strings, each of which is terminated by the LineBreak value.

Note: On Windows, the default LineBreak value is a carriage return and line feed combination (#13#10), whereas on Android, Linux, macOS and iOS it is just a line feed (#10).

Type:: str

LoadFromFile(filename)¶: Fills the list with the lines of text in a specified file.

LoadFromStream(Stream: Stream) → None¶: Fills the list with lines of text read from a stream. LoadFromStream fills the string list of the TStrings object from the stream specified by Stream. The text read from the stream is parsed into strings separated by a carriage return and a line feed (#13#10) characters on Windows operating systems and a carriage return (#13) character on the macOS operating system. Thus, LoadFromStream reads the value of the Text property. If the Encoding parameter is not given, then the strings are loaded using the appropriate encoding. The value of the encoding is obtained by calling the GetBufferEncoding routine of the TEncoding class. LoadFromStream then saves the value of the encoding in the Encoding property, to be used if the stream is saved. If the stream is a file stream, LoadFromStream does the same thing as LoadFromFile, except that LoadFromFile creates and destroys the file stream. Fills the list with lines of text read from a stream. LoadFromStream fills the string list of the TStrings object from the stream specified by Stream. The text read from the stream is parsed into strings separated by a carriage return and a line feed (#13#10) characters on Windows operating systems and a carriage return (#13) character on the macOS operating system. Thus, LoadFromStream reads the value of the Text property. If the Encoding parameter is not given, then the strings are loaded using the appropriate encoding. The value of the encoding is obtained by calling the GetBufferEncoding routine of the TEncoding class. LoadFromStream then saves the value of the encoding in the Encoding property, to be used if the stream is saved. If the stream is a file stream, LoadFromStream does the same thing as LoadFromFile, except that LoadFromFile creates and destroys the file stream.

Move(CurIndex: int, NewIndex: int) → None¶

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. For example, the following lines of code move the string in the first position to the last position: For Delphi:

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

For C++:

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

If the string has an associated object, the object remains associated with the string in its new position.

NameValueSeparator¶

Indicates the character used to separate names from values. Strings that contain the NameValueSeparator character are considered name-value pairs. NameValueSeparator defaults to the equal sign (=). TStrings defines various methods for accessing names and values and for searching for specific names. Strings that are name-value pairs consist of a name part, the separator character, and a value part. Any spaces around the separator character are part of the name or value. This convention corresponds to the format used in many initialization files. For example:

DisplayGrid=1 SnapToGrid=1 GridSizeX=8 GridSizeY=8

Type:: unicodechr(str)

Names¶: str:

Objects¶: Represents a set of objects that are associated one with each of the strings in the Strings property.

Options¶

Controls a set of boolean properties of TStrings. Use Options to specify the value of the following boolean properties of the list of strings:

Option

Property

soStrictDelimiter

StrictDelimiter

soWriteBOM

WriteBOM

soTrailingLineBreak

TrailingLineBreak

soUseLocale

UseLocale

Type:: StringsOptions

QuoteChar¶

Specifies the quote character used by the DelimitedText property. Use QuoteChar to get or set the quote character that is used to enclose individual strings in the DelimitedText property. When QuoteChar is set to the null character, then DelimitedText does the following:

At reading, does not return quoted list items. At assigning, does not check an assigning value for quote char. That is, you can set QuoteChar to the null character to disable quoting in DelimitedText. To set the QuoteChar to the null character, do the following:

Delphi:

MyStringList.QuoteChar := #0;

C++:

MyStringList->QuoteChar = ‘0’;

Type:: unicodechr(str)

SaveToFile(filename)¶: Saves the strings in the list to the specified file.

SaveToStream(Stream: Stream) → None¶

Writes the value of the Text property to the Stream stream. SaveToStream gets all strings from the current TStrings object and combines them into the single string containing these strings delimited by LineBreak sequence. Then SaveToStream encodes this string using the specified Encoding. Then SaveToStream writes the encoded string into the specified Stream stream. If WriteBOM is True then SaveToStream first gets the preamble of the specified Encoding or of the DefaultEncoding (if Encoding = nil) and writes the preamble bytes into the stream before the main string. If the Encoding parameter is not given, then the strings are saved with the encoding specified in the Encoding property.

Note: On Windows, the default LineBreak value is a carriage return and line feed combination (#13#10), whereas on macOS, it is just a line feed (#10). Note: If TrailingLineBreak is True, then SaveToStream writes a finishing line break LineBreak after the last string. If the stream is a file stream, SaveToStream does the same thing as SaveToFile, except that SaveToFile creates and destroys the file stream. Writes the value of the Text property to the Stream stream. SaveToStream gets all strings from the current TStrings object and combines them into the single string containing these strings delimited by LineBreak sequence. Then SaveToStream encodes this string using the specified Encoding. Then SaveToStream writes the encoded string into the specified Stream stream. If WriteBOM is True then SaveToStream first gets the preamble of the specified Encoding or of the DefaultEncoding (if Encoding = nil) and writes the preamble bytes into the stream before the main string. If the Encoding parameter is not given, then the strings are saved with the encoding specified in the Encoding property.

SetStrings(Source: Strings) → None¶

Sets the strings from another TStrings object to the list of strings. Use SetStrings to assign the value of the TStrings object from another TStrings object (Source).

Note: SetStrings is similar to Assign, but Assign also copies multiple additional properties.

SetText(Text: PWideChar) → None¶: Sets the Text property. 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 in Text as delimiters indicating when to add a new string.

StrictDelimiter¶

Determines how the Delimiter property is used. If StrictDelimiter is True, individual strings in DelimitedText are only separated by Delimiter or quoted between QuoteChar. If StrictDelimiter is False, spaces and non-printable character are also used as delimiters.

Tip: You can set QuoteChar to the null character (#0 in Delphi, ‘0’ in C++) if you do not want quoted strings to be extracted as if they where surrounded by Delimiter.

Type:: bool

Strings¶: str:

StringsAdapter¶

Implements an IStringsAdapter interface for the TStrings object.

StringsAdapter specifies the attached TStringsAdapter when it is used in OLE applications.

Note: To create a StringsAdapter you can use GetOleStrings and SetOleStrings instead of creating an instance of TStringsAdapter. StringsAdapter is used internally with OLE applications.

Type:: IStringsAdapter

Text¶: Lists the strings in the TStrings object as a single string with the individual strings delimited by carriage returns and line feeds.

ToObjectArray()¶

Returns the TObject array associated with Strings.

Use ToObjectArray to obtain the array of TObject associated with Strings.

Note: TStrings is an abstract class and this method has no effect. Descendent classes can associate objects with strings. Note: The TStrings object does not own the objects in the Objects array. Objects added to the Objects array still exist even if the TStrings object is destroyed. They must be explicitly destroyed by the application.

ToStringArray()¶

Converts a TStrings descendant to a string array.

Use ToStringArray to obtain an array of strings for each string in the list.

TrailingLineBreak¶

Determines whether to add a line Break after the last line of the Text property or not. Use TrailingLineBreak to add a finishing line break to Text. Set TrailingLineBreak to True to add a line Break after the last line of Text. Set TrailingLineBreak to False to finish Text without a line Break. Default is True.

Type:: bool

Updating¶

Indicates whether or not the list of strings is in the middle of an update.

Type:: bool

UseLocale¶

Determines the implementation that the list of strings must use for string comparison. Set UseLocale to True to use AnsiCompareStr and AnsiCompareText to compare strings. Set UseLocale to False to use CompareStr and CompareText. Default is True.

Type:: bool

ValueFromIndex¶: str:

Values¶: str:

WriteBOM¶

Will cause SaveToStream and SaveToFile to write a BOM. Set WriteBOM to True to cause SaveToStream to write a BOM (byte-order mark) to the stream and to cause SaveToFile to write a BOM to the file.

Type:: bool