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

 

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

flags - character or characters that control justification of output and adding of signs, blanks, decimal points, and octal and hexadecimal prefixes.

width - number that specifies the minimum number of characters in output.

precision - number that specifies the maximum number of characters used for all or part of the output field, or the minimum number of digits used for integer values.

h, l, I64, L - character that specifies argument size. For arguments of type long, use I64. Note: here I is uppercase i, not lowercase L.

 

Remarks

%% in format strings is replaced with %.

 

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

 

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.

 

Char. Type Output format
     
i, d integer Signed decimal integer. Example: int i=5; out "i=%i" i
u integer Unsigned decimal integer.
x integer Unsigned hexadecimal integer, using "abcdef."
X integer Unsigned hexadecimal integer, using "ABCDEF."
e double Signed value having the form [ - ]d.dddd e [sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or -.
E double Identical to the e format except that E rather than e introduces the exponent.
f double Signed value having the form [ - ]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision.
g double Signed value in f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than -4 or greater than or equal to the precision field. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.
G double Identical to the g format, except that E, rather than e, introduces the exponent (where appropriate).
s string Characters are added up to the first null character or until the precision value is reached.
S word* QM 2.3.3. Unicode UTF-16 string. Example: BSTR b="utf-16 string"; out "%S" b.pstr
c integer

Character code.

Note: In Unicode mode, don't use non ASCII characters.

C integer QM 2.3.3. Unicode UTF-16 character code. Must be <0x10000.
m pointer QM 2.3.3. Binary data. Length must be specified using precision. Example: _s.format("%.*m" 10 ptr) ;;10 bytes from ptr
m byte QM 2.3.3. Fill with an ASCII character. Length must be specified using precision. Example: out "%.*m" 4 '*' ;;****. For character code 0 use argument value 0x100.

 

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.

 

Flag Meaning Default
- Left align the result within the given field width. Right align.
+ Prefix the output value with a sign (+ or -) if the output value is of a signed type. Sign appears only for negative signed values (-).
0 If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and - appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored. No padding.
space Prefix the output value with a space if the output value is signed and positive; the blank is ignored if both the space and + flags appear. No blank appears.
# When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively. No blank appears.
# When used with the e, E, or f format, the # flag forces the output value to contain a decimal point in all cases. Decimal point appears only if digits follow it.
# When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros.
Decimal point appears only if digits follow it. Trailing zeros are truncated.
#

QM 2.3.3. When used with the s format, # specifies that precision is the number of characters, not bytes. In Unicode mode, non-ASCII characters have several bytes. Example: out "%#.5s" "ąčęėįšųūž"

 

 

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:

 

Type Meaning Default
c, C precision has no effect.  
d, i, u, o, x, X precision specifies the minimum number of digits to be added. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision. Default precision is 1.
e, E precision specifies the number of digits to be added after the decimal point. The last added digit is rounded. Default precision is 6; if precision is 0 or if . appears without a number following it, no decimal point is added.
f precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. Default precision is 6; if precision is 0 or if . appears without a number following it, no decimal point is added.
g, G precision specifies the maximum number of significant digits added. Six significant digits are added, with any trailing zeros truncated.
s, S

precision specifies the maximum number of characters to be added. Characters in excess of precision are not added.

 

Note: With s, precision is the number of bytes. In Unicode mode, non-ASCII characters have several bytes. In QM 2.3.3 and later you can use flag # to specify that precision must be number of characters. Example: out "%#.5s" "ąčęėįšųūž"

Characters are added until a null character is encountered.
m precision specifies the number of bytes to be added. 0

 

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:

To specify Use prefix With type
int l d, i, o, x, or X
unsigned int l u
signed word h d, i, o, x, or X
word h u
long I64 d, i, o, u, x, or X
Single-byte character h c or C
Wide character l c or C
Single-byte character string h s or S
Wide-character string l s or S