fTStringClass
Version 2.01





A PChar based string management object 
for
Borlands DELPHI Windows development 
environment







Copyright of 
ICFM Software,
London,UK
(Email: Compuserve 100010,1415)


ICFM SOFTWARE
LIBRARY DOCUMENTATION


Date:	5th November,1995

Re:		STRCLASS.PAS - The Pascal PChar based string object


Contents

1. Introduction	4
2. Working with TStringClass objects	5
3. Character Positions	5
4. Parameters	6
5. Working with VCL text components	8
6. Pushing data directly into the class text buffer	9
7. Using the Global string class variable gSc	10
8. ExceptionHandling	10
9. Limitations	10
10. Bug fixes, Ideas etc	11
11. Copyright Notice	11
12. TStringClass - Object Definition	12
12.1 Data Members	12
12.2 Private Methods	12
12.3 Protected Methods	13
12.4 Properties	14
12.5 Public Methods	15
12.5.1 Constructors/Destructors	15
12.5.2 Copy related	16
12.5.3 Clear type functions	16
12.5.3	16
12.5.4 Admin type functions	16
12.5.5 Assign related functions	16
12.5.6 Append related functions	18
12.5.7 Character element related functions	20
12.5.8 Other data type related functions	21
12.5.9 SysUtils unit compatible functions	24
12.5.10 Strings unit compatible functions	26
12.5.11 Comparison related functions	27
12.5.12 Insert/Delete/Trim related functions	29
12.5.12	29
12.5.13 Command Line related functions	30
12.5.14 Resource string related functions	30
12.5.15 INI file related functions	31
12.5.16 DOS path/filename related functions	31
12.5.17 Search related functions	34
12.5.18 Case related functions	37
12.5.19 Search & replace related functions	37
12.5.20 Parsing related functions	38
13. Container Objects	42
13.1 TBaseContainer	42
13.1.1 Public methods	42
13.1.2 Properties	43
13.2 TObjectContainer	45
13.2.1 Public methods	45
13.2.2 Properties	49
13.3 TRecordContainer	49
13.3.1 Public methods	49
13.4 TPCharContainer = CLASS(TObjectContainer)	50
13.5 TIntegerContainer = CLASS(TBaseContainer)	50
13.5.1 Public methods	50
13.5.2 Properties	50
13.6 TWordContainer = CLASS(TBaseContainer)	50
13.6.1 Public methods	50
13.6.2 Properties	51
13.7 TLongIntContainer = CLASS(TBaseContainer)	51
13.7.1 Public methods	51
13.7.2 Properties	51
13.8 TCustomTypeContainer = CLASS(TBaseContainer)	51
13.8.1 Public methods	51
14. Version Management	53
15. Index	56


1. Introduction

This TStringClass object is designed to manage large string variables by encapsulating a 
core PChar type text buffer within a controlled object wrapper.

Pascal STRING type text variables are easy to use and manipulate, but suffer from a having a 
maximum size of 255 characters. If you are processing large arrays of STRING type variables 
they can waste valuable stack or heap space.

The alternative to using STRING types is to use the null terminated string (or PChar) type.  For 
most programmers PChars are a necessary evil.  

This 'TStringClass'  object was originally developed to solve some of the problems that are 
frequently encountered whilst using 'PChar' type variables, namely:

*	Using un-intialised or 'NIL' PChar variables with any of the STRINGS unit functions, and 
*	Not declaring buffers of sufficient length, such that concatenating variables leads to 
internal memory overwrites.

The TStringClass object offers solutions to these and other related problems. It controls its own 
internal buffer for holding the PChar variable, and before performing any assignments or 
concatenations it always checks to see that sufficient room is available. If there is insufficient 
space it re-sizes the buffer to fit the required action.

This object was originally created to counteract problems with 'guess-timating' the PChar 
variable buffer length for complicated SQL expressions. Since then it has been expanded to 
cover almost anything that can be done with a string type variable.

The object has the following main categories of methods:

  Multiple constructors for initiating the object for different situations
  A set of high level methods for working with other TStringClass type variables.
  A range of different 'Assign' methods for moving different types of text variables into the 
object data value.
  A range of different 'Append' methods for adding different types of text variables onto the 
end of any existing object data value
  A set of character level methods for testing the object data string.
  A set of methods associated with converting other numeric data types into strings, or vice-
versa
  A set of methods that mimic the functions found in the STRINGS unit
  A set of methods that mimic the text related functions found in the SysUtils unit.
  Methods for string resource and INI file access
  A set of methods for inserting, deleting, padding and trimming the object's data string.
  A set of methods to manage comparisons with another PChar variable.
  A set of methods to provide DOS/Path name related processing and testing.
  Methods for searching characters and sub strings
  Methods for changing case
  Methods for replacing characters or sub strings.
  Methods for parsing the object's data value

As a rule the object is designed to handle the problems of passing NIL or zero length PChar 
parameters. It can also manage the thorny old problem of passing parameters which are un-
initialised or remain in use after they have been disposed. These are captured by exception 
handling.

2. Working with TStringClass objects

To employ the TStringClass object in any of your units add the StrClass name to the list of 
units found in the USES clause. For example ....

unit Testbed;

interface

uses

   SysUtils,
   WinTypes,
   WinProcs,
   Messages,
   Classes,
   Graphics,
   Controls,
   Forms,
   Dialogs,
   StdCtrls,
   ExtCtrls,
   StrClass,
   ContainR;

Some of the TStringClass object methods use a container object to hold lists of strings. This 
container object is located within the ContainR.Pas  unit.  If you are empoying any of these 
container related functions make sure the ContainR unit is included in the USES list as shown 
above.
3. Character Positions

The TStringClass object is based around a core PChar object data member. Like a PChar 
variable all character position referencing is normally zero (0) based.  In that the first character 
in a PChar string is at position 0, as shown below  ...

	VAR
		APChar : Pchar;
		AStr : STRING;
		FirstCharacter : CHAR;
		SObj : TStringClass;
	BEGIN
		....
		....
		GetMem(APChar,200);
		StrCopy(APChar,Spring);
		AStr := String;
		FirstCharacter :=  APChar[0];
		FirstCharacter := AStr[1];
		SObj := TStringClass.Create;
		SObj.Assign([AStr]);
		FirstCharacter := SObj.Ch[0];
		.
		.

As a favour to those hard-core STRING users who are unable or unwilling to remember that 
PChar positioning is zero based, the StrClass library includes a new optional facility that allows 
all character position referencing to be one (1) based.  The boolean typed constant 
StrClassBaseZero  is by default to TRUE. If this constant is reset to FALSE then the first 
character position is treated as 1 not 0.

With StrClassBaseZero set to FALSE the following is correct  ..

	VAR
		APChar : Pchar;
		AStr : STRING;
		FirstCharacter : CHAR;
		SObj : TStringClass;
	BEGIN
		....
		....
		StrClassBaseZero := FALSE;
		....
		....
		GetMem(APChar,200);
		StrCopy(APChar,Spring);
		AStr := String;
		FirstCharacter :=  APChar[0];
		FirstCharacter := AStr[1];
		SObj := TStringClass.Create;
		SObj.Assign([Astr]);
		FirstCharacter := SObj.Ch[1];
		.
		.
Note: this change to a base 1 first character affects all class methods that use or report a 
character position.

4. Parameters

With Object Pascal there are several different types of variables that can be used to store text 
strings, as shown below ....

	VAR

		MyArray :		ARRAY[0..200] OF CHAR;
		MyPChar :	PChar;
		MyStr :		STRING;

Rather than create a mass of different object methods to handle different parameter types, I 
decided to design TStringClass so that any type of parameter can be passed to the same 
function.

This is possible with the new DELPHI Object Pascal Open Array constructors facility. This 
allows a function or procedure to be created that accepts an open ended set of parameters of 
different variable types. (See Chapter 8 page 82 of the Language Guide).

Most of the TStringClass object methods that have text type input parameters use this type of 
parameter. For instance ....

	FUNCTION Assign(CONST Args : ARRAY OF CONST) : PChar;

The Assign method converts the Args collection of parameters to a string and then assigns 
that string to the object, replacing any existing string value.

One condition to using ARRAY OF CONST type parameters is that the entries must be 
enclosed within square brackets, as shown below ....

	VAR
		Sobj : TStringClass;
		L : LONGINT;
		AStr : STRING;
	BEGIN
		.....
		....
		L := 5;
		AStr  := I am ;
		SObj := TStringClass.Create;
		SObj.Assign([There are ,L, boats in the harbour]);
		SObj.Assign([AStr,L, years old]);
		.......
		.......

The TStringClass object will accept and process all standard variables types, it will even accept 
other TStringClass objects as items in the parameter list. 

	VAR
		Sobj,TObj : TStringClass;
		L : LONGINT;
		AStr : STRING;
	BEGIN
		.....
		....
		L := 5;
		AStr  := I am ;
		SObj := TStringClass.Create;
		TObj := TStringClass.CreateString([its my birthday]);
		SObj.Assign([AStr,L, years old and ,TObj]);
		.......
		.......

With Version 2 of TStringClass, the Args parameter list can now include text related VCL 
components, such as memo and edit box controls. For example :

	VAR
		Sobj : TStringClass;
		TheMemo : TMemo;
	BEGIN
		.....
		....
		TheMemo.Lines.Add(This is the 1st line);
		TheMemo.Lines.Add(This is the 2ndt line);
		SObj := TStringClass.Create;
		SObj.Assign([TheMemo]);
		.......
		.......

Where an ARRAY OF CONST type parameter is passed to a TStringClass object they will be 
processed in a left to right order. For a function like Assign, the sum of all parts within the 
ARRAY OF CONST will be converted to a string - in a left to right order - and the resulting 
string will be assigned to the objects own text variable.

To help identification all ARRAY OF CONST type parameters have an Args part to their 
name.

Where an objects method returns strings or part strings as results, the function requires another 
instantiated TStringClass object as the target for that assignment.

Some of the parsing related functions use a container object to store lists of parsed sub strings. 
In such cases the function uses a TObjectContainer object as the storage container. Refer to 
chapter 9 for more information of the container object hierarchy.

Certain of TStringClasss methods make use of a container method to hold the results of a 
parsing or string extracting process. For example the parsing function ParseDelimToList  will 
chop a delimited text into its parts and place each part into a string object which inturn is added 
to the parameter list object.  For example .

	AList := TObjectContainer.Create;
      	AList.Capacity := 100;
      	TObj := TStringClass.CreateString(['xxx,yyy,zzzz,wwww,,qqqq,rrrr']);
      	TObj.ParseDelimToList(',',delim_None,AList);

The AList parameter is a container object. It is an instance of the TObjectContainer open 
array type container provided within this library. 

With the example above AList now holds a list of 6 items - each of which is an instance of 
TStringClass. To gain access to one of these string parts use the object containers Items 
property, for example   ..

	AStrObj := TStringClass(AList.Items[0]);   { first string part - xxx }
	AStrObj := TStringClass(AList.Items[AList.Count-1]);   { last string part - rrrr }

5. Working with VCL text components

The TStringClass library now includes functions for moving data in and out of VCL text related 
controls. These functions are useful for situations where a control contains multi-line strings that 
exceed the 255 character limit.

Any method that includes an Args ARRAY OF CONST type parameter can now include one or 
more VCL components in its list. 

The TStringClass object will process any VCL component that drives from the parent class 
TWinControl. This includes the TEdit and TMemo controls. In all cases it is using the 
GetTextBuf and SetTextBuf VCL methods to move text in and out of a control. 

There are also separate methods for working with VCL components. 

The FromComponent method will extract the text from a single designated component control 
and assign it to the string classs own text buffer.

The ToComponent moves a text string from the string class into the VCL components own 
text buffer. 

The FromComponentItem method extracts part of the components own string list and assigns 
it to the string class buffer. This method has a second Idx INTEGER parameter that is used to 
determine which part. For list boxes and combo boxes this is equivalent to the list item number. 
For Memo controls it is equivalent to the text line number.  Note: if the typed constant 
StrClassBaseZero is set to FALSE then the first character position starts from one (1) not zero 
(0).

For memo controls only, if the Idx parameter is set to the constant selected_text then the 
method extracts the highlighted text.

6. Pushing data directly into the class text buffer

Strange thought his might seem there are situations where you might want to push data directly 
into the objects text buffer. 

Although such actions are very un-OOP there can often occur. Typically they arise where a low 
level function requires a PChar type parameter. In such a situation you would normally have to 
cope as follows .

	VAR
		AStr : PChar;
		SObj : TStringClass;
	BEGIN
		..
		..
		GetMem(AStr,1000);
		SObj := TStringClass.Create;
		SomeLowLevelFunction(AStr,1000);
		SObj.Assign([AStr]);
		FreeMem(AStr,1000);
		..
		..
	END

Having to create and dispose of the AStr local variable is a pain.  By contrast TStringClass 
offers a method of pushing data directly into its buffer, as shown below:

	VAR
		AStr : PChar;
		SObj : TStringClass;
	BEGIN
		..
		..
		SObj := TStringClass.CreateSize(1000);
		SomeLowLevelFunction(SObj.ZString,1000);
		Sobj.RecalcLength;
		FreeMem(AStr,1000);
		..
		..
	END

Fundamental to this approach is the use of the RecalcLength method. This is used to re-
calibrate the objects own internal data members.

This approach of pushing data indirectly into the objects text buffer is a short cut which ICFM 
Software cannot wholeheartedly recommend. However, not wishing to straight jacket our users 
it is issue which we felt was worth documenting.

7. Using the Global string class variable gSc

Another tiresome issue underlying the use of objects is the need to create or instantiate 
objects prior to their use. For purists this gives any code a measure of self containment which 
ensures its own security. However, on a more practical level having to include 

	VAR
		SObj : TStringClass;
	BEGIN
		..
		..
		SObj := TStringClass.Create
		..
		..

. requires a lot more typing, and also requires that the SObj be disposed of at the end of the 
process.

As a convenience for more pragmatic users of objects the StrClass unit includes a global 
variable gSc (Global String Class) as an already instantiated string class variable.

This variable can be used a convenient vehicle for string class functions at any time. However, 
do not dispose of this variable. This is taken care of by the unit itself.

8. ExceptionHandling

The TStringClass object makes extensive use of exception handling.  It has it own 
EStringClass exception class. 

	EStringClass = class(Exception);

In reporting an exception error the TStringClass object will raise an exception with a description 
that includes the class name, function name and cause.

As some TStringClass object methods are called by other methods, the process of raising 
exceptions may actually cause several such messages to appear.

To minimise the space consumed by text error descriptions, all TStringClass exception 
reporting strings are held as a custom resource in the StrClass.Res file. (Not a string table, a 
custom resource!)
9. Limitations

The string class will only manage strings of up to 64K in size. If an objects string exceeds this 
size an exception error is raised. The container objects used within the parsing functions are 
limited to having no more than 2 billion items on a list.
10. Bug fixes, Ideas etc

If you detect any bugs or would like to suggest ideas for improvements then please email them 
to my Compuserve account [100010,1415].

11. Copyright Notice

No liability can be accepted for use of this source code.

This source code remains the copyright of ICFM Software. You may use it in your own 
applications, but cannot employ it as part of another software library without the express 
permission of ICFM Software.


12. TStringClass - Object Definition
12.1 Data Members

All the object's data members are deliberately set as 'PRIVATE' to ensure that the object's 
buffer management is left to internal procedures. (Note: all object data members start with the 
prefix 'F'. It is usually the case that all local variables and parameters start with a prefix of 'A').

FBuffer : PChar;
This holds the object's PChar data value.

FMaxSize : WORD;
This stores the size of the 'FBuffer' PChar variable memory buffer.

FLength  : WORD;
This holds the length of the 'FBuffer' data member - excluding the null terminator. Thus a 
'FBuffer' value of 'CAT' would equate to a 'TheLength' value of 3.

FSizeInc : WORD;
This variable can be used to control by how much the internal memory buffer is increased. It 
can be set via the 'SizeInc' property.
12.2 Private Methods

Most of the private methods are concerned with maintaining the PChar string buffer, or 
converting other data types into PChar types. They are listed here for completeness:

         FUNCTION AssignFromPChar(Source : PChar; Start : WORD) : PChar;
         FUNCTION AssignMidPChar(Source : PChar; Start,Count : WORD) : PChar;
         FUNCTION AssignLenPChar(Source : PChar; Len : WORD) : PChar;
         FUNCTION AssignNLPChar(Source : PChar) : PChar;
         FUNCTION AssignPadPChar(Source : PChar; Len : WORD; ACh : CHAR) : PChar;
         FUNCTION AssignPChar(Source : PChar) : PChar;
         FUNCTION AssignRightPChar(Source : PChar; Len : WORD) : PChar;
         FUNCTION AssignString(CONST Source : STRING) : PChar;
         FUNCTION AppendLenPChar(Source : PChar; Len : WORD) : PChar;
         FUNCTION AppendMidPChar(Source : PChar; Start,Count : WORD) : PChar;
         FUNCTION AppendNLPChar(Source : PChar) : PChar;
         FUNCTION AppendPadPChar(Source : PChar; Len : WORD; ACh : CHAR) : PChar;
         FUNCTION AppendPChar(Source : PChar) : PChar;
         FUNCTION AppendRightPChar(Source : PChar; Len : WORD) : PChar;
         FUNCTION AppendString(Source : STRING) : PChar;
         FUNCTION AppendTClass(T : TClass) : PChar;
         FUNCTION AppendTObject(T : TObject) : PChar;
         FUNCTION AppendTrimPChar(Source : PChar) : PChar;
         FUNCTION AppendWithTabPChar(Source : PChar) : PChar;
         FUNCTION PrependPChar(Source : PChar) : PChar;
         FUNCTION ComparePChar(Other : PChar) : INTEGER;
         FUNCTION CompareIPChar(Other : PChar) : INTEGER;
         FUNCTION CompareLPChar(Other : PChar; Len : WORD) : INTEGER;
         FUNCTION CompareLIPChar(Other : PChar; Len : WORD) : INTEGER;
         FUNCTION InsertPChar(Source : PChar; Index : WORD) : PChar;
         FUNCTION CanCat(Source : PChar; VAR Extra : WORD) : BOOLEAN;
         FUNCTION CanCopy(Source : PChar; VAR Extra : WORD) : BOOLEAN;
         FUNCTION ChkSizeInc(E : WORD) : WORD;
         FUNCTION CompConv(I : INTEGER) : INTEGER;
         PROCEDURE DisposeStr;
         FUNCTION ExpandBy(ExtraLen : WORD) : BOOLEAN;
         FUNCTION GetCh(w : WORD) : CHAR;
         FUNCTION GetLength : WORD;
         FUNCTION GetMaxSize : WORD;
         FUNCTION GetPChar : PChar;
         FUNCTION GetSizeInc : WORD;
         FUNCTION GetString : STRING;
         PROCEDURE SetBufferLen(NewLen : WORD);
         PROCEDURE SetSizeInc(ASize : WORD);
12.3 Protected Methods
The object includes a number of protected methods. All the DoXXXXX type methods are those 
that relate to processing strings based upon a character position.  These have been introduced 
to allow for the safe processing of the StrClassBaseZero related optional first character facility. 
Each of these DoXXXX methods work using a base character position of zero (0). If you intend 
creating your own objects derived from TStringClass and having your own new methods that 
involve character position related processing, then to ensure correct processing use the 
DoXXX method and set all calculations around a base zero first character.

Similarly, the InitDataMembers  function has been made virtual and moved to the protected 
section to allow for the initialisation of new data fields defined in descendant objects.

The AppendTObject method has been virtual to allow for situations where a developer wants 
to allow the passing of the text associated with custom VCL classes into the string class object.

         FUNCTION AppendTObject(T : TObject) : PChar; VIRTUAL;
         PROCEDURE InitDataMembers; VIRTUAL;
         FUNCTION DoAssignFrom(CONST Args : ARRAY OF CONST; Start : WORD) : PChar;
         FUNCTION DoAssignMid(CONST Args : ARRAY OF CONST; 
                                                  Start,Count : WORD) : PChar;
         FUNCTION DoAppendMid(CONST Args : ARRAY OF CONST; 
                                                    Start,Count : WORD) : PChar;
         FUNCTION DoFirstNonSpaceCh(VAR ACh : CHAR) : WORD;
         FUNCTION DoHasCh(ACh : CHAR; VAR Pos : WORD) : BOOLEAN;
         FUNCTION DoIsCh(W : WORD; ACh : CHAR) : BOOLEAN;
         FUNCTION DoLastNonSpaceCh(VAR ACh : CHAR) : WORD;
         PROCEDURE DoSetCh(W : WORD; ACh : CHAR);
         FUNCTION DoDelete(Index,Count : WORD) : PChar;
         FUNCTION DoDeleteFrom(Index : WORD) : PChar;
         FUNCTION DoInsert(CONST Args : ARRAY OF CONST; Index : WORD) : PChar;
         FUNCTION DoInsertL(CONST Args : ARRAY OF CONST; Len,Index : WORD) : PChar;
         FUNCTION DoFindBetween2Ch(FirstCh,
                                                             SecondCh        : CHAR;
                                                             StartFrom       : WORD;
                                                             VAR SubStrStart : WORD;
                                                             VAR SubStrLen   : WORD;
                                                             CutSubStr,
                                                             IncDelims       : BOOLEAN;
                                                             VAR ASubStr     : TStringClass) : BOOLEAN;
         FUNCTION DoFindFirst(CONST SubArgs : ARRAY OF CONST; 
                                                VAR P : WORD) : BOOLEAN;
         FUNCTION DoFindFirstCh(ACh : CHAR; VAR P : WORD) : BOOLEAN;
         FUNCTION DoFindLast(CONST SubArgs : ARRAY OF CONST; 
                                                VAR P : WORD) : BOOLEAN;
         FUNCTION DoFindLastCh(ACh : CHAR; VAR P : WORD) : BOOLEAN;
         FUNCTION DoFindNext(CONST SubArgs : ARRAY OF CONST;
                                                StartPos : WORD;
                                                VAR NextPos : WORD) : BOOLEAN;
         FUNCTION DoFindNextCh(ACh : CHAR; StartPos : WORD; 
                                                    VAR NextPos : WORD) : BOOLEAN;
         FUNCTION DoFindPrev(CONST SubArgs : ARRAY OF CONST;
                                                StartPos : WORD; VAR PrevPos : WORD) : BOOLEAN;
         FUNCTION DoFindPrevCh(ACh : CHAR; StartPos : WORD; 
                                                    VAR PrevPos : WORD) : BOOLEAN;
         FUNCTION DoFirstParseDelim(CONST Args : ARRAY OF CONST;
                                                           DelimCh      : CHAR;
                                                           VAR DelimPos : WORD) : BOOLEAN;
         FUNCTION DoNextParseDelim(CONST Args : ARRAY OF CONST;
                                                            DelimCh          : CHAR;
                                                            StartPos         : WORD;
                                                            VAR NextDelimPos : WORD) : BOOLEAN;
12.4 Properties
All but one of the properties are read only types.

PROPERTY Ch[w : WORD] : CHAR READ GetCh;
Returns the CHAR type at position w within the objects text string. (Remember w should be 
calculated from base 0. e.g. the 2nd character would be position 1). If the w value exceeds the 
length of the object text string an exception error is raised.
Note: If the typed constant StrClassBaseZero is set to FALSE then character position starts 
from one (1) not zero (0).

PROPERTY Length : WORD READ GetLength;
Returns the current object text string length (excluding the null terminator). Thus, a string of 
ABC would have a length of 3. 

PROPERTY MaxSize : WORD READ GetMaxSize;
Returns the current buffer size. This may be larger than the object text string length.

PROPERTY SizeInc : WORD READ GetSizeInc WRITE SetSizeInc;
Used to set (or read) the minimum amount in bytes by which the buffer size will increase the 
next time it is required to expand. If a string object anticipates receiving multiple appends  
then it is worth using the SizeInc property to set a large incremental jump in the internal buffer 
size.

PROPERTY Text : STRING READ GetString;
Returns the object text string as a STRING type variable. If the object text string variable length 
exceeds 255 characters then an exception error is raised.

PROPERTY ZString : PChar READ GetPChar;
Returns a PChar type to the objects own text string buffer.

12.5 Public Methods
12.5.1 Constructors/Destructors
CONSTRUCTOR Create;
Instantiates the object with a NIL default PChar value and zero length internal buffer. Example :
	AStrObj := TStringClass.Create;

CONSTRUCTOR CreateSize(ASize: WORD);
Instantiates the object with a NIL PChar value and an initial internal buffer size of 'ASize'. This 
constructor is useful for situations where lots of individual appends are anticipated, thus 
avoiding lots of individual buffer re-sizing.
Example :
	AStrObj := TStringClass.CreateSize(2000);

CONSTRUCTOR CreateString(CONST Args : ARRAY OF CONST);
Instantiates the object with a starting PChar value equivalent to the Args parameters. The Args 
array can include any mix of standard variable types including TStringClass and VCL text 
related objects.
Example:

	VAR
		AString : STRING
		APChar : Pchar;
		L           : LONGINT;
		AStrObj : TStringClass;
	BEGIN
		.....
		AString := There are ;
		L := 5;
		GetMem(APChar,256);
		StrCopy(APChar, shopping months to Christmas);
		AStrObj := TStringClass.CreateString([AString,L,APChar]);  
		......

CONSTRUCTOR CreateNL(CONST Args : ARRAY OF CONST);
Instantiates the object with a starting string value (as with CreateString), and appends a new 
line instruction (#13#10) to the end of the PChar data member.

CONSTRUCTOR CreateBoolean(B : BOOLEAN; StrType : INTEGER);
Instantiates the object with a starting PChar value converted from a BOOLEAN parameter.  
The 'StrType' parameter determines the type of string conversion, where

		StrType constant	String conversion(TRUE/FALSE)

		bt_NoYes   			No / Yes
		bt_01        			0  /  1
		bt_FalseTrue 			False / True
		bt_FT       			F / T
		bt_NY        			N / Y
		bt_OffOn     			Off / On

If the 'StrType' is not one of the constant values shown above then no conversion or 
assignment is made.

DESTRUCTOR Destroy;
This disposes of all data members and destroys the object. (Do not call this directly. Use the 
Free method to dispose of a object)

	VAR
		AStrObj : TStringClass;
	BEGIN
		.....
		AStrObj := TStringClass.Create;
		.....
		.....
		AStrObj.Free;  

12.5.2 Copy related
Two functions for copying a string objects attributes.

FUNCTION Copy : POINTER; VIRTUAL;
This function instantiates and returns a copy of itself.

PROCEDURE CopyFrom(Source : TStringClass);
Copies the attributes and text string buffer of the parameter object Source.
12.5.3 Clear type functions
PROCEDURE Clear;
Disposes of any object string, clears the internal buffer length to NIL and all other object 
attributes to 0.

PROCEDURE Empty
Clears the internal text string to #0, but leaves the buffer size intact.

12.5.4 Admin type functions
PROCEDURE RecalcLength;
This method re-calculates the length of the text string found in the FBuffer  and assigns the 
result to the FLength private variable. This method only ever need be called if a process 
pushes data directly into the objects text buffer.
12.5.5 Assign related functions
Assign related functions replace the objects existing text string value with the values passed 
within the function parameters.

FUNCTION Assign(CONST Args : ARRAY OF CONST) : Pchar;
Copies the Args list of parameters into the object, replacing any existing object string value.  If 
Args contains more than one element, then the first entry is assigned to the object, and all 
subsequent elements are appended.  If all elements represent NIL or blank text parameters 
then NIL is assigned to the object text string.
Example:
	VAR
		AString  : STRING;
		Sobj : TStringClass;
	BEGIN
		....
		....
		AString := Now is the winter of our discontent
		Sobj := TStringClass.Create; 
		SObj.Assign([AString]);    { Now is the winter of our discontent }

FUNCTION AssignFrom(CONST Args : ARRAY OF CONST; Start : WORD) : Pchar;
Converts the Args parameter list into a text string and then assigns part of the string starting 
from position Start (base 0) to the object text buffer.
Example:
	VAR
		AString  : STRING;
		Sobj : TStringClass;
	BEGIN
		....
		....
		AString := Now is the winter of our discontent
		Sobj := TStringClass.Create; 
		SObj.AssignFrom([AString],7);    { the winter of our discontent }

If the Args generates a NIL string, or the Start parameter is greater than or equal to the Args 
string length then a NIL string value is assigned to the object text buffer.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).
		
FUNCTION AssignLen(CONST Args : ARRAY OF CONST; Len : WORD) : Pchar;
Converts the Args parameter list into a text string and then assigns the first part of the 
parameter string up to Len characters to the object text buffer.
Example:
	VAR
		AString  : STRING;
		Sobj : TStringClass;
	BEGIN
		....
		....
		AString := Now is the winter of our discontent
		Sobj := TStringClass.Create; 
		SObj.AssignLen([AString],6);    { Now is }

If Len exceeds the Arg text string length then the whole Args string is assigned to the object 
text buffer.

FUNCTION AssignMid(CONST Args : ARRAY OF CONST; Start,Count : WORD) : Pchar;
Converts the Args parameter list into a text string and then assigns part of the parameter string 
from Start (base 0) for Count characters to the object text buffer.
Example:
	VAR
		AString  : STRING;
		Sobj : TStringClass;
	BEGIN
		....
		....
		AString := Now is the winter of our discontent
		Sobj := TStringClass.Create; 
		SObj.AssignMid([AString],7,3);    { the }

If Start exceeds the parameter string length or the parameter string is Nil then a NIL string is 
assigned to the object. 
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION AssignNL(CONST Args : ARRAY OF CONST) : PChar;
As with Assign this converts the Args parameter to a text string and assigns it to the object 
text buffer. In addition this function appends a New Line character combination (#13#10) to the 
end of the object string.

FUNCTION AssignPad(CONST Args : ARRAY OF CONST; 
                                      Len : WORD; ACh : CHAR) : PChar;
As with Assign this converts the Args parameter to a text string and assigns it to the object 
text buffer. If the resultant text string is less than Len characters long, the object string is right 
padded with multiple ACh characters to bring it up to the length ALen.
Example:
	VAR
		AString  : STRING;
		Sobj : TStringClass;
	BEGIN
		....
		....
		AString := Now is
		Sobj := TStringClass.Create; 
		SObj.AssignPad([AString],8,X);    { Now isXX }

FUNCTION AssignRight(CONST Args : ARRAY OF CONST; Len : WORD) : PChar;
Converts the Args parameter list into a text string and then assigns the rightmost Len 
characters to the object text buffer.
Example:
	VAR
		AString  : STRING;
		Sobj : TStringClass;
	BEGIN
		....
		....
		AString := Now is the winter of our discontent
		Sobj := TStringClass.Create; 
		SObj.AssignRight([AString],14);    { our discontent }

FUNCTION AssignTrim(CONST Args : ARRAY OF CONST) : PChar;
As with Assign this converts the Args parameter to a text string and assigns it to the object 
text buffer. The resultant text string is then trimmed to remove all leading and trailing space 
characters.
12.5.6 Append related functions	
A set of functions for appending other text strings to the end or front of the objects own text 
string.

FUNCTION Append(CONST Args : ARRAY OF CONST) : Pchar;
Appends the string represented by Args to the end of the objects own text string.

FUNCTION AppendBoolean(B : BOOLEAN; bt : INTEGER) : Pchar;
Converts the boolean value 'B' to a string of type 'bt' and then appends that string to the end of 
the objects existing text string. The parameter 'bt' can be any of the following values.

		'bt' constant			String conversion(FALSE/TRUE)

		bt_NoYes   			No / Yes 
		bt_01        			0  /  1
		bt_FalseTrue 			False / True
		bt_FT       			F / T
		bt_NY        			N / Y
		bt_OffOn     			Off / On

If the 'bt' is not one of the constant values shown above then no conversion or append is made.

FUNCTION AppendByte(B : BYTE) : Pchar;
Converts the BYTE parameter B to a string and appends that string to the end of the objects 
existing text string value.

FUNCTION AppendCh(C : CHAR) : PChar;
Appends the CHAR C to the end of the objects existing text string value.

FUNCTION AppendDIC(CONST Args : ARRAY OF CONST) : Pchar;
The Args parameter is converted to a string. That string is then enclosed by double inverted 
comma characters (), and the enclosed string is then appended to the end of the objects own 
text string.

FUNCTION AppendDouble(D : DOUBLE; Width,Places : BYTE) : Pchar;
Converts the DOUBLE parameter D to a right justified string of Width characters and Places 
decimal precision. The resulting string is then appended that string to the end of the objects 
existing text string value.

FUNCTION AppendDoubleTrim(D : DOUBLE) : Pchar;
Converts the DOUBLE parameter D to a decimal string with all leading spaces and trailing 
zeros removed. The resulting string is then appended to the end of the objects existing text 
string value.

FUNCTION AppendExt(E : EXTENDED; Width,Places : BYTE) : PChar;
Converts the EXTENDED parameter E to a right justified string of Width characters and 
Places decimal precision. The resulting string is then appended to the end of the objects 
existing text string value.

FUNCTION AppendExtTrim(E : EXTENDED) : Pchar;
Converts the EXTENDED parameter E to a decimal string with all leading spaces and trailing 
zeros removed. The resulting string is then appended to the end of the objects existing text 
string value.

FUNCTION AppendLen(CONST Args : ARRAY OF CONST; Len : WORD) : Pchar;
The Args parameter is converted to a string and the first Len characters are appended to the 
end of the objects existing text string.

FUNCTION AppendLong(L : LONGINT) : Pchar;
Converts the LONG parameter L to string and appends it to the end of the objects existing text 
string value.

FUNCTION AppendMid(CONST Args : ARRAY OF CONST; Start,Count : WORD) : Pchar;
The Args parameter is converted to a string, and starting from the Start character (base 0), 
Count characters of the Args string are appended to the end of the objects existing text 
string.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION AppendNL(CONST Args : ARRAY OF CONST) : Pchar;
Appends the string represented by Args to the end of the objects own text string and then 
appends a further NewLine character combination (#13#10) to the end of the object text string.

FUNCTION AppendPad(CONST Args : ARRAY OF CONST; 
                                       Len : WORD; 
                                       ACh : CHAR) : Pchar;
The Args parameter is converted to a string, and appended to the end of the objects existing 
text string. If the resulting object string is less than Len characters long, then multiple ACh 
characters are appended to the end of the object text string to create a string of length Len.

FUNCTION AppendPtr(P : POINTER) : Pchar;
Converts the POINTER parameter P to a hexidecimal string format and appends it to the end 
of the objects existing text string value.

FUNCTION AppendReal(R : REAL; Width,Places : BYTE) : PChar;
Converts the REAL parameter R to a right justified string of Width characters and Places 
decimal precision. The resulting string is then appended to the end of the objects existing text 
string value.

FUNCTION AppendRight(CONST Args : ARRAY OF CONST; Len : WORD) : Pchar;
The Args parameter is converted to a string and the right most Len characters are appended 
to the end of the objects existing text string.

FUNCTION AppendSIC(CONST Args : ARRAY OF CONST) : Pchar;
The Args parameter is converted to a string. That string is then enclosed by single inverted 
comma characters (), and the enclosed string is then appended to the end of the objects own 
text string.

FUNCTION AppendTrim(CONST Args : ARRAY OF CONST) : Pchar;
The Args parameter is converted to a string, trimmed of all leading and trailing spaces and 
then appended to the end of the objects existing text string.

FUNCTION AppendWithTab(CONST Args : ARRAY OF CONST) : PChar;
The Args parameter is converted to a string and appended to the end of the objects own text 
string. A tab character (#9) is then appended to the end of the object text string.

FUNCTION NL : PChar;
Appends a NewLine character combination to the end of the object text string.

FUNCTION NLAppend(CONST Args : ARRAY OF CONST) : Pchar;
Appends a NewLine character combination to the object text string BEFORE appending the 
Args string to the end of the object text string.

FUNCTION Prepend(CONST Args : ARRAY OF CONST) : Pchar;
The Args parameter is converted to a string, and then inserted in front of any existing object 
text string.
12.5.7 Character element related functions
FUNCTION FirstNonSpaceCh(VAR Ch : CHAR) : WORD;
Returns the position (base 0) of the first non space character in the string. It also sets the 'Ch' 
parameter with the CHAR value at that location. If no non-space characters are found or the 
string is NIL the function returns a 'WORDRESERROR' result (equivalent to $FFFF).
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION HasCh(Ch : CHAR; VAR Pos : WORD) : BOOLEAN;
Returns TRUE is the object's string includes the 'Ch' character. It returns the position of the 
instance of that character in variable 'Pos' (base 0).
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION IsCh(W : WORD; Ch : CHAR) : BOOLEAN;
Returns TRUE if the character in the object's string at position 'W' (base 0) is 'Ch'. The function 
returns FALSE if the string is NIL or 'W' exceeds the string length.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION IsFirstCh(Ch : CHAR) : BOOLEAN;
Returns TRUE if the first character in the object's string is 'Ch'. The function returns FALSE if 
the string is NIL.

FUNCTION IsLastCh(Ch : CHAR) : BOOLEAN;
Returns TRUE if the last character in the object's string is 'Ch'. The function returns FALSE if 
the string is NIL.

FUNCTION LastNonSpaceCh(VAR Ch : CHAR) : WORD;
Starting from the end of the object's string, this function returns the position (base 0) of the 
lright-most non space character in the string. It also sets the 'Ch' parameter with the CHAR 
value at that location. If no non-space characters are found or the string is NIL the function 
returns a 'WORDRESERROR' result (equivalent to $FFFF).
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

PROCEDURE RemoveLastCh;
This will remove the last character from the object string.

PROCEDURE SetCh(W : WORD; Ch : CHAR);
This will set the character at position 'W' (base 0) to 'Ch'.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).
12.5.8 Other data type related functions
This set of functions provides a means of assigning or appending number type variables into 
the object string. In most cases the functions return a PChar pointer to the object's own string.

The FromXXXX functions are provided for convenience, but the same result can be achieved 
in most cases by using the Assign function with the required parameter type.

FUNCTION FromBoolean(B : BOOLEAN; bt : INTEGER) : PChar;
Converts the boolean value 'B' to a string of type 'bt' and then assigns that value to the object 
string. The parameter 'bt' can be any of the following values.

		'bt' constant			String conversion(FALSE/TRUE)

		bt_NoYes   			No / Yes 
		bt_01        			0  /  1
		bt_FalseTrue 			False / True
		bt_FT       			F / T
		bt_NY        			N / Y
		bt_OffOn     			Off / On

If the 'bt' is not one of the constant values shown above then no conversion or assignment is 
made.

FUNCTION FromByte(B : BYTE) : PChar;
Converts the byte number 'B' to a string and assigns that string to the object string.

FUNCTION FromChar(C : CHAR) : PChar;
Converts the CHAR 'Ch' to a string and assigns this to the object string.

FUNCTION FromComponent(AComp : TWinControl) : PChar;
Assigns to the objects own text buffer the text string associated with VCL component.  This 
function will accept any VCL object that derives from TWinControl and responds to the 
GetTextBuf method. 

FUNCTION FromComponentItem(AComp : TWinControl; Idx : INTEGER) : PChar;
Assigns to the objects own text buffer a text string taken from a line or item of the VCL 
component. For list boxes and combo boxes the Idx parameter is equivalent to the item 
number. For memo controls it is equivalent to the line number. 

Two special cases arise for the Idx parameter. 

	All_Items     = -1;
	Selected_text = -2;

Use of the All_Items parameter is equivalent to calling FromComponent where the whole 
component text string is retrieved. Use of the selected_text parameter only retrieves 
highlighted/selected text.

FUNCTION FromDouble(D : DOUBLE; Width,Places : BYTE) : PChar;
Converts the double number 'D' to a string of the designated Width in characters and number 
of decimal places.

FUNCTION FromDoubleTrim(D : DOUBLE) : Pchar;
Converts the double number 'D' to a string with all leading white spaces and all trailing zeros 
removed.

FUNCTION FromExt(E : EXTENDED; Width,Places : BYTE) : PChar;
Converts the 'E' number to a string of the declared 'Width' and 'Places' decimal places, and 
then assigns that string to object string.

FUNCTION FromExtTrim(E : EXTENDED) : PChar;
Converts the extended number 'E' to a string with all leading white spaces and all trailing zeros 
removed.

FUNCTION FromLong(L : LONGINT) : PChar;
Converts the 'L' number to a string and assigns that string to the object string.

FUNCTION FromPtr(P : POINTER) : PChar;
Converts the pointer value 'P' to a string of type 'SEGMENT:OFFSET' and then assigns that 
string to the object.

FUNCTION FromReal(R : REAL; Width,Places : BYTE) : PChar;
Converts the 'R' number to a string of the declared 'Width' and 'Places' decimal places, and 
then assigns that string to the object string.

FUNCTION FromRealTrim(R : REAL) : PChar;
Converts the REAL number 'R' to a string with all leading white spaces and all trailing zeros 
removed.

FUNCTION FromRGB(C : TColorRef) : PChar;
Converts the RGB colour value into a comma delimited string of type 'RED,GREEN,BLUE', and 
then assigns that string to the object.(This is useful for writing values back to an INI file).

FUNCTION HexFromByte(B : BYTE) : PChar;
Converts the byte value 'B' into a hexidecimal string and assigns that string to the object.

FUNCTION HexFromLong(L : LONGINT) : PChar;
Converts the 'L' number into a hexidecimal string of type 'nnnn:nnnn' and assigns that string to 
the object.

FUNCTION HexFromPtr(P : POINTER) : PChar;
Converts the pointer 'P' into a hexidecimal string of type 'nnnn:nnnn' and assigns that string to 
the object.

FUNCTION HexFromWord(W : WORD) : PChar;
Converts the 'W' number into a hexidecimal string of type 'nnnn' and assigns that string to the 
object.

FUNCTION ToBoolean(VAR B : BOOLEAN) : BOOLEAN;
Returns TRUE if the object string can be converted into a BOOLEAN type. The variable 
parameter 'B' is set with the converted value. The conversion is tested against the range of 
boolean to string conversions permitted by the 'bt_xxx' constants.

FUNCTION ToByte(VAR B : BYTE) : BOOLEAN;
Returns TRUE if the object string can be converted into a BYTE number type. The variable 
parameter 'B' is set with the converted value.

FUNCTION ToChar(VAR C : CHAR) : BOOLEAN;
Returns TRUE if the string has at least one character, and assigns the first character of the 
string into the parameter 'C'.

FUNCTION ToComponent(AComp : TWinControl) : BOOLEAN;
This assigns the objects own text string to the VCL component. The process will return TRUE if 
the assignment is completed. This method will work with any descendant of the TWinControl 
class that implements a SetTextBuf method.

FUNCTION ToDouble(VAR D : DOUBLE) : BOOLEAN;
Returns TRUE if the object string can be converted into a DOUBLE number type. The variable 
parameter 'D' is set with the converted value.

FUNCTION ToExt(VAR E : EXTENDED) : BOOLEAN;
Returns TRUE if the object string can be converted into an EXTENDED number type. The 
variable parameter 'E' is set with the converted value.

FUNCTION ToInteger(VAR I : INTEGER) : BOOLEAN;
Returns TRUE if the object string can be converted into an INTEGER number type. The 
variable parameter 'I' is set with the converted value. If the object string includes a decimal 
place dot the conversion will fail.

FUNCTION ToLong(VAR L : LONGINT) : BOOLEAN;
Returns TRUE if the object string can be converted into an LONGINT number type. The 
variable parameter 'L' is set with the converted value. If the object string includes a decimal 
place dot the conversion will fail.

FUNCTION ToReal(VAR R : REAL) : BOOLEAN;
Returns TRUE if the object string can be converted into an REAL number type. The variable 
parameter 'R' is set with the converted value.

FUNCTION ToRGB(VAR C : TColorRef) : BOOLEAN;
Returns TRUE if the object string can be converted from a 'RED,GREEN,BLUE' delimited string 
type into a valid TColorRef value. This is useful for reading INI file values. (Refer to the 
'FromRGB' function).

FUNCTION ToWord(VAR W : WORD) : BOOLEAN;
Returns TRUE if the object string can be converted from a text string type into a valid WORD  
value. The variable parameter 'W' is set with the converted value.
12.5.9 SysUtils unit compatible functions
This section provides a set of object methods to mimic the string related functions found in the 
SysUtils unit. In most cases the function result or target string has been omitted from the list of 
functions parameters.

These methods are quite useful if you are looking to quickly amend existing code with 
TStringClass based equivalent functions.

The use of any function like IsValidIndent that presumes a STRING type parameter will create 
an exception error if the objects text string is greater than 255 characters long.

FUNCTION AppendStr(CONST S: string) : Pchar;
Appends the S string to the end of the objects own text buffer.

FUNCTION UpperCase(CONST S: string) : Pchar;
Converts the S parameter to upper case and assigns to the object text buffer, replacing any 
existing text string value.

FUNCTION LowerCase(const S: string): PChar;
Converts the S parameter to lower case and assigns to the object text buffer, replacing any 
existing text string value.

FUNCTION CompareStr(CONST S2: STRING): Integer;
A case sensitive comparison between the objects own text string and the parameter S2 string. 
This is equivalent to the Compare function.

FUNCTION CompareText(CONST S2: STRING): Integer;
A comparison between the objects own text string and the parameter S2 string, which ignores 
case. This is equivalent to the CompareI function.

FUNCTION AnsiUpperCase(CONST S : STRING) : Pchar;
AnsiUpperCase converts all characters in the given string S to upper case and assigns the 
result to the object text buffer. The conversion uses the currently installed language driver. 

FUNCTION AnsiLowerCase(CONST S : STRING) : PChar;
AnsiUpperCase converts all characters in the given string S to lower case and assigns the 
result to the object text buffer. The conversion uses the currently installed language driver. 

FUNCTION AnsiCompareStr(CONST S2: STRING): Integer;
AnsiCompareStr compares the objects own text string to S2, with case-sensitivity. The 
compare operation is controlled by the currently installed language driver. The return value is 
the same as for CompareStr.

FUNCTION AnsiCompareText(CONST S2: STRING): Integer;
AnsiCompareText compares the objects text string to S2, without case-sensitivity. The 
compare operation is controlled by the currently installed language driver. The return value is 
the same as for CompareText. 

FUNCTION IsValidIdent: Boolean;
IsValidIdent returns true if the object string is a valid identifier. An identifier is defined as a 
character from the set ['A'..'Z', 'a'..'z', '_'] followed by zero or more characters from the set 
['A'..'Z', 'a'..'z', '0..'9', '_'].

FUNCTION IntToStr(Value: Longint): Pchar;
Converts the LONGINT Value into a text string and assigns it to the object text buffer, 
replacing any existing text value.

FUNCTION IntToHex(Value: Longint; Digits: Integer): Pchar;
The IntToHex function converts a number into a string containing the number's hexadecimal 
(base 16) representation with a specific number of digits; and assigns the resultant string to the 
object text buffer.

FUNCTION StrToInt : Longint;
The StrToInt function converts the object text string representing an integer-type number in 
either decimal or hexadecimal notation into a number. If the string does not represent a valid 
number, StrToInt raises an EConvertError exception. Use of the alternative ToLong function is 
recommended.

FUNCTION StrToIntDef(Default: Longint): Longint;
The StrToIntDef function converts the object text string into a number. If S does not represent a 
valid number, StrToIntDef returns the number passed in Default.

FUNCTION LoadStr(Ident: Word): Pchar;
LoadStr loads the string resource given by Ident from the application's executable file into the 
objects tetx buffer. If the string resource does not exist, an empty string is returned. 

FUNCTION FmtLoadStr(Ident: Word; CONST Args: ARRAY OF CONST): Pchar;
FmtLoadStr loads a string from a program's resource string table and uses that sting, plus the 
args array, as a parameter to Format. Ident is the string resource ID of the desired format 
string.
Result is the output of Format. The resulting formatted text string is assigned to the object text 
buffer.

FUNCTION Format(CONST Format: STRING; CONST Args: ARRAY OF CONST): Pchar;
This function formats the series of arguments in the open array Args. Formatting is controlled 
by the Format parameter; the results are assigned to the objects text buffer.

FUNCTION FloatToStr(Value: Extended): Pchar;
FloatToStr converts the floating-point value given by Value to its string representation, and 
assigns that string to the object text buffer. The conversion uses general number format with 15 
significant digits.

FUNCTION FloatToStrF(Value: Extended; 
                                       Format: TFloatFormat; 
                                       Precision, Digits: Integer): Pchar;
FloatToStrF converts the floating-point value given by Value to its string representation, and 
assigns that string to the object buffer.

FUNCTION FormatFloat(const Format: STRING; Value: Extended): Pchar;
FormatFloat formats the floating-point value given by Value using the format string given by 
Format, and assigns the resulting string to the object text buffer.

FUNCTION StrToFloat : Extended;
StrToFloat converts the object text string to a floating-point value. The string must consist of an 
optional sign (+ or -), a string of digits with an optional decimal point, and an optional 'E' or 'e' 
followed by a signed integer. Leading and trailing blanks in the string are ignored. The 
DecimalSeparator global variable defines the character that must be used as a decimal point. 
Thousand separators and currency symbols are not allowed in the string. If the string doesn't 
contain a valid value, an EConvertError exception is raised. 
12.5.10 Strings unit compatible functions
This section provides a set of object methods to mimic the STRINGS unit functions. In most 
cases the 1st parameter of the equivalent STRINGS unit function has been omitted.  Unlike the 
STRINGS unit functions these methods include error and parameter value testing for NIL and 
zero length strings. In most cases these methods return a PChar pointer to the object's string.

These methods are quite useful if you are looking to quickly amend existing PChar orientated 
source code with TStringClass based equivalent functions.

FUNCTION StrCat(Source : PChar) : PChar;
Appends the string 'Source; to the end of the object's own string (equivalent to the 'Append' 
method).

FUNCTION StrComp(Str2 : PChar) : INTEGER;
Compares the object's string with another string 'Str2'. The comparison is case sensitive. 
(Equivalent to the 'Compare' method).

FUNCTION StrCopy(Source : PChar) : PChar;
Copies the 'Source' string into the object string (equivalent to the 'Assign' method).

FUNCTION StrECopy(Source : PChar) : PChar;
Copies the 'Source' string into the object string and returns a PChar pointer to the end of the 
resulting string.

FUNCTION StrEnd : PChar;
Returns a PChar pointer to the end of the object string (i.e. the \0 NULL terminator character 
position).

FUNCTION StrIComp(Str2 : PChar) : INTEGER;
Compares the object string with the parameter string 'Str2', ignoring any case differences. It 
returns a '-1', '0' or '1' result as defined in the 'Compare_xxx' constants. (Equivalent to the 
'CompareI' method).

FUNCTION StrLCat(Source : PChar; MaxLen : WORD) : PChar;
Appends the first 'Maxlen' characters of parameter 'Source' to the end of the object's own string 
(equivalent to the 'AppendLen' method).

FUNCTION StrLIComp(Str2 : PChar; MaxLen : WORD) : INTEGER;
Compares the first 'Maxlen' characters of the object string with the string 'Str2', ignoring case. 
The function returns one of the 'Compare_xxx' constants. (Equivalent to the 'CompareLI' 
method).

FUNCTION StrLComp(Str2 : PChar; MaxLen : WORD) : INTEGER;
Compares the first 'Maxlen' characters of the object string with the string 'Str2',  including case. 
The function returns one of the 'Compare_xxx' constants. (Equivalent to the 'CompareL' 
method).

FUNCTION StrLCopy(Str2 : PChar; MaxLen : WORD) : INTEGER;
Copies the first 'MaxLen' characters of 'Str2' into the object string (equivalent to the 'AssignLen' 
method).

FUNCTION StrLen : WORD;
Returns the length of the object string (equivalent to the 'GetLength' method).

FUNCTION StrLower : PChar;
Converts the object string to lower case (equivalent to the 'ToLower' method).

FUNCTION StrMove(Source : PChar; Count : WORD) : PChar;
Copies the first 'Count' characters of 'Source' into the string object.

FUNCTION StrPas : STRING;
Returns the object PChar as a Pascal STRING variable.

FUNCTION StrPCopy(Source : STRING) : PChar;
Copies a Pascal STRING type into the object PChar string.

FUNCTION StrPos(Str2 : PChar) : PChar;
Returns the PChar position of sub string 'Str2' within the object's own string. The function 
returns NIL if no substring is found. (refer to the 'FindFirst' method for similar functionality).

FUNCTION StrRScan(Chr : CHAR) : PChar;
Returns a PChar pointer to the right most location of the 'Chr' CHAR in the object string.

FUNCTION StrScan(Chr : CHAR) : PChar;
Returns a PChar pointer to the first location (from the left side) of the 'Chr' CHAR in the object 
string.

FUNCTION StrUpper : PChar;
Converts the object string to upper case (equivalent to the 'ToUpper' method).
12.5.11 Comparison related functions
A set of methods for comparing the object string with another string.  For functions that return 
INTEGER results the values are interpreted as:

	Result type						Result	Constant Id

	Object string less than other string		-1	Compare_LT
	Object string equal to other string		 0	Compare_EQ	
	Object string greater than other string	 1	Compare_GT

The StrClass.Pas unit includes three 'Compare_XX' constants that map to the -1/0/1 results to 
aide source code legibility.

FUNCTION Compare(CONST Args : ARRAY OF CONST) : INTEGER;
Compares the object string to the other string defined in Args and returns an integer 
comparison result of type 'Compare_xx'.  The test is case sensitive.

FUNCTION CompareI(CONST Args : ARRAY OF CONST) : INTEGER;
Compares the object string to the other string defined in Args and returns an integer 
comparison result of type 'Compare_xx'.  The test ignores case.

FUNCTION CompareL(CONST Args : ARRAY OF CONST; Len : WORD) : INTEGER;
Compares the first 'Len' characters of the object string with the same set of characters from the 
'Args'  string. The test is case sensitive.

FUNCTION CompareLI(CONST Args : ARRAY OF CONST; Len : WORD) : INTEGER;
Compares the first 'Len' characters of the object string with the same set of characters from the 
'Args'  string. The test ignores case.

FUNCTION CompareLong(L : LONGINT) : INTEGER;
The function attempts to convert the object string to a LONGINT number type and then 
compares the converted number to the 'L' number, returning one of the 'Compare_xx'  type 
results. If the string cannot be converted to a LONGINT the function returns a 'Compare_LT' 
result.

FUNCTION CompareDouble(D : DOUBLE) : INTEGER;
The function attempts to convert the object string to a DOUBLE number type and then 
compares the converted number to the 'D' number, returning one of the 'Compare_xx'  type 
results. If the string cannot be converted to a double the function returns a 'Compare_LT' result.

FUNCTION CompareExt(E : EXTENDED) : INTEGER;
The function attempts to convert the object string to a EXTENDED number type and then 
compares the converted number to the 'E' number, returning one of the 'Compare_xx'  type 
results. If the string cannot be converted to a double the function returns a 'Compare_LT' result.

FUNCTION IsSame(CONST Args : ARRAY OF CONST) : BOOLEAN;
Returns TRUE if the object string is the same as the 'Args' string. The test is case sensitive. 
This is equivalent to the command:

	IsSame := (Compare(Other) = Compare_EQ);

FUNCTION IsSameI(Other : PChar) : BOOLEAN;
Returns TRUE if the object string is the same as the 'Args' string. The test ignores case. This is 
equivalent to the command:

	IsSameI := (CompareI(Other) = Compare_EQ);

FUNCTION IsSameL(CONST Args : ARRAY OF CONST; Len : WORD) : BOOLEAN;
Returns TRUE if the first 'Len' characters of the object string are the same as the 'Args' string. 
The test is case sensitive. This is equivalent to the command:

	IsSameL := (CompareL(Other,Len) = Compare_EQ);

FUNCTION IsSameLI(CONST Args : ARRAY OF CONST; Len : WORD) : BOOLEAN;
Returns TRUE if the first 'Len' characters of the object string are the same as the 'Args' string. 
The test ignores case. This is equivalent to the command:

	IsSameLI := (CompareLI(Other,Len) = Compare_EQ);

FUNCTION Includes(CONST Args : ARRAY OF CONST) : BOOLEAN;
Returns TRUE if the Args text string is to be found within the objects own text string. The 
comparison is case sensitive.

FUNCTION Within(CONST Args : ARRAY OF CONST) : BOOLEAN;
Returns TRUE if the objects own text string is found within the Args text string. The 
comparison is case sensitive.
12.5.12 Insert/Delete/Trim related functions
Most of these functions return a PChar pointer to the object's own string.

FUNCTION AddDIC : PChar;
Inserts a double inverted comma () character at the start and end of the object string. The 
insert at either end  is only made where the character is not already there.

FUNCTION AddDIC : PChar;
Inserts a single inverted comma () character at the start and end of the object string. The insert 
at either end  is only made where the character is not already there.

FUNCTION Delete(Index,Count : WORD) : PChar;
Deletes from the object string characters starting from position 'Index' (base 0) for 'Count' 
number of characters. Example:

			Str1.Assign('This is a test')
			Str1.Delete(5,5);
			Writeln(Str1.ZString);	{This test}

Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION DeleteFrom(Index : WORD) : PChar;
Deletes from the object string all characters starting from position 'Index' (base 0) for. Example:

			Str1.Assign('This is a test')
			Str1.DeleteFrom(3);
			Writeln(Str1.ZString);	{ Thi }

Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION Insert(CONST Args : ARRAY OF CONST; Index : WORD) : PChar;
Inserts string 'Args' into the object string at position 'Index' (base 0). 
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION InsertL(CONST Args : ARRAY OF CONST; Len,Index : WORD) : PChar;
Inserts 'Len' characters from string 'Args' into the object string at position 'Index' (base 0).
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION PadCentre(NewLen : WORD; Ch : CHAR) : PChar;
Expands the object string to a new length of 'NewLen' characters. If the old object string was 
less than 'Newlen' long the string is padded equally at both front and end with the 'Ch' character 
to create a string of the required overall length.

FUNCTION PadEnd(NewLen : WORD; Ch : CHAR) : PChar;
Expands the object string to a new length of 'NewLen' characters. If the old object string was 
less than 'Newlen' long the string is padded at its end with the 'Ch' character to create a string of 
the required overall length.

FUNCTION PadFront(NewLen : WORD; Ch : CHAR) : PChar;
Expands the object string to a new length of 'NewLen' characters. If the old object string was 
less than 'NewLen' long the string is padded at its front with the 'Ch' character to create a string 
of the required overall length.

FUNCTION RemoveDIC : PChar;
If the object string has double inverted commas ( " ) at the start and end of its string these are 
removed from both ends.

FUNCTION RemoveSIC : PChar;
If the object string has single inverted commas ( ' ) at the start and end of its string these are 
removed from both ends.

FUNCTION Trim : PChar;
Removes all leading and trailing spaces from the object string.

FUNCTION TrimEnd : PChar;
Removes all trailing spaces from the object string.

FUNCTION TrimFront : PChar;
Removes all leading spaces from the object string.

FUNCTION TrimZero : PChar;
Removes all trailing '0' zero characters from the object string. (Useful for removing redundant 
zeros from real number strings). If the last character in the just trimmed string is . (decimal 
dot) then that is also removed.
12.5.13 Command Line related functions
FUNCTION FindCmdLine : Pchar;
Recreates the current applications command line (both EXE and all parameters) as a string 
and assigns it to the object text buffer.

FUNCTION FindCmdLineAndParse(IncExeParam : BOOLEAN;
                                                           VAR AList   : TObjectContainer) : Pchar;
Recreates the current applications command line (both EXE and all parameters) as a string 
and assigns it to the object text buffer. The component parts of the command line are then 
assigned to new string objects which are added to the AList container object (which owns those 
new string objects). If IncExeParam is TRUE then the index 0 command line parameter is 
included on the container list. 

FUNCTION FindCmdLineParam(Idx : INTEGER) : Pchar;
Retrieves a component part of an applications command line parameter and assigns it to the 
object text buffer. An Idx of 0 retrieves the application EXE path.
12.5.14 Resource string related functions
FUNCTION AppendStringRes(Instance : THandle; Id : WORD) : Pchar;
Loads the string resource Id and appends it to the end of the existing object text string. 

FUNCTION LoadStringRes(Instance : THandle; Id : WORD) : Pchar;
Assigns to the object the string loaded from the task resources that has an identifier of 'Id'.
12.5.15 INI file related functions
A small set of methods to help with loading string resources and INI file settings.

FUNCTION ReadIniKeyword(CONST IniFileArgs : ARRAY OF CONST;
                                               CONST SectionArgs : ARRAY OF CONST;
                                              CONST KeyWordArgs : ARRAY OF CONST) : WORD;
Assigns to the object string the INI file keyword value associated with the keyword, section and 
INI file name xxxxArgs parameters.

FUNCTION WriteIniKeyword(CONST IniFileArgs : ARRAY OF CONST;
                                               CONST SectionArgs : ARRAY OF CONST;
                                               CONST KeyWordArgs : ARRAY OF CONST) : WORD;
Writes to the INI file the object string associated with the keyword, section and INI file name 
xxxArgs parameters.

FUNCTION FindIniSectionKeywords(CONST IniFileArgs,
                                                            SectionArgs  : ARRAY OF CONST;
                                                            VAR   AList : TObjectContainer) : WORD;
Loads into the objects own buffer the text string equivalent to all keywords found in the 
SectionArgs section of the IniFileArgs INI file. The keywords are then parsed and placed as 
individual TStringClass instances on the container object Alist. The list owns the newly created 
string objects. The functions returns the number of keywords found.
12.5.16 DOS path/filename related functions
A set of methods for helping with DOS path and file name string processing. Most functions 
return a PChar pointer to the object's own string.

FUNCTION AddBackSlash : PChar;
Adds a '\' back slash to the end of the object string.

FUNCTION AddFilterDesc(CONST DescArgs,ExtArgs : ARRAY OF CONST) : PChar;
This method builds a string in the format required by the Filter property of the TOpenDialog 
VCL component.  DescArgs represents a description of the file type, whilst ExtArgs holds the 
file extension. For example, the command .

SObj.AddFilterDesc([Pascal source],[PAS])

.. builds the string .

	Pascal Source (*.PAS)|*.PAS

The same method can be called multiple times, with each secondary call adding the new 
formatted text to the end of the object text string. For example 


SObj.AddFilterDesc([Pascal source],[PAS])
SObj.AddFilterDesc([C source],[C])

.. builds the string .

	Pascal Source (*.PAS)|*.PAS|C Source (*.C)|*.C

The ExtArgs can include either or both of the * or . characters. If either or both are missing 
the method adds them to the resulting string.

FUNCTION BuildPathName(CONST DirArgs,
                                             FileNameArgs,
                                            ExtArgs : ARRAY OF CONST) : PChar;
Builds a validated path name from the three components.

FUNCTION CreateDirectory : BOOLEAN;
This function will attempt to create the DOS directory of the directory part of the objects own 
text string. The text string can hold a full file name (i.e. C:\test\test.txt). The process will 
extract the related directory path (without affecting the object string) and try to create that 
directory. The function returns TRUE if the directory was successfully created.

FUNCTION DefaultExtension(CONST Args : ARRAY OF CONST) : Pchar;
If the object string has no file name extension the extension 'Args' is appended to the end of the 
object string. The 'Args' parameter can have a '.' prefix. The method will check for duplicate '.' 
entries.

FUNCTION DirectoryExists : BOOLEAN;
Returns TRUE if the directory component of the object string value exists. The object string can 
be a full path/file name. This method will extract the directory component (without affecting the 
object string) and test for the directory's existence.

FUNCTION DriveExists : BOOLEAN;
Returns TRUE if the drive letter component of the object string value exists. The object string 
can be a full path/file name. This method will extract the drive letter component (without 
affecting the object string) and test for the drive's existence.

FUNCTION ExpandFileName : Pchar;
Converts a DOS path file into a full drive, path and file name, removing any .. type re-
directions.

FUNCTION FileExists : BOOLEAN;
Returns TRUE if the object string representing a DOS path name exists as a DOS file.

FUNCTION FileSplit(VAR ADirObj,ANameObj,AnExtObj : TStringClass) : WORD;
Takes the objects own text string and splits it into the three DOS parts of directory/path, 
filename (excluding extension) and extension (excluding the . dot). The three resulting sub 
strings are assigned to the three TStringClass parameters. These TStringClass objects must be 
instantiated prior to calling this function. The function returns a WORD value that indicates the 
presence of each sub string. This WORD value is composed from the fs_xxx constants :

	fs_Directory = 1;
	fs_Name      = 2;
	fs_extension = 4;

FUNCTION FindCurrentDir : PChar;
Copies the current DOS directory path name into the object text string.

FUNCTION FindRelPath(CONST StartDirArgs,EndDirArgs : ARRAY OF CONST) : PChar; 
Builds a DOS path string that allows the relative movement from the StartDirArgs directory to 
the end EndDirArgs directory. If both args are the same or the drives are different a NULL 
string is assigned to the object. For example :

	TObj := TStringClass.Create;
      	TObj.FindRelPath(['c:\windows'],['c:\test\data']);    { ..\test\data }

FUNCTION ForceExtension(CONST Args : ARRAY OF CONST) : Pchar;
Force the object string to have the file name extension 'Args'.

FUNCTION GetSystemDirectory : PChar;
Assigns the Windows system directory path to the object text string.

FUNCTION GetWindowsDirectory : PChar;
Assigns the Windows directory path to the object text string.

FUNCTION HasBackSlash : BOOLEAN;
Returns TRUE if the last character of the object string is a '\' back slash.

FUNCTION HasDrive : BOOLEAN;
Returns TRUE if the object string is at least three characters long and the first letter is between 
'A' and 'Z'.

FUNCTION HasExtension(VAR DotPos : WORD) : BOOLEAN;
Returns TRUE if the object string includes an extension, setting the 'DotPos' variable parameter 
with the base 0 position of the '.' delimiter.

FUNCTION HasFileName : BOOLEAN;
Returns TRUE if the object string has a file name component.

FUNCTION HasDirectory : BOOLEAN;
Returns TRUE iof the object string has a directory component.

FUNCTION JustDirectory(CONST Args : ARRAY OF CONST) : Pchar;
Extracts from the 'Args' parameter the directory component and assigns this to the object string.

FUNCTION JustExtension(CONST Args : ARRAY OF CONST) : PChar;
Extracts from the 'Args parameter the extension component and assigns this to the object 
string.

FUNCTION JustFileName(CONST Args : ARRAY OF CONST) : Pchar;
Extracts from the 'Args' parameter the DOS 8.3 style file name component and assigns this to 
the object string.

FUNCTION JustName(CONST Args : ARRAY OF CONST) : Pchar;
Extracts from the 'Args' parameter the file name component (excluding any . and extension) 
and assigns this to the object string.

FUNCTION RemoveDirectory : BOOLEAN;
This function will attempt to delete a DOS directory of the directory part of the objects own text 
string. The text string can hold a full file name (i.e. C:\test\test.txt). The process will extract the 
related directory path (without affecting the object string) and try to delete that directory. The 
function returns TRUE if the directory was successfully deleted.

FUNCTION SameDrive(CONST Args : ARRAY OF CONST) : BOOLEAN;
Compares the objects own string to the string in Args and returns TRUE if they share the 
same disk drive letter. This test process presumes that each entry is at least three characters 
long (i.e. C:\)

FUNCTION SameDirectory(CONST Args : ARRAY OF CONST) : BOOLEAN;
Compares the objects own string to the string in Args and returns TRUE if they share the 
same DOS directory.  Example:

	AStrObj := TStringClass.CreateString([c:\test\company.dat]);
	BStrObj := TStringClass.CreateString([c:\test\employee.dat]);
	AStrObj.SameDirectory([BStrObj]);  { returns TRUE }

FUNCTION SameExtension(CONST Args : ARRAY OF CONST) : BOOLEAN;
Compares the objects own string to the string in Args and returns TRUE if they share the 
same DOS file name extension.

FUNCTION SameFileName(CONST Args : ARRAY OF CONST) : BOOLEAN;
Compares the objects own string to the string in Args and returns TRUE if they share the 
same DOS 8.3 file name.

FUNCTION SameName(CONST Args : ARRAY OF CONST) : BOOLEAN;
Compares the objects own string to the string in Args and returns TRUE if they share the 
same DOS 8 file name. Example :

	AStrObj := TStringClass.CreateString([c:\data\company.dat]);
	BStrObj := TStringClass.CreateString([c:\test\company.idx]);
	AStrObj.SameName([BStrObj]);  { returns TRUE }

FUNCTION SetCurDir : BOOLEAN;
Returns TRUE if the object string includes a directory component that can be made the current 
working directory. The object string can include a full DOS path/file name. This process will 
extract the directory component, and attempt to change the current directory to that component. 
The current object text string is NOT affected.
12.5.17 Search related functions
A set of methods that search the object string for occurrences of sub strings or characters.

FUNCTION ChCount(ACh : CHAR) : WORD;
Returns the number of occurrences of CHAR 'Ch' in the object string.

FUNCTION FindBetween2Ch(FirstCh,
                                               SecondCh        : CHAR;
                                               StartFrom       : WORD;
                                               VAR SubStrStart : WORD;
                                               VAR SubStrLen   : WORD;
                                               CutSubStr,
                                               IncDelims       : BOOLEAN;
                                              VAR ASubStr     : TStringClass) : BOOLEAN;
Retrieves a sub string from the objects own text string starting from the first instance of 
character FirstCh to the netx instance of character SecondCh. The substring is assigned to 
the ASubStr string object. The ASubStr object must be an already instantiated TStringClass 
object. The function returns TRUE if a sub string is found. The base 0 relative start position and 
length is returned in SubStrStart and SubStrLen. If CutSubStr is TRUE the located sub string 
is deleted from the objects own text string. If 'IncDelims' is TRUE the FirstCh/SecondCh 
characters are included in the string assigned to 'ASubStr.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION FindFirst(CONST SubArgs : ARRAY OF CONST; VAR P : WORD) : BOOLEAN;
Searches for the first occurrence of sub string 'SubArgs' in the object string, and returns TRUE 
if the sub string is found. The position of the sub string (base 0) is returned in variable 
parameter 'P'.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION FindFirstCh(ACh : CHAR; VAR P : WORD) : BOOLEAN;
Searches for the first occurrence of CHAR 'Ch' in the object string, and returns TRUE if the 
CHAR is found. The position of the CHAR (base 0) is returned in variable parameter 'P'.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION FindLast(CONST SubArgs : ARRAY OF CONST; VAR P : WORD) : BOOLEAN;
Searches for the last occurrence of sub string 'SubArgs' in the object string (starting from the 
end of the string), and returns TRUE if the sub string is found. The position of the sub string 
(base 0) is returned in variable parameter 'P'.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION FindLastCh(ACh : CHAR; VAR P : WORD) : BOOLEAN;
Searches for the last occurrence of CHAR 'Ch' in the object string, and returns TRUE if the 
CHAR is found. The position of the CHAR (base 0) is returned in variable parameter 'P'.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION FindNext(CONST SubArgs : ARRAY OF CONST;
                                  StartPos : WORD;
                                  VAR NextPos : WORD) : BOOLEAN;
Searches for the next occurrence of sub string 'SubArgs' in the object string starting from 
character position 'StartPos' (base 0), and returns TRUE if the sub string is found. The position 
of the sub string (base 0) is returned in variable parameter 'NextPos'.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION FindNextCh(ACh : CHAR; 
                                       StartPos : WORD; VAR NextPos : WORD) : BOOLEAN;
Searches for the next occurrence of CHAR 'Ch' in the object string starting from character 
position 'StartPos' (base 0), and returns TRUE if the CHAR is found. The position of the CHAR 
(base 0) is returned in variable parameter 'NextPos'.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION FindPrev(CONST SubArgs : ARRAY OF CONST;
                                   StartPos : WORD; VAR PrevPos : WORD) : BOOLEAN;
Searches for the previous occurrence of sub string 'SubArgs' in the object string starting from 
character position 'StartPos' (base 0) and searching in a right to left direction. The function 
returns TRUE if the sub string is found. The position of the new sub string (base 0) is returned 
in variable parameter 'PrevPos'.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION FindPrevCh(ACh : CHAR; StartPos : WORD; VAR PrevPos : WORD) : 
BOOLEAN;
Searches for the previous occurrence of CHAR 'Ch' in the object string starting from character 
position 'StartPos' (base 0) and searching in a right to left direction. The function returns TRUE 
if the CHAR is found. The position of the new CHAR (base 0) is returned in variable parameter 
'PrevPos'.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION Grep(CONST SearchArgs : ARRAY OF CONST; 
                            VAR AList : TWordContainer) : WORD;
This method will search the objects own string for a pattern of characters defined in the 
SearchArgs parameter, and will report the position of each such occurrence as a WORD entry 
in the word list array AList. The method function returns the number of occurrences found.

For example .

	VAR
		MObj : TStringClass;
		AList : TWordContainer;
	BEGIN
		..
		..
		MObj := TStringClass.CreateString([WIN.INI]);
		AList := TWordContainer.Create
		MObj.Grep([IN],AList)
		..
		..

The Grep function will return a result of 2 will word array entries of 1 and 4. Note: if the 
typed constant StrClassBaseZero is set to FALSE then the character positions returned in the 
word array are base one (1).

The search pattern is case sensitive. 

The SearchArgs parameter can take a number of special characters:

?	This can be any character. Thus, a search pattern of A? will find both AB and AZ.
\	This is a special delimiter to indicate that the next character in the parameter list should 
be taken as a literal. Thus, if you wanted to search for the ? character you should use 
\? as part of the search pattern.
[]	Any set of characters within square brackets allows an OR type test against each of 
the characters within the square brackets. For example a search pattern of A[BC] will 
find both AB and AC. 
[!]	Placing a ! character as the first within the square brackets means that the search will 
succeed for any character other than those listed within the square brackets. For 
example., a search pattern of A[!BC] will find AD but not find AB.
:a	This will match any alphabetic character (A to Z or a to z), irrespective of case
:d	This will match any digit (0 to 9)
:n	This will match any alpha-numeric (A to Z, or a to z, or 0 to 9)
-	A minus sign placed after a character makes that characters presence optional  For 
example, a search pattern of SM-X will find both SMX and SX. 
*	An asterix (*) placed after a character will set matches to occur if optional extensions 
of the same character appear. Thus, FR* will find both FR and FRR and FRRR.
+	A plus placed after a character will set matches to occur of further examples of the 
same character are found. Thus, FR+ will find both FRR and FRRR, but not find 
FR.

The StrClass unit includes a number of constants to assist with the preparation of grep related 
search patterns 

grep_any          = '?';
grep_nextLiteral  = '\';
grep_optionStart  = '[';
grep_optionEnd    = ']';
   grep_class        = ':';
grep_Alpha        = 'A';
grep_numeric      = 'D';
grep_alphaNumeric = 'N';
grep_Chcont0      = '*';
grep_Chcont1      = '+';
grep_ChOption     = '-';
grep_Not          = '!';

The example project GrepTest.Dpr can be used to demonstrate the various grep related 
search options.

If the SearchArgs parameter includes an invalid sequence of characters an exception error is 
raised.

FUNCTION SubStrCount(CONST SubArgs : ARRAY OF CONST) : WORD;
Returns the total number of occurrences that sub string 'SubArgs' is located within the object 
string.
12.5.18 Case related functions
FUNCTION FirstCharToUpper : PChar;
Converts the first character of each separate word in the object string to upper case. For 
example:

			Str1.Assign('This is a test')
			Str1.FirstCharToUpper;
			Writeln(Str1.ZString);		{ This Is A Test }

FUNCTION IsAlphaNumeric : BOOLEAN;
Returns TRUE if all characters in the text string are alpha numeric (between A to Z , a to z, 
or 0 to 9).

FUNCTION ToLower : PChar;
Converts the whole object string to lower case.

FUNCTION ToUpper : Pchar;
Converts the whole object string to upper case.
12.5.19 Search & replace related functions
Most of these methods return a PChar pointer to the object string.

FUNCTION ReplaceAll(CONST OldArgs,NewArgs : ARRAY OF CONST) : PChar;
Replaces every occurrence of the sub string 'OldArgs' in the object string with the replacement 
sub string 'NewArgs'. If 'NewArgs' is NIL then the process will just remove all instances of 
'OldArgs.

FUNCTION ReplaceChAll(OldCh,NewCh : CHAR) : PChar;
Replaces every occurrence of the CHAR 'OldCh'  with the replacement CHAR 'NewCh'.

FUNCTION ReplaceChFirst(OldCh,NewCh : CHAR) : PChar;
Replaces the first occurrence of the CHAR 'OldCh'  with the replacement CHAR 'NewCh'.

FUNCTION ReplaceChLast(OldCh,NewCh : CHAR) : Pchar;
Replaces the last occurrence of the CHAR 'OldCh'  with the replacement CHAR 'NewCh'.

FUNCTION ReplaceFirst(CONST OldArgs,NewArgs : ARRAY OF CONST) : PChar;
Replaces the first occurrence of the sub string 'OldArgs' in the object string with the 
replacement sub string 'NewArgs'. If 'NewArgs' is NIL then the process will just remove 
'OldArgs'.

FUNCTION ReplaceLast(CONST OldArgs,NewArgs : ARRAY OF CONST) : PChar;
Replaces the last occurrence of the sub string 'OldArgs' in the object string with the 
replacement sub string 'NewArgs'. If 'NewArgs is NIL then process will just remove 'OldArgs'.

12.5.20 Parsing related functions
This set of functions provides a variety of methods for parsing or splitting text strings into a 
number of parts.  Parsing operations place parsed sub strings into their own string class. A 
container class TObjectContainer is used to hold multiple sub strings. (Refer to section 9 for an 
explanation of container objects).

FUNCTION FirstParseDelim(CONST Args : ARRAY OF CONST;
                                               DelimCh      : CHAR;
                                               VAR DelimPos : WORD) : BOOLEAN;
The 'Args' string is presumed to be a string holding multiple values delimited by the character 
'DelimCh'. This method will extract the first item from the source string and assign it to this 
object string. In the process it sets the variable parameter 'DelimPos' with the index position 
(base 0) of the next delimited item. The function will return FALSE if the 'Args' string is NIL or 
of zero length.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION NextParseDelim(CONST Args : ARRAY OF CONST;
                                              DelimCh          : CHAR;
                                              StartPos         : WORD;
                                              VAR NextDelimPos : WORD) : BOOLEAN;
Used in association with 'FirstParseDelim', this method returns the next item to be parsed from 
the 'Args' string. The search starts at position 'StartPos'  and assigns the parsed string into the 
object string.  The method updates the variable parameter 'NextDelimPos' with the starting 
position of the next delimited entry. The method returns FALSE if there are no further string 
items to parse.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

FUNCTION ParseDelimCount(DelimCh : CHAR) : WORD;
Returns the number of items in a string delimited by the 'DelimCh' character.

FUNCTION ParseDelimToList(DelimCh   : CHAR;
                                                 Special   : INTEGER;
                                                 VAR AList : TObjectContainer) : WORD;
A high level method of parsing the object's own string. 'DelimCh' specifies the character used to 
delimiter string entries. The method adds a new 'TStringClass' to the 'AList' container class for 
each item it parses from its own string (the object string is unaffected by this process). The 
container class owns the newly created string class objects. The 'Special' parameter is used to 
determine how double inserted commas or single inverted commas should be treated. The 
options are:

   delim_None    = 0;     { do nothing }
   delim_IncDIC  = 1;     { add double inverted commas to the start/end of each item }
   delim_IncSIC  = 2;     { add single inverted commas to the start/end of each item }
   delim_ExcDIC = 4;    { remove any double inverted commas from the start/end of each item }
   delim_ExcSIC = 8;    { remove any single inverted commas from the start/end of each item }

   delim_ExcNull = 16   { exclude any NULL strings from the list }

If there is no text between the location of two delimiters the String Object created for that item 
is set to have a NIL string.  However, if the Special parameter includes delim_ExcNull such 
null part strings are not added to this list.

If the 'AList' parameter is passed as a NIL value this method will create the container object. 
The function returns the number of items parsed from the object's own string.

Examples .

VAR
   AList : TObjectContainer;
   SObj  : TStringClass;

   { ++++++++++++++++++++++++++++++++++++++++++++++++++ }

   PROCEDURE AddToListBox(S : TStringClass); FAR;
   BEGIN
      AListBox.Items.Add(S.Text);
   END;

   { ++++++++++++++++++++++++++++++++++++++++++++++++++ }

BEGIN
   ...
   ...
   AList := TObjectContainer.Create;
   SObj := TStringClass.CreateString(['aaa,bbb,ccc']);
   SObj.ParseDelimToList(',',delim_none,AList);
   AList.ForEach(@AddToListBox);
   AList.Free;
   SObj.Free;
   ...
   ...
END;

With the above you must not forget to make the nested procedure a 'FAR', and the 'action' 
procedure ('AddToListBox') can only be nested within the same procedure block.

                                  ...oOo...

Or, secondly .....


VAR
   AList : TObjectContainer;
   PartObj,SObj  : TStringClass;
   E : LONGINT;
BEGIN
   ...
   ...
   AList := TObjectContainer.Create;
   SObj := TStringClass.CreateString(['aaa,bbb,ccc']);
   SObj.ParseDelimToList(',',delim_none,AList);
   FOR E := 0 TO AList.Count-1 DO
   BEGIN
      PartObj := AList.Items[E];
      AListBox.Items.Add(PartObj.Text);
   END;
   AList.Free;
   SObj.Free;
   ...
   ...
END;

Where the source string ends with a delimiter character, the parsing process adds a null string 
object to the target list. For example .

	AStrObj.Assign([AA*BB*CC**]);
	AStrObj.ParseDelimToList(*,delim_none,AList)

  . returns a result of 5 sub strings: AA, BB, CC, null and null.


FUNCTION ParseMultiDelimToList(CONST DelimArgs : ARRAY OF CONST;
                                                         Special         : INTEGER;
                                                         VAR AList       : TObjectContainer) : WORD;
This method is similar to the previous ParseDelimToList. It differs in that the first parameter 
can contain multiple delimiters and that these delimiters can be of any variable type accepted 
as part of an ARRAY OF CONST. Thus a delimiter may be either a single character or multi-
character string.  The parsing process checks each item on the DelimArgs list to see what 
delimiter appears first.  The order of items within the DelimArgs parameter is not relevant.

 For example .

TObj := TStringClass.CreateString(['>QFADS 14:30:30 - 14:45:00  95/11/01']);
TObj.ParseMultiDelimToList([' - ',' ','>QFADS',':','/'],delim_ExcNull,AList);

. will parse down to 

14
30
30
14
45
00
95
11
01

The method uses the same set of Special parameters as outlined under ParseDelimToList.


FUNCTION ParsePosToList(VAR PosArray;
                                              PosCt : WORD;
                                              VAR AList : TObjectContainer) : WORD;
A high level method of parsing the object's own string based around an array of start and length 
settings passed to it in the 'PosArray' parameter. The 'PosArray' psarameter musty be a two 
dimension INTEGER array that holds 'PosCt' number of entries. Each array entry must have as 
its first element the starting position of the sub string to be extracted (base zero) and as its 
second element the number of characters to extracted.
Note: if the typed constant StrClassBaseZero is set to FALSE then the first character position 
starts from one (1) not zero (0).

For each entry in the PosArray the method will create a new string object, assign it the sub 
string extracetd from the main string and add it to the 'AList' collection (the collection owns all 
string objects created in this manner). If the PosArray entries are located at a position beyond 
the end of the string the string object created for that entry is assigned a NIL string. If the 'AList' 
parameter is passed as a NIL value this method will create the collection object. The function 
returns the number of items parsed and added to the 'AList' collection.

13. Container Objects

For certain of the parsing related methods the TStringClass object uses container objects to 
hold lists of parsed sub strings.

These container objects are of the type TObjectContainer.

For those who used Borland Pascal for Windows the hierarchy of container objects defined in 
ContainR.Pas will have a familiar ring. They are based largely upon the TCollection object 
used in the OWL application framework.

For those unfamiliar with OWL, a TCollection object was a type of open ended array into which 
items could be added, inserted or deleted. 

Ive taken the basic TCollection concept and adapted this for use in the DELPHI world. The 
differences include:

  The container objects can manage open ended arrays of up to 2,147,483,647 items.
  The container object hierarchy includes objects for holding basic data types i.e. large arrays 
of integers, objects, and records. 
  It makes extensive use of the Property aspect of object definition.

13.1 TBaseContainer
All container objects derive from the abstract class TBaseContainer .  
13.1.1 Public methods
CONSTRUCTOR Create; VIRTUAL;
Creates a new object. 

DESTRUCTOR Destroy; OVERRIDE;
Destroys the open array list and all its list items 

PROCEDURE Clear; VIRTUAL;
Clears all items from the list, disposing of any records/objects on the list.

PROCEDURE Delete(Idx : LONGINT); VIRTUAL;
Deletes the Idx item (base 0) from the list. The item itself is not disposed of.

PROCEDURE DeleteAll; VIRTUAL;
Deletes all items from the list, resetting the count to zero. None of the items previously on the 
list are disposed of.

PROCEDURE DeleteBlock(SIdx,EIdx : LONGINT);
Deletes a block of items starting from item Sidx to Eidx inclusive (base 0), without disposing 
of any objects/records.

PROCEDURE Exchange(Idx1,Idx2: LONGINT); VIRTUAL;
Exchanges the position of two items on the list.

FUNCTION InsertBlock(Idx,Number : LONGINT) : LONGINT; VIRTUAL;
Inserts Number empty (null) item pointers starting from position Idx.

PROCEDURE Move(CurIdx, NewIdx: LONGINT); VIRTUAL;
Moves the item CurIdx to the new position NewIdx.

PROCEDURE Pack; VIRTUAL;
Scans the list to remove any null item pointers.

PROCEDURE RemoveAll;
Removes and disposes of all objects/records on the list.
13.1.2 Properties
PROPERTY Capacity: LONGINT READ FCapacity WRITE SetCapacity;
Each list can be assigned a capacity. Items are added to list until the list count reaches the 
capacity. Once this is reached the list is re-organised to provide extra capacity. By defining a 
large capacity in advance the process can avoid wasteful list re-organisiing.

PROPERTY CompareFunc : TCompareFunc READ FCompareFunc WRITE 
FCompareFunc;
For containers where items are to be sorted the object can use a global function located in 
another unit to determine the comparison result between items on the list. This is achieved by 
assigning the address of that global function to this property. The global function must be of the 
type .

TCompareFunc = FUNCTION(VAR Ptr1,Ptr2) : INTEGER;

The two parameters Ptr1 and Ptr2 are of the same type as the item being stored on the list, 
i.e. if the list holds objects each parameter will be an object pointer (TObject), or INTEGER 
types if the list holds integers. The compare function assigned to this property must be declared 
in the interface section of a unit. This function must return an INTEGER result. If the related 
sort process requires that Ptr1 be located before Ptr2 then the function should return a -1 
result.  If the sort process determines that both parameters are equal the function should return 
a 0 result. Or if Ptr1 is to be placed after Ptr2 then the function must return a 1 result.

For example 

INTERFACE

TYPE

TDataClass = CLASS(TObject)
      PRIVATE
         Name : STRING;
      PUBLIC
         CONSTRUCTOR CreateName(CONST AName : STRING);
         FUNCTION GetName : STRING;
   END;

   FUNCTION NameCompare(VAR Ptr1,Ptr2) : INTEGER;

	IMPLEMENTATION

..

FUNCTION NameCompare(VAR Ptr1,Ptr2) : INTEGER;
BEGIN
   Result := CompareText(TDataClass(Ptr1).GetName,TDataClass(Ptr2).GetName);
END;



AList := TObjectContainer.Create;
AList.Sort := sortAscending;
AList.CompareFunc := NameCompare;

If for some reason a container object uses both this property and overrides the Compare 
function method, then the sort process will always use the virtual Compare method.

PROPERTY Count: LONGINT READ Fcount;
Returns the number of items on the list.

PROPERTY Delta : LONGINT READ FDelta WRITE FDelta;
Sets or returns the size by which the capacity will grow each time the count reaches the 
capacity limit.

PROPERTY Duplicates : TDuplicates READ FDuplicates WRITE Fduplicates;
This property determines how to handle the addition of duplicate items to a sorted container, 
and only applies to containers which are sorting there contents. By default this property is set to 
dupIgnore. With sorted collections this means that an attempt to add a duplicate item will 
simply be ignored, with no exception error. 

TDuplicates = (dupIgnore, dupAccept, dupError);

If this property is set to dupAccept then the container will process and accept duplicate list 
entries. However, if this property is set to dupError, then any attempt to add a duplicate item 
will create a run time exception error. 

PROPERTY GrowAsRequired : BOOLEAN READ FGrowAsRequired WRITE 
FGrowAsRequired;
Using the Items property found in descendant container objects a list item can be assigned to 
a specific list position. This does not have to be at the last used position. This allows a list to 
hold ono-contiguous entries., The GrowAsRequired property is used to control whether such 
Items assignments can be made past the capacity limit. If set to TRUE (the default) then the 
capacity will grow to meet any use of the Items property. If set to FALSE then any attempt to 
use the Items property outside of the list capacity will create an exception error.

PROPERTY Sort : TContainerSortType READ FSort WRITE SetSort;
Used to set whether a list should be sorted into a pre-determined order. The attribute should be 
passed a TContainerSortType value.

	TContainerSortType = (sortNone,sortAscending,sortDescending);

A sorted container requires that either:

  a new class be derived from the required class type, and the protected method Compare 
be overriden with a new method.

	FUNCTION Compare(Ptr1,Ptr2 : POINTER) : INTEGER; VIRTUAL;

  or that the CompareFunc function property be set.  This is a function variable type uses 
the following prototype format ..

TCompareFunc = FUNCTION(VAR Ptr1,Ptr2) : INTEGER;

The two parameters Ptr1 and Ptr2 are of the same type as the item being stored on the 
list, i.e. if the list holds objects each parameter will be an object pointer (TObject), or 
INTEGER types if the list holds integers. The compare function assigned to this property 
must be declared in the interface section of a unit. This function must return an INTEGER 
result. If the related sort process requires that Ptr1 be located before Ptr2 then the 
function should return a -1 result.  If the sort process determines that both parameters are 
equal the function should return a 0 result. Or if Ptr1 is to be placed after Ptr2 then the 
function must return a 1 result.

For example 

INTERFACE

TYPE

TDataClass = CLASS(TObject)
      PRIVATE
         Name : STRING;
      PUBLIC
         CONSTRUCTOR CreateName(CONST AName : STRING);
         FUNCTION GetName : STRING;
   END;

   FUNCTION NameCompare(VAR Ptr1,Ptr2) : INTEGER;

	IMPLEMENTATION

..

FUNCTION NameCompare(VAR Ptr1,Ptr2) : INTEGER;
BEGIN
   Result := CompareText(TDataClass(Ptr1).GetName,TDataClass(Ptr2).GetName);
END;



AList := TObjectContainer.Create;
AList.Sort := sortAscending;
AList.CompareFunc := NameCompare;

13.2 TObjectContainer

An open ended array type container for holding object pointers.
13.2.1 Public methods
CONSTRUCTOR Create; OVERRIDE;
Creates an instance of the new object type.

FUNCTION Add(Item: POINTER): LONGINT; VIRTUAL;
Adds an instantiated object to the list. If sorting is not active then the object instance is added to 
the end of the list. If sorting is active then the object will be placed in a positioned based upon 
the objects Compare result.

FUNCTION Append(Item : POINTER) : LONGINT; VIRTUAL;
Adds the object to the end of the list.

FUNCTION First: POINTER; VIRTUAL;
Returns a pointer to the first object on the list.

FUNCTION FirstThat(Test: Pointer): Pointer;
Iterates across the objects on the list calling the local nested function Test with the current list 
object as the parameter. The process continues until such time that the test function returns 
TRUE. The function returns a pointer to the object that was active when the TRUE condition 
prevailed. If no TRUE return is returned the FirstThat function returns NIL.

Example ...

	VAR
		Alist : TObjectContainer;

		{ ++++++++++++++++++++++++++++++++++++++++++ }

		FUNCTION DoTest(AnObject : TMyObject) : BOOLEAN; FAR;
		BEGIN
                         
		END;

		{ ++++++++++++++++++++++++++++++++++++++++++ }

	BEGIN
		Alist := TObjectContainer.Create;
		.......
		......
		AList.FirstThat(@DoTest);
		.....
		.....

The Test function must be nested function and must be declared as a FAR function. It can 
have only one parameter - an object of whatever type is being stored in the container.

This function is useful for reviewing objects on the list and returning a pointer to some object 
that meets a test.

FUNCTION FirstThatIdx(Test: Pointer): Pointer;
This is a variation on the FirstThat method described above. With FirstThatIdx the nested 
local function requires two parameters. The first being an object pointer of whatever type is 
being stored on the list. The second must be a LONGINT parameter. This is passed by the 
FirstThat process and represents the base zero (0) index position of current data object within 
the list (i.e. somewhere between 0 to Count-1).  

	VAR
		AList : TObjectContainer;
		ATotal : LONGINT

		{ ++++++++++++++++++++++++++++++++++++++++++ }

		FUNCTION DoTest(AnObject : TMyObject; Idx : LONGINT) : BOOLEAN; FAR;
		BEGIN
                         		
			
		END;

		{ ++++++++++++++++++++++++++++++++++++++++++ }

	BEGIN
		Alist := TObjectContainer.Create;
		.......
		......
		ATotal := 0;
		AList.FirstThatIdx(@DoTest);
		.....
		.....

PROCEDURE ForEach(Action: Pointer);
Similar to FirstThat this function iterates across all objects on the list, running the procedure 
Action for each object. The iteration cannot be stopped. The Action procedure must be nested 
procedure and must be declared as a FAR type. It can have only one parameter - an object of 
whatever type is being stored in the container. This function is useful for reviewing objects on 
the list and accumulating list wide totals.

This method is useful for counting items data elements of data objects on a list, for example :

VAR
	AList : TObjectContainer;
	TotalAge : LONGINT;
   
{ +++++++++++++++++++++++++++++++++++++++++++++++++++++ }

PROCEDURE DoAgeCount(ThisDataObj : TDataObject; Idx : LONGINT); FAR;
BEGIN
 	   INC(TotalAge,ThisDataObj.Age);
END;

{ +++++++++++++++++++++++++++++++++++++++++++++++++++++ }

BEGIN
   .
   ..

   AList := TObjectContainer.Create;
   AList.Capacity := 100;
   { params - initials, surname, age and salary }
   ADataObj := TDataObject.CreateInit('J','Smith',34,10500.45);
   AList.Add(ADataObj);
   ADataObj := TDataObject.CreateInit('F','Brown',40,17453.89);
   AList.Add(ADataObj);
   ADataObj := TDataObject.CreateInit('A','Jones',23,12765.34);
   AList.Add(ADataObj);
   ADataObj := TDataObject.CreateInit('W','Bloggs',19,23456.21);
   AList.Add(ADataObj);
   TotalAge := 0;
   { count total ages }
   AList.ForEach(@DoAgeCount);

The DoAgeCount local nested procedure is called for each data object on he list, thus allowing 
TotalAge to accumalate a total. 

PROCEDURE ForEachIdx(Action: Pointer): Pointer;
This is a variation on the ForEach method described above. With ForEachIdx the nested 
local procedure requires two parameters. The first being an object pointer of whatever type is 
being stored on the list. The second must be a LONGINT parameter. This is passed by the 
ForEach process and represents the base zero (0) index position of current data object within 
the list (i.e. somewhere between 0 to Count-1).  

	VAR
		AList : TObjectContainer;
		ATotal : LONGINT

		{ ++++++++++++++++++++++++++++++++++++++++++ }

		PROCEDURE DoTest(AnObject : TMyObject; Idx : LONGINT); FAR;
		BEGIN
                         		
			
		END;

		{ ++++++++++++++++++++++++++++++++++++++++++ }

	BEGIN
		Alist := TObjectContainer.Create;
		.......
		......
		ATotal := 0;
		AList.ForEachIdx(@DoTest);
		.....
		.....


FUNCTION Includes(Item : POINTER; VAR Idx : LONGINT) : BOOLEAN;
Returns TRUE if the object Item is found on the list. The base 0 zero list position is returned in 
Idx

FUNCTION IndexOf(Item: POINTER): LONGINT; VIRTUAL;
Returns the base 0 index position of an object on the list.

FUNCTION Insert(Idx: LONGINT; Item: POINTER) : LONGINT; VIRTUAL;
Inserts an object Item at the list position Idx. This was create an exception error if sorting is 
active.

FUNCTION Last: POINTER;
Returns a pointer to the last object on the list.

FUNCTION LastThat(Test: Pointer): Pointer;
Similar to the FirstThat function this iterates across the list from last to first.

FUNCTION LastThatIdx(Test: Pointer): Pointer;
This is a variation on the LastThat method described above. With LastThatIdx the nested 
local function requires two parameters. The first being an object pointer of whatever type is 
being stored on the list. The second must be a LONGINT parameter. This is passed by the 
LastThat process and represents the base zero (0) index position of current data object within 
the list (i.e. somewhere between 0 to Count-1).   For example 

	VAR
		AList : TObjectContainer;
		ATotal : LONGINT

		{ ++++++++++++++++++++++++++++++++++++++++++ }

		FUNCTION DoTest(AnObject : TMyObject; Idx : LONGINT) : BOOLEAN; FAR;
		BEGIN
                         		
			
		END;

		{ ++++++++++++++++++++++++++++++++++++++++++ }

	BEGIN
		Alist := TObjectContainer.Create;
		.......
		......
		ATotal := 0;
		AList.LastThatIdx(@DoTest);
		.....
		.....

FUNCTION Prepend(Item : POINTER) : LONGINT; VIRTUAL;
Insert the object Item at the front of the list.

FUNCTION Remove(Item: POINTER): LONGINT; VIRTUAL;
Removes the object Item from the list and disposes it.
13.2.2 Properties
PROPERTY Items[Idx : LONGINT]: POINTER READ GetPtr WRITE PutPtr;
Allows an object to be assigned to a zero based position in the list, or returns the object found 
at position Idx.

PROPERTY Own : BOOLEAN READ Fown WRITE Fown;
If set to TRUE the list is deemed to own the objects and will dispose of them once they are 
removed from the list. If set to FALSE the object will NOT dispose of the object if it is removed 
from the list.
13.3 TRecordContainer

A container object to used to store lists of record pointers. The Items property should have 
assigned to it a pointer to the record structure.
13.3.1 Public methods
CONSTRUCTOR Create(ARecSize : WORD);
Used to create the record container. Example ...

	TYPE
		PMyRec = ^TMyRec;
		TMyRec = RECORD
			Name : STRING;
			Age   : LONGINT;
		END;
	VAR
		Alist : TRecordContainer
		Arec : PMyRec;
	BEGIN
		.....
		.....
		Alist := TRecordContainer.Create(SIZEOF(TMyRec));

13.4 TPCharContainer = CLASS(TObjectContainer)

A container object for holding lists of PChar variable types.

13.5 TIntegerContainer = CLASS(TBaseContainer)

A container for holding lists of integers.
13.5.1 Public methods
CONSTRUCTOR Create;
Creates a container object to hold integer items.

FUNCTION Add(Item: INTEGER): LONGINT; VIRTUAL;
Adds the new integer value to the list. If sorting is not active it is appended to the end of the list.

FUNCTION Append(Item : INTEGER) : LONGINT; VIRTUAL;
Appends the new integer item to the end of the list.

FUNCTION First: INTEGER; VIRTUAL;
Returns the integer value of the first item on the list.

FUNCTION Includes(Item : INTEGER; VAR Idx : LONGINT) : BOOLEAN;
Returns TRUE if the Item integer is found on the list. Idx is returned with the base zero list 
position.

FUNCTION Insert(Idx: LONGINT; Item: INTEGER) : LONGINT; VIRTUAL;
Inserts the new integer entry Item into the list at position Idx (base 0)

FUNCTION Last: INTEGER;
Returns the integer value of the last item on the list.

FUNCTION Prepend(Item : INTEGER) : LONGINT; VIRTUAL;
Inserts the Item value into the start of the list.

FUNCTION Remove(Item: INTEGER): LONGINT; VIRTUAL;
Removes the integer item from the list.
13.5.2 Properties
PROPERTY Items[Idx : LONGINT]: INTEGER READ GetInteger WRITE PutInteger;
Used to assign integer values to specific positions on the list, or to return the integer value 
found at position Idx on the list.

13.6 TWordContainer = CLASS(TBaseContainer)
A container for holding lists of WORD type values. The methods and properties have the exact 
same purpose as for the TIntegerContainer, except that they use WORD type item 
parameters.
13.6.1 Public methods
CONSTRUCTOR Create;
FUNCTION Add(Item: WORD): LONGINT; VIRTUAL;
FUNCTION Append(Item : WORD) : LONGINT; VIRTUAL;
FUNCTION First: WORD; VIRTUAL;
FUNCTION Includes(Item : WORD; VAR Idx : LONGINT) : BOOLEAN;
FUNCTION Insert(Idx: LONGINT; Item: WORD) : LONGINT; VIRTUAL;
FUNCTION Last: WORD;
FUNCTION Prepend(Item : WORD) : LONGINT; VIRTUAL;
FUNCTION Remove(Item: WORD): LONGINT; VIRTUAL;
13.6.2 Properties
PROPERTY Items[Idx : LONGINT]: WORD READ GetWord WRITE PutWord;
13.7 TLongIntContainer = CLASS(TBaseContainer)
A container for holding lists of LONGINT type values. The methods and properties have the 
exact same purpose as for the TIntegerContainer, except that they use LONGINT type item 
parameters.
13.7.1 Public methods
CONSTRUCTOR Create;
FUNCTION Add(Item: LONGINT): LONGINT; VIRTUAL;
FUNCTION Append(Item : LONGINT) : LONGINT; VIRTUAL;
FUNCTION First: LONGINT; VIRTUAL;
FUNCTION Includes(Item : LONGINT; VAR Idx : LONGINT) : BOOLEAN;
FUNCTION Insert(Idx: LONGINT; Item: LONGINT) : LONGINT; VIRTUAL;
FUNCTION Last: LONGINT;
FUNCTION Prepend(Item : LONGINT) : LONGINT; VIRTUAL;
FUNCTION Remove(Item: LONGINT): LONGINT; VIRTUAL;
13.7.2 Properties
PROPERTY Items[Idx : LONGINT]: LONGINT READ GetLongInt WRITE PutLongInt;

13.8 TCustomTypeContainer = CLASS(TBaseContainer)
A container for holding items of user defined length. Note that for this container an item is 
passed as undefined variable type. This presumes that a valid record/variable is passed, NOT a 
pointer to the record or variable.
13.8.1 Public methods
CONSTRUCTOR Create(CustomTypeLen : WORD);
Creates a container object to hold items of length CustomTypeLen bytes

FUNCTION Add(VAR Item): LONGINT; VIRTUAL;
Adds the custom type to the list.

FUNCTION Append(VAR Item) : LONGINT; VIRTUAL;
Adds the custom item to the end of the list.

FUNCTION Insert(Idx: LONGINT; VAR Item) : LONGINT; VIRTUAL;
Inserts the custom item at position Idx.

FUNCTION Prepend(VAR Item) : LONGINT; VIRTUAL;
Asdds the custom item to the front of the list.

FUNCTION Retrieve(Idx : LONGINT; VAR Item) : BOOLEAN;
Retrieves the custom item at position Idx into the variable Item.

14. Version Management

Changes for Version 1.1

Known Bugs & Bug fixes

JustDirectory 
Fixed a bug where for parameters such as c:\windows the process was extracting C:\ as the 
directory. The function now tests for the existence of the . dot and the number of \ delimiters. 
If no dot is present and the number of \ is less than 2 then the parameter string is assumed to 
be a directory and is simply assigned to the object.

FindCmdLineParam, FindCmdLine, FindCmdLineParam
If called as part of a DLL these functions might fail.

IsSameI
The function had an erroneous Len 2nd parameter which has been removed.

New functions:

DeleteFrom
FindRelPath


Changes for Version 1.2

Known Bugs & Bug fixes

Container objects - using sorted object containers
The TObjectContainer class if pre-declared as Sorted failed to sort the objects, even crashed 
in certain situations. There were multiple (coding error) reasons for this. The Compare and 
Search methods were faulty in accessing pointers on the list. (See also the new 
CompareFunc function property).

Container Objects - Capacity property : un-initialised memory arrays
The SetCapacity method failed to initialise local memory block memory arrays to zero. This 
lead to a situation where a direct assignment of an item via the Items property failed to 
increment the container item count. (This error only applied to small lists where the item pointer 
array was less than 64K in size).

ReadIniKeyword - buffer length
Within this method the internal PChar variable used as the target buffer for the initial INI file 
read was limited to 255 characters. Thus, if the INI file entry was longer than 255 characters it 
only read the first 255. This has been increased to 1000 (can anybody envisage an INI file entry 
exceeding 1000 characters??)

New functions

Container object - CompareFunc function property.


Changes for Version 1.3

Known Bugs & Bug fixes

ReadIniKeyword - no clear if key word not found
If the ReadIniKeyword function was used on a string class that already contained a text value, 
and the keyword does not exist or has a null value, the object text value was not being reset to 
null. This has been fixed so that in such situations the objects own text buffer is reset to null.


Changes for Version 1.4

Known Bugs & Bug fixes

ParseDelimToList - parse error if delimiter char is last char in source string.
The ParseDelimToList function failed to parse a source string correctly where the delimiter was 
the last character in the source string.
Previously  the source string A*** with a delimiter of * was being returned as a list of two 
string objects A and null, when it should have been three: A , null and null. This has been 
fixed so that any source string with a trailing delimiter character will always returns a list with an 
extra null sub string entry.

TBaseContainer.SortInPlace : memory leak
The quick-sort procedure used by this method was using two private unit level pointers which 
were not being released at the end of the process, thus losing 8 bytes of memory each time the 
process was called. This has been fixed.


Changes for Version 1.5

New TStringClass methods:

FUNCTION SameDrive(CONST Args : ARRAY OF CONST) : BOOLEAN;
FUNCTION SameDirectory(CONST Args : ARRAY OF CONST) : BOOLEAN;
FUNCTION SameExtension(CONST Args : ARRAY OF CONST) : BOOLEAN;
FUNCTION SameFileName(CONST Args : ARRAY OF CONST) : BOOLEAN;
FUNCTION SameName(CONST Args : ARRAY OF CONST) : BOOLEAN;


Changes for Version 1.6

Known bugs & bug fixes

ParseDelimToList  : delim_IncSIC and delim_IncDIC - not implemented
The use of the delim_IncSIC and delim_IncDIC parameters was documented by NOT 
implemented. This has been fixed.

New TStringClass methods:

FUNCTION AddDIC : PChar;
FUNCTION AddSIC : PChar;

Changes for Version 1.7

Bug fixes:

TBaseContainer Move method
This included a coding error that trashed the target pointer. 

TBaseContainer SetCapacity method
A similar error to the above, it only affected containers where a local memory to global memory 
move was enacted.

New TStringClass functionality:

The StrClassBaseZero typed constant used for setting base 0 or base 1 character positioning.

New TStringClass method functions:

FUNCTION GetSystemDirectory : PChar;
FUNCTION GetWindowsDirectory : PChar;
FUNCTION NL : PChar

Changes for Version 2.0

New Functionality:

TStringClass 

Args ARRAY OF CONST type parameters now except VCL text related components

gSc global string class variable

New delim_ExcNull  constant that can applied to ParseDelimToList.

AddFilterDesc
FromComponent method
FromComponentItem method
Grep method
ParseMultiDelimToList method
RecalcLength method procedure
RemoveDirectory method function
 ToComponent method

Bug fixes:

TStringClass  Destroy not virtual
A major bug and cause of memory leaks! Sorry! Somehow the OVERRIDE qualifier was left 
off the end of the Destroy interface declaration.

PadEnd/PadFront/Pad Centre - one character too long.
The Pad functions were adding one too many characters to the padding process.

TObjectContainer: new methods :

FirstThatIdx
ForEachIdx
LastThatIdx

Changes for Version 2.01

TBaseContainer object : AddItem method - duplicates bug
If a duplicate item was being added to a container and Duplicates was set to dupIgnore, this 
method was still reporting an exception error. This has been changed so that with dupIgnore 
active, any attempt to add a duplicate item is ignored with no exception error being created.

TPCharContainer : missing Compare method
The TPCharContainer object was missing a Compare method to enable sorted PChar lists. 
This has been added.


15. Index


A
Add, 7, 29, 31, 39, 40, 45, 50, 51, 54
AddBackSlash, 31
AddDIC, 29
AddFilterDesc, 31
All_Items, 22
AnsiCompareStr, 25
AnsiCompareText, 25
AnsiLowerCase, 24
AnsiUpperCase, 24
Append, 18, 45, 50, 51
AppendBoolean, 18
AppendByte, 19
AppendCh, 19
AppendDIC, 19
AppendDouble, 19
AppendDoubleTrim, 19
AppendExt, 19
AppendExtTrim, 19
AppendLen, 19
AppendLong, 19
AppendMid, 19
AppendNL, 20
AppendPad, 20
AppendPtr, 20
AppendReal, 20
AppendRight, 20
AppendSIC, 20
AppendStr, 24
AppendStringRes, 30
AppendTObject, 13
AppendTrim, 20
AppendWithTab, 20
Assign, 16
AssignFrom, 17
AssignLen, 17
AssignMid, 17
AssignNL, 18
AssignPad, 18
AssignRight, 18
AssignTrim, 18
B
BuildPathName, 32
C
Capacity, 43, 53
Ch, 14
ChCount, 34
Clear, 16, 42
Compare, 28
Compare_EQ, 27, 28
Compare_GT, 27
Compare_LT, 27, 28
CompareDouble, 28
CompareExt, 28
CompareFunc, 43, 53
CompareI, 28
CompareL, 28
CompareLI, 28
CompareLong, 28
CompareStr, 24
CompareText, 24
ContainR, 5
Copy, 16
CopyFrom, 16
Count, 44
Create, 5, 6, 7, 8, 9, 10, 15, 16, 17, 18, 32, 34, 36, 
39, 40, 42, 43, 44, 45, 46, 48, 49, 50, 51
CreateBoolean, 15
CreateDirectory, 32
CreateNL, 15
CreateSize, 15
CreateString, 15
D
DefaultExtension, 32
Delete, 13, 29, 42, 53
DeleteAll, 42
DeleteBlock, 42
DeleteFrom, 29
delim_ExcDIC, 38
delim_ExcNull, 39, 40, 55
delim_ExcSIC, 39
delim_IncDIC, 38, 54
delim_IncSIC, 38, 54
delim_None, 8, 38
Delta, 44
Destroy, 16, 42, 55
DirectoryExists, 32
DriveExists, 32
Duplicates, 44
E
EConvertError, 25
Empty, 16
EStringClass, 10
Exchange, 42
ExpandFileName, 32
F
FBuffer, 12, 16
FileExists, 32
FileSplit, 32
FindBetween2Ch, 34
FindCmdLine, 30, 53
FindCmdLineAndParse, 30
FindCmdLineParam, 30, 53
FindCurrentDir, 32
FindFirst, 34
FindFirstCh, 35
FindIniSectionKeywords, 31
FindLast, 35
FindLastCh, 35
FindNext, 35
FindNextCh, 35
FindPrev, 35
FindPrevCh, 35
FindRelPath, 32, 53
First, 45, 50, 51
FirstCharToUpper, 37
FirstNonSpaceCh, 20
FirstParseDelim, 38
FirstThat, 46
FirstThatIdx, 46
FLength, 12, 16
FloatToStr, 25
FloatToStrF, 25
FMaxSize, 12
FmtLoadStr, 25
ForceExtension, 33
ForEach, 47
ForEachIdx, 47
Format, 25
FormatFloat, 26
FromBoolean, 21
FromByte, 22
FromChar, 22
FromComponent, 22
Working with VCL, 8
FromComponent, 22
FromComponentItem, 22
Working with VCL, 9
FromDouble, 22
FromDoubleTrim, 22
FromExt, 22
FromExtTrim, 22
FromLong, 22
FromPtr, 22
FromReal, 22
FromRealTrim, 23
FromRGB, 23
fs_Directory, 32
fs_extension, 32
fs_Name, 32
FSizeInc, 12
G
GetSystemDirectory, 33
GetWindowsDirectory, 33
Grep, 36
GrowAsRequired, 44
gSc, 10
H
HasBackSlash, 33
HasCh, 21
HasDirectory, 33
HasDrive, 33
HasExtension, 33
HasFileName, 33
HexFromByte, 23
HexFromLong, 23
HexFromPtr, 23
HexFromWord, 23
I
Includes, 29, 48, 50, 51
IndexOf, 48
InitDataMembers, 13
Insert, 29, 48, 50, 51
InsertBlock, 42
InsertL, 29
IntToHex, 25
IntToStr, 25
IsAlphaNumeric, 37
IsCh, 21
IsFirstCh, 21
IsLastCh, 21
IsSame, 28
IsSameI, 28, 53
IsSameL, 28
IsSameLI, 28
IsValidIdent, 25
Items, 49, 50, 51
J
JustDirectory, 33, 53
JustExtension, 33
JustFileName, 33
JustName, 33
L
Last, 48, 50, 51
LastNonSpaceCh, 21
LastThat, 48
LastThatIdx, 48
Length, 14
LoadStr, 25
LoadStringRes, 31
LowerCase, 24
M
MaxSize, 14
Move, 42, 54
N
NextParseDelim, 38
NL, 20
NLAppend, 20
O
Own, 49
P
Pack, 43
PadCentre, 29
PadEnd, 30
PadFront, 30
ParseDelimCount, 38
ParseDelimToList, 38, 54
ParseMultiDelimToList, 40
ParsePosToList, 40
Prepend, 20, 49, 50, 51, 52
R
ReadIniKeyword, 31, 53
RecalcLength, 9, 10, 16, 55
Remove, 49, 50, 51
RemoveAll, 43
RemoveDIC, 30
RemoveDirectory, 33
RemoveLastCh, 21
RemoveSIC, 30
ReplaceAll, 37
ReplaceChAll, 37
ReplaceChFirst, 37
ReplaceChLast, 37
ReplaceFirst, 37
ReplaceLast, 38
Retrieve, 52
S
SameDirectory, 33
SameDrive, 33
SameExtension, 34
SameFileName, 34
SameName, 34
Selected_text, 22
SetCapacity, 54
SetCh, 21
SetCurDir, 34
SizeInc, 14
Sort, 44
SortInPlace, 54
StrCat, 26
StrClass, 5
StrClass.Res, 10
StrClassBaseZero, 6, 9, 13, 14, 17, 18, 19, 20, 21, 
29, 34, 35, 36, 38, 40, 55
Working with VCL, 9
StrClassBaseZero, 6
StrComp, 26
StrCopy, 26
StrECopy, 26
StrEnd, 26
StrIComp, 26
STRINGS, 26
StrLCat, 26
StrLComp, 27
StrLCopy, 27
StrLen, 27
StrLIComp, 26
StrLower, 27
StrMove, 27
StrPas, 27
StrPCopy, 27
StrPos, 27
StrRScan, 27
StrScan, 27
StrToFloat, 26
StrToInt, 25
StrToIntDef, 25
StrUpper, 27
SubStrCount, 37
SysUtils, 4, 24
T
TCollection, 42
TCompareFunc, 43, 44
TEdit, 8
Text, 14
TMemo, 8
TObjectContainer, 8
ToBoolean, 23
ToByte, 23
ToChar, 23
ToComponent, 23
Working with VCL, 9
ToDouble, 23
ToExt, 23
ToLong, 23
ToLower, 37
ToReal, 24
ToRGB, 24
ToUpper, 37
ToWord, 24
Trim, 30
TrimEnd, 30
TrimFront, 30
TrimZero, 30
TWinControl, 8, 23
U
UpperCase, 24
USES, 5
W
Within, 29
WriteIniKeyword, 31
Z
zero based, 5
ZString, 9, 14



Page  



