![Symbian Developer Library](../../../../../../../a_stock/images/mainheading.gif)
![]() |
![]() |
|
TDes8::Format()
,
TDes16::Format()
and some other functions take a format
string containing literal text embedded with directives for converting a
trailing list of arguments into text. Each formatting directive consumes a
number of arguments from the trailing list. Directives have the following
syntax:
<format-directive>
<escaped-percent>
|
<simple-conversion>
|
<padded-conversion>
|
<aligned-conversion>
<escaped-percent>
%%
Formatting directives begin with a "%
". To insert a
percentage sign, use the digraph "%%
".
Examples of how to use format string syntax are provided in Formatting text.
<simple-conversion>
%
<conversion-specifier>
Data from the argument list is converted without padding, and only occupies the space required. The conversion specifier describes how the data is to be formatted into a string.
<padded-conversion>
%
<zero-or-space-pad>
<field-width>
[ .
<precision>
]
<conversion-specifier>
<zero-or-space-pad>
0
|
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 conversion specifier as follows:
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 KMaxRealWidth
.
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 KDefaultRealWidth
.
If the conversion specifier is anything else, then the number of converted characters is limited to the width value.
Note that for this formatting conversion, only a zero or a space is permitted for the pad character.
<aligned-conversion>
%
<alignment>
[<pad>
]
<field-width>
[ .
<precision>
]
<conversion-specifier>
The full aligned-conversion 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.
Undefined terms are discussed below.
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.
The alignment specifier is a single character with one of the following values:
Spec | Alignment |
---|---|
|
Right alignment |
|
Left alignment |
|
Centre alignment |
Data may be formatted into a field with a fixed or a dynamic width. Fixed field widths require an extra argument.
The field-width 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 ('*
') character. An asterisk
indicates that the size of the field is taken from the next
TUint
value in the argument list.
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.
The pad character may be any non-numeric character
(although "0
" can be specified). If the pad character is an
asterisk ("*
"), then the next argument in the list is read,
interpreted as a TUint
, and used as the pad character.
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.
If the precision specifier is omitted, conversion defaults to
KDefaultPrecision
decimal places.
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.
Immediately after the initial %
character preceding every
conversion specifier,
$
x
$
may optionally be
specified, where x
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.
Examples of this are provided in Formatting text.
The conversion of argument data is dictated by the value of the conversion specifier 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.
The possible values for conversion-specifier are as follows:
Spec | Interpretation and formatting |
---|---|
b |
Interpret the argument as a |
o |
Interpret the argument as a |
d |
Interpret the argument as a If the value is negative, the representation will be prefixed by a minus sign. |
Ld |
Interpret the argument as a If the value is negative, the representation will be prefixed by a minus sign. |
LD |
This is the same as Ld above, i.e. interpret the
argument as a |
i |
This is the same as d above, i.e. interpret the
argument as a |
Li |
This is the same as Ld above, i.e. interpret the
argument as a |
LI |
This is the same as LD above, i.e. interpret the
argument as a |
e |
Interpret the argument as a (Note the lower case) |
E |
Interpret the argument as a (Note the upper case) |
f |
Interpret the argument as a (Note the lower case) |
F |
Interpret the argument as a (Note the upper case) |
g |
Interpret the argument as a
If the exponent format is chosen, three digit exponents are
allowed. (See also (Note the lower case) |
G |
Interpret the argument as a
If the exponent format is chosen, three digit exponents are
allowed. (See also (Note the upper case) |
u |
Interpret the argument as a |
Lu |
Interpret the argument as a |
LU |
This is the same as Lu above. |
x |
Interpret the argument as a |
p |
Generate the required number of pad characters. No arguments are accessed. This specifier is case insensitive. For this directive to be useful, a field with should be specified. |
c |
Interpret the argument as a |
s |
Interpret the argument as a pointer to a (Note the lower case). |
S |
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. (Note the upper case). |
w |
Interpret the argument as a (Note the lower case). |
W |
Interpret the argument as a (Note the upper case). |
m |
Interpret the argument as a (Note the lower case). |
M |
Interpret the argument as a (Note the upper case). |
Using an asterisk for both field-width and
pad means that the width value and the pad character will be
taken from the argument list. Note that the first '*
' will be
interpreted as representing the width only if it is preceded by one of the
alignment characters '+
' '-
' or '=
'.
If precision is specified when the data to be converted is not a real number, then it is ignored.
See also: