Printf Format Specifier Syntax

This section discusses the format specifier fields that may appear in format strings passed to the Formatted I/O Printf methods. The Printf methods format the data provided by input arguments. The formatted data is created by replacing each format specifier in the format parameter with the corresponding parameter argument, formatted according to the format specifier. The data is formatted as ASCII strings, IEEE 488.2 arbitrary blocks, and raw binary blocks.

For further details, see:

Printf Format Specifier Overview

Printf format strings may include zero or more format specifiers, each of which provides information about how to format one of the variable arguments to Printf.

Format specifiers for Printf are very similar to those for the VISA viPrintf function, though there are some differences. For example, 'a', 'A', 'C', 'n', 'p', and 'S' are not supported in VISA.NET.

A basic format specifier always starts with a '%' (percent character) and ends with a format type, which indicates the data type of the value to be formatted. For example, "%d" is a format specifier that will print a signed integer as a sequence of decimal digits. If the integer is negative, it will be preceded by a minus sign (-).

A variety of optional modifiers are supported to provide a rich set of formatting options. Note that some modifiers are not valid with some format types, and some modifiers have different meanings, depending on the type.

The general syntax of a VISA.NET format specifier is:

"%[flags][width][.precision][,[arraySize]][sizeModifier]type"

For example:

%+@3d

The above format specifier uses the '+' and '@3' flags. It prints a signed integer in scientific notation, with a plus sign if the integer is non-negative and a minus sign if it is negative.

For each format specifier, there is one value argument that corresponds to the format specifier type, and there may be additional dynamic arguments (indicated by a '*' in the specifier) that provide information about the format specifier's modifiers. In the argument list, the dynamic arguments for a format specifier always come before the value argument. Printf formats a value (from a value argument) using a format specifier that may need additional information from dynamic arguments to be complete.

For example, calling Printf with a format specifier of "[%-*.*s]" and arguments of 10, 20, and "John" prints the string "[John ]". In this example, the first dynamic argument, 10, is the width - the minimum number of characters to print. The second dynamic argument, 20, is the precision – the maximum number of characters to print: If the string to be printed were longer than 20 characters, only twenty would be printed. The '-' indicates that if the string is shorter than the number of characters to be printed, the string should be left-justified and, by default, padded with spaces.

Not all combinations of modifiers and types are meaningful. For example, "%#@Hd" is invalid because of two ambiguities:

It is not clear whether the number should be formatted as a decimal integer (as indicated by the "d") or a hexadecimal integer (as indicated by the "@H").
If it is formatted as a hexadecimal number, it is not clear if it should be formatted with a "0x" or "0X" prefix (as indicated by the "#") or with a "#H" prefix (as indicated by the "@H").

Invalid combinations of modifiers and types are noted in Printf Modifiers. In addition, some size modifiers which could be inconsistent when used with certain types are ignored. These are also noted in Printf Modifiers.