<?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-EC21A1A2-FD5A-5764-A69A-18D74090BA92" xml:lang="en"><title>Format

string syntax</title><shortdesc><codeph>TDes8::Format()</codeph>, <codeph>TDes16::Format()</codeph> and

some other functions take a format string containing literal text embedded

with directives for converting a trailing list of arguments into text.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p> Each formatting directive consumes a number of arguments from the trailing

list. Directives have the following syntax: </p>

<codeblock xml:space="preserve">format directive

escaped-percent

simple-conversion

padded-conversion

aligned-conversion

escaped percent

%%</codeblock>

<p>Formatting directives begin with a "<codeph>%</codeph> ". To insert a percentage

sign, use the digraph "<codeph>%%</codeph> ". </p>

<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>

<section id="GUID-E6DF6CA4-D6BA-494B-A2B1-CCD63B3DC4A3"><title>Unpadded, dynamic-width

formatting </title><codeblock xml:space="preserve">simple-conversion

%

conversion-specifier</codeblock><p>Data from the argument list is converted

without padding, and only occupies the space required. The <codeph>conversion

specifier</codeph> describes how the data is to be formatted into a string. </p></section>

<section id="GUID-35FE3AB2-8B3D-4459-9A8F-8E3688216066"><title>Fixed-width,

padded formatting </title><codeblock xml:space="preserve">padded-conversion

%

zero-or-space-pad

field-width

precision

conversion-specifier

0</codeblock><p>Data from the argument list is converted, but may not occupy

more space than specified. If the width of the formatted data is less than

the field width, the field is padded to the left with the specified character.

If the width of the formatted string is greater than the field width, the

result depends on the <codeph>conversion specifier</codeph> as follows: </p><ul>

<li id="GUID-25BEB2AC-3A2C-5917-B417-61627F0FB9FC"><p>If the conversion specifier

is either: 'e', 'E', 'f', or 'F', i.e. the source data is a real number, then

the value of the width is ignored and all generated characters are accepted.

However, the maximum number of characters can never exceed the value of <codeph>KMaxRealWidth</codeph>. </p> </li>

<li id="GUID-878BB7DB-D66A-5965-AC0A-D058A3455413"><p>If the conversion specifier

is either 'g' or 'G', i.e. the source data is a real number, then the value

of the width is ignored and all generated characters are accepted. However,

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>

<li id="GUID-E4398EC7-16CF-5484-9A2D-A4A337F12A9B"><p>If the conversion specifier

is anything else, then the number of converted characters is limited to the

width value. </p> </li>

</ul></section>

<section id="GUID-C4A3149B-B791-4CD8-9E2F-F8BA7D27C0BD"><title>Formatting

with alignment, arbitrary pad character and a specified field width </title><p>Note

that for this formatting conversion, only a zero or a space is permitted for

the pad character. </p><codeblock xml:space="preserve">aligned-conversion

alignment	[pad]

field-width		[precision]

conversion-specifier</codeblock><p>The full <codeph>aligned-conversion</codeph> is

verbose, but in addition to the zero and space characters, it permits non-numeric

characters to be specified as the padding character. It also permits its value

to be aligned within the field. </p><p>Undefined terms are discussed below. </p></section>

<section id="GUID-0E226EE4-FDF2-4ED0-8F4F-82862EEAFE4A"><title>Alignment specifiers</title> <p>Formatted

data whose width in characters is less than the width of the field can optionally

be aligned to the left, or to the centre of the field. The default is right-alignment. </p> <p>The <codeph>alignment</codeph> specifier

is a single character with one of the following values: </p> <table id="GUID-D728B8E3-380B-5A78-B4A7-70EBAAB4ACF2">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Spec</entry>

<entry>Alignment</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>+</codeph> </p> </entry>

<entry><p>Right alignment </p> </entry>

</row>

<row>

<entry><p> <codeph>-</codeph> </p> </entry>

<entry><p>Left alignment </p> </entry>

</row>

<row>

<entry><p> <codeph>=</codeph> </p> </entry>

<entry><p>Centre alignment </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section id="GUID-80251801-E0A5-4733-AB94-D3311F005F0D"><title>Field width

specifiers</title> <p>Data may be formatted into a field with a fixed or a

dynamic width. Fixed field widths require an extra argument. </p> <p>The <codeph>field-width</codeph> specifier

is either a sequence of decimal digits which explicitly define the size of

the field to be occupied by the converted data, or an asterisk ('<codeph>*</codeph>')

character. An 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 in the argument list. </p> </section>

<section id="GUID-A7B658B7-E137-4FE0-B70C-F2F439A3E33F"><title>Pad characters</title> <p>Formatted

data whose width in characters is less than the width of the field can optionally

be padded with as many characters as are needed. </p> <p>The <codeph>pad</codeph> character

may be any non-numeric character (although "<codeph>0</codeph> " can be specified).

If the pad character is an asterisk ("<codeph>*</codeph> "), then the next

argument in the list is read, interpreted as a <codeph>TUint</codeph>, and

used as the pad character. </p> </section>

<section id="GUID-D7578AD1-9749-441E-B7E3-13170B961F1C"><title>Precision specifiers</title> <p>A

dot after a field width introduces a precision specifier. This is only useful

when formatting real values. Precision specifiers are integers whose decimal

values specify the number of decimal places to use when formatting the data. </p> <p>If

the precision specifier is omitted, conversion defaults to <codeph>KDefaultPrecision</codeph> decimal

places. </p> </section>

<section id="GUID-B317D693-E5B6-4F6F-90D3-5576B894DEAD"><title>Variable argument

positions</title> <p>The format string syntax was extended in v7.0 to include

a way of specifying which argument or argument block should correspond to

a conversion specifier. </p> <p>Immediately after the initial <codeph>%</codeph> character

preceding every conversion specifier, <codeph>$</codeph> <i>x</i> <codeph>$</codeph> may

optionally be specified, where <i>x</i> is an integer greater than zero. This

integer is used as a one-based index indicating which argument or block of

arguments in the argument list should be used for that conversion specifier.

Note that arguments in the argument list may be grouped into argument blocks.

For instance an integer field width argument and the data to insert into the

field are an argument block and share the same index. </p> <p>Examples of

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

text</xref>. </p> </section>

<section id="GUID-8B1B622B-4FA4-5B31-908B-7B03F8B851F0"><title>Conversion

specifiers</title> <p>The conversion of argument data is dictated by the value

of the <i>conversion specifier</i> which can consist of one or more characters;

most of the conversion specifiers are just a single character. For some of

these specifiers, the case is significant. </p> <p>The possible values for <codeph>conversion-specifier</codeph> are

as follows: </p> <table id="GUID-9ECD5627-3AA7-560C-B8CB-93E2EA43CDF0">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Spec</entry>

<entry>Interpretation and formatting</entry>

</row>

</thead>

<tbody>

<row>

<entry><p>b</p> </entry>

<entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert it

to its binary character representation. This specifier is case insensitive. </p> </entry>

</row>

<row>

<entry><p>o</p> </entry>

<entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert it

to its octal character representation. This specifier is case insensitive. </p> </entry>

</row>

<row>

<entry><p>d</p> </entry>

<entry><p>Interpret the argument as a <codeph>TInt</codeph> and convert it

to its signed decimal representation. This specifier is case insensitive. </p> <p>If

the value is negative, the representation will be prefixed by a minus sign. </p> </entry>

</row>

<row>

<entry><p>Ld </p> </entry>

<entry><p>Interpret the argument as a <codeph>TInt64</codeph> and convert

it to its signed decimal representation. The second character of this specifier

is case insensitive, so that the character pair <i>LD</i> has the same meaning. </p> <p>If

the value is negative, the representation will be prefixed by a minus sign. </p> </entry>

</row>

<row>

<entry><p>LD </p> </entry>

<entry><p>This is the same as <i>Ld</i> above, i.e. interpret the argument

as a <codeph>TInt64</codeph>. </p> </entry>

</row>

<row>

<entry><p>i</p> </entry>

<entry><p>This is the same as <i>d</i> above, i.e. interpret the argument

as a <codeph>TInt</codeph>. </p> </entry>

</row>

<row>

<entry><p>Li </p> </entry>

<entry><p>This is the same as <i>Ld</i> above, i.e. interpret the argument

as a <codeph>TInt64</codeph>. </p> </entry>

</row>

<row>

<entry><p>LI </p> </entry>

<entry><p>This is the same as <i>LD</i> above, i.e. interpret the argument

as a <codeph>TInt64</codeph>. </p> </entry>

</row>

<row>

<entry><p>e</p> </entry>

<entry><p>Interpret the argument as a <codeph>TReal</codeph> and convert it

to exponent format representation. Three digit exponents are allowed. (See

also <codeph>TRealFormat</codeph>). </p> <p>(Note the lower case) </p> </entry>

</row>

<row>

<entry><p>E</p> </entry>

<entry><p>Interpret the argument as a <codeph>TRealX</codeph>, and convert

it to exponent format representation. Three digit exponents are allowed (See

also <codeph>TRealFormat</codeph>). </p> <p>(Note the upper case) </p> </entry>

</row>

<row>

<entry><p>f</p> </entry>

<entry><p>Interpret the argument as a <codeph>TReal</codeph> and convert it

to fixed format representation (See <codeph>TRealFormat</codeph>). </p> <p>(Note

the lower case) </p> </entry>

</row>

<row>

<entry><p>F</p> </entry>

<entry><p>Interpret the argument as a <codeph>TRealX</codeph>, and convert

it to fixed format representation (See <codeph>TRealFormat</codeph>). </p> <p>(Note

the upper case) </p> </entry>

</row>

<row>

<entry><p>g</p> </entry>

<entry><p>Interpret the argument as a <codeph>TReal</codeph> and convert it

to either fixed or exponent format representation, whichever format can present

the greater number of significant digits. </p> <p>If the exponent format is

chosen, three digit exponents are allowed. (See also <codeph>TRealFormat</codeph>). </p> <p>(Note

the lower case) </p> </entry>

</row>

<row>

<entry><p>G</p> </entry>

<entry><p>Interpret the argument as a <codeph>TRealX</codeph>, and convert

it to either fixed or exponent format representation, whichever format can

present the greater number of significant digits. </p> <p>If the exponent

format is chosen, three digit exponents are allowed. (See also <codeph>TRealFormat</codeph>). </p> <p>(Note

the upper case) </p> </entry>

</row>

<row>

<entry><p>u</p> </entry>

<entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert it

to its unsigned decimal representation. This specifier is case insensitive. </p> </entry>

</row>

<row>

<entry><p>Lu </p> </entry>

<entry><p>Interpret the argument as a <codeph>TUint64</codeph> and convert

it to its unsigned decimal representation. The second character of this specifier

is case insensitive, so that the character pair LU has the same meaning. </p> </entry>

</row>

<row>

<entry><p>LU </p> </entry>

<entry><p>This is the same as <i>Lu</i> above. </p> </entry>

</row>

<row>

<entry><p>x</p> </entry>

<entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert it

to its hexadecimal representation. This specifier is case insensitive. </p> </entry>

</row>

<row>

<entry><p>p</p> </entry>

<entry><p>Generate the required number of pad characters. No arguments are

accessed. This specifier is case insensitive. </p> <p>For this directive to

be useful, a field with should be specified. </p> </entry>

</row>

<row>

<entry><p>c</p> </entry>

<entry><p>Interpret the argument as a <codeph>TUint</codeph> value and convert

it to a single character value. This specifier is case insensitive. </p> </entry>

</row>

<row>

<entry><p>s</p> </entry>

<entry><p>Interpret the argument as a pointer to a <codeph>TUint16</codeph> type,

for 16 bit descriptors, or a <codeph>TUint8</codeph> type, for 8 bit descriptors,

and copy all data starting at this location up to, but not including the location

which contains a zero value. </p> <p>(Note the lower case). </p> </entry>

</row>

<row>

<entry><p>S</p> </entry>

<entry><p>In 16 bit descriptors, interpret the argument as a pointer to a

16 bit descriptor, and copy the data from it; in 8 bit descriptors, interpret

the argument as a pointer to an 8 bit descriptor, and copy the data from it. </p> <p>(Note

the upper case). </p> </entry>

</row>

<row>

<entry><p>w</p> </entry>

<entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert the

value to a two byte binary numeric representation with the least significant

byte first. The generated output is two bytes. </p> <p>(Note the lower case). </p> </entry>

</row>

<row>

<entry><p>W</p> </entry>

<entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert the

value to a four byte binary numeric representation with the least significant

byte first. The generated output is four bytes. </p> <p>(Note the upper case). </p> </entry>

</row>

<row>

<entry><p>m</p> </entry>

<entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert the

value to a two byte binary numeric representation with the most significant

byte first. The generated output is two bytes. </p> <p>(Note the lower case). </p> </entry>

</row>

<row>

<entry><p>M</p> </entry>

<entry><p>Interpret the argument as a <codeph>TUint</codeph> and convert the

value to a four byte binary numeric representation with the most significant

byte first. The generated output is four bytes. </p> <p>(Note the upper case). </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<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

that the width value and the pad character will be taken from the argument

list. Note that the first '<codeph>*</codeph>' will be interpreted as representing

the width only if it is preceded by one of the alignment characters '<codeph>+</codeph>'

'<codeph>-</codeph>' or '<codeph>=</codeph>'. </p> <p>If <codeph>precision</codeph> is

specified when the data to be converted is not a real number, then it is ignored. </p><b>Related

APIs</b> <ul>

<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>

<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>

<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>

<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>

<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>

<li><p><xref href="GUID-262C74C7-AAF9-3A57-AA33-FE69F460A5C7.dita"><apiname>TDes8:Format()</apiname></xref></p></li>

<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>

<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>

</ul></section>

</conbody></concept>