Format String Syntax

This section describes the format string syntax. Format string is used in format() function and format attribute.

Library format string syntax is not compatible with the standard printf syntax. Instead, it has a different syntax.

The format string has blocks of plain text which are directly copied to the output and parameter placeholders. Each placeholder has the following syntax:

{<param-index>[width-decl][alignment-decl][plus-decl]
[precision-decl][base-decl][padding-decl][ellipsis-decl]
[locale-decl]}

The placeholder must be enclosed in curly braces. If you need to use the opening curly brace in the text, you need to duplicate it to distinguish from the placeholder beginning. There is no need to escape the closing brace, it will always be parsed correctly.

Parameter declaration starts with a parameter’s number. This is the only mandatory field. Parameters are ordered starting from zero. All subsequent declarations are optional. If several declarations are used, their order is not significant and there must be no space or any other separator between them.

width-decl

Use this declaration to limit the minimum and/or maximum length of a rendered parameter, in characters. The syntax of a declaration is one of:

w<min-width>,<max-width>
w<min-width>
w,<max-width>

Both min-width and max-width must be decimal integers and if specified, max-width must be larger than min-width.

alignment-decl

Use this declaration to set parameter alignment. It is ignored unless width-decl is also used. Use one of:

al – align left (default)
ar – align right
ac – align center

plus-decl

Forces the plus sign to be rendered for positive numbers. Syntax:

precision-decl

Use the declaration to specify the number of digits to be displayed after the comma. Used only for floating-point types. If not specified, the default one (6) is used.

p<number>

base-decl

Specify a base for an integer. If any base besides 10 is used with the floating-point type, only the integer part is rendered. Only bases of 2, 8, 10, and 16 are supported. Lowercase or uppercase hexadecimal may be specified:

b2 – binary
b8 – octal
b10 – decimal (default)
b[0]16[x] – lowercase hexadecimal. If prefix “0” is used, library adds “0x” before the number
b[0]16X – uppercase hexadecimal. If prefix “0” is used, library adds “0X” before the number

padding-decl

Set the character to fill the space when min-width is set (see the width-decl above). The default one is space.

f<character>

ellipsis-decl

Add the ellipsis sign when truncating output. It is not compatible with center alignment (will act as left alignment).

locale-decl

Separate thousands with the default user locale's thousand separator. Will work only for base 10.