Class CFmt

java.lang.Object
  CFmt

All Implemented Interfaces:

java.io.Serializable

public class CFmt
extends java.lang.Object
implements java.io.Serializable

CFmt: Formatting strings and numbers like printf in C.

The first purpose of this class is to ease the migration of C-programs regarding the printf family. I needed this kind of class, but I am not very experienced in Java, so if anyone sees very funny kind of programming style in parts of this class, he / she should tell me about an alternative. Same thing applies to any errors in programming or erronous behaviour of the class.

This class is meant to be completely public domain - do whatever you like to do with it, but if you would like to see some improvements or if you implemented some improvements, I would like to know of it as well.

Thomas Mack, May 1999
mack@ifis.cs.tu-bs.de

Introduction:

The format specifier splits up into 5 parts: '%'; flags '-', '+', ' ', '#'; minimum fieldwidth; "." + precision; type specifier (c (char), s (string), d,i,o,u,p,x,X (integer numbers), f,e,E,g,G (real numbers)). "%" and type specifier are necessary, all others are optional.

For further info see the excerpt of the manpage below.

Examples:

CFmt cv = new CFmt();
System.out.println("Int: '"+ cv.fmt("%17d",-653)+"'";
System.out.println("Int: '"+ cv.fmt("%17X", 653)+"'";
System.out.println("Int: '"+ cv.fmt("%#17x", 653)+"'";
System.out.println("Double: '"+ cv.fmt("%17.4f",-653.0)+"'";
System.out.println("Double: '"+ cv.fmt("%-17.4e",-653.0)+"'";
System.out.println("Double: '"+ cv.fmt("%17.4G",-653.0)+"'";
System.out.println("Double: '"+ cv.fmt("%#17.4G",-653.0)+"'";
System.out.println("String: '"+ cv.fmt("%17.10s","I like it! (Do I?)")+"'";
System.out.println("Char: '"+ cv.fmt("%-5c",'Y')+"'";


Output:

Int: ' -653'
Int: ' 28D'
Int: ' 0x28d'
Double: ' -653.0000'
Double: '-6.5300e+02 '
Double: ' -653'
Double: ' -653.0'
String: ' I like it!'
Char: 'Y '


Read the relevant excerpt of the man(ual)page for printf further below for a rather complete description of the formatting options.

Behaviour that is different to C under Solaris 2.6:

• Hexadecimal numbers (type 'x', 'X' und 'p') in C will be displayed with max. 4 Bytes, in Java with max. 8 bytes:

  Java (x): ffffffffffffffff [-1 decimal]
C (x): ffffffff [-1 decimal]

  Same behaviour applies to octal numbers (type 'o'):

  Java (o): 1777777777777777777777 [-1 decimal]
C (o): 37777777777 [-1 decimal]

  You can optionally adjust the behaviour in CFmt via the constructor or with the method "void setHexByteCnt(int)". You would have to pass an integer specifying the maximum number of bytes that should be used for display. This could be four or eight. All other values will NOT change the behaviour!

  CFmt cv = new CFmt(4) will switch to the C behaviour, default is the Java behaviour with 8 bytes displayed.

  You can always query the value with "int getHexByteCnt()".

• Type 'u' (unsigned) kann ONLY display bytes, shorts or ints, if you want to display longs, you would have to use 'd', 'i', 'o', 'p', 'x', or 'X'. (Funnily, I did not manage to display a "long long" or similar in C via printf - but I did not look too close into these mechanics.)

• precision and / or minimum field width can be 320 maximum. Bigger Values will be shortened to 320.

• If type specifications don't match the value, an empty string will be returned. Example:

  fmt("Hello","%f");

  So far I did allow two exceptions: Strings with "%c" and Characters with a format specifier of "%s".

• Format specifier not sticking to the below detailed scheme will lead to "some" result, but the behaviour is not clearly defined. Definately the behaviour is different to the behaviour under C in our environment.

Excerpt of the manpage used as the basis for the CFmt class:

[...]

Each conversion specification is introduced by the character %. After the %, the following appear in sequence:

Zero or more flags, which modify the meaning of the conversion specification.

An optional decimal digit string specifying a minimum field width. If the converted value has fewer charac- ters than the field width, it will be padded on the left (or right, if the left-adjustment flag `-', described below, has been given) to the field width. The padding is with blanks unless the field width digit string starts with a zero, in which case the padding is with zeros.

A precision that gives the minimum number of digits to appear for the d, i, o, u, x, or X conversions, the number of digits to appear after the decimal point for the e, E, and f conversions, the maximum number of sig- nificant digits for the g and G conversion, or the max- imum number of characters to be printed from a string in s conversion. The precision takes the form of a period (.) followed by a decimal digit string; a NULL digit string is treated as zero. Padding specified by the precision overrides the padding specified by the field width.

An optional l (ell) specifying that a following d, i, o, u, x, or X conversion character applies to a long integer arg. An l before any other conversion charac- ter is ignored.

>[Note: I did never(!) see any difference between the output with > a specification containing an additional 'l' and a specification > not containing the 'l'.]

A character that indicates the type of conversion to be applied.

A field width or precision or both may be indicated by an asterisk (*) instead of a digit string. In this case, an integer arg supplies the field width or precision. The arg that is actually converted is not fetched until the conver- sion letter is seen, so the args specifying field width or precision must appear before the arg (if any) to be con- verted. A negative field width argument is taken as a `-' flag followed by a positive field width. If the precision argument is negative, it will be changed to zero.

The flag characters and their meanings are:

- The result of the conversion will be left- justified within the field.
+ The result of a signed conversion will always begin with a sign (+ or -).
blank If the first character of a signed conversion is not a sign, a blank will be prefixed to the result. This implies that if the blank and + flags both appear, the blank flag will be ignored.
# This flag specifies that the value is to be con- verted to an "alternate form."For c, d, i, s, and u conversions, the flag has no effect. For o conversion, it increases the precision to force the first digit of the result to be a zero. For x or X conversion, a non-zero result will have 0x or 0X prefixed to it. For e, E, f, g, and G conver- sions, the result will always contain a decimal point, even if no digits follow the point (nor- mally, a decimal point appears in the result of these conversions only if a digit follows it). For g and G conversions, trailing zeroes will not be removed from the result (which they normally are).

The conversion characters and their meanings are:

d,i,o,u,x,X
The integer arg is converted to signed decimal (d or i), unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal notation (x and X), respectively; the letters abcdef are used for x conversion and the letters ABCDEF for X conver- sion. The precision specifies the minimum number of digits to appear; if the value being converted can be represented in fewer digits, it will be expanded with leading zeroes. (For compatibility with older versions, padding with leading zeroes may alternatively be specified by prepending a zero to the field width. This does not imply an octal value for the field width.) The default precision is 1. The result of converting a zero value with a precision of zero is a NULL string.
f The float or double arg is converted to decimal notation in the style [-]ddd.ddd where the number of digits after the decimal point is equal to the precision specification. If the precision is missing, 6 digits are given; if the precision is explicitly 0, no digits and no decimal point are printed.
e,E The float or double arg is converted in the style [-]d.ddde+ddd, where there is one digit before the decimal point and the number of digits after it is equal to the precision; when the precision is missing, 6 digits are produced; if the precision is zero, no decimal point appears. The E format code will produce a number with E instead of e introducing the exponent. The exponent always contains at least two digits.
g,G The float or double arg is printed in style f or e (or in style E in the case of a G format code), with the precision specifying the number of signi- ficant digits. The style used depends on the value converted: style e or E will be used only if the exponent resulting from the conversion is less than -4 or greater than the precision. Trailing zeroes are removed from the result; a decimal point appears only if it is followed by a digit.

The e, E f, g, and G formats print IEEE indeterminate values (infinity or not-a-number) as "Infinity" or "NaN" respec- tively.

c The character arg is printed.
s The arg is taken to be a string (character pointer) and characters from the string are printed until a NULL character (\0) is encountered or until the number of characters indicated by the precision specification is reached. If the preci- sion is missing, it is taken to be infinite, so all characters up to the first NULL character are printed. A NULL value for arg will yield unde- fined results.
% Print a %; no argument is converted.

In no case does a non-existent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is simply expanded to contain the conversion result. Padding takes place only if the specified field width exceeds the actual width. Charac- ters generated by printf() and fprintf() are printed as if putc(3S) had been called.

[...]

EXAMPLES
To print a date and time in the form "Sunday, July 3, 10:02," where weekday and month are pointers to NULL- terminated strings:

printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min);

[Note:

System.out.print(cv.fmt("%s",weekday)+", "+
cv.fmt("%s",month)+" "+
cv.fmt("%i",day)+", "+
cv.fmt("%d",hour)+":"+
cv.fmt("%.2d",min));

should be abbreviated to:

System.out.print(weekday+", "+month+" "+day+", "+
hour+":"+cv.fmt("%.2d",min));

as in the first four places the CFmt conversion does nothing more than the default conversions in System.out.print().
]

To print pi to 5 decimal places:

printf("pi = %.5f", 4 * atan(1. 0));

[Note:
System.out.print("pi = "+cv.fmt("%.5f",4 * atan(1.0)));
]

[...]

Very wide fields (>128 characters) fail.

[Note: The limit in this class is about 320]

[...]

See Also:

Serialized Form

Constructor Summary

CFmt()
This creates a new instance with a default of 8 as the hexByteCount.

CFmt(int hexByteCnt)
This creates a new instance with the specified value as hexByteCnt.

Method Summary

java.lang.String	fmt(java.lang.String conv, byte bval) Formats a byte as specified by the conversion specification.
java.lang.String	fmt(java.lang.String conv, char c) Formats a character as specified by the conversion specification.
java.lang.String	fmt(java.lang.String conv, double dval) Formats a double value as specified by the conversion specification.
java.lang.String	fmt(java.lang.String conv, float fval) Formats a float value as specified by the conversion specification.
java.lang.String	fmt(java.lang.String conv, int ival) Formats an integer as specified by the conversion specification.
java.lang.String	fmt(java.lang.String conv, long lval) Formats a long value as specified by the conversion specification.
java.lang.String	fmt(java.lang.String conv, java.lang.String s) Formats a String as specified by the conversion specification.
int	getHexByteCnt() Returns the current value for hexByteCnt.
void	setHexByteCnt(int hexByteCnt) The Hexadecimal-Byte-Count is ONLY relevant to negative numbers of one of byte, short and int and type of 'o', 'x', 'X', 'p'.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CFmt

public CFmt()

This creates a new instance with a default of 8 as the hexByteCount.

See Also:

setHexByteCnt(int)

CFmt

public CFmt(int hexByteCnt)

This creates a new instance with the specified value as hexByteCnt.

Parameters:

hexByteCnt - How many bytes a hexadecimal number will contain maximum (4 or 8).

See Also:

setHexByteCnt(int)

Method Detail

setHexByteCnt

public void setHexByteCnt(int hexByteCnt)

The Hexadecimal-Byte-Count is ONLY relevant to negative numbers of one of byte, short and int and type of 'o', 'x', 'X', 'p'. It specifies how many bytes maximum a resulting hexadecimal number will contain.

Examples:

-1 will be displayed with a format of "%x" and hexByteCnt of 4 as:

ffffffff

and with a hexByteCnt of 8 as:

ffffffffffffffff

In C the default seems to be 4 bytes, the default here is 8 bytes. Possible values are 4 and 8, other values will NOT change the last value!

Parameters:

hexByteCnt - How many bytes to use for output of negative hexadecimal numbers.

getHexByteCnt

public int getHexByteCnt()

Returns the current value for hexByteCnt.

Returns:

the current value of hexByteCnt

See Also:

setHexByteCnt(int)

fmt

public java.lang.String fmt(java.lang.String conv,
                            char c)

Formats a character as specified by the conversion specification.

Parameters:

conv - the conversion specification. It may only contain the character 'c' as conversion character.

c - the char that should become formatted

Returns:

A String containing the formatted character

fmt

public java.lang.String fmt(java.lang.String conv,
                            java.lang.String s)

Formats a String as specified by the conversion specification.

Parameters:

conv - the conversion specification. It may only contain the character 's' as conversion character.

s - the String that should become formatted

Returns:

A String containing the formatted String

fmt

public java.lang.String fmt(java.lang.String conv,
                            byte bval)

Formats a byte as specified by the conversion specification.

Parameters:

conv - the conversion specification. It may contain the characters 'd', 'i', 'o', 'p', 'u', 'x' and 'X' as conversion characters.

bval - the byte value that should become formatted

Returns:

A String containing the formatted byte value

fmt

public java.lang.String fmt(java.lang.String conv,
                            int ival)

Formats an integer as specified by the conversion specification.

Parameters:

conv - the conversion specification. It may contain the characters 'd', 'i', 'o', 'p', 'u', 'x' and 'X' as conversion characters.

ival - the integer value that should become formatted

Returns:

A String containing the formatted integer value

fmt

public java.lang.String fmt(java.lang.String conv,
                            long lval)

Formats a long value as specified by the conversion specification.

Parameters:

conv - the conversion specification. It may contain the characters 'd', 'i', 'o', 'p', 'u', 'x' and 'X' as conversion characters.

lval - the long value that should become formatted

Returns:

A String containing the formatted long value

fmt

public java.lang.String fmt(java.lang.String conv,
                            float fval)

Formats a float value as specified by the conversion specification.

Parameters:

conv - the conversion specification. It may contain the characters 'f', 'e', 'E', 'g' and 'G' as conversion characters.

fval - the float value that should become formatted

Returns:

A String containing the formatted float value

fmt

public java.lang.String fmt(java.lang.String conv,
                            double dval)

Formats a double value as specified by the conversion specification.

Parameters:

conv - the conversion specification. It may contain the characters 'f', 'e', 'E', 'g' and 'G' as conversion characters.

dval - the double value that should become formatted

Returns:

A String containing the formatted double value