Implements a Formatter according to the formatting standards of the Java language.
- Note
- Inherited, public fields of parent class FormatterStdImpl provide important possibilities for changing the formatting behavior of instances of this class. Therefore, do not forget to consult the parent classes documentation.
In general, the original specification is covered quite well. The differences and specialties are:
- In deviation of the Java specification, after creation, a formatter in this implementation does not produce locale aware output. Instead, number formatting is set to "computational", hence the decimal point separator is
'.'
and the grouping character ','
. As the syntax specification does not provide a feature to switch between standard and locale setting, the corresponding fields of alternativeNumberFormat are not used with this formatter. Instead, to enable localized output, method NumberFormat.setFromLocale has to be invoked on field FormatterStdImpl.defaultNumberFormat. Alternatively, attributes of this object may be changed manually or by other means to reflect a desired locale.
- Hexadecimal floating point output (conversion type
'a'
and 'A'
) is not supported.
- Flag
'
(', used to write negative numbers in round brackets, is not supported.
- Addressing the previous argument index using
'%<'
is already allowed with the first placeholder. This Chooses the first argument. (In Java a MissingFormatArgumentException would be thrown.)
- Flag
'^'
is an extension to the standard and denotes center-alignment - just like '-'
in the standard denotes left-alignment. Right-alignment is the default.
- Floating point values:
- If standard field type
's'
is given together with a precision, the field is cut, even if it cuts the number somewhere. (This is just a warning and same behavior as in original specification.)
- For lower case floating point format types (
'f'
, 'g'
and 'e'
), the values specified in attributes ExponentSeparator, NANLiteral and INFLiteral of object alternativeNumberFormat are used. For upper case types ('G'
and 'E'
), the corresponding attributes in defaultNumberFormat apply.
- Fixed point format (
'f'
) is not supported to use arbitrary length. See class NumberFormat for the limits. Due to this limitation, the default number of fractional digits is not set with type 'f'
, while in Java it is set to 6
. This is to allow higher numbers up to 1.e13
to be printed in non-scientific format
- When both, a width and a precision is given, then the precision determines the fractional part, even if the type is 'g' or 'G'. This is different than specified with Java formatter, which uses precision as the overall width in case of types 'g' or 'G'.
- Hexadecimal and Octal Numbers:
- Hexadecimal and octal output is cut in size (!) when a field width is given that is smaller than the resulting amount of digits of the number arguments provided.
- Note
- This implies that a value written might not be equal to the value given. This is not a bug but a design decision. The rational behind this is that with this behavior, there is no need to mask lower digits when passing the arguments to the format invocation. In other words, the formatter "assumes" that the given field width indicates that only a corresponding number of lower digits are of interest.
- The number grouping option (
','
) can also be used with binary, hexadecimal and octal output. The types support different grouping separators for nibbles, bytes, 16-bit and 32-bit words. Changing the separator symbols, is not possible with the format fields of the format strings (if it was, this would become very incompatible to Java standards). Changes have to be made prior to the format operation by modifying field alternativeNumberFormat which is provided through parent class FormatterStdImpl.
Alternative form ('#'
) adds prefixes as specified in members
For upper case formats, those are taken from field defaultNumberFormat, for lower case formats from alternativeNumberFormat. All defaults may be changed by the user.
- Time and Date:
- In the Java version, boxed values of types Ticks and java.util.Date are applicable to conversion type
't'
.
- The following time conversion suffix characters are supported:
'H'
, 'k'
, 'I'
, 'l'
, 'M'
, 'S'
, 'B'
, 'b'
, 'h'
, 'A'
, 'a'
, 'Y'
, 'y'
, 'm'
, 'd'
, 'e'
, 'R'
, 'T'
, 'D'
and 'F'
- The following time conversion suffix characters are not supported:
'L'
, 'N'
, 'p'
, 'z'
, 'Z'
, 's'
, 'Q'
, 'C'
, 'j'
, 'r'
and 'c'
.