Class PaddedDecimalFormat

java.lang.Object
   |
   +----java.text.Format
           |
           +----java.text.NumberFormat
                   |
                   +----java.text.DecimalFormat
                           |
                           +----PaddedDecimalFormat

public class PaddedDecimalFormat
extends DecimalFormat

This class adds easy right-justified output (formatting) and alignment of the decimal separator to the existing capabilities of java.text.DecimalFormat and its parent class, java.text.NumberFormat.

Create a formatter/parser using one of the factory methods of the form, getXXXInstance( int decPlaces, Locale loc). Specify the maximum number of decimal places your program will need, across all locales where it will be run. Make (instantiate) a separate formatter object for each format type (Number, Currency, or Percent). Use Locale.getDefault() to localize the formatting and parsing to whatever a user's particular language and country may be. Or you can specify the Locale variables and then display output for several locales at once.

If the decPlaces variable is the same and you do not change the default alignField variable, the decimal separators will align across all the different formatters. Use the same fieldsize in your calls to the different objects' format() methods.

The following additions are provided to what is already available from the core java.text.DecimalFormat class:

format( double dval, int fieldsize) -- Output will be right-aligned to the decimal point using the default (space) or whatever pad character you specify with setPadCharacter(char padChar).
setPattern( String pat ) and getPattern() -- Methods override the applyPattern( String pat ) and toPattern() methods in DecimalFormat so you can use the pattern string as a JavaBean property.
setMaxFieldSize( int size ) and getMaxFieldSize() -- control the maxFieldSize property. The maxFieldSize is the largest fieldsize your monospaced program output needs. Default is 80. Use the set()er method if you need something larger.
setFractionDigits( int digits ) and getFractionDigits() -- The set()er sets both the maximum and minimum number of fraction digits. The get()er gets the current minimum number of fraction digits, regardless of whether setFractionDigits() has been previously called.
setAlignField( int ) and getAlignField() -- When the alignField is INTEGER_FIELD, decimal separators will align. If you set this to FRACTION_FIELD, alignment will be at the last decimal digit.
getDecPlaces() -- returns the current setting.
getLoc() -- returns the current Locale setting.

For compatibility with code you may have written already, all three standard DecimalFormat constructors are provided. But to really take advantage of this class's raison d'être, use one of the getXXXInstance factory constructors wherever you can. The standard constructors allow you to use PaddedDecimalFormat wherever you have used DecimalFormat in your existing code.

Use at your own risk! If you find bugs, please let me know.

Version:: 1.0 99/08/19 - Original version
Author:: Tony Dahlman

alignField
decPlaces
defaultCurPlaces
fp
loc
maxFieldSize
padCharacter
spaces

PaddedDecimalFormat(): Default constructor.
PaddedDecimalFormat(String): Mimics the usual DecimalFormat constructor, allowing you to use this class everywhere your existing code uses DecimalFormat.
PaddedDecimalFormat(String, DecimalFormatSymbols): The full-function DecimalFormat constructor.

format(double, int): Right-justified double-to-String conversion.
getAlignField(): Get the current setting for alignField.
getCurrencyInstance(int, Locale): Static method returns an instance, set up for a particular locale and number of decimal places.
getDecPlaces(): Get the current setting for the number of decimal places specified when this formatter was constructed.
getFractionDigits(): Get current setting for both maximum and minimum number of fraction digits.
getLoc(): Get the current locale setting.
getLocalizedPattern(): Use DecimalFormat's toLocalizedPattern() method to get this formatter's current formatting string.
getMaxFieldSize(): Get current setting for maximum fieldsize.
getNumberInstance(int, Locale): Static method returns an instance, set up for a particular locale and number of decimal places.
getPadCharacter(): Get the pad character.
getPattern(): Use DecimalFormat's toPattern() method to get this formatter's current formatting string.
getPercentInstance(int, Locale): Static method returns an instance, set up for a particular locale and number of decimal places.
setAlignField(int): Control whether alignment will occur at the decimal separator or at the last numeric digit.
setFractionDigits(int): Set both the maximum and minimum number of fraction digits to be displayed.
setLocalizedPattern(String): Attempt to change this formatting object by supplying a new DecimalFormat pattern string.
setMaxFieldSize(int): Set the maximum fieldsize: useful if you need more than the default value of 80.
setPadCharacter(char): Set the pad character.
setPattern(String): Attempt to change this formatting object by supplying a new DecimalFormat pattern string.

decPlaces

 protected int decPlaces

loc

 protected Locale loc

padCharacter

 protected char padCharacter

maxFieldSize

 protected int maxFieldSize

defaultCurPlaces

 protected int defaultCurPlaces

alignField

 protected int alignField

 protected FieldPosition fp

spaces

 protected String spaces

PaddedDecimalFormat

 public PaddedDecimalFormat()

Default constructor. Useful for JavaBeans (good luck!) but not much else.

See Also:: getNumberInstance, getPercentInstance, getCurrencyInstance

PaddedDecimalFormat

 public PaddedDecimalFormat(String pattern)

Mimics the usual DecimalFormat constructor, allowing you to use this class everywhere your existing code uses DecimalFormat.

See Also:: getNumberInstance, getPercentInstance, getCurrencyInstance

PaddedDecimalFormat

 public PaddedDecimalFormat(String pattern,
                            DecimalFormatSymbols dfs)

The full-function DecimalFormat constructor. Included here for use by the getXXXInstance() methods which follow. It is public simply to provide complete compatibility with existing DecimalFormat code.

See Also:: getNumberInstance, getPercentInstance, getCurrencyInstance

getNumberInstance

 public static PaddedDecimalFormat getNumberInstance(int decPlaces,
                                                     Locale loc)

Static method returns an instance, set up for a particular locale and number of decimal places. This is the easy way to get right-justified, decimal-aligned output.

Parameters:: decPlaces - Number of decimal places to plan for. Make this the maximum number of decimal places your application will use, and keep its value constant across all the formatters you may instantiate.; loc - The Locale (language and country combination).

getCurrencyInstance

 public static PaddedDecimalFormat getCurrencyInstance(int decPlaces,
                                                       Locale loc)

Static method returns an instance, set up for a particular locale and number of decimal places. This is the easy way to get right-justified, decimal-aligned output.

Parameters:: decPlaces - Number of decimal places to plan for. Make this the maximum number of decimal places your application will use, and keep its value constant across all the formatters you may instantiate.; loc - The Locale (language and country combination).

getPercentInstance

 public static PaddedDecimalFormat getPercentInstance(int decPlaces,
                                                      Locale loc)

Static method returns an instance, set up for a particular locale and number of decimal places. This is the easy way to get right-justified, decimal-aligned output.

Parameters:: decPlaces - Number of decimal places to plan for. Make this the maximum number of decimal places your application will use, and keep its value constant across all the formatters you may instantiate.; loc - The Locale (language and country combination).

format

 String format(double dval,
               int fieldsize)

Right-justified double-to-String conversion. Default behavior is to return decimal aligned decimal strings, as long as the fieldsize is large enough.

Parameters:: dval - a double (small "d") value. Returns an error message for values larger than the maximum (smaller than the minimum) Long integer.; fieldsize - desired number of monospaced characters, including padding. The fieldsize must be less than the maxFieldSize, which defaults to 80.
See Also:: setMaxFieldSize, setAlignField, setPadCharacter

setPadCharacter

 public void setPadCharacter(char ch)

Set the pad character.

getPadCharacter

 public char getPadCharacter()

Get the pad character.

setMaxFieldSize

 public void setMaxFieldSize(int size)

Set the maximum fieldsize: useful if you need more than the default value of 80.

getMaxFieldSize

 public int getMaxFieldSize()

Get current setting for maximum fieldsize.

setFractionDigits

 public void setFractionDigits(int places)

Set both the maximum and minimum number of fraction digits to be displayed.

Parameters:: places - Values can be 0 to the decPlaces value used to create this formatting object. Specify -1 to indicate you want the default currency format's maximum number of decimal places.

getFractionDigits

 public int getFractionDigits()

Get current setting for both maximum and minimum number of fraction digits.

Returns:: a return value of -1 indicates setFractionDigits() has not yet been called.

setAlignField

 public void setAlignField(int alignField)

Control whether alignment will occur at the decimal separator or at the last numeric digit.

Parameters:: alignField - Can be NumberFormat.INTEGER_FIELD (the default) which causes alignment of decimal separators, or NumberFormat.FRACTION_FIELD which causes alignment of the last numeric digit.

getAlignField

 public int getAlignField()

Get the current setting for alignField. Compare the int result with the NumberFormat constants, INTEGER_FIELD and FRACTION_FIELD.

setPattern

 public void setPattern(String pat)

Attempt to change this formatting object by supplying a new DecimalFormat pattern string. Throws IllegalArgumentException if the attempt fails. For example, switching the decimal separator to be a grouping separator will fail. Use a new formatting object rather than setPattern() to switch among locales.
This method uses DecimalFormat's applyPattern() method. I have not found the applyLocalizedPattern() method useful.

getPattern

 public String getPattern()

Use DecimalFormat's toPattern() method to get this formatter's current formatting string. I have not found the toLocalizedPattern() method useful.

setLocalizedPattern

 public void setLocalizedPattern(String pat)

Attempt to change this formatting object by supplying a new DecimalFormat pattern string. Throws IllegalArgumentException if the attempt fails.
Uses DecimalFormat's applyLocalizedPattern() method and provided here for "completeness." I haven't found it useful.

getLocalizedPattern

 public String getLocalizedPattern()

Use DecimalFormat's toLocalizedPattern() method to get this formatter's current formatting string. Provided only for "completeness": I haven't found it useful.

getDecPlaces

 public int getDecPlaces()

Get the current setting for the number of decimal places specified when this formatter was constructed. This value should not be changed for the life of this formatting object. All formatting objects should use the same value to permit easy decimal alignment.

getLoc

 public Locale getLoc()

Get the current locale setting. Use separate formatting objects for each needed locale (language/country combination). To cause formatting to localize for any particular user's locale, call the constructor with Locale.getDefault() as the Locale variable.