|
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-EC21A1A2-FD5A-5764-A69A-18D74090BA92" xml:lang="en"><title>Format |
|
13 string syntax</title><shortdesc><apiname>TDes8::Format()</apiname>, <apiname>TDes16::Format()</apiname> and |
|
14 some other functions take a format string containing literal text embedded |
|
15 with directives for converting a trailing list of arguments into text.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <p> Each formatting directive consumes a number of arguments from the trailing |
|
17 list. Directives have the following syntax: </p> |
|
18 <codeblock xml:space="preserve">format directive |
|
19 escaped-percent |
|
20 simple-conversion |
|
21 padded-conversion |
|
22 aligned-conversion |
|
23 escaped percent |
|
24 %%</codeblock> |
|
25 <p>Formatting directives begin with a "<codeph>%</codeph> ". To insert a percentage |
|
26 sign, use the digraph "<codeph>%%</codeph> ". </p> |
|
27 <p>Examples of how to use format string syntax are provided in <xref href="GUID-0B6C97D3-0E2D-5BBE-B8AC-985902715160.dita#GUID-0B6C97D3-0E2D-5BBE-B8AC-985902715160/GUID-E0D95020-9E74-5FE1-8A84-74FFE8C2CB1E">Formatting text</xref>. </p> |
|
28 <section id="GUID-E6DF6CA4-D6BA-494B-A2B1-CCD63B3DC4A3"><title>Unpadded, dynamic-width formatting </title><codeblock xml:space="preserve">simple-conversion |
|
29 % |
|
30 conversion-specifier</codeblock><p>Data from the argument list is converted |
|
31 without padding, and only occupies the space required. The <codeph>conversion |
|
32 specifier</codeph> describes how the data is to be formatted into a string. </p></section> |
|
33 <section id="GUID-35FE3AB2-8B3D-4459-9A8F-8E3688216066"><title>Fixed-width, padded formatting </title><codeblock xml:space="preserve">padded-conversion |
|
34 % |
|
35 zero-or-space-pad |
|
36 field-width |
|
37 precision |
|
38 conversion-specifier |
|
39 0</codeblock><p>Data from the argument list is converted, but may not occupy |
|
40 more space than specified. If the width of the formatted data is less than |
|
41 the field width, the field is padded to the left with the specified character. |
|
42 If the width of the formatted string is greater than the field width, the |
|
43 result depends on the <codeph>conversion specifier</codeph> as follows: </p><ul> |
|
44 <li id="GUID-25BEB2AC-3A2C-5917-B417-61627F0FB9FC"><p>If the conversion specifier |
|
45 is either: 'e', 'E', 'f', or 'F', i.e. the source data is a real number, then |
|
46 the value of the width is ignored and all generated characters are accepted. |
|
47 However, the maximum number of characters can never exceed the value of <codeph>KMaxRealWidth</codeph>. </p> </li> |
|
48 <li id="GUID-878BB7DB-D66A-5965-AC0A-D058A3455413"><p>If the conversion specifier |
|
49 is either 'g' or 'G', i.e. the source data is a real number, then the value |
|
50 of the width is ignored and all generated characters are accepted. However, |
|
51 the maximum number of characters can never exceed the value of <xref href="GUID-A6F9D2A1-51D7-366A-9F41-90FEBB476B05.dita"><apiname>KDefaultRealWidth</apiname></xref>. </p> </li> |
|
52 <li id="GUID-E4398EC7-16CF-5484-9A2D-A4A337F12A9B"><p>If the conversion specifier |
|
53 is anything else, then the number of converted characters is limited to the |
|
54 width value. </p> </li> |
|
55 </ul></section> |
|
56 <section id="GUID-C4A3149B-B791-4CD8-9E2F-F8BA7D27C0BD"><title>Formatting with alignment, arbitrary pad character and a specified |
|
57 field width </title><p>Note that for this formatting conversion, only a zero |
|
58 or a space is permitted for the pad character. </p><codeblock xml:space="preserve">aligned-conversion |
|
59 alignment [pad] |
|
60 field-width [precision] |
|
61 conversion-specifier</codeblock><p>The full <codeph>aligned-conversion</codeph> is |
|
62 verbose, but in addition to the zero and space characters, it permits non-numeric |
|
63 characters to be specified as the padding character. It also permits its value |
|
64 to be aligned within the field. </p><p>Undefined terms are discussed below. </p></section> |
|
65 <section id="GUID-0E226EE4-FDF2-4ED0-8F4F-82862EEAFE4A"><title>Alignment specifiers</title> <p>Formatted data whose width |
|
66 in characters is less than the width of the field can optionally be aligned |
|
67 to the left, or to the centre of the field. The default is right-alignment. </p> <p>The <codeph>alignment</codeph> specifier |
|
68 is a single character with one of the following values: </p> <table id="GUID-D728B8E3-380B-5A78-B4A7-70EBAAB4ACF2"> |
|
69 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
70 <thead> |
|
71 <row> |
|
72 <entry>Spec</entry> |
|
73 <entry>Alignment</entry> |
|
74 </row> |
|
75 </thead> |
|
76 <tbody> |
|
77 <row> |
|
78 <entry><p> <codeph>+</codeph> </p> </entry> |
|
79 <entry><p>Right alignment </p> </entry> |
|
80 </row> |
|
81 <row> |
|
82 <entry><p> <codeph>-</codeph> </p> </entry> |
|
83 <entry><p>Left alignment </p> </entry> |
|
84 </row> |
|
85 <row> |
|
86 <entry><p> <codeph>=</codeph> </p> </entry> |
|
87 <entry><p>Centre alignment </p> </entry> |
|
88 </row> |
|
89 </tbody> |
|
90 </tgroup> |
|
91 </table> </section> |
|
92 <section id="GUID-80251801-E0A5-4733-AB94-D3311F005F0D"><title>Field width specifiers</title> <p>Data may be formatted into |
|
93 a field with a fixed or a dynamic width. Fixed field widths require an extra |
|
94 argument. </p> <p>The <codeph>field-width</codeph> specifier is either a sequence |
|
95 of decimal digits which explicitly define the size of the field to be occupied |
|
96 by the converted data, or an asterisk ('<codeph>*</codeph>') character. An |
|
97 asterisk indicates that the size of the field is taken from the next <xref href="GUID-F9432D7B-41C9-3048-AC50-B5BCF8BE11D0.dita"><apiname>TUint</apiname></xref> value |
|
98 in the argument list. </p> </section> |
|
99 <section id="GUID-A7B658B7-E137-4FE0-B70C-F2F439A3E33F"><title>Pad characters</title> <p>Formatted data whose width in characters |
|
100 is less than the width of the field can optionally be padded with as many |
|
101 characters as are needed. </p> <p>The <codeph>pad</codeph> character may be |
|
102 any non-numeric character (although "<codeph>0</codeph> " can be specified). |
|
103 If the pad character is an asterisk ("<codeph>*</codeph> "), then the next |
|
104 argument in the list is read, interpreted as a <codeph>TUint</codeph>, and |
|
105 used as the pad character. </p> </section> |
|
106 <section id="GUID-D7578AD1-9749-441E-B7E3-13170B961F1C"><title>Precision specifiers</title> <p>A dot after a field width |
|
107 introduces a precision specifier. This is only useful when formatting real |
|
108 values. Precision specifiers are integers whose decimal values specify the |
|
109 number of decimal places to use when formatting the data. </p> <p>If the precision |
|
110 specifier is omitted, conversion defaults to <codeph>KDefaultPrecision</codeph> decimal |
|
111 places. </p> </section> |
|
112 <section id="GUID-B317D693-E5B6-4F6F-90D3-5576B894DEAD"><title>Variable argument positions</title> <p>The format string syntax |
|
113 was extended in v7.0 to include a way of specifying which argument or argument |
|
114 block should correspond to a conversion specifier. </p> <p>Immediately after |
|
115 the initial <codeph>%</codeph> character preceding every conversion specifier, <codeph>$</codeph> <i>x</i> <codeph>$</codeph> may |
|
116 optionally be specified, where <i>x</i> is an integer greater than zero. This |
|
117 integer is used as a one-based index indicating which argument or block of |
|
118 arguments in the argument list should be used for that conversion specifier. |
|
119 Note that arguments in the argument list may be grouped into argument blocks. |
|
120 For instance an integer field width argument and the data to insert into the |
|
121 field are an argument block and share the same index. </p> <p>Examples of |
|
122 this are provided in <xref href="GUID-0B6C97D3-0E2D-5BBE-B8AC-985902715160.dita#GUID-0B6C97D3-0E2D-5BBE-B8AC-985902715160/GUID-E0D95020-9E74-5FE1-8A84-74FFE8C2CB1E">Formatting |
|
123 text</xref>. </p> </section> |
|
124 <section id="GUID-8B1B622B-4FA4-5B31-908B-7B03F8B851F0"><title>Conversion |
|
125 specifiers</title> <p>The conversion of argument data is dictated by the value |
|
126 of the <i>conversion specifier</i> which can consist of one or more characters; |
|
127 most of the conversion specifiers are just a single character. For some of |
|
128 these specifiers, the case is significant. </p> <p>The possible values for <codeph>conversion-specifier</codeph> are |
|
129 as follows: </p> <table id="GUID-9ECD5627-3AA7-560C-B8CB-93E2EA43CDF0"> |
|
130 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
131 <thead> |
|
132 <row> |
|
133 <entry>Spec</entry> |
|
134 <entry>Interpretation and formatting</entry> |
|
135 </row> |
|
136 </thead> |
|
137 <tbody> |
|
138 <row> |
|
139 <entry><p>b</p> </entry> |
|
140 <entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert it |
|
141 to its binary character representation. This specifier is case insensitive. </p> </entry> |
|
142 </row> |
|
143 <row> |
|
144 <entry><p>o</p> </entry> |
|
145 <entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert it |
|
146 to its octal character representation. This specifier is case insensitive. </p> </entry> |
|
147 </row> |
|
148 <row> |
|
149 <entry><p>d</p> </entry> |
|
150 <entry><p>Interpret the argument as a <codeph>TInt</codeph> and convert it |
|
151 to its signed decimal representation. This specifier is case insensitive. </p> <p>If |
|
152 the value is negative, the representation will be prefixed by a minus sign. </p> </entry> |
|
153 </row> |
|
154 <row> |
|
155 <entry><p>Ld </p> </entry> |
|
156 <entry><p>Interpret the argument as a <codeph>TInt64</codeph> and convert |
|
157 it to its signed decimal representation. The second character of this specifier |
|
158 is case insensitive, so that the character pair <i>LD</i> has the same meaning. </p> <p>If |
|
159 the value is negative, the representation will be prefixed by a minus sign. </p> </entry> |
|
160 </row> |
|
161 <row> |
|
162 <entry><p>LD </p> </entry> |
|
163 <entry><p>This is the same as <i>Ld</i> above, i.e. interpret the argument |
|
164 as a <codeph>TInt64</codeph>. </p> </entry> |
|
165 </row> |
|
166 <row> |
|
167 <entry><p>i</p> </entry> |
|
168 <entry><p>This is the same as <i>d</i> above, i.e. interpret the argument |
|
169 as a <codeph>TInt</codeph>. </p> </entry> |
|
170 </row> |
|
171 <row> |
|
172 <entry><p>Li </p> </entry> |
|
173 <entry><p>This is the same as <i>Ld</i> above, i.e. interpret the argument |
|
174 as a <codeph>TInt64</codeph>. </p> </entry> |
|
175 </row> |
|
176 <row> |
|
177 <entry><p>LI </p> </entry> |
|
178 <entry><p>This is the same as <i>LD</i> above, i.e. interpret the argument |
|
179 as a <codeph>TInt64</codeph>. </p> </entry> |
|
180 </row> |
|
181 <row> |
|
182 <entry><p>e</p> </entry> |
|
183 <entry><p>Interpret the argument as a <codeph>TReal</codeph> and convert it |
|
184 to exponent format representation. Three digit exponents are allowed. (See |
|
185 also <codeph>TRealFormat</codeph>). </p> <p>(Note the lower case) </p> </entry> |
|
186 </row> |
|
187 <row> |
|
188 <entry><p>E</p> </entry> |
|
189 <entry><p>Interpret the argument as a <codeph>TRealX</codeph>, and convert |
|
190 it to exponent format representation. Three digit exponents are allowed (See |
|
191 also <codeph>TRealFormat</codeph>). </p> <p>(Note the upper case) </p> </entry> |
|
192 </row> |
|
193 <row> |
|
194 <entry><p>f</p> </entry> |
|
195 <entry><p>Interpret the argument as a <codeph>TReal</codeph> and convert it |
|
196 to fixed format representation (See <codeph>TRealFormat</codeph>). </p> <p>(Note |
|
197 the lower case) </p> </entry> |
|
198 </row> |
|
199 <row> |
|
200 <entry><p>F</p> </entry> |
|
201 <entry><p>Interpret the argument as a <codeph>TRealX</codeph>, and convert |
|
202 it to fixed format representation (See <codeph>TRealFormat</codeph>). </p> <p>(Note |
|
203 the upper case) </p> </entry> |
|
204 </row> |
|
205 <row> |
|
206 <entry><p>g</p> </entry> |
|
207 <entry><p>Interpret the argument as a <codeph>TReal</codeph> and convert it |
|
208 to either fixed or exponent format representation, whichever format can present |
|
209 the greater number of significant digits. </p> <p>If the exponent format is |
|
210 chosen, three digit exponents are allowed. (See also <codeph>TRealFormat</codeph>). </p> <p>(Note |
|
211 the lower case) </p> </entry> |
|
212 </row> |
|
213 <row> |
|
214 <entry><p>G</p> </entry> |
|
215 <entry><p>Interpret the argument as a <codeph>TRealX</codeph>, and convert |
|
216 it to either fixed or exponent format representation, whichever format can |
|
217 present the greater number of significant digits. </p> <p>If the exponent |
|
218 format is chosen, three digit exponents are allowed. (See also <codeph>TRealFormat</codeph>). </p> <p>(Note |
|
219 the upper case) </p> </entry> |
|
220 </row> |
|
221 <row> |
|
222 <entry><p>u</p> </entry> |
|
223 <entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert it |
|
224 to its unsigned decimal representation. This specifier is case insensitive. </p> </entry> |
|
225 </row> |
|
226 <row> |
|
227 <entry><p>Lu </p> </entry> |
|
228 <entry><p>Interpret the argument as a <codeph>TUint64</codeph> and convert |
|
229 it to its unsigned decimal representation. The second character of this specifier |
|
230 is case insensitive, so that the character pair LU has the same meaning. </p> </entry> |
|
231 </row> |
|
232 <row> |
|
233 <entry><p>LU </p> </entry> |
|
234 <entry><p>This is the same as <i>Lu</i> above. </p> </entry> |
|
235 </row> |
|
236 <row> |
|
237 <entry><p>x</p> </entry> |
|
238 <entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert it |
|
239 to its hexadecimal representation. This specifier is case insensitive. </p> </entry> |
|
240 </row> |
|
241 <row> |
|
242 <entry><p>p</p> </entry> |
|
243 <entry><p>Generate the required number of pad characters. No arguments are |
|
244 accessed. This specifier is case insensitive. </p> <p>For this directive to |
|
245 be useful, a field with should be specified. </p> </entry> |
|
246 </row> |
|
247 <row> |
|
248 <entry><p>c</p> </entry> |
|
249 <entry><p>Interpret the argument as a <codeph>TUint</codeph> value and convert |
|
250 it to a single character value. This specifier is case insensitive. </p> </entry> |
|
251 </row> |
|
252 <row> |
|
253 <entry><p>s</p> </entry> |
|
254 <entry><p>Interpret the argument as a pointer to a <codeph>TUint16</codeph> type, |
|
255 for 16 bit descriptors, or a <codeph>TUint8</codeph> type, for 8 bit descriptors, |
|
256 and copy all data starting at this location up to, but not including the location |
|
257 which contains a zero value. </p> <p>(Note the lower case). </p> </entry> |
|
258 </row> |
|
259 <row> |
|
260 <entry><p>S</p> </entry> |
|
261 <entry><p>In 16 bit descriptors, interpret the argument as a pointer to a |
|
262 16 bit descriptor, and copy the data from it; in 8 bit descriptors, interpret |
|
263 the argument as a pointer to an 8 bit descriptor, and copy the data from it. </p> <p>(Note |
|
264 the upper case). </p> </entry> |
|
265 </row> |
|
266 <row> |
|
267 <entry><p>w</p> </entry> |
|
268 <entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert the |
|
269 value to a two byte binary numeric representation with the least significant |
|
270 byte first. The generated output is two bytes. </p> <p>(Note the lower case). </p> </entry> |
|
271 </row> |
|
272 <row> |
|
273 <entry><p>W</p> </entry> |
|
274 <entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert the |
|
275 value to a four byte binary numeric representation with the least significant |
|
276 byte first. The generated output is four bytes. </p> <p>(Note the upper case). </p> </entry> |
|
277 </row> |
|
278 <row> |
|
279 <entry><p>m</p> </entry> |
|
280 <entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert the |
|
281 value to a two byte binary numeric representation with the most significant |
|
282 byte first. The generated output is two bytes. </p> <p>(Note the lower case). </p> </entry> |
|
283 </row> |
|
284 <row> |
|
285 <entry><p>M</p> </entry> |
|
286 <entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert the |
|
287 value to a four byte binary numeric representation with the most significant |
|
288 byte first. The generated output is four bytes. </p> <p>(Note the upper case). </p> </entry> |
|
289 </row> |
|
290 </tbody> |
|
291 </tgroup> |
|
292 </table> </section> |
|
293 <section id="GUID-D2A688DE-C73C-4086-946A-9A9724D04252"><title>Notes</title> <p>Using an asterisk for both <codeph>field-width</codeph> and <codeph>pad</codeph> means |
|
294 that the width value and the pad character will be taken from the argument |
|
295 list. Note that the first '<codeph>*</codeph>' will be interpreted as representing |
|
296 the width only if it is preceded by one of the alignment characters '<codeph>+</codeph>' |
|
297 '<codeph>-</codeph>' or '<codeph>=</codeph>'. </p> <p>If <codeph>precision</codeph> is |
|
298 specified when the data to be converted is not a real number, then it is ignored. </p><b>Related |
|
299 APIs</b> <ul> |
|
300 <li><p><xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita#GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD/GUID-D7E07487-DCE6-39D9-B4A2-BA7E5BD4A4B9"><apiname>TDes16::AppendFormat()</apiname></xref></p></li> |
|
301 <li><p><xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita#GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD/GUID-F3ED8A38-74C5-3C4D-AEAF-B405A0C5807D"><apiname>TDes16::Format()</apiname></xref></p></li> |
|
302 <li><p><xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita#GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD/GUID-3939029A-12DF-3CBB-9408-B1FF4A1287E6"><apiname>TDes16::AppendFormatList()</apiname></xref></p></li> |
|
303 <li><p><xref href="GUID-BF093552-3EB5-3E0C-BA2B-2DDD11DAE38A.dita#GUID-BF093552-3EB5-3E0C-BA2B-2DDD11DAE38A/GUID-6811EC39-AB32-3BE6-A8BB-0EEFE0F4F683"><apiname>Des16::FormatList()</apiname></xref></p></li> |
|
304 <li><p><xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita#GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507/GUID-E8BE9DD1-2D96-3E8E-943A-CD2ECFD78333"><apiname>TDes8::AppendFormat()</apiname></xref></p></li> |
|
305 <li><p><xref href="GUID-262C74C7-AAF9-3A57-AA33-FE69F460A5C7.dita"><apiname>TDes8:Format()</apiname></xref></p></li> |
|
306 <li><p><xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita#GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507/GUID-8B605683-979A-3505-9755-FEA085BD5427"><apiname>TDes8::AppendFormatList()</apiname></xref></p></li> |
|
307 <li><p><xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita#GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507/GUID-1380E737-F4C4-3D6F-9B9B-B0ED267B6BFF"><apiname>TDes8::FormatList()</apiname></xref></p></li> |
|
308 </ul></section> |
|
309 </conbody></concept> |