Using String Pool

Adding tables to a string pool

1. Create a string pool with no static string tables. This is, in effect an empty string pool. Static string tables can be added later. Use the following variant of OpenL():

   void RStringPool::OpenL()

2. Add a static string table to the pool by using the following variant of OpenL().

   void RStringPool::OpenL( const TStringTable& aTable )

   This function creates the string pool, if it doesn't already exist, before adding the string table. Use the same function to add further string tables whenever required.

There is a variation on the OpenL() function that provides a mechanism for notifying when the string pool is being closed. Following is the variant:

void OpenL(const TStringTable& aTable, MStringPoolCloseCallBack& aCallBack);

Closing the string pool is performed using the RStringPool::Close() function. It closes all open references to the string pool. This may be important in environments where asynchronous programming techniques is used. Provide an implementation of the MStringPoolCloseCallBack to handle the situation.

Note: The implementation assumes that the string tables remain in existence and are located at the same address for as long as the string pool remains open. This assumption is almost always justified as the tables are static data.

Accessing strings in a string pool

Accessing strings involves getting a handle to a string in the string pool. These handles are instances of RString and RStringF classes, which are used in the code to represent strings.

RString represents a case-sensitive string. For example, a string that is compared in a case-sensitive manner.

RStringF represents a case-insensitive string. For example, when you compare two RStringF objects where the represented strings only differ in terms of case, the two strings are considered identical.

Follow the steps given below to create an RString to represent a specific string:

Note: Creating an RStringF object is same as creating an RString. Where RString is discussed, this information also applies to RStringF:

1. Create an RString to represent a specific string in a static string table by using the variant,

   RString RStringPool::String( TInt aIndex,const TStringTable& aTable ) const;

   pass the reference to the specific string table and the index number that identifies the string. Based on the example string table illustrated in Static String Tables section, the following code is a commonly used pattern to generate an RString. Here we generate an RString to represent the string "banana". The code does no error handling and ignores leave situations.

   #include <>
   
   RStringPool thepool;
   RString thebanana;
   ...
   thepool.OpenL( ExampleStringTable::Table );
   thebanana = thepool.String( ExampleStringTable::EBanana,ExampleStringTable::Table );
   ...

   In more sophisticated code, and where there is more than one static string table, use a function or a member function of some class to retrieve that TStringTable reference. The following is a common pattern:

   void X::Foo( CSomeClass aInstance,... )
       {
       ...
       thebanana = thepool.String( ExampleStringTable::EBanana,aInstance.GetTable() );
       ...
       }

   where GetTable() is a function that returns a reference to a specific TStringTable.

2. Create an RString to represent a string that may not exist in any existing static string table within the string pool. Use the following function:

   RString  RStringPool::OpenStringL( const TDesC8& aString ) const;

   Following is an example of dynamically adding a string to the pool (which also generates the RString to represent it). If the string already exists in a static string table, then the string value itself is not added; instead a new reference to the existing string is created. The following is a simple code fragment:

   class X
       {
   public :
       ...
       void Foo( const TDesC8& aString,... );
       ...
       }

   void X::Foo( aString,... )
       {
       ...
       RString theString;
       theString = thepool.OpenStringL( aString );
       ...
       }

Retrieving a string from a string pool

Given an RString object (or an RStringF), you can retrieve the string value itself. To retrieve the string value, use the DesC() function that is provided by the RStringBase base class of RString and RStringF classes.

For example:

class X
    {
    public :
        ...
        void Foo( RString aString, ... );
        ...
    }

void X::Foo( aString )
    {
    const TDesC8& stringValue = aString.DesC();
    ...
    }

Comparing strings in a string pool

Comparing strings becomes a fast and simple process once an RString handle (or an RStringF) has been created. A common use is to route processing based on the value of the string, for example:

class X
    {
    public :
        ...
        void Foo( RString aString,... );
        ...
    }

void X::Foo( aString,... )
    {
    ...
    switch( aString )
        {
        case ExampleStringTable::EBanana :
            {
            // do something
            }
        case ExampleStringTable::EOrange :
            {
            // do something
            }
        ...
        }
    }