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)