Format fields

Format fields are used in strings with functions str.format, out, paste and operator F. A format field is a special character, or several characters, preceded with %. The whole string is followed by variables or other values that will replace the format fields. The format fields tell how to format the values.

Syntax

%[flags][width][.precision][h|l|I64|L]type

Remarks

%% in format strings is replaced with %.

Almost everything is the same as with C/C++ printf, sprintf and similar functions. Differences:

• Does not add "(null)" for null strings.
• QM 2.3.3. Supports binary data (%m).

Example

int i=50
str s="stringvar"
double d=3.1415926535897932384626433832795
str f
f.format("variables: i=%i, s=''%s'', d=%.10G" i s d)
out f ;;variables: i=50, s="stringvar", d=3.141592654

Type

type is a character that determines whether the argument is interpreted as a number, string, character, etc.

Flags

flags is a character that justifies output and adds signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag may appear in a format field.

Width

width is a decimal integer controlling the minimum number of characters added. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values (depending on whether the - flag (for left alignment) is specified) until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers).

The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if width is not given, all characters of the value are added.

If the width specification is an asterisk (*), an int argument from the argument list supplies the value. The width argument must precede the value being formatted in the argument list. Example: out "%*s" 20 "string"

Precision

precision is a nonnegative decimal integer, preceded by dot (.), which specifies the number of characters to be added, the number of decimal places, or the number of significant digits. Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value.

The type determines the interpretation of precision and the default when precision is omitted, as shown in table:

Example:

str s.format("%.4s %.3f" "123456789" 1.12345)
out s ;;1234 1.123

If the precision specification is an asterisk (*), an int argument from the argument list supplies the value. The precision argument must precede the value being formatted in the argument list. Example:

str s.format("%.*s %.*f" 4 "123456789" 3 1.12345)
out s ;;1234 1.123

Argument size

For arguments of type long need to specify size I64. Example:

long k=123456789012345
out "incorrect: %i" k
out "correct: %I64i" k

For arguments of other types usually don't need to specify size. But anyway, here is the table: