home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Java Fundamental Classes Reference

Previous Chapter 16
The java.text Package
Next
 

NumberFormat

Name

NumberFormat

Synopsis

Class Name:

java.text.NumberFormat

Superclass:

java.text.Format

Immediate Subclasses:

java.text.ChoiceFormat, java.text.DecimalFormat

Interfaces Implemented:

java.lang.Cloneable

Availability:

New as of JDK 1.1

Description

The NumberFormat class formats and parses numbers in a locale-specific manner. NumberFormat is an abstract class, but it provides factory methods that return useful instances of NumberFormat subclasses. These factory methods come in three groups:

  • The getCurrencyInstance() methods return objects that format and parse currency values.

  • The getNumberInstance() methods return objects that format and parse normal numbers.

  • The getPercentInstance() methods return objects that format percentage values.

For example, to format a number as an Italian currency value, you can use this code:

double salary = 1234.56;
System.out.println
  (NumberFormat.getCurrencyInstance(Locale.ITALY).format(salary));

This produces the following output:

L 1.234,56

The NumberFormat class defines two field constants that represent the integer and fractional fields in a formatted number. These field constants create FieldPosition objects.

Class Summary

public abstract class java.text.NumberFormat extends java.text.Format
                      implements java.lang.Cloneable {
  // Constants
  public static final int FRACTION_FIELD;
  public static final int INTEGER_FIELD;
  // Class Methods
  public static Locale[] getAvailableLocales();
  public static final NumberFormat getCurrencyInstance();
  public static NumberFormat getCurrencyInstance(Locale inLocale);
  public static final NumberFormat getInstance();
  public static NumberFormat getInstance(Locale inLocale);
  public static final NumberFormat getNumberInstance();
  public static NumberFormat getNumberInstance(Locale inLocale);
  public static final NumberFormat getPercentInstance();
  public static NumberFormat getPercentInstance(Locale inLocale);
  // Instance Methods
  public Object clone();
  public boolean equals(Object obj); 
  public final String format(double number);
  public final String format(long number);
  public final StringBuffer format(Object number, StringBuffer toAppendTo,
                            FieldPosition pos); 
  public abstract StringBuffer format(double number, 
                               StringBuffer toAppendTo, FieldPosition pos);
  public abstract StringBuffer format(long number, StringBuffer toAppendTo, 
                               FieldPosition pos);
  public int getMaximumFractionDigits();
  public int getMaximumIntegerDigits();
  public int getMinimumFractionDigits();
  public int getMinimumIntegerDigits();
  public int hashCode();
  public boolean isGroupingUsed();
  public boolean isParseIntegerOnly();
  public Number parse(String text);
  public abstract Number parse(String text, ParsePosition parsePosition);
  public final Object parseObject(String source, 
                      ParsePosition parsePosition); 
  public void setGroupingUsed(boolean newValue);
  public void setMaximumFractionDigits(int newValue);
  public void setMaximumIntegerDigits(int newValue);
  public void setMinimumFractionDigits(int newValue);
  public void setMinimumIntegerDigits(int newValue);
  public void setParseIntegerOnly(boolean value);
}

Constants

FRACTION_FIELD

public final static int FRACTION_FIELD

Description

A field constant that represents the fractional part of the number.

INTEGER_FIELD

public final static int INTEGER_FIELD

Description

A field constant that represents the integer part of the number.

Class Methods

getAvailableLocales

public static Locale[] getAvailableLocales()

Returns

An array of Locale objects.

Description

This method returns an array of the Locale objects for which this class can create NumberFormat objects.

getCurrencyInstance

public static final NumberFormat getCurrencyInstance()

Returns

A NumberFormat appropriate for the default Locale that formats currency values.

Description

This method creates a NumberFormat that formats and parses currency values in the default locale.

public static NumberFormat getCurrencyInstance(Locale inLocale)

Parameters

inLocale

The Locale to use.

Returns

A NumberFormat appropriate for the given Locale that formats currency values.

Description

This method creates a NumberFormat that formats and parses currency values in the given locale.

getInstance

public static final NumberFormat getInstance()

Returns

A default NumberFormat appropriate for the default Locale.

Description

This method creates a default NumberFormat that formats and parses values in the default locale.

public static NumberFormat getInstance(Locale inLocale)

Parameters

inLocale

The Locale to use.

Returns

A default NumberFormat appropriate for the given Locale.

Description

This method creates a NumberFormat that formats and parses values in the given locale.

getNumberInstance

public static final NumberFormat getNumberInstance()

Returns

A NumberFormat appropriate for the default Locale that formats normal numbers.

Description

This method creates a NumberFormat that formats and parses number values in the default locale.

public static NumberFormat getNumberInstance(Locale inLocale)

Parameters

inLocale

The Locale to use.

Returns

A NumberFormat appropriate for the given Locale that formats normal numbers.

Description

This method creates a NumberFormat that formats and parses number values in the given locale.

getPercentInstance

public static final NumberFormat getPercentInstance()

Returns

A NumberFormat appropriate for the default Locale that formats percentage values.

Description

This method creates a NumberFormat that formats and parses percent values in the default locale.

public static NumberFormat getPercentInstance(Locale inLocale)

Parameters

inLocale

The Locale to use.

Returns

A NumberFormat appropriate for the given Locale that formats percentage values.

Description

This method creates a NumberFormat that formats and parses percent values in the given locale.

Instance Methods

clone

public Object clone()

Returns

A copy of this NumberFormat.

Overrides

Format.clone()

Description

This method creates a copy of this NumberFormat and returns it.

equals

public boolean equals(Object obj)

Parameters

obj

The object to be compared with this object.

Returns

true if the objects are equal; false if they are not.

Overrides

Object.equals()

Description

This method returns true if obj is an instance of NumberFormat and is equivalent to this NumberFormat.

format

public final String format(double number)

Parameters

number

The double value to be formatted.

Returns

A string that contains a formatted representation of the value.

Description

This method formats the given number and returns the result as a string.

public final String format(long number)

Parameters

number

The long value to be formatted.

Returns

A string that contains a formatted representation of the value.

Description

This method formats the given number and returns the result as a string.

 public final StringBuffer format(Object number, StringBuffer toAppendTo, FieldPosition pos) 

Parameters

number

The object to be formatted.

toAppendTo

A StringBuffer on which to append the formatted information.

pos

A number field.

Returns

The given buffer toAppendTo with the formatted representation of the object appended to it.

Overrides

Format.format(Object, StringBuffer, FieldPosition)

Description

This method formats the given object and appends the result to the given StringBuffer. If pos refers to one of the number fields, its beginning and ending indices are filled with the beginning and ending positions of the given field in the resulting formatted string.

 public abstract StringBuffer format(double number, StringBuffer toAppendTo, FieldPosition pos) 

Parameters

number

The double value to be formatted.

toAppendTo

A StringBuffer on which to append the formatted information.

pos

A number field.

Returns

The given buffer toAppendTo with the formatted representation of the object appended to it.

Description

This method formats the given number and appends the result to the given StringBuffer. If pos refers to one of the number fields, its beginning and ending indices are filled with the beginning and ending positions of the given field in the resulting formatted string.

 public abstract StringBuffer format(long number, StringBuffer toAppendTo, FieldPosition pos) 

Parameters

number

The long value to be formatted.

toAppendTo

A StringBuffer on which to append the formatted information.

pos

A number field.

Returns

The given buffer toAppendTo with the formatted representation of the object appended to it.

Description

This method formats the given number and appends the result to the given StringBuffer. If pos refers to one of the number fields, its beginning and ending indices are filled with the beginning and ending positions of the given field in the resulting formatted string.

getMaximumFractionDigits

public int getMaximumFractionDigits()

Returns

The maximum number of digits allowed in the fraction portion.

Description

This method returns the maximum number of digits that can be in the fraction part of the number.

getMaximumIntegerDigits

public int getMaximumIntegerDigits()

Returns

The maximum number of digits allowed in the integer portion.

Description

This method returns the maximum number of digits that can be in the integer part of the number.

getMinimumFractionDigits

public int getMinimumFractionDigits()

Returns

The minimum number of digits allowed in the fraction portion.

Description

This method returns the minimum number of digits that can be in the fraction part of the number.

getMinimumIntegerDigits

public int getMinimumIntegerDigits()

Returns

The minimum number of digits allowed in the integer portion.

Description

This method returns the minimum number of digits that can be in the integer part of the number.

hashCode

public int hashCode()

Returns

A hashcode for this object.

Overrides

Object.hashCode()

Description

This method returns a hashcode for this NumberFormat.

isGroupingUsed

public boolean isGroupingUsed()

Returns

A boolean value that indicates whether or not this NumberFormat uses a grouping character to break up long sequences of digits in the integer part of a number.

Description

This method returns true if this NumberFormat uses a grouping character. For example, it is common in the United States to use a comma as a grouping character: 1,234.56.

isParseIntegerOnly

public boolean isParseIntegerOnly()

Returns

A boolean value that indicates whether or not this NumberFormat parses only integers.

Description

This method returns true if this NumberFormat parses only integers.

parse

public Number parse(String text) throws ParseException

Parameters

text

The string to be parsed.

Returns

The Number object represented by the given string.

Throws

ParseException

If the text cannot be parsed as a number.

Description

This method parses a number from the given string, starting from the beginning of the string.

 public abstract Number parse(String text, ParsePosition parsePosition) 

Parameters

text

The string to be parsed.

parsePosition

A ParsePosition object that specifies a position in the string.

Returns

The Number object represented by the text starting at the given position.

Description

This method parses a number from the given string, starting from the given position. After the string has been parsed, the given ParsePosition object is updated so that its index is after the parsed text.

parseObject

 public final Object parseObject(String source, ParsePosition parsePosition) 

Parameters

source

The string to be parsed.

parsePosition

A ParsePosition object that specifies a position in the string.

Returns

The object represented by the text starting at the given position.

Overrides

Format.parseObject(String, ParsePosition)

Description

This method parses a number from the given string, starting from the given position. After the string has been parsed, the given ParsePosition object is updated so that its index is after the parsed text.

setGroupingUsed

public void setGroupingUsed(boolean newValue)

Parameters

newValue

The new grouping flag.

Description

This method sets whether or not this NumberFormat uses a grouping character to break up long sequences of digits in the integer part of a number. For example, it is common in the United States to use a comma as a grouping character: 1,234.56.

setMaximumFractionDigits

public void setMaximumFractionDigits(int newValue)

Parameters

newValue

The new maximum number of fraction digits.

Description

This method sets the maximum number of digits that may be present in the fraction part of the number. The maximum value must be greater than the minimum number of fraction digits allowed. If the value is less than the current minimum, the minimum is also set to this value.

setMaximumIntegerDigits

public void setMaximumIntegerDigits(int newValue)

Parameters

newValue

The new maximum number of integer digits.

Description

This method sets the maximum number of digits that may be present in the integer part of the number. The maximum value must be greater than the minimum number of integer digits allowed. If the value is less than the current minimum, the minimum is also set to this value.

setMinimumFractionDigits

public void setMinimumFractionDigits(int newValue)

Parameters

newValue

The new minimum number of fraction digits.

Description

This method sets the minimum number of digits that may be present in the fraction part of the number. The minimum value must be less than the maximum number of fraction digits allowed. If the value is greater than the current maximum, the maximum is also set to this value.

setMinimumIntegerDigits

public void setMinimumIntegerDigits(int newValue)

Parameters

newValue

The new minimum number of integer digits.

Description

This method sets the minimum number of digits that may be present in the integer part of the number. The minimum value must be less than the maximum number of integer digits allowed. If the value is greater than the current maximum, the maximum is also set to this value.

setParseIntegerOnly

public void setParseIntegerOnly(boolean value)

Parameters

value

The new parsing flag.

Description

This method sets whether or not this NumberFormat parses only integers. If the value is true, this NumberFormat only parse integers. Otherwise it parses both the integer and fractional parts of numbers.

Inherited Methods

Method Inherited From Method Inherited From

finalize()

Object

format(Object)

Format

getClass()

Object

notify()

Object

notifyAll()

Object

parseObject(String)

Format

toString()

Object

wait()

Object

wait(long)

Object

wait(long, int)

Object

See Also

ChoiceFormat, DecimalFormat, FieldPosition, Format, Number, ParseException, ParsePosition, String, StringBuffer


Previous Home Next
MessageFormat Book Index ParseException

Java in a Nutshell Java Language Reference Java AWT Java Fundamental Classes Exploring Java