模块  java.base
软件包  java.text

Class 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]) + "; ");
 }
    要格式化其他区域设置的数字，请在对getInstance的调用中指定它。 
    
 NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);

    如果区域设置包含“nu”（数字）和/或“rg”（区域覆盖） Unicode extensions ， 则会覆盖十进制数字和/或用于格式化的国家/地区。 如果同时指定了“nu”和“rg”，则“nu”扩展名中的十进制数字将取代“rg”扩展名中的隐含数字。

    您还可以使用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。

    您还可以使用parse和format方法的ParsePosition以及FieldPosition和FieldPosition ，以便：

    • 逐步解析字符串
    • 对齐小数点和其他区域
    例如，您可以通过两种方式对齐数字：
    1. 如果您使用带间距的等宽字体进行对齐，则可以在格式调用中传递FieldPosition ，其中包含字段 = INTEGER_FIELD 。 在输出时， getEndIndex将被设置为整数的最后一个字符和小数之间的偏移量。 在字符串的前面添加（desiredSpaceCount - getEndIndex）空格。
    2. 如果您使用的是比例字体，而不是使用空格填充，请测量从开头到getEndIndex的字符串宽度（以像素为getEndIndex 。 然后在绘制文本之前将笔移动（desiredPixelWidth - widthToAlignmentPoint）。 它也可以在没有小数的情况下工作，但最后可能还有其他字符，例如，带有括号的负数：“（12）”表示-12。

    Synchronization

    数字格式通常不同步。 建议为每个线程创建单独的格式实例。 如果多个线程同时访问格式，则必须在外部进行同步。

    实现要求：
    该format(double, StringBuffer, FieldPosition) ， format(long, StringBuffer, FieldPosition)和parse(String, ParsePosition)方法可能抛出NullPointerException ，如果他们的任何参数为null 。 子类可以提供其自己的实现和规范，关于NullPointerException 。

    默认实现提供了RoundingMode中定义的舍入模式，用于格式化数字。 它使用round half-even algorithm 。 要更改舍入模式，请使用setRoundingMode 。 静态工厂方法返回的NumberFormat配置为使用半偶数舍入（请参阅RoundingMode.HALF_EVEN ）舍入浮点数以进行格式化。

    从以下版本开始：
    1.1
    另请参见：
    DecimalFormat ， ChoiceFormat ， Serialized Form

    • 字段详细信息

      • INTEGER_FIELD

        public static final int INTEGER_FIELD
        用于构造FieldPosition对象的字段常量。 表示应返回格式化数字的整数部分的位置。
        另请参见：
        FieldPosition ， 常数字段值

      • FRACTION_FIELD

        public static final int FRACTION_FIELD
        用于构造FieldPosition对象的字段常量。 表示应返回格式化数字的小数部分的位置。
        另请参见：
        FieldPosition ， 常数字段值

    • 构造方法详细信息

      • NumberFormat

        protected NumberFormat()
        唯一的构造函数。 （对于子类构造函数的调用，通常是隐式的。）

    • 方法详细信息

      • parseObject

        public final Object parseObject​(String source,
                                ParsePosition pos)
        解析字符串中的文本以生成Number 。

        该方法尝试从pos给出的索引处开始解析文本。 如果解析成功，则在使用最后一个字符之后将索引pos更新为索引（解析不一定使用直到字符串末尾的所有字符），并返回解析的数字。 更新的pos可用于指示下一次调用此方法的起点。 如果发生错误，则索引pos不会更改，错误索引pos将设置为发生错误的字符的索引，并返回null。

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

        Specified by:
        parseObject在课程 Format
        参数
        source - A String ，其中一部分应该被解析。
        pos - 具有索引和错误索引信息的 ParsePosition对象，如上所述。
        结果
        从字符串解析的Number 。 如果出现错误，则返回null。
        异常
        NullPointerException - 如果 source或 pos为空。

      • format

        public abstract StringBuffer format​(double number,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)
        格式专业化。
        参数
        number - 要格式化的双数字
        toAppendTo - 要将格式化文本附加到的StringBuffer
        pos - 跟踪返回字符串中字段的位置。 例如，要格式化Locale.US语言环境中的数字1234567.89 ，如果给定的fieldPosition是INTEGER_FIELD ，则对于输出字符串1,234,567.89 ，开始索引和结束索引fieldPosition将分别设置为0和9。
        结果
        格式化的StringBuffer
        异常
        ArithmeticException - 如果舍入模式设置为RoundingMode需要舍入 ArithmeticException
        另请参见：
        Format.format(java.lang.Object)

      • format

        public abstract StringBuffer format​(long number,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)
        格式专业化。
        参数
        number - 要格式化的长数字
        toAppendTo - 要附加格式化文本的StringBuffer
        pos - 跟踪返回字符串中字段的位置。 例如，要格式化Locale.US语言环境中的数字123456789 ，如果给定的fieldPosition是INTEGER_FIELD ，则对于输出字符串123,456,789 ，开始索引和结束索引fieldPosition将分别设置为0和11。
        结果
        格式化的StringBuffer
        异常
        ArithmeticException - 如果舍入模式设置为RoundingMode需要舍入 ArithmeticException
        另请参见：
        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之后停止）。 不抛出异常; 如果没有对象可以解析，索引就不变了！
        参数
        source - 要解析的String
        parsePosition - 解析位置
        结果
        解析后的值
        另请参见：
        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的子类确定。
        结果
        true如果数字应仅解析为整数; 否则为false

      • setParseIntegerOnly

        public void setParseIntegerOnly​(boolean value)
        设置是否应仅将数字解析为整数。
        参数
        value - true如果数字应仅解析为整数; 否则为false
        另请参见：
        isParseIntegerOnly()

      • getInstance

        public static final NumberFormat getInstance()
        返回当前默认FORMAT语言环境的通用数字格式。 这与致电getNumberInstance()相同。
        结果
        用于通用数字格式的 NumberFormat实例

      • getInstance

        public static NumberFormat getInstance​(Locale inLocale)
        返回指定语言环境的通用数字格式。 这与致电getNumberInstance(inLocale)相同。
        参数
        inLocale - 所需的区域设置
        结果
        用于通用数字格式的 NumberFormat实例

      • getNumberInstance

        public static NumberFormat getNumberInstance​(Locale inLocale)
        返回指定语言环境的通用数字格式。
        参数
        inLocale - 所需的区域设置
        结果
        用于通用数字格式的 NumberFormat实例

      • getIntegerInstance

        public static NumberFormat getIntegerInstance​(Locale inLocale)
        返回指定语言环境的整数数字格式。 返回的数字格式配置为使用半偶数舍入（参见RoundingMode.HALF_EVEN ）将浮点数舍入为最接近的整数进行格式化，并仅解析输入字符串的整数部分（请参阅isParseIntegerOnly ）。
        参数
        inLocale - 所需的区域设置
        结果
        整数值的数字格式
        从以下版本开始：
        1.4
        另请参见：
        getRoundingMode()

      • getCurrencyInstance

        public static NumberFormat getCurrencyInstance​(Locale inLocale)
        返回指定语言环境的货币格式。
        参数
        inLocale - 所需的区域设置
        结果
        货币格式的 NumberFormat实例

      • getPercentInstance

        public static NumberFormat getPercentInstance​(Locale inLocale)
        返回指定语言环境的百分比格式。
        参数
        inLocale - 所需的语言环境
        结果
        NumberFormat实例的百分比格式

      • getAvailableLocales

        public static Locale[] getAvailableLocales()
        返回所有语言环境的数组， get*Instance方法可以get*Instance返回本地化实例。 返回的数组表示Java运行时和已安装的NumberFormatProvider实现支持的语言环境的并集 。 它必须至少包含Locale实例，等于Locale.US 。
        结果
        一组区域设置，其本地化的 NumberFormat实例可用。

      • equals

        public boolean equals​(Object obj)
        覆盖等于。
        重写：
        equals in class Object
        参数
        obj - 要与之比较的引用对象。
        结果
        true如果此对象与obj参数相同; 否则为false 。
        另请参见：
        Object.hashCode() ， HashMap

      • clone

        public Object clone()
        覆盖Cloneable。
        重写：
        clone in class Format
        结果
        这个实例的克隆。
        另请参见：
        Cloneable

      • isGroupingUsed

        public boolean isGroupingUsed()
        如果以此格式使用分组，则返回true。 例如，在英语区域设置中，如果打开分组，则数字1234567可能会格式化为“1,234,567”。 分组分隔符以及每个组的大小取决于区域设置，并由NumberFormat的子类确定。
        结果
        true如果使用分组; 否则为false
        另请参见：
        setGroupingUsed(boolean)

      • setGroupingUsed

        public void setGroupingUsed​(boolean newValue)
        设置是否以此格式使用分组。
        参数
        newValue - true如果使用分组; 否则为false
        另请参见：
        isGroupingUsed()

      • getMaximumIntegerDigits

        public int getMaximumIntegerDigits()
        返回数字整数部分允许的最大位数。
        结果
        最大位数
        另请参见：
        setMaximumIntegerDigits(int)

      • setMaximumIntegerDigits

        public void setMaximumIntegerDigits​(int newValue)
        设置数字整数部分允许的最大位数。 maximumIntegerDigits必须是≥minimumIntegerDigits。 如果maximumIntegerDigits的新值小于minimumIntegerDigits的当前值，则minimumIntegerDigits也将设置为新值。
        参数
        newValue - 要显示的最大整数位数; 如果小于零，则使用零。 具体子类可以对适合于格式化的数字类型的此值强制执行上限。
        另请参见：
        getMaximumIntegerDigits()

      • getMinimumIntegerDigits

        public int getMinimumIntegerDigits()
        返回数字整数部分允许的最小位数。
        结果
        最小位数
        另请参见：
        setMinimumIntegerDigits(int)

      • setMinimumIntegerDigits

        public void setMinimumIntegerDigits​(int newValue)
        设置数字整数部分允许的最小位数。 minimumIntegerDigits必须是≤maxIntegerDigits。 如果minimumIntegerDigits的新值超过maximumIntegerDigits的当前值，则maximumIntegerDigits也将设置为新值
        参数
        newValue - 要显示的最小整数位数; 如果小于零，则使用零。 具体子类可以对适合于格式化的数字类型的此值强制执行上限。
        另请参见：
        getMinimumIntegerDigits()

      • getMaximumFractionDigits

        public int getMaximumFractionDigits()
        返回数字小数部分允许的最大位数。
        结果
        最大位数。
        另请参见：
        setMaximumFractionDigits(int)

      • setMaximumFractionDigits

        public void setMaximumFractionDigits​(int newValue)
        设置数字小数部分允许的最大位数。 maximumFractionDigits必须是≥minimumFractionDigits。 如果maximumFractionDigits的新值小于minimumFractionDigits的当前值，则minimumFractionDigits也将设置为新值。
        参数
        newValue - 要显示的最大小数位数; 如果小于零，则使用零。 具体子类可以对适合于格式化的数字类型的此值强制执行上限。
        另请参见：
        getMaximumFractionDigits()

      • getMinimumFractionDigits

        public int getMinimumFractionDigits()
        返回数字小数部分中允许的最小位数。
        结果
        最小位数
        另请参见：
        setMinimumFractionDigits(int)

      • setMinimumFractionDigits

        public void setMinimumFractionDigits​(int newValue)
        设置数字小数部分允许的最小位数。 minimumFractionDigits必须是？maximumFractionDigits。 如果minimumFractionDigits的新值超过maximumFractionDigits的当前值，则maximumIntegerDigits也将设置为新值
        参数
        newValue - 要显示的最小分数位数; 如果小于零，则使用零。 具体子类可以对适合于格式化的数字类型的此值强制执行上限。
        另请参见：
        getMinimumFractionDigits()

      • getCurrency

        public Currency getCurrency()
        获取格式化货币值时此数字格式使用的货币。 初始值以区域设置相关的方式派生。 如果无法确定有效货币且未使用setCurrency设置货币，则返回值可能为null。

        默认实现抛出UnsupportedOperationException 。

        结果
        此数字格式使用的货币，或 null
        异常
        UnsupportedOperationException - 如果数字格式类未实现货币格式
        从以下版本开始：
        1.4

      • setCurrency

        public void setCurrency​(Currency currency)
        设置货币值格式时设置此数字格式使用的货币。 这不会更新数字格式使用的最小或最大小数位数。

        默认实现抛出UnsupportedOperationException 。

        参数
        currency - 此数字格式使用的新货币
        异常
        UnsupportedOperationException - 如果数字格式类未实现货币格式
        NullPointerException - 如果 currency为空
        从以下版本开始：
        1.4