JavaTM 2 Platform
Standard Ed. 5.0

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 有助于格式化和分析任何语言环境的数字。代码能够完全独立于语言环境对于小数点、千位分隔符或特殊的十进制数字的约定,甚至与数字格式是否为十进制也是无关的。

为了格式化当前语言环境的数字,要使用一个工厂类方法:

  myString = NumberFormat.getInstance().format(myNumber);
 
如果格式化多个数字,那么获得该格式并多次使用它是更为高效的做法,这样系统就不必多次获取关于语言环境语言和国家/地区约定的信息了。
 NumberFormat nf = NumberFormat.getInstance();
 for (int i = 0; i < a.length; ++i) {
     output.println(nf.format(myNumber[i]) + "; ");
 }
 
要格式化不同语言环境的日期,可在 getInstance 的调用中指定它。
 NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
 
还可以使用 NumberFormat 来分析数字:
 myNumber = nf.parse(myString);
 
使用 getInstancegetNumberInstance 来获取常规数字格式。使用 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。

还可以使用带有 ParsePositionFieldPositionparseformat 方法的形式,它们允许:

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

同步

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

另请参见:
DecimalFormat, ChoiceFormat, 序列化表格

嵌套类摘要
static class NumberFormat.Field
          在从 NumberFormat.formatToCharacterIterator 返回的 AttributedCharacterIterator 中定义用作属性键的常量,并将其作为 FieldPosition 中的字段标识符。
 
字段摘要
static int FRACTION_FIELD
          用于构造 FieldPosition 对象的字段常量。
static int INTEGER_FIELD
          用于构造 FieldPosition 对象的字段常量。
 
构造方法摘要
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)
          返回指定语言环境的百分比格式。
 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)
          设置数是否应该仅作为整数来分析。
 
从类 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

public NumberFormat()
方法详细信息

format

public StringBuffer format(Object number,
                           StringBuffer toAppendTo,
                           FieldPosition pos)
格式化一个数并把所得文本追加到给定字符串缓冲区。该数可以是 Number 的任何子类。

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

指定者:
Format 中的 format
参数:
number - 要格式化的数
toAppendTo - 字符串要被追加到的 StringBuffer
pos - 在输入时:如果需要,是一个对齐字段。在输出时:为对齐字段的偏移量。
返回:
作为 toAppendTo 被传递进来的值
抛出:
IllegalArgumentException - 如果 number 为 null 或不是 Number 的实例。
NullPointerException - 如果 toAppendTopos 为 null
另请参见:
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)
格式规范。

另请参见:
Format.format(java.lang.Object)

format

public final String format(long number)
格式规范。

另请参见:
Format.format(java.lang.Object)

format

public abstract StringBuffer format(double number,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)
格式规范。

另请参见:
Format.format(java.lang.Object)

format

public abstract StringBuffer format(long number,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)
格式规范。

另请参见:
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。例如,在英国语言环境中,如果 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()
返回当前默认语言环境的整数格式。返回的数的格式使用 IEEE 四舍五入算法将浮点数字舍入为最接近的整数(参见 ROUND_HALF_EVEN),并只分析输入字符串的整数部分(参见 isParseIntegerOnly)。

返回:
整数值的数字格式
从以下版本开始:
1.4

getIntegerInstance

public static NumberFormat getIntegerInstance(Locale inLocale)
返回指定语言环境的整数格式。返回的数的格式使用 IEEE 四舍五入算法将浮点数字舍入为最接近的整数(参见 ROUND_HALF_EVEN),并只分析输入字符串的整数部分(参见 isParseIntegerOnly)。

参数:
inLocale - 数字格式所需的语言环境
返回:
整数值的数字格式
从以下版本开始:
1.4

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 方法可以为其返回本地化的实例。返回的数组至少必须包含一个 Locale 实例,它等同于 Locale.US

返回:
语言环境的数组,对于该数组,模块化的 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。例如,在英国语言环境中,如果设置了组,则数 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

JavaTM 2 Platform
Standard Ed. 5.0

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

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