String Pools

Key features of string pool

• The string pool as supplied by the Symbian platform supports any strings that can be represented by a TDes8 descriptor; this includes ASCII or UTF-8 encoded strings. Note that a TDes8 type can represent any type of data , including binary data, and means that a string pool can easily handle the extended characters of another encoding.

• Within the string pool, strings are of two types - case sensitive and case insensitive. This affects the way strings are compared. Case insensitivity implies that strings are folded for the purpose of comparison.

• A string pool can contain up to 4,096 static string tables, and each table can represent up 26,2144 strings.

Static string tables

Static string tables are defined and built at compile time. They are represented by a TStringTable object. A string table can be added to the string pool by passing the string table reference to a call to:

void RStringTable::OpenL( const TStringTable& aTable );

The following diagram illustrates a general picture. Note that the strings in any given string table are deemed to be either case sensitive or case insensitive, and this governs how comparisons are made.

As the name implies, a static string table is declared as a const TStringTable data member of a class with a user-defined name. The class name is defined in a header file while the table itself is implemented in a .cpp C++ source file. Both the header file and the C++ source file are normally included in the project definition. Typically, a set of enum values are also defined within the scope of the class, and each value is associated with the strings in the table; code in other parts of the program access the strings in the string pool using these enum values.

The Perl script, stringtable.pl, located in ...\syslibs\bafl\stringtools\, can be used to generate these .cpp and .h files from a simple text definition. The text definition file simply lists the strings and the enum symbols to be associated with them; the file itself is given a .st file type.

Following is a simple example of ExampleStringTable.st file:

# Example String Table
fstringtable ExampleStringTable
!// Some types of fruit
# This comment won't appear in the .h file, but the one above will.
EApple apple
EOrange orange
EBanana banana
# Some animals
ECat cat
EDog dog

The main points to note are:

• the keyword fstringtable is used to define the name of the class that contains the string table declaration and the enum value symbols. The class name itself follows the keyword. For example, ExampleStringTable.

  Note that you can include underscore characters in the class name. For example, Example_StringTable.

• the symbols EApple and EOrange form the enum value symbols that correspond to the strings apple and orange respectively.

• all statements starting with a # are comments and are completely ignored. However # characters can appear in a string. For example ap#ple is a valid string and is not interpreted as a comment.

• all statements starting with a ! are comments that are inserted into the generated header file.

Running the Perl script with ExampleStringTable.st as source generates the header file ExampleStringTable.h and the C++ source file ExampleStringTable.cpp as illustrated below:

// Autogenerated from epoc32\build\generated\example\ExampleStringTable.st by the stringtable tool - Do not edit

#ifndef STRINGTABLE_ExampleStringTable
#define STRINGTABLE_ExampleStringTable

#include "StringPool.h"

struct TStringTable;

/** A String table */
class ExampleStringTable 
       {
    public:
           enum TStrings
              {
              // Some types of fruit
              /** apple */
              EApple,
              /** orange */
              EOrange,
              /** banana */
              EBanana,
              /** cat */
              ECat,
              /** dog */
              EDog
              };
       static const TStringTable Table;    
       };

#endif // STRINGTABLE_ExampleStringTable

// Autogenerated from epoc32\build\generated\example\ExampleStringTable.st by the stringtable tool - Do not edit
#include <e32std.h>
#include "StringPool.h"
#include "StringTableSupport.h"
#include "ExampleStringTable.h"
#ifdef _DEBUG
#undef _DEBUG
#endif

_STLIT8( K1, "apple" );
_STLIT8( K2, "orange" );
_STLIT8( K3, "banana" );
_STLIT8( K4, "cat" );
_STLIT8( K5, "dog" );

// Intermediate
const void * const KStringPointers[] =
       {
       ( const void* )&K1,
       ( const void* )&K2,
       ( const void* )&K3,
       ( const void* )&K4,
       ( const void* )&K5
       };

const TStringTable ExampleStringTable::Table = {5, KStringPointers, EFalse};

The table itself is the static data member Table of class ExampleStringTable.