The general syntax of the format specification implies that there is a set of arguments (or elements if array or a collection variants of the methods are used) which are replaced in the format string in the order in which they appear. For example the first argument will be used for the first control escape, the second for the second control escape and so on.

The format string consists of text and embedded control escapes.  Each control escape begins with the % character and ends according to the syntax specified below. To output a % character you need to repeat the % twice - e.g. a "%%" in the format string will produce only one "%" in the output.

The general syntax for a control escape sequence is:

%[[name] | (index)] [flags] [width] [.precision] [{h | l}] [N] type

As it is shown above only the type part is required. The other parts are specified if more detailed control over the format is needed.

Here are the descriptions of each part:

[name] | (index)

Optionally you can use one of the both - name or index specified immediately after the % character to break the natural order of the parameters formatted into the output. 

name:  If specified it is enclosed in [] - for example "something %[name1]020d" means argument named "name1" to be formatted in 20 chars wide field padded with zeros. The name must be less then 255 characters long. This feature will have any effect only if the method in which the format string is specified uses a parameter source which supports names. For instance specifying name with Sprintf or SAprintf will have no effect while in SCprintf it will work ok - as long as the collection/dictionary object supplied as argument supports names. After the named argument is fetched and formatted one argument is skipped in the internal argument index. Thus if the first escape names an argument which is let say 5-th in the collection and the second escape sequence does not use [name] nor (index) it will fetch the second argument - not the first! See the notice below for useful recommendations.

Is it case sensitive? This depends on the source (e.g. in SCprintf the collection/dictionary object passed as argument). If it treats the names in case insensitive manner the name will be case insensitive if not the case will matter. Try to lookup this information in the collection object documentation. Most collections use case-insensitive names, but there are exceptions. 

index: (added in axpack1 version 2.4.5.0) If specified it is enclosed in () - for example "something %(2)020d" means argument 2  to be formatted in 20 chars wide field padded with zeros. The number should be positive and is 0 - based. This feature works with all the printf methods. Note that using index breaks the natural order of the parameters. Therefore the next parameter fetched will be the index + 1 argument! For example:

o.Sprintf("%d,%(2)d,%d,%(1)d",0,1,2,3) will return "0,2,3,1" - i.e. the 3-d escape will fetch the next argument after the argument number 2 which means the last argument, instead of fetching the 3-d argument as you may expect.

The index is 0 based even if in SCprintf you use as argument a collection that is 1-based. The SCprintf will automatically recognize the collection base index and transpose the indices internally.

Notice

It is recommended to use [name] and (index) specifications for all the format sequences in the format string or for none at all. If named/indexed and unnamed and non-indexed specifications are mixed the result can be misleading because of the changes to the natural order in which the arguments are fetched. Of course, you can calculate carefully what will happen after using [name] or (index), but still this can be a source for human made mistakes. 

negative (index) is accepted by the format parser, but is not currently used for anything. This is reserved for future versions.  

Flags

The flags are single characters found first in the escape command sequence. If the combination is meaningful more than one flag can be specified.

Width

Specifies the minimum width of the field in which the value will be placed. If the value requires more space the field width will be extended to fit. When the value is shorter it is padded left or right with blanks or 0-s (according to the flags and default behaviors specified in the Flags section).

Width is non-negative decimal integer or a * character. In case of * the function fetches the next argument/element and tries to convert it to integer that specifies the actual field width to be used.

Precision

Non-negative integer preceded with . that specifies the number of characters or decimal places for the value. The effect depends on the type as follows:

d,i,u,o,x,X - The minimal number of digits. The number is padded with zeros to fit the precision specified. Default is 1.

e,E - Number of digits after the decimal point.

f - The 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.

g,G - The precision specifies the maximum number of significant digits printed

Currently has no effect over the other types. You should not use it if no effect is expected in order to avoid incompatibility with future versions.

Type modifiers

One of h or l (small L) can be specified to modify the size of the type to which the argument is converted. They have effect on the following types as follows:

N - Allow nulls. If specified this allows the argument to be Null and the NullName is put instead of error.

The L (capital L) is not used in the current version, but it is reserved for future functionality extensions.

Types

Each type character instructs the function to fetch the next argument and try to convert it to a certain type. If this succeeds it is formatted according to the other parameters specified before it in the escape command sequence (the flags, width, precision etc.). If the argument cannot be converted an error occurs (it states the index of the argument at which it has been occurred). If the argument is Null (VT_NULL VARIANT type) error occurs unless N is specified before the type, which allows the Null-s to be displayed with the name specified by the NullName property.