--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-27340D18-A31D-512E-920A-B06C784A978A.dita Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,188 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-27340D18-A31D-512E-920A-B06C784A978A" xml:lang="en"><title>String
+Pools </title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>Many systems, components and applications deal with pre-defined, well known
+string constants. For example, parsing and manipulating text containing structure
+mostly requires comparisons against standard string constants. </p>
+<p>In a complex system, composed of a large number of objects, there may also
+be a need to pass strings between objects, and to route processing depending
+on the value of some string. The implementation of the HTTP transport framework
+and the XML framework are examples within the Symbian platform where such
+intense string handling is required. </p>
+<p>To improve efficiency, the Symbian platform uses the idea of the string
+pool. </p>
+<p>A string pool is referenced through an <xref href="GUID-4BF6ECD3-5FB3-3A6A-B9CE-98871BD0812B.dita"><apiname>RStringPool</apiname></xref>,
+which is a handle like object. The following diagram illustrates the basic
+idea: </p>
+<fig id="GUID-756DB8BA-1D6F-56AE-9C93-66DD3512B4A7">
+<title> String pool representation </title>
+<image href="GUID-7F8F6ABB-8F46-5486-A116-6965787BC539_d0e183943_href.png" placement="inline"/>
+</fig>
+<p>A string pool is a mechanism for storing strings in a particular way that
+makes the comparison of strings a very fast operation. It is particularly
+efficient at handling strings that can be set up at program compile time.
+For example, strings that identify lexical elements in a structured text.
+Typically, they are well known strings that are likely to be used very often
+in a given context. </p>
+<p>Such strings are organised into tables, and each string within a table
+can be referenced by an index value, which can be symbolised by an enum. Such
+tables are referred to as <b>static string tables</b> (See <xref href="GUID-27340D18-A31D-512E-920A-B06C784A978A.dita#GUID-27340D18-A31D-512E-920A-B06C784A978A/GUID-8221E235-15F9-55E9-8C17-4015051F70CD">Static string tables</xref>). The basic algorithm used internally ensures
+that the pool contains only one string of any particular value, and uses a
+reference counting mechanism to keep track of usage. </p>
+<p>The advantages of representing string constants in such a way are: </p>
+<ul>
+<li id="GUID-DE544092-1FA8-5537-8357-62510F42D2EA"><p>avoiding a proliferation
+of duplicate strings throughout a component or an application; typically there
+is one string pool per thread, and one copy of a string </p> </li>
+<li id="GUID-55E5FD27-5E2B-51D6-91AA-435AE1A4421C"><p>allowing string constants
+to be represented by integer values </p> </li>
+<li id="GUID-3C5CA539-11E1-53EB-8A1F-69AEF0D9C1F0"><p>allowing strings to
+be passed between objects by passing integer values, wrapped in a class (any
+one of the <xref href="GUID-C117EB69-0B1E-3D16-88E1-B44349C716DE.dita"><apiname>String</apiname></xref> and <xref href="GUID-B886F0AA-DB9C-356C-9B96-33252820F93E.dita"><apiname>RStringF</apiname></xref> classes) </p> </li>
+<li id="GUID-559BCA58-B426-5919-A948-DC15ED501397"><p>allowing strings to
+be compared by comparing the integer values. </p> </li>
+</ul>
+<p>Internally, a string pool uses hash tables to reference strings. </p>
+<p>Static string tables and string constants can be added dynamically to the
+string pool, for example, at run time. However, there is always a performance
+penalty while adding either a static or a dynamic string to the string pool
+as the hash tables need to be updated. This means that it is better to add
+static string tables at string pool initialisation time, as this is the best
+time to absorb the overhead. </p>
+<section id="GUID-B2F3D713-6BCA-4A47-99E4-EC4886F857EA"><title>Key features of string pool</title> <ul>
+<li id="GUID-39F73513-7F37-57DA-AF7A-D3A7B2B28A76"><p>The string pool as supplied
+by the Symbian platform supports any strings that can be represented
+by a <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> descriptor; this includes ASCII or UTF-8 encoded
+strings. Note that a <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> 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. </p> </li>
+<li id="GUID-8F9BA578-B6B5-54FD-8C29-8C2996AED4D0"><p>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. </p> </li>
+<li id="GUID-D958763A-70F8-5452-A556-99F92B2B0246"><p>A string pool can contain
+up to 4,096 static string tables, and each table can represent up 26,2144
+strings. </p> </li>
+</ul> </section>
+<section id="GUID-8221E235-15F9-55E9-8C17-4015051F70CD"><title>Static string
+tables</title> <p>Static string tables are defined and built at compile time.
+They are represented by a <xref href="GUID-91322CD6-6DA0-3868-A5D7-CA561A102074.dita"><apiname>TStringTable</apiname></xref> object. A string
+table can be added to the string pool by passing the string table reference
+to a call to: </p> <codeblock id="GUID-2FAB371D-74A4-5D7E-99F1-B7C02BEDA8D5" xml:space="preserve">void RStringTable::OpenL( const TStringTable& aTable );</codeblock> <p>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. </p> <fig id="GUID-D7CEA86C-0643-5BDA-A60E-D80B97008BF2">
+<image href="GUID-ECACB935-AD19-5BE6-AC27-A63465244087_d0e184050_href.png" placement="inline"/>
+</fig> <p>As the name implies, a static string table is declared as a <codeph>const
+ TStringTable</codeph> 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 <codeph>.cpp</codeph> 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. </p> <p>The
+Perl script, <codeph>stringtable.pl</codeph>, located in <filepath>...\syslibs\bafl\stringtools\</filepath>,
+can be used to generate these <codeph>.cpp</codeph> and <codeph>.h</codeph> 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 <codeph>.st</codeph> file type. </p> <p>Following is a simple example of <codeph>ExampleStringTable.st</codeph> file: </p> <codeblock id="GUID-5D487C02-D710-55E6-BD8D-769BE4C4E754" xml:space="preserve"># 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
+</codeblock> <p>The main points to note are: </p> <ul>
+<li id="GUID-8FCB19B1-7033-5120-98DD-08EECA91C65B"><p>the keyword <i>fstringtable</i> 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, <codeph>ExampleStringTable</codeph>. </p> <p>Note that you can include
+underscore characters in the class name. For example, <codeph>Example_StringTable</codeph>. </p> </li>
+<li id="GUID-0E714FA5-859E-597F-9B33-2F0DC3372FCD"><p>the symbols <codeph>EApple</codeph> and <codeph>EOrange</codeph> form
+the enum value symbols that correspond to the strings <codeph>apple</codeph> and <codeph>orange</codeph> respectively. </p> </li>
+<li id="GUID-F9F62AD7-5209-5D01-9F60-413C7E161689"><p>all statements starting
+with a <b>#</b> are comments and are completely ignored. However <b>#</b> characters
+can appear in a string. For example <codeph>ap#ple</codeph> is a valid string
+and is not interpreted as a comment. </p> </li>
+<li id="GUID-F70C2B1A-2029-5B1A-A27D-A65A123A6CA9"><p>all statements starting
+with a <b>!</b> are comments that are inserted into the generated header file. </p> </li>
+</ul> <p>Running the Perl script with <codeph>ExampleStringTable.st</codeph> as
+source generates the header file <codeph>ExampleStringTable.h</codeph> and
+the C++ source file <codeph>ExampleStringTable.cpp</codeph> as illustrated
+below: </p> <codeblock id="GUID-7E0263D1-D4A5-5B0A-B355-C2D958247590" xml:space="preserve">// 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
+</codeblock> <codeblock id="GUID-6447B06C-00EB-527C-8381-7239F2220D61" xml:space="preserve">// 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};
+</codeblock> <p>The table itself is the static data member <codeph>Table</codeph> of
+class <codeph>ExampleStringTable</codeph>. </p> </section>
+</conbody><related-links>
+<link href="GUID-24D509E8-CF46-58D3-85E9-27DA7AB22012.dita"><linktext>Constructing
+a Static String Table</linktext></link>
+<link href="GUID-2B6D7221-A23E-562E-9D9C-5EC197F1CB78.dita"><linktext>Using string
+pools</linktext></link>
+</related-links></concept>
\ No newline at end of file