Guido Krüger's Web Service

C-style printf formatting

Introduction

The gk.util.Str class provides a number of extensions over the standard String class in Java. The most useful methods are those of the getFormatted family which could be used to create formatted output similar to the capabilities of the well-known printf function in C.

Documentation

The documentation is inlined and could be created using the javadoc utility. Here, we give only a short summary:

This class provides a number of supporting String methods which are otherwise not found in the java.util package. They are implemented as static methods which take a String as argument and/or provide a String as return value. This class can be divided into the following sections:

General String and String manipulation methods.
- getSpaces() returns an empty String
- getZeros() returns a zero-filled String
- padLeft() left-pads a String to a given width
- padRight() right-pads a String to a given width
- padZero() left-pads a String with zeros
Formatted output of primitive data types (like printf in C/C++).
- getFormatted() takes a String and a value argument and returns a composed String according to the printf formatting rules. This method is available for values of type int, double, char and String.

getFormatted mostly follows the conventions used in C/C++ printf formatting, though there are some slight differences. If you're not familar with printf, you may consider to take a look in any good C reference. Here are the rules for out format String:

There may be an arbibtrary number of format specifiers. Only the first one is used to obtain the format information.
The format specifier must have the form:
```
     %[-][+][0-9][.0-9][lL][dxXuofeEgGcs]
     ||  |  |    |     |   |
     ||  |  |    |     |   +- format char, see below
     ||  |  |    |     +----- long modifier, ignored
     ||  |  |    +----------- decimals
     ||  |  +---------------- field length
     ||  +------------------- plus sign
     |+---------------------- leftalign
     +----------------------- percent sign, starts format specifier
     
```
- The percent sign always starts the format specifiert. Two consecutive %'s could be used to literally generate a single %
- A "-" aligns output left (usually, it's right-aligned).
- A "+" outputs a plus sign for positive numbers (usually, it is supressed.
- The field length specifies the overall field length. If the formatted value is shorter, it will be padded with blanks, if it longer, it will remain unchanged.
- The number of decimals specifies the length of the fractional part for floating point numbers. If ommitted, the default is 6.
The format char determines the base type for the formatted value and has a big impact on how the result appears:
- "d": integer value in decimal format.
- "x": integer value in hexadecimal format (letters in lowercase).
- "X": integer value in hexadecimal format (letters in uppercase).
- "u": absolute integer value in decimal format. Result will always be positive.
- "o": integer value in octal format.
- "f": floating point value in fixed format (xxx.yyyyyy).
- "e": floating point value in scientific format (0.yyyyyye+zzz).
- "E": floating point value in scientific format (0.yyyyyyE+zzz).
- "g": same as "f" for absolute values not smaller than 0.001 and not greater or equal than 1000. Otherwise, same as "e".
- "G": same as "f" for absolute values not smaller than 0.001 and not greater or equal than 1000. Otherwise, same as "E".
- "c": single character.
- "s": String.
Here are some additional hints:
- For the "e" and "E" format chars the following is true:
  - The mantissa is normalized to its canonical form, i.e. it's always smaller than 1.0 and greater than or equal to 0.1
  - The exponent has always three digits.
  - The exponent always shows a sign, even for positive values.
  - The length of the frational part is subject to the number of decimals specified in the format string. If omitted, it defaults to 6.
- The fractional part is subject to rounding for the last visible digit. Overflows could be propagated into the integer part or even into the exponent.
- The "u" format char behaves different as in C/C++. Here, it always displays the absolute value of the argument in decimal format.
- The "l" and "L" modfiers are completely ignored.
- The number of decimals is applied to all format chars except "c" and "s". For integer values, the fractional part is always 0.