Top  Previous  Next

Scripts > Class elements and c++ instructions > Formatting instructions > Syntax


format(  format-string  ) % arg1 % arg2 % ... % argN


The format-string contains text in which special directives will be replaced by strings resulting from the formatting of the given arguments.


Remark: The format syntax is leaned on the one used by printf of the c-language. If you are familiar with printf you can look at Samuel Krempps original documentation at, where some differences of the syntax of the Format library to that of printf is discussed. On top of the standard printf format specifications, new features were implemented, like centered alignment.


Format accepts several forms of directives in format-strings :


Legacy printf format strings : %spec where spec is a printf format specification. This is considered as obsolete in the TextTransformer.


%|spec| where spec is a printf format specification.  The brackets are introduced, to improve the readability of the format-string, but primarily, to make the type-conversion character superfluous in spec, which are necessary in the first form. (Optionally it still can be used.) e.g. : "%|-5|" will format the next variable with width set to 5, and left-alignment (just like the following printf directives : "%-5g", "%-5f", "%-5s" ..)


%N%; this simple positional notation requests the formatting of the N-th argument - without any formatting option.



A specification spec has the form: [ N$ ] [ flags ] [ width ] [ . precision ]


Fields inside square brackets are optional. Each of those fields are explained one by one in the following list:


N $ (optional field) specifies that the format specification applies to the N-th argument. (it is called a positional format specification) If this is not present, arguments are taken one by one. (and it is then an error to later supply an argument number)


flags is a sequences of any of those:





left alignment


centered alignment


internal alignment


show sign even for positive numbers


show numerical base, and decimal point


pad with 0's (inserted after sign or base indicator)

' '

if the string does not begin with + or -, insert a space before the converted string



# width specifies a minimal width for the string resulting form the conversion. If necessary, the string will be padded with alignment and fill characters specified by the format-string (e.g. flags '0', '-', ..)


# precision (preceded by a point), sets the precision


When outputting a floating type number, it sets the maximum number of digits:


       after decimal point when in fixed or scientific mode

       in total when in default mode


When used for a string argument it takes another meaning: the conversion string is truncated to the precision first chars. (Note that the eventual padding to width is done after truncation.)


#  %{nt} , where n is a positive number, inserts an absolute tabulation. It means that format will, if needed, fill the string with characters, until the length of the string created so far reaches n characters. (see examples )


# %{nTX} inserts a tabulation in the same way, but using X as fill character instead of the current 'fill' char (which is space in default state)







This page belongs to the TextTransformer Documentation

Home  Content  German