maspack.util
Class NumberFormat

java.lang.Object
  extended by maspack.util.NumberFormat

public class NumberFormat
extends java.lang.Object

Object for formatting numbers in the same way similiar to the C printf function.

A printf style format string is specified in the constructor, or can be respecified using the set method. Once instantiated, the format methods of this class may be used to convert numeric types (float, double, int, long) into Strings.

Examples:

 double theta1 = 45.0;
 double theta2 = 85.0;
 NumberFormat fmt = new NumberFormat ("%7.2f\n");
 
 System.out.println ("theta1=" + fmt.format (theta1) + "theta2="
 + fmt.format (theta2));
 

Author:
John E. Lloyd, Winter 2004

Constructor Summary
NumberFormat()
          Creates a new instance of PrintfFormat with the default format string %g.
NumberFormat(NumberFormat fmt)
          Creates a new NumberFormat, whose setting are copied from an existing NumberFormat.
NumberFormat(java.lang.String fmtStr)
          Creates a new NumberFormat, with settings given by the supplied format string.
 
Method Summary
 boolean equals(NumberFormat fmt)
          Returns true if this NumberFormat is identical in function (i.e., will produce the same output) as the NumberFormat supplied as an argument.
 java.lang.String format(double x)
          Formats a double into a string.
 java.lang.StringBuffer format(double x, java.lang.StringBuffer sbuf)
          Formats a double and appends it to the end of a StringBuffer.
 java.lang.String format(int x)
          Formats an int into a string.
 java.lang.StringBuffer format(int x, java.lang.StringBuffer sbuf)
          Formats an int and appends it to the end of a StringBuffer.
 java.lang.String format(long x)
          Formats a long into a string.
 java.lang.StringBuffer format(long x, java.lang.StringBuffer sbuf)
          Formats a long and appends it to the end of a StringBuffer.
static java.lang.String formatHex(int num)
           
 int getConversionChar()
          Returns the conversion character for this format.
 int getFieldWidth()
          Returns the field width associated with this format.
 int getIndentColumn()
           
 int getPrecision()
          Returns the precision associated with this format.
 java.lang.String getPrefix()
          Gets the prefix associated with this format.
 java.lang.String getSuffix()
          Gets the suffix associated with this format.
 void incIndentColumn(int inc)
           
 java.lang.String indent()
           
 boolean isFullPrecisionDouble()
          Returns true if this number format corresponds to '%g'.
 void set(NumberFormat fmt)
          Sets this formatter to have the same settings as the formatter supplied by the argument.
 void set(java.lang.String fmtStr)
          Sets the format characteristics according to the supplied String.
 void setAlternate(boolean enable)
          Enables 'alternate' formatting.
 void setFieldWidth(int w)
          Sets the field width associated with this format.
 void setIndentColumn(int col)
           
 void setPrecision(int p)
          Sets the precision associated with this format.
 void setPrefix(java.lang.String pre)
          Sets the prefix associated with this format.
 void setSuffix(java.lang.String suf)
          Sets the suffix associated with this format.
 java.lang.String toString()
          Returns a string representation of this NumberFormat.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

NumberFormat

public NumberFormat()
Creates a new instance of PrintfFormat with the default format string %g.


NumberFormat

public NumberFormat(java.lang.String fmtStr)
Creates a new NumberFormat, with settings given by the supplied format string. The structure of the format string is described in the documentation for set.

Parameters:
fmtStr - Format string
Throws:
java.lang.IllegalArgumentException - Malformed format string
See Also:
set(String)

NumberFormat

public NumberFormat(NumberFormat fmt)
Creates a new NumberFormat, whose setting are copied from an existing NumberFormat.

Parameters:
fmt - formatter to be copies
See Also:
set(NumberFormat)
Method Detail

setFieldWidth

public void setFieldWidth(int w)
Sets the field width associated with this format. The numeric portion of the final formatted string is padded to ensure that it is at least this width.

Parameters:
w - field width
Throws:
java.lang.IllegalArgumentException - Negative field width
See Also:
getFieldWidth(), set(java.lang.String)

getFieldWidth

public int getFieldWidth()
Returns the field width associated with this format.

Returns:
field width
See Also:
setFieldWidth(int), set(java.lang.String)

setAlternate

public void setAlternate(boolean enable)
Enables 'alternate' formatting. This implies the following: For 'o' conversions, the output is always prefixed with a '0'. For 'x' and 'X' conversions, the output is prefixed with "0x" or "0X", respectively. For 'a', 'A', 'e', 'E', and 'f' conversions, the result will always contain a decimal point. There is no effect for other conversions.

Parameters:
enable - if true, enables 'alternate' formatting
See Also:
isAlternate()

setPrecision

public void setPrecision(int p)
Sets the precision associated with this format. For a floating point type, the precision generally gives the number of digits that appear after the decimal point. For more precise details, see the documentation for set. A negative value implies either that no precision is set, or a default value should be set.

Parameters:
p - precision
See Also:
getPrecision(), set(java.lang.String)

getPrecision

public int getPrecision()
Returns the precision associated with this format.

Returns:
precision
See Also:
setPrecision(int), set(java.lang.String)

setPrefix

public void setPrefix(java.lang.String pre)
Sets the prefix associated with this format. The prefix is the (possibly empty) string that precedes the numeric part.

Parameters:
pre - new prefix
See Also:
getPrefix()

getPrefix

public java.lang.String getPrefix()
Gets the prefix associated with this format.

Returns:
prefix

setSuffix

public void setSuffix(java.lang.String suf)
Sets the suffix associated with this format. The suffix is the (possibly empty) string that follows the numeric part.

Parameters:
suf - new suffix
See Also:
getSuffix()

getSuffix

public java.lang.String getSuffix()
Gets the suffix associated with this format.

Returns:
suffix

getConversionChar

public int getConversionChar()
Returns the conversion character for this format.

Returns:
conversion character

set

public void set(java.lang.String fmtStr)
         throws java.lang.IllegalArgumentException
Sets the format characteristics according to the supplied String.

The format string has a format similar to the one used by the C printf function, except that only one conversion may be specified.

The format string consists of an optional prefix of regular characters, followed by a conversion sequence, followed by an optional suffix of regular characters.

The conversion sequence is introduced by a '%' character, and is followed by any number of optional flag characters, an optional unsigned decimal integer specifying a field width, another optional unsigned decimal integer (preceded by a '.' character) specifying a precision, and finally a conversion character. To incorporate a '%' character into either the prefix or suffix, one should specify the sequence "%%". The allowed flag characters are:

#
The value is converted into an "alternate" form. For 'o' conversions, the output is always prefixed with a '0'. For 'x' and 'X' conversions, the output is prefixed with "0x" or "0X", respectively. For 'a', 'A', 'e', 'E', and 'f' conversions, the result will always contain a decimal point. There is no effect for other conversions.
0
Use '0' to pad the field on the left, instead of blanks. If the conversion is 'd', 'i', 'o', 'u', 'x', or 'X', and a precision is given, then this flag is ignored.
-
The output is aligned with the left of the field boundary, and padded on the right with blanks. This flag overrides the '0' flag.
' '
Leave a blank before a positive number produced by a signed conversion.
+
A '+' sign is placed before non-negative numbers produced by a signed conversion. This flag overrides the ' ' flag.

The conversion character is one of:

d,i
The integer argument is output as a signed decimal number. If a precision is given, it describes the minimum number of digits that must appear (default 1). If the precision exceeds the number of digits that would normally appear, the output is padded on the left with zeros. When 0 is printed with precision 0, the result is empty.
o,u,x,X
The integer argument is output as an unsigned number in either octal ('o'), decimal ('u'), or hexadecimal ('x' or 'X'). The digits "abcdef" are used for 'x', and "ABCDEF" are used for 'X'. If a precision is given, it describes the minimum number of digits that must appear (default 1). If the precision exceeds the number of digits that would normally appear, the output is padded on the left with zeros. When 0 is printed with precision 0, the result is empty.
e,E
The floating point argument is output in the exponential form [-]d.ddde+dd, with the number of digits after the decimal point given by the precision. The default precision value is 6. No decimal point is output if the precision is 0. Conversion 'E' causes 'E' to be used as an exponent instead of 'e'. The exponent is always at least two characters.
f
The floating point argument is output in the form [-]ddd.ddd, with the number of digits after the decimal point given by the precision. The default precision value is 6. No decimal point is output if the precision is 0. If a decimal point appears, at least one digit appears before it.
g
If the precision is undefined, the floating point argument is output using the Java Double.toString method. This produces a decimal representation that is accurate enough to reproduce the number exactly if it is read back into a Java application using Double.parseDouble. Note that this is a different behavior from the usual C printf interpretation of %g.
If a precision is defined, then the number is output in decimal format if its value lies between 1e-4 and 10^precision, with the number of significant digits equaling the precision. Otherwise, the number is output in exponential format, again with the number of significant digits equaling the precision. A precision specified as 0 is incremented to 1.
a,A
The floating point argument is output in the hexadecimal floating point form [-]0xh.hhhp+dd. The exponent is a decimal number and describes a power of 2. The 'A' style uses the prefix "0X", the hex digits "ABCDEF", and the exponent character 'P'. The number of digits after the decimal point is given by the precision. The default precision is enough for an exact representation of the value.

Parameters:
fmtStr - Format string
Throws:
java.lang.IllegalArgumentException - Malformed format string

format

public java.lang.String format(double x)
Formats a double into a string.

Parameters:
x - value to be formatted
Returns:
formatted string

format

public java.lang.StringBuffer format(double x,
                                     java.lang.StringBuffer sbuf)
Formats a double and appends it to the end of a StringBuffer.

Parameters:
x - value to be formatted
sbuf - buffer to place the result in
Returns:
pointer to the result buffer

format

public java.lang.String format(int x)
Formats an int into a string.

Parameters:
x - value to be formatted
Returns:
formatted string

format

public java.lang.StringBuffer format(int x,
                                     java.lang.StringBuffer sbuf)
Formats an int and appends it to the end of a StringBuffer.

Parameters:
x - value to be formatted
sbuf - buffer to place the result in
Returns:
pointer to the result buffer

format

public java.lang.String format(long x)
Formats a long into a string.

Parameters:
x - value to be formatted
Returns:
formatted string

format

public java.lang.StringBuffer format(long x,
                                     java.lang.StringBuffer sbuf)
Formats a long and appends it to the end of a StringBuffer.

Parameters:
x - value to be formatted
sbuf - buffer to place the result in
Returns:
pointer to the result buffer

setIndentColumn

public void setIndentColumn(int col)

incIndentColumn

public void incIndentColumn(int inc)

getIndentColumn

public int getIndentColumn()

indent

public java.lang.String indent()

toString

public java.lang.String toString()
Returns a string representation of this NumberFormat. If passed as an argument to set, this string should specify a NumberFormat identical to this one.

Overrides:
toString in class java.lang.Object
Returns:
string representation of this format

isFullPrecisionDouble

public boolean isFullPrecisionDouble()
Returns true if this number format corresponds to '%g'.

Returns:
true if format corresponds to '%g'.

set

public void set(NumberFormat fmt)
Sets this formatter to have the same settings as the formatter supplied by the argument.

Parameters:
fmt - formatter to be copied

equals

public boolean equals(NumberFormat fmt)
Returns true if this NumberFormat is identical in function (i.e., will produce the same output) as the NumberFormat supplied as an argument.

Parameters:
fmt - NumberFormat to compare with
Returns:
true if this format is identical in function to fmt

formatHex

public static java.lang.String formatHex(int num)