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