当前页面: 在线文档首页 > JavaTM 2 Platform Standard Edition 6.0 API 规范中文版

NumberFormat (Java Platform SE 6) - JavaTM 2 Platform Standard Edition 6.0 API 规范中文版

---

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM Platform Standard Ed. 6
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

java.text
类 NumberFormat

java.lang.Object
  java.text.Format
      java.text.NumberFormat

所有已实现的接口：

Serializable, Cloneable

直接已知子类：

ChoiceFormat, DecimalFormat

---

public abstract class NumberFormat
extends Format

NumberFormat 是所有数值格式的抽象基类。此类提供格式化和解析数值的接口。NumberFormat 还提供了一些方法来确定哪些语言环境具有数值格式，以及它们的名称是什么。

NumberFormat 可用于格式化和解析任何语言环境的数值。使代码能够完全独立于小数点、千位分隔符甚至所用特定小数位数的语言环境约定，并与数值格式是否为偶小数无关。

若要格式化当前 Locale 的数值，可使用其中一个工厂类方法：

  myString = NumberFormat.getInstance().format(myNumber);
 

如果格式化多个数值，那么获取该格式并多次使用它是更为高效的做法，这样系统就不必多次获取关于语言环境语言和国家/地区约定的信息了。

 NumberFormat nf = NumberFormat.getInstance();
 for (int i = 0; i < myNumber.length; ++i) {
     output.println(nf.format(myNumber[i]) + "; ");
 }
 

若要格式化不同 Locale 的日期，可在对 getInstance 的调用中指定它。

 NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
 

还可以使用 NumberFormat 来解析数值：

 myNumber = nf.parse(myString);
 

使用 getInstance 或 getNumberInstance 来获取常规数值格式。使用 getIntegerInstance 来获取整数数值格式。使用 getCurrencyInstance 来获取货币数值格式。使用 getPercentInstance 来获取显示百分比的格式。使用此格式，小数 0.53 将显示为 53%。

使用 setMinimumFractionDigits 之类的方法还可以控制数值的显示。如果想对格式化和解析进行更多的控制（或者给予用户更多的控制），可以尝试将从工厂方法获取的 NumberFormat 强制转换为 DecimalFormat。这适用于大多数语言环境；只是要记住将其放入一个 try 代码块中，以防遇到特殊情况。

NumberFormat 和 DecimalFormat 的作用在于，有一些方法控制格式化，还有一些方法控制解析。以下是对每种控制方法的详细描述：

setParseIntegerOnly : 只影响解析，例如，如果为 true，则 "3456.78" -> 3456（并保留索引 6 后面的那个解析位置），如果为 false，则 "3456.78" -> 3456.78（并保留索引 8 后面的那个解析位置）。此方法与格式化无关。如果希望在小数点后面没有数值的情况下不显示小数点，则使用 setDecimalSeparatorAlwaysShown。

setDecimalSeparatorAlwaysShown :只影响格式化，且只影响小数点后没有数值的情况，例如模式 "#,##0.##"，如果为 true，则 3456.00 -> "3,456."，如果为 false，则 3456.00 -> "3456"。此方法与解析无关。如果希望解析在小数点处停止，则使用 setParseIntegerOnly。

还可以使用带有 ParsePosition 和 FieldPosition 的 parse 和 format 方法的形式，它们允许：

• 逐步地解析字符串的各部分
• 对齐小数点和其他区域

例如，可以通过两种方式对齐数值：

1. 如果使用以间隔来对齐的等宽字体，可以在格式调用中传递 FieldPosition，令 field = INTEGER_FIELD。在输出时，getEndIndex 将被设置为最后一个整数字符和小数字符之间的偏移量。在字符串前面加入 (desiredSpaceCount - getEndIndex) 个空格。
2. 如果使用成比例的字体，则不是通过填充空格的方法，而是以像素为单位度量从开始处到 getEndIndex 的字符串宽度。然后在绘制文本之前将画笔移动 (desiredPixelWidth - widthToAlignmentPoint) 个像素。对于没有小数但可能在末尾有其他字符的字符串，这种方法也是有效的，例如，带有圆括号的负数："(12)" 用于 -12。

同步

数值格式化通常是不同步的。建议为每个线程创建独立的格式实例。如果多个线程同时访问一个格式，则它必须是外部同步的。

另请参见：

DecimalFormat, ChoiceFormat, 序列化表格

---

嵌套类摘要
static class	NumberFormat.Field           定义将用作从 NumberFormat.formatToCharacterIterator 返回的 AttributedCharacterIterator 中属性键以及 FieldPosition 中字段标识符的常量。

 

字段摘要
static int	FRACTION_FIELD           用于构造 FieldPosition 对象的字段常量。
static int	INTEGER_FIELD           用于构造 FieldPosition 对象的字段常量。

 

构造方法摘要
protected	NumberFormat()           唯一的构造方法。

 

方法摘要
Object	clone()           重写 Cloneable
boolean	equals(Object obj)           重写 equals
String	format(double number)           格式规范。
abstract  StringBuffer	format(double number, StringBuffer toAppendTo, FieldPosition pos)           格式规范。
String	format(long number)           格式规范。
abstract  StringBuffer	format(long number, StringBuffer toAppendTo, FieldPosition pos)           格式规范。
StringBuffer	format(Object number, StringBuffer toAppendTo, FieldPosition pos)           格式化一个数并将所得文本添加到给定字符串缓冲区。
static Locale[]	getAvailableLocales()           返回一个数组，它包含所有此类的 get*Instance 方法可以为其返回本地化实例的语言环境。
Currency	getCurrency()           获取格式化货币值时此数值格式使用的货币。
static NumberFormat	getCurrencyInstance()           返回当前默认语言环境的货币格式。
static NumberFormat	getCurrencyInstance(Locale inLocale)           返回指定语言环境的货币格式。
static NumberFormat	getInstance()           返回当前默认语言环境的通用数值格式。
static NumberFormat	getInstance(Locale inLocale)           返回指定语言环境的通用数值格式。
static NumberFormat	getIntegerInstance()           返回当前默认语言环境的整数格式。
static NumberFormat	getIntegerInstance(Locale inLocale)           返回指定语言环境的整数格式。
int	getMaximumFractionDigits()           返回数的小数部分所允许的最大位数。
int	getMaximumIntegerDigits()           返回数的整数部分所允许的最大位数。
int	getMinimumFractionDigits()           返回数的小数部分所允许的最小位数。
int	getMinimumIntegerDigits()           返回数的整数部分所允许的最小位数。
static NumberFormat	getNumberInstance()           返回当前默认语言环境的通用数值格式。
static NumberFormat	getNumberInstance(Locale inLocale)           返回指定语言环境的通用数值格式。
static NumberFormat	getPercentInstance()           返回当前默认语言环境的百分比格式。
static NumberFormat	getPercentInstance(Locale inLocale)           返回指定语言环境的百分比格式。
RoundingMode	getRoundingMode()           获取在此 NumberFormat 中使用的 RoundingMode。
int	hashCode()           重写 hashCode
boolean	isGroupingUsed()           如果此格式中使用了分组，则返回 true。
boolean	isParseIntegerOnly()           如果此格式只将数作为整数解析，则返回 true。
Number	parse(String source)           解析给定字符串开头的文本，生成一个数值。
abstract  Number	parse(String source, ParsePosition parsePosition)           如果可能则返回 Long （例如，在 [Long.MIN_VALUE, Long.MAX_VALUE] 范围内且没有小数），否则返回 Double。
Object	parseObject(String source, ParsePosition pos)           解析字符串中的文本，以生成一个 Number。
void	setCurrency(Currency currency)           设置格式化货币值时此数值格式使用的货币。
void	setGroupingUsed(boolean newValue)           设置此格式中是否使用分组。
void	setMaximumFractionDigits(int newValue)           设置数的小数部分所允许的最大位数。
void	setMaximumIntegerDigits(int newValue)           设置数的整数部分所允许的最大位数。
void	setMinimumFractionDigits(int newValue)           设置数的小数部分所允许的最小位数。
void	setMinimumIntegerDigits(int newValue)           设置数的整数部分所允许的最小位数。
void	setParseIntegerOnly(boolean value)           设置数是否应该仅作为整数进行解析。
void	setRoundingMode(RoundingMode roundingMode)           设置在此 NumberFormat 中使用的 RoundingMode。

 

从类 java.text.Format 继承的方法
format, formatToCharacterIterator, parseObject

 

从类 java.lang.Object 继承的方法
finalize, getClass, notify, notifyAll, toString, wait, wait, wait

 

字段详细信息

INTEGER_FIELD

public static final int INTEGER_FIELD

用于构造 FieldPosition 对象的字段常量。表示必须返回格式化数值整数部分的位置。

另请参见：

FieldPosition, 常量字段值

---

FRACTION_FIELD

public static final int FRACTION_FIELD

用于构造 FieldPosition 对象的字段常量。表示必须返回格式化数值小数部分的位置。

另请参见：

FieldPosition, 常量字段值

构造方法详细信息

NumberFormat

protected NumberFormat()

唯一的构造方法。（由子类构造方法调用，通常是隐式的）。

方法详细信息

format

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

格式化一个数并将所得文本添加到给定字符串缓冲区。该数可以是 Number 的任何子类。

对于能够被转换为 long 类型而不丢失信息的所有整型值，此实现使用 Number.longValue() 提取其数值，包括位长小于 64 的 BigInteger 值；使用 Number.doubleValue() 提取所有其他类型的值。然后它调用 format(long,java.lang.StringBuffer,java.text.FieldPosition) 或 format(double,java.lang.StringBuffer,java.text.FieldPosition)。这可能导致丢失数值信息以及 BigInteger 和 BigDecimal 值的精度。

指定者：

类 Format 中的 format

参数：

number - 要格式化的数

toAppendTo - 要添加格式化文本的 StringBuffer

pos - 输入时：如果需要，是一个对齐字段。输出时：是对齐字段的偏移量。

返回：

作为 toAppendTo 传入的值

抛出：

IllegalArgumentException - 如果 number 为 null 或不是 Number 的实例。

NullPointerException - 如果 toAppendTo 或 pos 为 null

ArithmeticException - 如果需要进行舍入但舍入模式设置为 RoundingMode.UNNECESSARY

另请参见：

FieldPosition

---

parseObject

public final Object parseObject(String source,
                                ParsePosition pos)

解析字符串中的文本，以生成一个 Number。

此方法试图解析从 pos 给定的索引处开始的文本。如果解析成功，则将 pos 的索引更新为所解析的最后一字符后的索引（不一定对直到字符串结尾的所有字符进行解析），并返回解析后的数。更新后的 pos 可以用来指示下次调用此方法的起始点。如果发生错误，则 pos 的索引不变，pos 的错误索引被设置为发生错误的字符的索引，并返回 null。

有关数值解析的更多信息，请参阅 parse(String, ParsePosition) 方法。

指定者：

类 Format 中的 parseObject

参数：

source - 一部分将要被解析的 String。

pos - 具有以上所述的索引和错误索引信息的 ParsePosition 对象。

返回：

从字符串进行解析的 Number。如果发生错误，则返回 null。

抛出：

NullPointerException - 如果 pos 为 null。

---

format

public final String format(double number)

格式规范。

抛出：

ArithmeticException - 如果需要进行舍入但舍入模式设置为 RoundingMode.UNNECESSARY

另请参见：

Format.format(java.lang.Object)

---

format

public final String format(long number)

格式规范。

抛出：

ArithmeticException - 如果需要进行舍入但舍入模式设置为 RoundingMode.UNNECESSARY

另请参见：

Format.format(java.lang.Object)

---

format

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

格式规范。

抛出：

ArithmeticException - 如果需要进行舍入但舍入模式设置为 RoundingMode.UNNECESSARY

另请参见：

Format.format(java.lang.Object)

---

format

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

格式规范。

抛出：

ArithmeticException - 如果需要进行舍入但舍入模式设置为 RoundingMode.UNNECESSARY

另请参见：

Format.format(java.lang.Object)

---

parse

public abstract Number parse(String source,
                             ParsePosition parsePosition)

如果可能则返回 Long （例如，在 [Long.MIN_VALUE, Long.MAX_VALUE] 范围内且没有小数），否则返回 Double。如果设置了 IntegerOnly，则将在小数点处停止解析（或者；例如，对于有理数 "1 2/3"，将在 1 后面停止）。不抛出异常；如果没有可被解析的对象，则索引不变！

另请参见：

isParseIntegerOnly(), Format.parseObject(java.lang.String, java.text.ParsePosition)

---

parse

public Number parse(String source)
             throws ParseException

解析给定字符串开头的文本，生成一个数值。此方法不可以使用给定字符串的全部文本。

有关数值解析的更多信息，请参阅 parse(String, ParsePosition) 方法。

参数：

source - 开头应被解析的 String。

返回：

从字符串解析的 Number。

抛出：

ParseException - 如果无法解析指定字符串的开头。

---

isParseIntegerOnly

public boolean isParseIntegerOnly()

如果此格式只将数作为整数解析，则返回 true。例如，在 English 语言环境中，如果 ParseIntegerOnly 为 true，则字符串 "1234." 将作为整数值 1234 进行解析，且解析将在 "." 字符处停止。当然，解析操作所接受的确切格式与语言环境相关，并且是由 NumberFormat 的子类确定的。

---

setParseIntegerOnly

public void setParseIntegerOnly(boolean value)

设置数是否应该仅作为整数进行解析。

另请参见：

isParseIntegerOnly()

---

getInstance

public static final NumberFormat getInstance()

返回当前默认语言环境的通用数值格式。这与调用 getNumberInstance() 相同。

---

getInstance

public static NumberFormat getInstance(Locale inLocale)

返回指定语言环境的通用数值格式。这与调用 getNumberInstance(inLocale) 相同。

---

getNumberInstance

public static final NumberFormat getNumberInstance()

返回当前默认语言环境的通用数值格式。

---

getNumberInstance

public static NumberFormat getNumberInstance(Locale inLocale)

返回指定语言环境的通用数值格式。

---

getIntegerInstance

public static final NumberFormat getIntegerInstance()

返回当前默认语言环境的整数格式。返回数的格式使用四舍五入算法将浮点数舍入为最接近的整数（参见 RoundingMode.HALF_EVEN)，并只解析输入字符串的整数部分（参见 isParseIntegerOnly）。

返回：

整数值的数值格式

从以下版本开始：

1.4

另请参见：

getRoundingMode()

---

getIntegerInstance

public static NumberFormat getIntegerInstance(Locale inLocale)

返回指定语言环境的整数格式。返回数的格式使用四舍五入算法将浮点数舍入为最接近的整数（参见 RoundingMode.HALF_EVEN)，并只解析输入字符串的整数部分（参见 isParseIntegerOnly）。

返回：

整数值的数值格式

从以下版本开始：

1.4

另请参见：

getRoundingMode()

---

getCurrencyInstance

public static final NumberFormat getCurrencyInstance()

返回当前默认语言环境的货币格式。

---

getCurrencyInstance

public static NumberFormat getCurrencyInstance(Locale inLocale)

返回指定语言环境的货币格式。

---

getPercentInstance

public static final NumberFormat getPercentInstance()

返回当前默认语言环境的百分比格式。

---

getPercentInstance

public static NumberFormat getPercentInstance(Locale inLocale)

返回指定语言环境的百分比格式。

---

getAvailableLocales

public static Locale[] getAvailableLocales()

返回一个数组，它包含所有此类的 get*Instance 方法可以为其返回本地化实例的语言环境。返回数组表示 Java 运行时和安装的 NumberFormatProvider 实现所支持的语言环境的并集。它必须至少包含一个等同于 Locale.US 的 Locale 实例。

返回：

一个数组，它包含可获得其本地化 NumberFormat 实例的语言环境。

---

hashCode

public int hashCode()

重写 hashCode

覆盖：

类 Object 中的 hashCode

返回：

此对象的一个哈希码值。

另请参见：

Object.equals(java.lang.Object), Hashtable

---

equals

public boolean equals(Object obj)

重写 equals

覆盖：

类 Object 中的 equals

参数：

obj - 要与之比较的引用对象。

返回：

如果此对象与 obj 参数相同，则返回 true；否则返回 false。

另请参见：

Object.hashCode(), Hashtable

---

clone

public Object clone()

重写 Cloneable

覆盖：

类 Format 中的 clone

返回：

此实例的一个副本。

另请参见：

Cloneable

---

isGroupingUsed

public boolean isGroupingUsed()

如果此格式中使用了分组，则返回 true。例如，在 English 语言环境中，如果使用了分组，则数 1234567 将被格式化为 "1,234,567"。组分隔符以及每个组的大小是与语言环境相关的，由 NumberFormat 的子类确定。

另请参见：

setGroupingUsed(boolean)

---

setGroupingUsed

public void setGroupingUsed(boolean newValue)

设置此格式中是否使用分组。

另请参见：

isGroupingUsed()

---

getMaximumIntegerDigits

public int getMaximumIntegerDigits()

返回数的整数部分所允许的最大位数。

另请参见：

setMaximumIntegerDigits(int)

---

setMaximumIntegerDigits

public void setMaximumIntegerDigits(int newValue)

设置数的整数部分所允许的最大位数。maximumIntegerDigits 必须 >= minimumIntegerDigits。如果 maximumIntegerDigits 的新值小于 minimumIntegerDigits 的当前值，则 minimumIntegerDigits 也将被设置为新值。

参数：

newValue - 要显示的最大整数位数；如果小于 0，则使用 0。具体子类可以为此值强加一个上限，以适合于被格式化的数值类型。

另请参见：

getMaximumIntegerDigits()

---

getMinimumIntegerDigits

public int getMinimumIntegerDigits()

返回数的整数部分所允许的最小位数。

另请参见：

setMinimumIntegerDigits(int)

---

setMinimumIntegerDigits

public void setMinimumIntegerDigits(int newValue)

设置数的整数部分所允许的最小位数。minimumIntegerDigits 必须 <= maximumIntegerDigits。如果 minimumIntegerDigits 的新值超过了 maximumIntegerDigits 的当前值，那么 maximumIntegerDigits 也将被设置为新值

参数：

newValue - 要显示的整数的最小位数；如果小于 0，则使用 0。具体子类可以为此值强加一个上限，以适合于被格式化的数值类型。

另请参见：

getMinimumIntegerDigits()

---

getMaximumFractionDigits

public int getMaximumFractionDigits()

返回数的小数部分所允许的最大位数。

另请参见：

setMaximumFractionDigits(int)

---

setMaximumFractionDigits

public void setMaximumFractionDigits(int newValue)

设置数的小数部分所允许的最大位数。maximumFractionDigits 必须 >= minimumFractionDigits。如果 maximumFractionDigits 的新值小于 minimumFractionDigits 的当前值，则 minimumFractionDigits 也将被设置为新值。

参数：

newValue - 要显示的小数的最大位数；如果小于 0，则使用 0。具体子类可以为此值强加一个上限，以适合于被格式化的数值类型。

另请参见：

getMaximumFractionDigits()

---

getMinimumFractionDigits

public int getMinimumFractionDigits()

返回数的小数部分所允许的最小位数。

另请参见：

setMinimumFractionDigits(int)

---

setMinimumFractionDigits

public void setMinimumFractionDigits(int newValue)

设置数的小数部分所允许的最小位数。minimumFractionDigits 必须 <= maximumFractionDigits。如果 minimumFractionDigits 的新值超过了 maximumFractionDigits 的当前值，那么 maximumIntegerDigits 也将被设置为新值

参数：

newValue - 要显示的小数的最小位数；如果小于 0，则使用 0。具体子类可以为此值强加一个上限，以适合于被格式化的数值类型。

另请参见：

getMinimumFractionDigits()

---

getCurrency

public Currency getCurrency()

获取格式化货币值时此数值格式使用的货币。以与语言环境相关的方式导出初始值。如果不能确定有效的货币，或者没有使用 setCurrency 设置任何货币，则返回值为 null。

默认实现抛出 UnsupportedOperationException。

返回：

此数值格式使用的货币，或者 null

抛出：

UnsupportedOperationException - 如果数值格式类不实现货币格式化

从以下版本开始：

1.4

---

setCurrency

public void setCurrency(Currency currency)

设置格式化货币值时此数值格式使用的货币。此方法不更新数值格式所使用的小数的最小位数或最大位数。

默认实现抛出 UnsupportedOperationException。

参数：

currency - 此数值格式要使用的新货币

抛出：

UnsupportedOperationException - 如果数值格式类不实现货币格式化

NullPointerException - 如果 currency 为 null

从以下版本开始：

1.4

---

getRoundingMode

public RoundingMode getRoundingMode()

获取在此 NumberFormat 中使用的 RoundingMode。在 NumberFormat 中此方法的默认实现始终抛出 UnsupportedOperationException。处理不同舍入模式的子类应该重写此方法。

返回：

用于此 NumberFormat 的 RoundingMode。

抛出：

UnsupportedOperationException - 默认实现始终抛出此异常

从以下版本开始：

1.6

另请参见：

setRoundingMode(RoundingMode)

---

setRoundingMode

public void setRoundingMode(RoundingMode roundingMode)

设置在此 NumberFormat 中使用的 RoundingMode。在 NumberFormat 中此方法的默认实现始终抛出 UnsupportedOperationException。处理不同舍入模式的子类应该重写此方法。

参数：

roundingMode - 要使用的 RoundingMode

抛出：

UnsupportedOperationException - 默认实现始终抛出此异常

NullPointerException - 如果 roundingMode 为 null

从以下版本开始：

1.6

另请参见：

getRoundingMode()

---

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM Platform Standard Ed. 6
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。