Format string syntax

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.

Unpadded, dynamic-width formatting

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.

Fixed-width, padded formatting

padded-conversion
%
zero-or-space-pad
field-width
precision
conversion-specifier
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.

Formatting with alignment, arbitrary pad character and a specified field width

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.

Alignment specifiers

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

Field width specifiers

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.

Pad characters

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.

Precision specifiers

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.

Variable argument positions

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.

Conversion specifiers

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 `TUint` and convert it to its binary character representation. This specifier is case insensitive.
o	Interpret the argument as a `TUint` and convert it to its octal character representation. This specifier is case insensitive.
d	Interpret the argument as a `TInt` and convert it to its signed decimal representation. This specifier is case insensitive. If the value is negative, the representation will be prefixed by a minus sign.
Ld	Interpret the argument as a `TInt64` and convert it to its signed decimal representation. The second character of this specifier is case insensitive, so that the character pair LD has the same meaning. 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 `TInt64`.
i	This is the same as d above, i.e. interpret the argument as a `TInt`.
Li	This is the same as Ld above, i.e. interpret the argument as a `TInt64`.
LI	This is the same as LD above, i.e. interpret the argument as a `TInt64`.
e	Interpret the argument as a `TReal` and convert it to exponent format representation. Three digit exponents are allowed. (See also `TRealFormat`). (Note the lower case)
E	Interpret the argument as a `TRealX`, and convert it to exponent format representation. Three digit exponents are allowed (See also `TRealFormat`). (Note the upper case)
f	Interpret the argument as a `TReal` and convert it to fixed format representation (See `TRealFormat`). (Note the lower case)
F	Interpret the argument as a `TRealX`, and convert it to fixed format representation (See `TRealFormat`). (Note the upper case)
g	Interpret the argument as a `TReal` and convert it to either fixed or exponent format representation, whichever format can present the greater number of significant digits. If the exponent format is chosen, three digit exponents are allowed. (See also `TRealFormat`). (Note the lower case)
G	Interpret the argument as a `TRealX`, and convert it to either fixed or exponent format representation, whichever format can present the greater number of significant digits. If the exponent format is chosen, three digit exponents are allowed. (See also `TRealFormat`). (Note the upper case)
u	Interpret the argument as a `TUint` and convert it to its unsigned decimal representation. This specifier is case insensitive.
Lu	Interpret the argument as a `TUint64` 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.
LU	This is the same as Lu above.
x	Interpret the argument as a `TUint` and convert it to its hexadecimal representation. This specifier is case insensitive.
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 `TUint` value and convert it to a single character value. This specifier is case insensitive.
s	Interpret the argument as a pointer to a `TUint16` type, for 16 bit descriptors, or a `TUint8` 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. (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 `TUint` and convert the value to a two byte binary numeric representation with the least significant byte first. The generated output is two bytes. (Note the lower case).
W	Interpret the argument as a `TUint` and convert the value to a four byte binary numeric representation with the least significant byte first. The generated output is four bytes. (Note the upper case).
m	Interpret the argument as a `TUint` and convert the value to a two byte binary numeric representation with the most significant byte first. The generated output is two bytes. (Note the lower case).
M	Interpret the argument as a `TUint` and convert the value to a four byte binary numeric representation with the most significant byte first. The generated output is four bytes. (Note the upper case).

Notes

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.

Related APIs