/** @mainpage

	@section Header

	<center>

	<Table>

	<tr><td>Owner:</td><td>Application Frameworks & Protocols</td></tr>

	<tr><td>Author:</td><td>Leon Clarke</td></tr>

	<tr><td>Last Revised:</td><td>20 March 2002.</td></tr>

	<tr><td>Revision:</td><td>3.0</td></tr>

	<tr><td>Status:</td><td>Released</td></tr>

	<tr><td>Reviewers:</td><td></td></tr>

	<tr><td>Approval:</td><td>(PM) Urmi Shah, (ESM) Akin Oyesola, (Architect) Andrew Baldwin</td></tr>

	</Table>

	</center>

	<hr>

	@section Revision History

	<Table>

	<tr><td>Date</td><td>Version</td><td>Status</td><td>Description</td></tr>

	<tr><td>21-05-2001</td><td>1.0</td><td>Issued</td><td>Issued</td></tr>

	<tr><td>05-07-2001</td><td>1.1</td><td>Added more detail, in particular about static tables.</td><td>Issued</td></tr>

	<tr><td>05-07-2001</td><td>1.2</td><td>Minor editorial changes following T3 review comments.</td><td>Issued</td></tr>

	<tr><td>23-07-2001</td><td>1.3</td><td>Added reference to example code.</td><td>Issued</td></tr>

	<tr><td>09-11-2001</td><td>2.0</td><td>Added mutiple table support and case-sensitive strings</td><td>Issued</td></tr>

	<tr><td>20-03-2002</td><td>3.0</td><td>Incorporated changes following defect fixing</td><td>Released</td></tr>

	</Table>

	@section Introduction

   The string pool is a way of storing strings that makes comparison

   almost instantaneous at the expense of string creation. It is

   particularly efficient at handling string constants that are known

   at compile time. It currently only supports 8 bit strings. The

   basic algorithm is to ensure that the pool only contains one string

   of any particular value, using reference counts to keep track of

   it. Subsequent strings with the same value will actualy refer to

   the same copy.

   To use the string pool, you need an RStringPool object. Strings

   from different string pools can't be compared, so there should only

   be 1 string pool open per thread (unless one is in a component that

   doesn't export its use of the string pool). Of course, you can have

   multiple RStringPool objects, as long as they are all handles to

   the same string pool.

   Within this object, there are 2 distinct pools of strings, one

   comprising strings that are 'case-sensitive' (represented using the

   RString class) and another representing strings that are 'case-insensitive' (RStringF). Case-sensitive strings behave in a

   straightforward way. Case-insensitive strings should be used in a

   situation where case doesn't matter at all; if you create a new

   RStringF that differs from an existing RStringF only in terms of

   case, when you read back the value of the 'new' string, it will

   have the same value as the 'existing' one. This can be very useful

   in situations where strings are considered case-insensitive, but

   there is a 'traditional case' that is normaly used. As long as the

   first value to be added is in the 'traditional case', all

   subsequent additions will be corrected to match this first entry.

   Case-insensitivity assumes a character set of us-ascii (i.e.it only

   considers A-Z to be equivalent to a-z)

   If a string has a more complex or different case-sensitivity

   requirement that this model doesn't match, then it may be necessary

   to compare strings outside the pool, which may make the string pool

   inapplicable.

   Corresponding to RString and RStringF are the classes RStringToken

   and RStringTokenF. These are smaller (4 bytes long rather than 8)

   but need to be turned into String or StringF classes before you can

   do anything useful with them. In particular, you can't directly

   find the contents of a string token. They should be used when space

   is absoluteley at a premium, for instance storing a lot of strings

   in an array, or similar applications.

   @section Static Tables

   A very important aspect of the string pool is the concept of static string

   table. This is best thought of as an array of common

   strings. Integers can be transformed into the strings corresponding

   to that index position in the array via the String and StringF

   functions. In addition, a string can be cast back to an integer,

   allowing a switch statement on strings (it returns -1 if the string

   isn't one from any static table of the pool). Another advantage to using the

   static table is that the function to create the string can't leave,

   and the string doesn't need to be closed (although closing it is

   harmless)

   Multiple case-insensitive and case-sensitive string tables are supported. 

   A static table is written as a .st file, and is processed by

   stringtable.pl early in the build process to generate the actual

   cpp and header files at compile time. The format of the .st file is

   basicaly as follows. The first noncomment line consists of

   fstringtable <TableName> for a case-insensitive table and stringtable <TableName>

   for a case-sensitive table. Each subsequent non-comment line consists

   of the name of an enum followed by the value of the string. Comment

   lines start with # and can be added anywhere. You can also have

   lines starting in !, which will be output into the header file if

   you want additional comments in the header. e.g.

   @code

   # Example String Table

   fstringtable ExampleStringTable

   !// Some types of fruit

   # This comment won't appear in the .h file, but the one above is.

   EApple apple

   EOrange orange

   EBanana banana

   # Some animals

   ECat cat

   EDog dog

   @endcode

   The string table name must be a valid C++ class name, and the

   generated code includes a class that contains within it an enum

   corresponding to the elements in the array, so entries in the above

   example could be referred to as MyStringTable::ECat and so on.

   The stringpool.pl script takes a .st file and creates .cpp and .h

   files of the same name in the same directory. The easiest way to

   use this is to export the .st file to /epoc32/generated/, create an

   extension makefile that runs the script during the makefile phase

   and then copies the generated .h file to epoc32, and then compile

   the .cpp file as normal from an mmp files. Look at the example code

   in //EPOC/main/generic/bafl/docs/stringtableexample/... for a

   simple example of how to do this.

   To be notified when the String Pool is closing you can derive from the mix-in class    MStringPoolCloseCallBack and implement the StringPoolClosing() function. The OpenL(const    TStringTable& aTable, MStringPoolCloseCallBack& aCallBack) overridden function must be    used to register the callback with the String Pool. Where aCallback is the pointer to the    callback. The StringPoolClosing() function will then get called when the String Pool is    closing. 

 **/