Register
Home Projects Help
History

Format String Reference

The syntax of a format specifier for a single argument is: ‘{‘ [ index ] [ ’,’ alignment ] [ ’:’ subformat ] ‘}’.
  • index – specifies which argument to output (starting at 0)
  • alignment – defines the minimum (but not maximum) width of the output, positive values append spaces on the left side, negative values on the right side

Just like Tango’s Layout, the actual type of the passed in argument defines permitted subformat strings for that argument.
The general syntax for a subformat specifier is: style parameter, where style is a single character and parameter is a positive number.

Unlike in Tango, escaping the ‘{‘ character is done using a slash; ‘}’ in nested format specifiers needs to be escaped as well.

Strings

Strings have no subformat, they are formatted as-is. UTF width conversion is performed as necessary.

Integers

Integer formatting follows that of Tango. The following styles are defined:
  • d – signed decimal
  • u – unsigned decimal
  • b – binary
  • o – octal
  • x, X – hexadecimal

Style defaults to ‘d’ or ‘u’, depending on actual type.

Example: 

sformat ("0x{:X10}", 0xdeadbeef); // returns "0x00DEADBEEF"

Floating point values

Floating point formatting follows that of Tango. The following styles are defined:
  • f – decimal notation
  • e, E – scientific notation

Style defaults to ‘f’.

Example: 

sformat ("{:f2}", 1.234); // returns "1.23"

Pointers

The following styles are defined:
  • p – output hexadecimal value of pointer, with 0x prepended
  • * – output value pointed to by pointer
  • z – output zero-terminated array (for character pointers only)

Style ‘p’ has no additional parameters.
Style ’*’ can be followed by a nested format specifier requesting formatting of the dereferenced value.
Style ‘z’ can be followed by a number limiting the maximum length of the zero-terminated array.
Style defaults to ‘p’.

Example: 

char* lpstr = "foobar".ptr;
formatln ("{0} {0:z5}", lpstr); // outputs "0x######## fooba" 

uint x = 0xdeadbeef;
uint* px = &x;
formatln ("{:*{:x}}", px); // outputs "deadbeef"

Linear arrays

Subformat syntax is: [ separator ] [ nested_format ].
  • separator is a sequence of characters used to delimit array members, defaults to ”, ”
  • nested_format is a format specifier used for each array member, defaults to “{}”

Example: 

sformat ("IP={0:.}, hex={0:{:X2}}", [192, 168, 1, 1]); // returns "IP=192.168.1.1, hex=C0A80101"

tango.time.Time.Time type

Formatting this type uses tango.text.locale.Convert.formatDateTime.

Composite types (structs, classes, interfaces, unions)

In general composite types have no defined formatting operation and requesting their formatting raises a compile-time error.
It is however possible to implement formatting for composite types by defining one or more of these methods inside:
  • uint opFormat (char[] format, uint delegate (char[]) sink)
  • uint opFormat (wchar[] format, uint delegate (wchar[]) sink)
  • uint opFormat (dchar[] format, uint delegate (dchar[]) sink)

These methods should perform output by calling sink and return the total number of characters written.

If a formatting operation was requested that used a character type for which opFormat was not overloaded, one of the other opFormat implementations will be used and UTF conversion performed automatically.

Export to HTML, TXT