Reference for package '#rtl'

TStrings

[Properties (by Name)][Methods (by Name)][Events (by Name)]

Class to manage arrays or collections of strings

Declaration

Source position: classesh.inc line 616

Type
  TStrings = class (TPersistent)
  private
    FDefaultEncoding : TEncoding;
    FEncoding : TEncoding;
    FMissingNameValueSeparatorAction : TMissingNameValueSeparatorAction;
    FSpecialCharsInited : Boolean;
    FAlwaysQuote : Boolean;
    FQuoteChar : Char;
    FDelimiter : Char;
    FNameValueSeparator : Char;
    FUpdateCount : Integer;
    FAdapter : IStringsAdapter;
    FLBS : TTextLineBreakStyle;
    FOptions : TStringsOptions;
    FLineBreak : string;
    function GetCommaText : string;
    function GetLineBreakCharLBS : string;
    function GetMissingNameValueSeparatorAction
                                                : TMissingNameValueSeparatorAction;
    function GetName(Index: Integer) : string;
    function GetStrictDelimiter : Boolean;
    function GetTrailingLineBreak : Boolean;
    function GetUseLocale : Boolean;
    function GetValue(const Name: string) : string;
    function GetWriteBOM : Boolean;
    function GetLBS : TTextLineBreakStyle;
    procedure SetDefaultEncoding(const ADefaultEncoding: TEncoding);
    procedure SetEncoding(const AEncoding: TEncoding);
    procedure SetLBS(AValue: TTextLineBreakStyle);
    procedure ReadData(Reader: TReader);
    procedure SetCommaText(const Value: string);
    procedure SetMissingNameValueSeparatorAction
                                                (AValue: TMissingNameValueSeparatorAction);
    procedure SetStringsAdapter(const Value: IStringsAdapter);
    procedure SetStrictDelimiter(AValue: Boolean);
    procedure SetTrailingLineBreak(AValue: Boolean);
    procedure SetUseLocale(AValue: Boolean);
    procedure SetWriteBOM(AValue: Boolean);
    procedure SetValue(const Name: string; const Value: string);
    procedure SetDelimiter(c: Char);
    procedure SetQuoteChar(c: Char);
    procedure SetNameValueSeparator(c: Char);
    procedure WriteData(Writer: TWriter);
    procedure DoSetTextStr(const Value: string; DoClear: Boolean);
    function GetDelimiter : Char;
    function GetNameValueSeparator : Char;
    function GetQuoteChar : Char;
    function GetLineBreak : string;
    procedure SetLineBreak(const S: string);
    function GetSkipLastLineBreak : Boolean;
    procedure SetSkipLastLineBreak(const AValue: Boolean);
    procedure DoSetDelimitedText(const AValue: string; DoClear: Boolean; 
                                aStrictDelimiter: Boolean; 
                                aQuoteChar: Char; aDelimiter: Char);
  protected
    function CompareStrings(const s1: string; const s2: string) : Integer
                           ;  Virtual;
    procedure DefineProperties(Filer: TFiler);  Override;
    procedure Error(const Msg: string; Data: Integer);
    procedure Error(const Msg: PString; Data: Integer);
    function Get(Index: Integer) : string;  Virtual;  Abstract;
    function GetCapacity : Integer;  Virtual;
    function GetCount : Integer;  Virtual;  Abstract;
    function GetObject(Index: Integer) : TObject;  Virtual;
    function GetTextStr : string;  Virtual;
    procedure Put(Index: Integer; const S: string);  Virtual;
    procedure PutObject(Index: Integer; AObject: TObject);  Virtual;
    procedure SetCapacity(NewCapacity: Integer);  Virtual;
    procedure SetTextStr(const Value: string);  Virtual;
    procedure SetUpdateState(Updating: Boolean);  Virtual;
    UpdateCount : Integer;
    function DoCompareText(const s1: string; const s2: string) : PtrInt
                          ;  Virtual;
    function GetDelimitedText : string;
    procedure SetDelimitedText(const AValue: string);
    function GetValueFromIndex(Index: Integer) : string;
    procedure SetValueFromIndex(Index: Integer; const Value: string);
    procedure CheckSpecialChars;
    class function GetNextLine(const Value: string; var S: string; 
                              var P: SizeInt) : Boolean;
    function GetNextLinebreak(const Value: string; var S: string; 
                             var P: SizeInt) : Boolean;
  public
    constructor Create;
    destructor Destroy;  Override;
    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;  Virtual;  Overload;
    function Add(const Fmt: string; const Args: Array of const) : Integer
                ;  Overload;
    function AddObject(const S: string; AObject: TObject) : Integer
                      ;  Virtual;  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);  Virtual;  Overload;
    procedure AddStrings(TheStrings: TStrings; ClearFirst: Boolean)
                        ;  Overload;
    procedure AddStrings(const TheStrings: Array of string);  Virtual
                        ;  Overload;
    procedure AddStrings(const TheStrings: Array of string; 
                        ClearFirst: Boolean);  Overload;
    procedure SetStrings(TheStrings: TStrings);  Virtual;  Overload;
    procedure SetStrings(TheStrings: Array of string);  Virtual;  Overload;
    procedure AddText(const S: string);  Virtual;
    procedure AddCommaText(const S: string);
    procedure AddDelimitedText(const S: string; ADelimiter: Char; 
                              AStrictDelimiter: Boolean);  Overload;
    procedure AddDelimitedtext(const S: string);  Overload;
    procedure Append(const S: string);
    procedure Assign(Source: TPersistent);  Override;
    procedure BeginUpdate;
    procedure Clear;  Virtual;  Abstract;
    procedure Delete(Index: Integer);  Virtual;  Abstract;
    procedure EndUpdate;
    function Equals(Obj: TObject) : Boolean;  Override;  Overload;
    function Equals(TheStrings: TStrings) : Boolean;  Overload;
    procedure Exchange(Index1: Integer; Index2: Integer);  Virtual;
    function ExtractName(const S: string) : string;
    procedure Filter(aFilter: TStringsFilterMethod; aList: TStrings);
    function Filter(aFilter: TStringsFilterMethod) : TStrings;
    procedure Fill(const aValue: string; aStart: Integer; aEnd: Integer);
    procedure ForEach(aCallback: TStringsForEachMethod);
    procedure ForEach(aCallback: TStringsForEachMethodEx);
    procedure ForEach(aCallback: TStringsForEachMethodExObj);
    function GetEnumerator : TStringsEnumerator;
    procedure GetNameValue(Index: Integer; out AName: string; 
                          out AValue: string);
    function GetText : PChar;  Virtual;
    function IndexOf(const S: string) : Integer;  Virtual;
    function IndexOf(const S: string; aStart: Integer) : Integer;  Virtual;
    function IndexOfName(const Name: string) : Integer;  Virtual;
    function IndexOfObject(AObject: TObject) : Integer;  Virtual;
    procedure Insert(Index: Integer; const S: string);  Virtual;  Abstract;
    procedure InsertObject(Index: Integer; const S: string; 
                          AObject: TObject);
    function LastIndexOf(const S: string; aStart: Integer) : Integer
                        ;  Virtual;
    function LastIndexOf(const S: string) : Integer;
    procedure LoadFromFile(const FileName: string);  Virtual;  Overload;
    procedure LoadFromFile(const FileName: string; IgnoreEncoding: Boolean);
    procedure LoadFromFile(const FileName: string; AEncoding: TEncoding)
                          ;  Virtual;  Overload;
    procedure LoadFromStream(Stream: TStream);  Virtual;  Overload;
    procedure LoadFromStream(Stream: TStream; IgnoreEncoding: Boolean)
                            ;  Overload;
    procedure LoadFromStream(Stream: TStream; AEncoding: TEncoding)
                            ;  Virtual;  Overload;
    procedure Map(aMap: TStringsMapMethod; aList: TStrings);
    function Map(aMap: TStringsMapMethod) : TStrings;
    procedure Move(CurIndex: Integer; NewIndex: Integer);  Virtual;
    function Pop : string;
    function Reduce(aReduceMethod: TStringsReduceMethod; 
                   const startingValue: string) : string;
    function Reverse : TStrings;
    procedure Reverse(aList: TStrings);
    procedure SaveToFile(const FileName: string);  Virtual;  Overload;
    procedure SaveToFile(const FileName: string; IgnoreEncoding: Boolean)
                        ;  Overload;
    procedure SaveToFile(const FileName: string; AEncoding: TEncoding)
                        ;  Virtual;  Overload;
    procedure SaveToStream(Stream: TStream);  Virtual;  Overload;
    procedure SaveToStream(Stream: TStream; IgnoreEncoding: Boolean)
                          ;  Overload;
    procedure SaveToStream(Stream: TStream; AEncoding: TEncoding);  Virtual
                          ;  Overload;
    function Shift : string;
    procedure Slice(fromIndex: Integer; aList: TStrings);
    function Slice(fromIndex: Integer) : TStrings;
    procedure SetText(TheText: PChar);  Virtual;
    AlwaysQuote : Boolean;
    Capacity : Integer;
    CommaText : string;
    Count : Integer;
    DefaultEncoding : TEncoding;
    DelimitedText : string;
    Delimiter : Char;
    Encoding : TEncoding;
    LineBreak : string;
    MissingNameValueSeparatorAction : TMissingNameValueSeparatorAction;
    Names[Index: Integer]: string;
    NameValueSeparator : Char;
    Objects[Index: Integer]: TObject;
    Options : TStringsOptions;
    QuoteChar : Char;
    SkipLastLineBreak : Boolean;
    TrailingLineBreak : Boolean;
    StrictDelimiter : Boolean;
    Strings[Index: Integer]: string; default;
    StringsAdapter : IStringsAdapter;
    Text : string;
    TextLineBreakStyle : TTextLineBreakStyle;
    UseLocale : Boolean;
    ValueFromIndex[Index: Integer]: string;
    Values[Name: string]: string;
    WriteBOM : Boolean;
  end
  ;

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.

Members

Member Type Visibility Description
Add Method public Add a string to the list
AddCommaText Method public
AddDelimitedText Method public
AddObject Method public Add a string and associated object to the list.
AddPair Method public Add a name-value pair
AddStrings Method public Add contents of another stringlist to this list.
AddText Method public Add text to the string list.
AlwaysQuote Property public Always quote strings in DelimitedText
Append Method public Add a string to the list.
Assign Method public Assign the contents of another stringlist to this one.
BeginUpdate Method public Mark the beginning of an update batch.
Capacity Property public Capacity of the list, i.e. number of strings that the list can currently hold before it tries to expand.
CheckSpecialChars Method protected
Clear Method public Removes all strings and associated objects from the list.
CommaText Property public Contents of the list as a comma-separated string.
CompareStrings Method protected
Count Property public Number of strings in the list.
Create Method public Initializ a new TStrings instance
DefaultEncoding Property public Default encoding of stringlist
DefineProperties Method protected Method to stream the contents of the string collection
Delete Method public Delete a string from the list.
DelimitedText Property public Get or set all strings in the list in a delimited form.
Delimiter Property public Delimiter character used in DelimitedText .
Destroy Method public Frees all strings and objects, and removes the list from memory.
DoCompareText Method protected
DoSetDelimitedText Method private
DoSetTextStr Method private
Encoding Property public Current encoding of stringlist
EndUpdate Method public Mark the end of an update batch.
Equals Method public Compares the contents of two stringlists.
Error Method protected Raises an EStringListError exception.
Exchange Method public Exchanges two strings in the list.
ExtractName Method public Extract the name part of a string
FAdapter Field private
FAlwaysQuote Field private
FDefaultEncoding Field private
FDelimiter Field private
FEncoding Field private
Fill Method public
Filter Method public
FLBS Field private
FLineBreak Field private
FMissingNameValueSeparatorAction Field private
FNameValueSeparator Field private
FOptions Field private
ForEach Method public
FQuoteChar Field private
FSpecialCharsInited Field private
FUpdateCount Field private
Get Method protected Abstract read handler for the TStrings.Strings property.
GetCapacity Method protected Abstract Read handler for the TStrings.Capacity property.
GetCommaText Method private
GetCount Method protected Abstract read handler for the TStrings.Count property.
GetDelimitedText Method protected
GetDelimiter Method private
GetEnumerator Method public Create an IEnumerator instance
GetLBS Method private
GetLineBreak Method private
GetLineBreakCharLBS Method private
GetMissingNameValueSeparatorAction Method private
GetName Method private
GetNameValue Method public Return both name and value of a name,value pair based on it's index.
GetNameValueSeparator Method private
GetNextLine Method protected
GetNextLinebreak Method protected
GetObject Method protected Abstract read handler for the TStrings.Objects property.
GetQuoteChar Method private
GetSkipLastLineBreak Method private
GetStrictDelimiter Method private
GetText Method public Returns the contents as a PChar
GetTextStr Method protected Read handler for the TStrings.Text property.
GetTrailingLineBreak Method private
GetUseLocale Method private
GetValue Method private
GetValueFromIndex Method protected
GetWriteBOM Method private
IndexOf Method public Find a string in the list and return its position.
IndexOfName Method public Finds the index of a name in the name-value pairs.
IndexOfObject Method public Finds an object in the list and returns its index.
Insert Method public Insert a string in the list.
InsertObject Method public Insert a string and associated object in the list.
LastIndexOf Method public
LineBreak Property public LineBreak character to use
LoadFromFile Method public Load the contents of a file as a series of strings.
LoadFromStream Method public Load the contents of a stream as a series of strings.
Map Method public
MissingNameValueSeparatorAction Property public
Move Method public Move a string from one place in the list to another.
Names Property public Name parts of the name-value pairs in the list.
NameValueSeparator Property public Value of the character used to separate name,value pairs
Objects Property public Indexed access to the objects associated with the strings in the list.
Options Property public A set of TStringsOption - various boolean properties.
Pop Method public
Put Method protected Write handler for the TStrings.Strings property.
PutObject Method protected Write handler for the TStrings.Objects property.
QuoteChar Property public Quote character used in DelimitedText .
ReadData Method private
Reduce Method public
Reverse Method public
SaveToFile Method public Save the contents of the list to a file.
SaveToStream Method public Save the contents of the string to a stream.
SetCapacity Method protected Write handler for the TStrings.Capacity property.
SetCommaText Method private
SetDefaultEncoding Method private
SetDelimitedText Method protected
SetDelimiter Method private
SetEncoding Method private
SetLBS Method private
SetLineBreak Method private
SetMissingNameValueSeparatorAction Method private
SetNameValueSeparator Method private
SetQuoteChar Method private
SetSkipLastLineBreak Method private
SetStrictDelimiter Method private
SetStrings Method public
SetStringsAdapter Method private
SetText Method public Set the contents of the list from a PChar.
SetTextStr Method protected Write handler for the TStrings.Text property.
SetTrailingLineBreak Method private
SetUpdateState Method protected Sets the update state.
SetUseLocale Method private
SetValue Method private
SetValueFromIndex Method protected
SetWriteBOM Method private
Shift Method public
SkipLastLineBreak Property public Do not add a linebreak to the last item
Slice Method public
StrictDelimiter Property public Should only the delimiter character be considered a delimiter
Strings Property public Indexed access to the strings in the list.
StringsAdapter Property public Not implemented in Free Pascal.
Text Property public Contents of the list as one big string.
TextLineBreakStyle Property public Determines which line breaks to use in the Text property
ToObjectArray Method public
ToStringArray Method public
TrailingLineBreak Property public Add a linebreak to the last item
UpdateCount Property protected
UseLocale Property public Determines what methods are used in strings comparison.
ValueFromIndex Property public Return the value part of a string based on it's index.
Values Property public Value parts of the name-value pairs in the list.
WriteBOM Property public Write BOM when writing stringlist to stream
WriteData Method private

Inheritance

Class Description
TStrings Class to manage arrays or collections of strings

See also

Name Description
Char Character type (1 byte)
Char Character type (1 byte)
Char Character type (1 byte)
Char Character type (1 byte)
Char Character type (1 byte)
Char Character type (1 byte)
IFPObserved Interface implemented by an object that can be observed.
Integer A signed 16-bits integer
Integer A signed 16-bits integer
Integer A signed 16-bits integer
Integer A signed 16-bits integer
IStringsAdapter IStringsAdapter Interface declaration.
IStringsAdapter IStringsAdapter Interface declaration.
TEncoding
TEncoding
TEncoding
TEncoding
TObject Base class of all classes.
TStringList Standard implementation of the TStrings class.
TStringsOptions Set of TStringsOption
TStringsOptions Set of TStringsOption
TTextLineBreakStyle Text line break style. (end of line character)
TTextLineBreakStyle Text line break style. (end of line character)