|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-27340D18-A31D-512E-920A-B06C784A978A" xml:lang="en"><title>String |
|
13 Pools </title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Many systems, components and applications deal with pre-defined, well known |
|
15 string constants. For example, parsing and manipulating text containing structure |
|
16 mostly requires comparisons against standard string constants. </p> |
|
17 <p>In a complex system, composed of a large number of objects, there may also |
|
18 be a need to pass strings between objects, and to route processing depending |
|
19 on the value of some string. The implementation of the HTTP transport framework |
|
20 and the XML framework are examples within the Symbian platform where such |
|
21 intense string handling is required. </p> |
|
22 <p>To improve efficiency, the Symbian platform uses the idea of the string |
|
23 pool. </p> |
|
24 <p>A string pool is referenced through an <xref href="GUID-4BF6ECD3-5FB3-3A6A-B9CE-98871BD0812B.dita"><apiname>RStringPool</apiname></xref>, |
|
25 which is a handle like object. The following diagram illustrates the basic |
|
26 idea: </p> |
|
27 <fig id="GUID-756DB8BA-1D6F-56AE-9C93-66DD3512B4A7"> |
|
28 <title> String pool representation </title> |
|
29 <image href="GUID-7F8F6ABB-8F46-5486-A116-6965787BC539_d0e183943_href.png" placement="inline"/> |
|
30 </fig> |
|
31 <p>A string pool is a mechanism for storing strings in a particular way that |
|
32 makes the comparison of strings a very fast operation. It is particularly |
|
33 efficient at handling strings that can be set up at program compile time. |
|
34 For example, strings that identify lexical elements in a structured text. |
|
35 Typically, they are well known strings that are likely to be used very often |
|
36 in a given context. </p> |
|
37 <p>Such strings are organised into tables, and each string within a table |
|
38 can be referenced by an index value, which can be symbolised by an enum. Such |
|
39 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 |
|
40 that the pool contains only one string of any particular value, and uses a |
|
41 reference counting mechanism to keep track of usage. </p> |
|
42 <p>The advantages of representing string constants in such a way are: </p> |
|
43 <ul> |
|
44 <li id="GUID-DE544092-1FA8-5537-8357-62510F42D2EA"><p>avoiding a proliferation |
|
45 of duplicate strings throughout a component or an application; typically there |
|
46 is one string pool per thread, and one copy of a string </p> </li> |
|
47 <li id="GUID-55E5FD27-5E2B-51D6-91AA-435AE1A4421C"><p>allowing string constants |
|
48 to be represented by integer values </p> </li> |
|
49 <li id="GUID-3C5CA539-11E1-53EB-8A1F-69AEF0D9C1F0"><p>allowing strings to |
|
50 be passed between objects by passing integer values, wrapped in a class (any |
|
51 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> |
|
52 <li id="GUID-559BCA58-B426-5919-A948-DC15ED501397"><p>allowing strings to |
|
53 be compared by comparing the integer values. </p> </li> |
|
54 </ul> |
|
55 <p>Internally, a string pool uses hash tables to reference strings. </p> |
|
56 <p>Static string tables and string constants can be added dynamically to the |
|
57 string pool, for example, at run time. However, there is always a performance |
|
58 penalty while adding either a static or a dynamic string to the string pool |
|
59 as the hash tables need to be updated. This means that it is better to add |
|
60 static string tables at string pool initialisation time, as this is the best |
|
61 time to absorb the overhead. </p> |
|
62 <section id="GUID-B2F3D713-6BCA-4A47-99E4-EC4886F857EA"><title>Key features of string pool</title> <ul> |
|
63 <li id="GUID-39F73513-7F37-57DA-AF7A-D3A7B2B28A76"><p>The string pool as supplied |
|
64 by the Symbian platform supports any strings that can be represented |
|
65 by a <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> descriptor; this includes ASCII or UTF-8 encoded |
|
66 strings. Note that a <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> type can represent any type |
|
67 of data , including binary data, and means that a string pool can easily handle |
|
68 the extended characters of another encoding. </p> </li> |
|
69 <li id="GUID-8F9BA578-B6B5-54FD-8C29-8C2996AED4D0"><p>Within the string pool, |
|
70 strings are of two types - case sensitive and case insensitive. This affects |
|
71 the way strings are compared. Case insensitivity implies that strings are |
|
72 folded for the purpose of comparison. </p> </li> |
|
73 <li id="GUID-D958763A-70F8-5452-A556-99F92B2B0246"><p>A string pool can contain |
|
74 up to 4,096 static string tables, and each table can represent up 26,2144 |
|
75 strings. </p> </li> |
|
76 </ul> </section> |
|
77 <section id="GUID-8221E235-15F9-55E9-8C17-4015051F70CD"><title>Static string |
|
78 tables</title> <p>Static string tables are defined and built at compile time. |
|
79 They are represented by a <xref href="GUID-91322CD6-6DA0-3868-A5D7-CA561A102074.dita"><apiname>TStringTable</apiname></xref> object. A string |
|
80 table can be added to the string pool by passing the string table reference |
|
81 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 |
|
82 in any given string table are deemed to be either case sensitive or case insensitive, |
|
83 and this governs how comparisons are made. </p> <fig id="GUID-D7CEA86C-0643-5BDA-A60E-D80B97008BF2"> |
|
84 <image href="GUID-ECACB935-AD19-5BE6-AC27-A63465244087_d0e184050_href.png" placement="inline"/> |
|
85 </fig> <p>As the name implies, a static string table is declared as a <codeph>const |
|
86 TStringTable</codeph> data member of a class with a user-defined |
|
87 name. The class name is defined in a header file while the table itself is |
|
88 implemented in a <codeph>.cpp</codeph> C++ source file. Both the header file |
|
89 and the C++ source file are normally included in the project definition. Typically, |
|
90 a set of enum values are also defined within the scope of the class, and each |
|
91 value is associated with the strings in the table; code in other parts of |
|
92 the program access the strings in the string pool using these enum values. </p> <p>The |
|
93 Perl script, <codeph>stringtable.pl</codeph>, located in <filepath>...\syslibs\bafl\stringtools\</filepath>, |
|
94 can be used to generate these <codeph>.cpp</codeph> and <codeph>.h</codeph> files |
|
95 from a simple text definition. The text definition file simply lists the strings |
|
96 and the enum symbols to be associated with them; the file itself is given |
|
97 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 |
|
98 fstringtable ExampleStringTable |
|
99 !// Some types of fruit |
|
100 # This comment won't appear in the .h file, but the one above will. |
|
101 EApple apple |
|
102 EOrange orange |
|
103 EBanana banana |
|
104 # Some animals |
|
105 ECat cat |
|
106 EDog dog |
|
107 </codeblock> <p>The main points to note are: </p> <ul> |
|
108 <li id="GUID-8FCB19B1-7033-5120-98DD-08EECA91C65B"><p>the keyword <i>fstringtable</i> is |
|
109 used to define the name of the class that contains the string table declaration |
|
110 and the enum value symbols. The class name itself follows the keyword. For |
|
111 example, <codeph>ExampleStringTable</codeph>. </p> <p>Note that you can include |
|
112 underscore characters in the class name. For example, <codeph>Example_StringTable</codeph>. </p> </li> |
|
113 <li id="GUID-0E714FA5-859E-597F-9B33-2F0DC3372FCD"><p>the symbols <codeph>EApple</codeph> and <codeph>EOrange</codeph> form |
|
114 the enum value symbols that correspond to the strings <codeph>apple</codeph> and <codeph>orange</codeph> respectively. </p> </li> |
|
115 <li id="GUID-F9F62AD7-5209-5D01-9F60-413C7E161689"><p>all statements starting |
|
116 with a <b>#</b> are comments and are completely ignored. However <b>#</b> characters |
|
117 can appear in a string. For example <codeph>ap#ple</codeph> is a valid string |
|
118 and is not interpreted as a comment. </p> </li> |
|
119 <li id="GUID-F70C2B1A-2029-5B1A-A27D-A65A123A6CA9"><p>all statements starting |
|
120 with a <b>!</b> are comments that are inserted into the generated header file. </p> </li> |
|
121 </ul> <p>Running the Perl script with <codeph>ExampleStringTable.st</codeph> as |
|
122 source generates the header file <codeph>ExampleStringTable.h</codeph> and |
|
123 the C++ source file <codeph>ExampleStringTable.cpp</codeph> as illustrated |
|
124 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 |
|
125 |
|
126 #ifndef STRINGTABLE_ExampleStringTable |
|
127 #define STRINGTABLE_ExampleStringTable |
|
128 |
|
129 #include "StringPool.h" |
|
130 |
|
131 struct TStringTable; |
|
132 |
|
133 /** A String table */ |
|
134 class ExampleStringTable |
|
135 { |
|
136 public: |
|
137 enum TStrings |
|
138 { |
|
139 // Some types of fruit |
|
140 /** apple */ |
|
141 EApple, |
|
142 /** orange */ |
|
143 EOrange, |
|
144 /** banana */ |
|
145 EBanana, |
|
146 /** cat */ |
|
147 ECat, |
|
148 /** dog */ |
|
149 EDog |
|
150 }; |
|
151 static const TStringTable Table; |
|
152 }; |
|
153 |
|
154 #endif // STRINGTABLE_ExampleStringTable |
|
155 </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 |
|
156 #include <e32std.h> |
|
157 #include "StringPool.h" |
|
158 #include "StringTableSupport.h" |
|
159 #include "ExampleStringTable.h" |
|
160 #ifdef _DEBUG |
|
161 #undef _DEBUG |
|
162 #endif |
|
163 |
|
164 _STLIT8( K1, "apple" ); |
|
165 _STLIT8( K2, "orange" ); |
|
166 _STLIT8( K3, "banana" ); |
|
167 _STLIT8( K4, "cat" ); |
|
168 _STLIT8( K5, "dog" ); |
|
169 |
|
170 // Intermediate |
|
171 const void * const KStringPointers[] = |
|
172 { |
|
173 ( const void* )&K1, |
|
174 ( const void* )&K2, |
|
175 ( const void* )&K3, |
|
176 ( const void* )&K4, |
|
177 ( const void* )&K5 |
|
178 }; |
|
179 |
|
180 const TStringTable ExampleStringTable::Table = {5, KStringPointers, EFalse}; |
|
181 </codeblock> <p>The table itself is the static data member <codeph>Table</codeph> of |
|
182 class <codeph>ExampleStringTable</codeph>. </p> </section> |
|
183 </conbody><related-links> |
|
184 <link href="GUID-24D509E8-CF46-58D3-85E9-27DA7AB22012.dita"><linktext>Constructing |
|
185 a Static String Table</linktext></link> |
|
186 <link href="GUID-2B6D7221-A23E-562E-9D9C-5EC197F1CB78.dita"><linktext>Using string |
|
187 pools</linktext></link> |
|
188 </related-links></concept> |