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; almost always one. Directives have the following syntax:

Formatting directives begin with a "%". To insert a percentage sign, use the digraph "%%".

Unpadded, dynamic-width formatting. Data from the argument list is converted without padding, and only occupies the space required. The conversion specifier descibes how the data is to be formatted into a string.

Fixed-width, padded formatting. 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 specifieras 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 specfier 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.

Formatting with alignment, arbitrary pad character and a specified field width. The full aligned-conversion is verbose, but permits characters other than a zero or a space to be used 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. Dynamic 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 non-blank characters as are needed.

The pad character may be any non-numeric character. 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. This feature may be used to pad with asterisk characters or a digit.

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 conversion of argument data is dictated by the value of the conversion specifier which consists of a single character. The case of this character 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 can be either upper or lower case. o Interpret the argument as a TUint and convert it to its octal character representation. This can be either upper or lower case. d Interpret the argument as a TInt and convert it to its signed decimal representation. This can be either upper or lower case. If the value is negative, the representation will be prefixed by a minus sign. 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 (or TReal96 in EPOC Release 5), 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 (or TReal96 in EPOC Release 5), 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 (or TReal96 in EPOC Release 5), 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 can be either upper or lower case. x Interpret the argument as a TUint and convert it to its hexadecimal representation. This can be either upper or lower case. p Generate the required number of pad characters. No arguments are accessed. This can be either upper or lower case. 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 can be either upper or lower case. 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 Interpret the argument as a pointer to a 16 bit descriptor and copy the characters 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. Should only be used to format 8 bit descriptors — it is meaningless for 16 bit descriptors. (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. Should only be used to format 8 bit descriptors — it is meaningless for 16 bit descriptors. (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. Should only be used to format 8 bit descriptors — it is meaningless for 16 bit descriptors. (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. Should only be used to format 8 bit descriptors — it is meaningless for 16 bit descriptors. (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.