TStrings¶

Class to manage arrays or collections of strings.

Declaration¶

Source position: classesh.inc line 1013

type

  TStrings = class(TPersistent)
  public
    constructor Create;
    destructor Destroy;
    function ToObjectArray(aStart: Integer; aEnd: Integer) : TObjectDynArray; overload;
    function ToObjectArray : TObjectDynArray; overload;
    function ToStringArray(aStart: Integer; aEnd: Integer) : TStringDynArray; overload;
    function ToStringArray : TStringDynArray; overload;
    function Add(const S: string) : Integer; overload;
    function Add(const Fmt: string; const Args: Array of const) : Integer; overload;
    function AddObject(const S: string; AObject: TObject) : Integer; overload;
    function AddObject(const Fmt: string; Args: Array of const; 
                  AObject: TObject) : Integer; overload;
    function AddPair(const AName: string; const AValue: string) : TStrings; overload;
    function AddPair(const AName: string; const AValue: string; 
                AObject: TObject) : TStrings; overload;
    procedure AddStrings(TheStrings: TStrings); overload;
    procedure AddStrings(TheStrings: TStrings; ClearFirst: Boolean); overload;
    procedure AddStrings(const TheStrings: Array of string = string); overload;
    procedure AddStrings(const TheStrings: Array of string = string; 
                    ClearFirst: Boolean); overload;
    procedure SetStrings(TheStrings: TStrings); overload;
    procedure SetStrings(TheStrings: Array of string = string); overload;
    procedure AddText;
    procedure AddCommaText;
    procedure AddDelimitedText(const S: string; ADelimiter: char; 
                          AStrictDelimiter: Boolean); overload;
    procedure AddDelimitedtext(const S: string); overload;
    procedure Append;
    procedure Assign;
    procedure BeginUpdate;
    procedure Clear;
    procedure Delete;
    procedure EndUpdate;
    function Equals(Obj: TObject) : Boolean; overload;
    function Equals(TheStrings: TStrings) : Boolean; overload;
    procedure Exchange;
    function ExtractName : string;
    procedure Filter(aFilter: TStringsFilterMethod; aList: TStrings);
    function Filter(aFilter: TStringsFilterMethod) : TStrings;
    procedure Fill;
    procedure ForEach(aCallback: TStringsForEachMethod);
    procedure ForEach(aCallback: TStringsForEachMethodEx);
    procedure ForEach(aCallback: TStringsForEachMethodExObj);
    function GetEnumerator : TStringsEnumerator;
    procedure GetNameValue;
    function GetText : PChar;
    function Contains : Boolean;
    function ContainsObject : Boolean;
    function IndexOf(const S: string) : Integer; overload;
    function IndexOf(const S: string; aStart: Integer) : Integer; overload;
    function ContainsName : Boolean;
    function IndexOfName : Integer;
    function IndexOfObject : Integer;
    procedure Insert;
    procedure InsertObject;
    function LastIndexOf(const S: string; aStart: Integer) : Integer; overload;
    function LastIndexOf(const S: string) : Integer; overload;
    procedure LoadFromFile(const FileName: string); overload;
    procedure LoadFromFile(const FileName: string; IgnoreEncoding: Boolean);
    procedure LoadFromFile(const FileName: string; AEncoding: TEncoding); overload;
    procedure LoadFromStream(Stream: TStream); overload;
    procedure LoadFromStream(Stream: TStream; IgnoreEncoding: Boolean); overload;
    procedure LoadFromStream(Stream: TStream; AEncoding: TEncoding); overload;
    procedure Map(aMap: TStringsMapMethod; aList: TStrings);
    function Map(aMap: TStringsMapMethod) : TStrings;
    procedure Move;
    function Pop : string;
    function Reduce : string;
    function Reverse : TStrings;
    procedure Reverse(aList: TStrings);
    procedure SaveToFile(const FileName: string); overload;
    procedure SaveToFile(const FileName: string; IgnoreEncoding: Boolean); overload;
    procedure SaveToFile(const FileName: string; AEncoding: TEncoding); overload;
    procedure SaveToStream(Stream: TStream); overload;
    procedure SaveToStream(Stream: TStream; IgnoreEncoding: Boolean); overload;
    procedure SaveToStream(Stream: TStream; AEncoding: TEncoding); overload;
    function Shift : string;
    procedure Slice(fromIndex: Integer; aList: TStrings); overload;
    procedure Slice(fromIndex: Integer; toIndex: Integer; aList: TStrings); overload;
    function Slice(fromIndex: Integer) : TStrings; overload;
    function Slice(fromIndex: Integer; toIndex: Integer) : TStrings; overload;
    procedure SetText;
    property AlwaysQuote: Boolean; {rw}
    property Capacity: Integer; {rw}
    property CommaText: string; {rw}
    property Count: Integer; {r}
    property DefaultEncoding: TEncoding; {rw}
    property DelimitedText: string; {rw}
    property Delimiter: char; {rw}
    property Encoding: TEncoding; {r}
    property LineBreak: string; {rw}
    property MissingNameValueSeparatorAction: TMissingNameValueSeparatorAction; {rw}
    property Names[Index : Integer]: string; {r}
    property NameValueSeparator: char; {rw}
    property Objects[Index : Integer]: TObject; {rw}
    property Options: TStringsOptions; {rw}
    property QuoteChar: char; {rw}
    property SkipLastLineBreak: Boolean; {rw}
    property TrailingLineBreak: Boolean; {rw}
    property StrictDelimiter: Boolean; {rw}
    property Strings[Index : Integer]: string; {rw}
    property StringsAdapter: IStringsAdapter; {rw}
    property Text: string; {rw}
    property TextLineBreakStyle: TTextLineBreakStyle; {rw}
    property UseLocale: Boolean; {rw}
    property ValueFromIndex[Index : Integer]: string; {rw}
    property Values[const  Name : string]: string; {rw}
    property WriteBOM: Boolean; {rw}
  end;

Inheritance¶

Description¶

TStrings implements an abstract class to manage an array of strings. It introduces methods to set and retrieve strings in the array, searching for a particular string, concatenating the strings and so on. It also allows an arbitrary object to be associated with each string.

It also introduces methods to manage a series of name=value settings, as found in many configuration files.

An instance of TStrings is never created directly, instead a descendant class such as TStringList should be created. This is because TStrings is an abstract class which does not implement all methods; TStrings also doesn't store any strings, this is the functionality introduced in descendants such as TStringList.

TStrings implements the IFPObserved interface: when the stringlist is changed, a ooChanged notification is sent to all observers.

Properties¶

Member	Visibility	Description
AlwaysQuote	public	Always quote strings in DelimitedText.
Capacity	public	Capacity of the list, i.e. number of strings that the list can currently hold before it tries to expand.
CommaText	public	Contents of the list as a comma-separated string.
Count read only	public	Number of strings in the list.
DefaultEncoding	public	Default encoding of stringlist.
DelimitedText	public	Get or set all strings in the list in a delimited form.
Delimiter	public	Delimiter character used in DelimitedText.
Encoding read only	public	Current encoding of stringlist.
LineBreak	public	LineBreak character to use.
MissingNameValueSeparatorAction	public	What to do if NameValueSeparator is missing in a string.
Names read only	public	Name parts of the name-value pairs in the list.
NameValueSeparator	public	Value of the character used to separate name,value pairs.
Objects	public	Indexed access to the objects associated with the strings in the list.
Options	public	A set of TStringsOption - various boolean properties.
QuoteChar	public	Quote character used in DelimitedText.
SkipLastLineBreak	public	Do not add a linebreak to the last item.
StrictDelimiter	public	Should only the delimiter character be considered a delimiter.
Strings	public	Indexed access to the strings in the list.
StringsAdapter	public	Not implemented in Free Pascal.
Text	public	Contents of the list as one big string.
TextLineBreakStyle	public	Determines which line breaks to use in the Text property.
TrailingLineBreak	public	Add a linebreak to the last item.
UseLocale	public	Determines what methods are used in strings comparison.
ValueFromIndex	public	Return the value part of a string based on it's index.
Values	public	Value parts of the name-value pairs in the list.
WriteBOM	public	Write BOM when writing stringlist to stream.

See all Properties

Methods¶

Member	Visibility	Description
Add	public	Add a string to the list.
AddCommaText	public	Adds a comma-separated list of strings.
AddDelimitedtext	public	Adds a separator-delimited list of strings.
AddObject	public	Add a string and associated object to the list.
AddPair	public	Add a name-value pair.
AddStrings	public	Add contents of another stringlist to this list.
AddText	public	Add text to the string list.
Append	public	Add a string to the list.
Assign	public	Assign the contents of another stringlist to this one.
BeginUpdate	public	Mark the beginning of an update batch.
Clear	public	Removes all strings and associated objects from the list.
Contains	public
ContainsName	public
ContainsObject	public
Create	public	Initializ a new TStrings instance.
Delete	public	Delete a string from the list.
Destroy	public	Frees all strings and objects, and removes the list from memory.
EndUpdate	public	Mark the end of an update batch.
Equals	public	Compares the contents of two stringlists.
Exchange	public	Exchanges two strings in the list.
ExtractName	public	Extract the name part of a string.
Fill	public	Set a range of strings in the list to the specified value.
Filter	public	Return a filtered list.
ForEach	public	Call a callback for each string in the list.
GetEnumerator	public	Create an IEnumerator instance.
GetNameValue	public	Return both name and value of a name,value pair based on it's index.
GetText	public	Returns the contents as a PChar.
IndexOf	public	Find a string in the list and return its position.
IndexOfName	public	Finds the index of a name in the name-value pairs.
IndexOfObject	public	Finds an object in the list and returns its index.
Insert	public	Insert a string in the list.
InsertObject	public	Insert a string and associated object in the list.
LastIndexOf	public	Return the index of the last occurrence of a string.
LoadFromFile	public	Load the contents of a file as a series of strings.
LoadFromStream	public	Load the contents of a stream as a series of strings.
Map	public	Call a map routine for each string in the list.
Move	public	Move a string from one place in the list to another.
Pop	public	Remove the last string of the list and return it.
Reduce	public	Get a reduced value from the string list.
Reverse	public	Reverse the order of the strings in the list.
SaveToFile	public	Save the contents of the list to a file.
SaveToStream	public	Save the contents of the string to a stream.
SetStrings	public	Replace the strings with the passed strings.
SetText	public	Set the contents of the list from a PChar.
Shift	public	Return and remove the first string in the list.
Slice	public	Return a subrange of strings starting at a given index.
ToObjectArray	public	Return the objects as an array of object.
ToStringArray	public	Return the strings as an array of string.

See all Methods

Name	Description
TStringList	Standard implementation of the TStrings class.
IFPObserved	Interface implemented by an object that can be observed.