8.8. Formatting printed numbers

In various places in VisIt’s interfaces (both the GUI and the CLI), there is often the need to control the formatting of printed numerical data to specify such things as the number of significant digits or whether to use a fixed point (e.g. 123.456) or an exponential format (e.g. 1.23e+02).

In many places in VisIt’s interface, a printf-style formatting specification string is used to handle this. This involves a percent sign (%), followed by several other fields of the general form

%[flags][width][.precision][length]type

where fields in square brackets are optional and within the context of VisIt, [length] should almost always be ignored. The table below provides a number of examples.

Format string

Result

Remarks

value is "31415.92653589793" as double type

%f

"31415.926536"

f is fixed point

%e

"3.141593e+04"

e is exponential

%g

"31415.9"

g yeilds e or f form depending on value (see below)

%a

"0x1.eadfb4c5d390bp+14"

%a dumps actual memory

%3.1g

"3e+04"

width=3, .precision=1

%10.1f

"   31415.9"

width=10, .precision=1

%10.1g

"     3e+04"

here, g yields e form

%12.1g

"       3e+04"

default is right justification

%-12.4g

"3.142e+04   "

left justification

% 12.4g

"   3.142e+04"

note space after %

%+12.4g

"  +3.142e+04"

always show a + or - sign

%012.4G

"0003.142E+04"

leading 0’s, cap E not e

value is "1234" as int type

%d / %i

"1234"

%u

"1234"

u treats data as unsigned

%08d

"00001234"

width 8 with leading zeros

%o

"2322"

print as octal

08X

"000004D2"

print as hexidecimal (caps)

value is "Einstein" as char* type

%s

"Einstein"

%16.5s

"           Einst"

5 chars, right justified

%-16.5s

"Einst           "

5 chars, left justified

By default, VisIt uses %g for most numerical data which uses a default [.precision] of 6 and a default [width] which is automatically determined based on the actual data value to be printed according to the rules below.

For precision p >= 1, this rounds the number to p significant digits and then formats the result in either fixed-point or scientific notation, depending on its magnitude.

Suppose that the result formatted with type specifier e and precision p-1 would have exponent exp. Then if -4 <= exp < p, the number is formatted with type specifier f (e.g. fixed point format) and precision p-1-exp. Otherwise, the number is formatted with type specifier e (e.g. exponential format) and precision p-1. In both cases insignificant trailing zeros are removed from the significand, and the decimal point is also removed if there are no remaining digits following it. Positive and negative infinity, positive and negative zero, and nans, are formatted as inf, -inf, 0, -0 and nan respectively, regardless of the precision. A precision of 0 is treated as equivalent to a precision of 1. The default precision is 6.

Often, users are interested in controlling only [width] and [.precision] as in, for example, %8.5g. In this example, the width of 8, is the minimum number of characters. If the value to be printed requires fewer than this number of characters, the result is padded with blank spaces. The value is never truncated even if the result will use more than the minimum number of characters. The precision of .5 means to print 5 digits after the decimal point. The type specification of g is the general type specification for floating point type data as described above.

The only time the [length] field may be needed is if the user is certain that the data being handled internally by VisIt is some unusual size (e.g. long long or short). In these circumstances, a [length] field may also be needed.

The full printf-style formatting specification is quite flexible and general allowing a lot of control over how numerical data is printed.