2004-2005
Berend de Boer
Berend
de Boer
berend@pobox.com 7 March 2005

# Scientific Format

The formatting specifications, which consist of optional and required fields, have the following form:

>     $[flags][minimum width][.precision]typechar

Each field of the formatting specification is a single character or a number indicating a particular format option. The simplest formatting specification contains only the escape character and a typechar (for example, $s). To print an escape character, write it twice (e.g. $$).

The optional fields, which appear before the type character, control other aspects of the formatting:

## Type character

The type character is required. It determines whether the associated parameter is interpreted as a character, as a string, or as a number.

The following typechars are available in class `ST_SCIENTIFIC_FORMATTER`:

### Recognized type characters

Typechar | Class | Description
--- | --- | ---
c | `CHARACTER` | Single character.
b | `BOOLEAN` | true or false strings.
B | `BOOLEAN` | True or False strings.
d | `INTEGER` | Signed decimal integer.
e | `DOUBLE` | Signed value having the form [-]d.dddde[sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is '+' or '-'.
E | `DOUBLE` | As 'e', but using the uppercase character 'E'.
f | `DOUBLE` | Signed value having the form [-]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision.
g | `DOUBLE` | Signed value printed in 'f' or 'e' format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than -4 or greater than or equal to the precision option. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.
G | `DOUBLE` | As 'g', but using the 'E' instead of 'e'.
i | `INTEGER` | Signed decimal integer.
o | `INTEGER` | Unsigned octal integer.
p | `POINTER` | Hexadecimal pointer output.
s | `STRING` | Character string; Characters are printed up to the end of string or until the precision value is reached.
u | `INTEGER` | Unsigned decimal integer.
x | `INTEGER` | Unsigned hexadecimal integer, using abcdef.
X | `INTEGER` | Unsigned hexadecimal integer, using ABCDEF.

Note that this list can be extended. Also note that only letters between a..z and A..Z are legal.

## Flags

Flags are optional character or characters that control justification of output and printing of signs, blanks. More than one flag can appear in a formatting specification, but they must be compatible with each other.

### Flags overview

Flag | Meaning | Default
--- | --- | ---
^ | Center the formatted parameter within the given field width | Right align
- | Left align the formatted parameter within the given field width. | Right align
+ | Prefix the formatted parameter with a sign (+ or -) if it has a signed type. | Sign appears only for negative values (-).
0 | Zeros are added until the minimum width is reached. | No padding.
_ | Prefix the formatted parameter with a blank (shown with an underscore here) if it is signed and positive. | No blank appears.

The following flag combinations:

- ' ' after '+'

- '0' with '-'

- '0' with '^'

- '-' with '^'

are not allowed.

## Minimum width

The width is an optional number that specifies the minimum number of characters in the formatted parameter.

The width argument is a non-negative decimal integer controlling the minimum number of characters printed. If the number of characters in the formatted parameter is less than the specified width, blanks are added to the left or to the right - depending on whether the '-' flag (for left alignment) is specified - until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers).

The width specification never causes a value to be truncated. If the number of characters in the formatted parameter is greater than the specified width, or if width is not given, all characters of the value are printed (subject to the precision specification).

If the width specification is an asterisk (*), an integer from the parameter list provides the value. The width option must precede the parameter being formatted in the parameter list. A non-existent or small field width does not cause the truncation of a field; if the formatted parameter is wider than the field width, the field expands to contain all characters.

## Precision

The third optional field of the format specification is the precision specification. It is made up of a non-negative decimal integer, preceded by a period '.', which specifies the number of characters to be printed, the number of decimal places, or the number of significant digits (see table below). Unlike the width specification, the precision specification can cause either truncation of the formatted parameter or rounding of a floating-point parameter. If precision is specified as 0 and the parameter to be formatted is 0, the result is no characters output:

    	print

    			format

    				"$.0d"
    				<<
    					integer_cell
    					0
    				>>

     -- No characters output

If the precision specification is an asterisk (*), an integer from the parameter list provides the value. The precision option must precede the parameter being formatted in the parameter list.

The table below details how precision affects type:

### How precision affects type

Type | Meaning | Default
--- | --- | ---
c | The precision has no effect. | Character is printed.
b, B | The precision has no effect. | "[tT]rue"/"[fF]alse" is printed.
d, i, u, o, x | The precision specifies the minimum number of digits to be printed. If the number of digits in the parameter is less than precision, the output value is padded on the left with zeros. | The value is not truncated when the number of digits exceeds precision. Default precision is 1.
e | The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded. | Default precision is 6; if precision is 0, no decimal point is printed.
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. | Default precision is 6; if precision is 0, no decimal point is printed.
g | The precision specifies the maximum number of significant digits printed. | Six significant digits are printed, with any trailing zeros truncated.
s | The precision specifies the maximum number of characters to be printed. Characters in excess of precision are not printed. | Characters are printed until end of string.