8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept id="GUID-EC21A1A2-FD5A-5764-A69A-18D74090BA92" xml:lang="en"><title>Format |
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 |
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 |
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> |
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 |
16 <p> Each formatting directive consumes a number of arguments from the trailing |
17 list. Directives have the following syntax: </p> |
17 list. Directives have the following syntax: </p> |
18 <codeblock xml:space="preserve">format directive |
18 <codeblock xml:space="preserve">format directive |
23 escaped percent |
23 escaped percent |
24 %%</codeblock> |
24 %%</codeblock> |
25 <p>Formatting directives begin with a "<codeph>%</codeph> ". To insert a percentage |
25 <p>Formatting directives begin with a "<codeph>%</codeph> ". To insert a percentage |
26 sign, use the digraph "<codeph>%%</codeph> ". </p> |
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> |
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 |
28 <section id="GUID-E6DF6CA4-D6BA-494B-A2B1-CCD63B3DC4A3"><title>Unpadded, dynamic-width |
|
29 formatting </title><codeblock xml:space="preserve">simple-conversion |
29 % |
30 % |
30 conversion-specifier</codeblock><p>Data from the argument list is converted |
31 conversion-specifier</codeblock><p>Data from the argument list is converted |
31 without padding, and only occupies the space required. The <codeph>conversion |
32 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 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 <section id="GUID-35FE3AB2-8B3D-4459-9A8F-8E3688216066"><title>Fixed-width, |
|
35 padded formatting </title><codeblock xml:space="preserve">padded-conversion |
34 % |
36 % |
35 zero-or-space-pad |
37 zero-or-space-pad |
36 field-width |
38 field-width |
37 precision |
39 precision |
38 conversion-specifier |
40 conversion-specifier |
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> |
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> |
52 <li id="GUID-E4398EC7-16CF-5484-9A2D-A4A337F12A9B"><p>If the conversion specifier |
54 <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 |
55 is anything else, then the number of converted characters is limited to the |
54 width value. </p> </li> |
56 width value. </p> </li> |
55 </ul></section> |
57 </ul></section> |
56 <section id="GUID-C4A3149B-B791-4CD8-9E2F-F8BA7D27C0BD"><title>Formatting with alignment, arbitrary pad character and a specified |
58 <section id="GUID-C4A3149B-B791-4CD8-9E2F-F8BA7D27C0BD"><title>Formatting |
57 field width </title><p>Note that for this formatting conversion, only a zero |
59 with alignment, arbitrary pad character and a specified field width </title><p>Note |
58 or a space is permitted for the pad character. </p><codeblock xml:space="preserve">aligned-conversion |
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 |
59 alignment [pad] |
62 alignment [pad] |
60 field-width [precision] |
63 field-width [precision] |
61 conversion-specifier</codeblock><p>The full <codeph>aligned-conversion</codeph> is |
64 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 |
65 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 |
66 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> |
67 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 |
68 <section id="GUID-0E226EE4-FDF2-4ED0-8F4F-82862EEAFE4A"><title>Alignment specifiers</title> <p>Formatted |
66 in characters is less than the width of the field can optionally be aligned |
69 data whose width in characters is less than the width of the field can optionally |
67 to the left, or to the centre of the field. The default is right-alignment. </p> <p>The <codeph>alignment</codeph> specifier |
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 |
68 is a single character with one of the following values: </p> <table id="GUID-D728B8E3-380B-5A78-B4A7-70EBAAB4ACF2"> |
71 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"/> |
72 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
70 <thead> |
73 <thead> |
71 <row> |
74 <row> |
72 <entry>Spec</entry> |
75 <entry>Spec</entry> |
87 <entry><p>Centre alignment </p> </entry> |
90 <entry><p>Centre alignment </p> </entry> |
88 </row> |
91 </row> |
89 </tbody> |
92 </tbody> |
90 </tgroup> |
93 </tgroup> |
91 </table> </section> |
94 </table> </section> |
92 <section id="GUID-80251801-E0A5-4733-AB94-D3311F005F0D"><title>Field width specifiers</title> <p>Data may be formatted into |
95 <section id="GUID-80251801-E0A5-4733-AB94-D3311F005F0D"><title>Field width |
93 a field with a fixed or a dynamic width. Fixed field widths require an extra |
96 specifiers</title> <p>Data may be formatted into a field with a fixed or a |
94 argument. </p> <p>The <codeph>field-width</codeph> specifier is either a sequence |
97 dynamic width. Fixed field widths require an extra argument. </p> <p>The <codeph>field-width</codeph> specifier |
95 of decimal digits which explicitly define the size of the field to be occupied |
98 is either a sequence of decimal digits which explicitly define the size of |
96 by the converted data, or an asterisk ('<codeph>*</codeph>') character. An |
99 the field to be occupied by the converted data, or an asterisk ('<codeph>*</codeph>') |
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 |
100 character. An asterisk indicates that the size of the field is taken from |
98 in the argument list. </p> </section> |
101 the next <xref href="GUID-F9432D7B-41C9-3048-AC50-B5BCF8BE11D0.dita"><apiname>TUint</apiname></xref> value 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 |
102 <section id="GUID-A7B658B7-E137-4FE0-B70C-F2F439A3E33F"><title>Pad characters</title> <p>Formatted |
100 is less than the width of the field can optionally be padded with as many |
103 data whose width in characters is less than the width of the field can optionally |
101 characters as are needed. </p> <p>The <codeph>pad</codeph> character may be |
104 be padded with as many characters as are needed. </p> <p>The <codeph>pad</codeph> character |
102 any non-numeric character (although "<codeph>0</codeph> " can be specified). |
105 may be any non-numeric character (although "<codeph>0</codeph> " can be specified). |
103 If the pad character is an asterisk ("<codeph>*</codeph> "), then the next |
106 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 |
107 argument in the list is read, interpreted as a <codeph>TUint</codeph>, and |
105 used as the pad character. </p> </section> |
108 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 |
109 <section id="GUID-D7578AD1-9749-441E-B7E3-13170B961F1C"><title>Precision specifiers</title> <p>A |
107 introduces a precision specifier. This is only useful when formatting real |
110 dot after a field width introduces a precision specifier. This is only useful |
108 values. Precision specifiers are integers whose decimal values specify the |
111 when formatting real values. Precision specifiers are integers whose decimal |
109 number of decimal places to use when formatting the data. </p> <p>If the precision |
112 values specify the number of decimal places to use when formatting the data. </p> <p>If |
110 specifier is omitted, conversion defaults to <codeph>KDefaultPrecision</codeph> decimal |
113 the precision specifier is omitted, conversion defaults to <codeph>KDefaultPrecision</codeph> decimal |
111 places. </p> </section> |
114 places. </p> </section> |
112 <section id="GUID-B317D693-E5B6-4F6F-90D3-5576B894DEAD"><title>Variable argument positions</title> <p>The format string syntax |
115 <section id="GUID-B317D693-E5B6-4F6F-90D3-5576B894DEAD"><title>Variable argument |
113 was extended in v7.0 to include a way of specifying which argument or argument |
116 positions</title> <p>The format string syntax was extended in v7.0 to include |
114 block should correspond to a conversion specifier. </p> <p>Immediately after |
117 a way of specifying which argument or argument block should correspond to |
115 the initial <codeph>%</codeph> character preceding every conversion specifier, <codeph>$</codeph> <i>x</i> <codeph>$</codeph> may |
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 |
116 optionally be specified, where <i>x</i> is an integer greater than zero. This |
120 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 |
121 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. |
122 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. |
123 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 |
124 For instance an integer field width argument and the data to insert into the |
288 byte first. The generated output is four bytes. </p> <p>(Note the upper case). </p> </entry> |
292 byte first. The generated output is four bytes. </p> <p>(Note the upper case). </p> </entry> |
289 </row> |
293 </row> |
290 </tbody> |
294 </tbody> |
291 </tgroup> |
295 </tgroup> |
292 </table> </section> |
296 </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 |
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 |
294 that the width value and the pad character will be taken from the argument |
299 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 |
300 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>' |
301 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 |
302 '<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 |
303 specified when the data to be converted is not a real number, then it is ignored. </p><b>Related |