模块  java.base
软件包  java.text

Class DecimalFormat

  • 实现的所有接口
    Serializable ， Cloneable 
    public class DecimalFormatextends NumberFormat
    DecimalFormat是的具体子类NumberFormat格式化十进制数字。 它具有多种功能，旨在解析和格式化任何语言环境中的数字，包括支持西方，阿拉伯语和印度语数字。 它还支持不同类型的数字，包括整数（123），定点数（123.4），科学记数法（1.23E4），百分比（12％）和货币金额（123美元）。 所有这些都可以本地化。

    要获取特定区域设置的NumberFormat （包括默认区域设置），请调用NumberFormat的工厂方法之一，例如getInstance() 。 通常，不要直接调用DecimalFormat构造函数，因为NumberFormat工厂方法可能返回DecimalFormat以外的子类。 如果需要自定义格式对象，请执行以下操作： 

     NumberFormat f = NumberFormat.getInstance(loc); if (f instanceof DecimalFormat) {     ((DecimalFormat) f).setDecimalSeparatorAlwaysShown(true); }

    DecimalFormat包括图案和一组符号 。 可以使用applyPattern()直接设置模式，也可以使用API方法间接设置模式。 符号存储在DecimalFormatSymbols对象中。 使用NumberFormat工厂方法时，将从本地化的ResourceBundle中读取模式和符号。

    模式

    DecimalFormat模式具有以下语法： 
     Pattern:         PositivePattern         PositivePattern ; NegativePattern PositivePattern:         Prefixopt Number Suffixopt NegativePattern:         Prefixopt Number Suffixopt Prefix:         any Unicode characters except \uFFFE, \uFFFF, and special characters Suffix:         any Unicode characters except \uFFFE, \uFFFF, and special characters Number:         Integer Exponentopt         Integer . Fraction Exponentopt Integer:         MinimumInteger         #         # Integer         # , Integer MinimumInteger:         0         0 MinimumInteger         0 , MinimumInteger Fraction:         MinimumFractionopt OptionalFractionopt MinimumFraction:         0 MinimumFractionopt OptionalFraction:         # OptionalFractionopt Exponent:         E MinimumExponent MinimumExponent:         0 MinimumExponentopt

    DecimalFormat模式包含正负子模式，例如， "#,##0.00;(#,##0.00)" 。 每个子模式都有前缀，数字部分和后缀。 负子模式是可选的; 如果不存在，那么前缀为局部减号的正子模式（大多数语言环境中为'-' ）将用作负子模式。 也就是说， "0.00"单独相当于"0.00;-0.00" 。 如果存在明确的否定子模式，则仅用于指定否定前缀和后缀; 数字，最小数字和其他特征都与正模式相同。 这意味着"#,##0.0#;(#)"产生与"#,##0.0#;(#,##0.0#)"完全相同的行为。

    用于无穷大，数字，千位分隔符，小数分隔符等的前缀，后缀和各种符号可以设置为任意值，并且在格式化期间它们将正确显示。 但是，必须注意符号和字符串不要冲突，否则解析将不可靠。 例如，正负DecimalFormat.parse()前缀或后缀必须是不同的DecimalFormat.parse()才能区分正值和负值。 （如果它们是相同的，那么DecimalFormat将表现为好像没有指定负子模式。）另一个例子是小数分隔符和千位分隔符应该是不同的字符，否则解析将是不可能的。

    分组分隔符通常用于数千个，但在某些国家/地区，它分离了数万个。 分组大小是分组字符之间的固定位数，例如3表示100,000,000或4表示1,0000,0000。 如果提供具有多个分组字符的模式，则最后一个和整数结尾之间的间隔是使用的间隔。 所以"#,##,###,####" == "######,####" == "##,####,####" 。

    特殊模式字符

    模式中的许多字符都是字面上的; 它们在解析期间匹配，并在格式化期间输出不变。 另一方面，特殊字符代表其他字符，字符串或字符类。 除非另有说明，否则必须引用它们，如果它们作为文字出现在前缀或后缀中。

    此处列出的字符用于非本地化模式。 本地化模式使用从此格式化程序的DecimalFormatSymbols对象中获取的相应字符，这些字符将失去其特殊状态。 货币符号和报价有两个例外，它们没有本地化。

    Chart showing symbol, location, localized, and meaning.
    Symbol Location Localized? Meaning
    0 Number Yes Digit
    # Number Yes Digit, zero shows as absent
    . Number Yes Decimal separator or monetary decimal separator
    - Number Yes Minus sign
    , Number Yes Grouping separator
    E Number Yes Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix.
    ; Subpattern boundary Yes Separates positive and negative subpatterns
    % Prefix or suffix Yes Multiply by 100 and show as percentage
    \u2030 Prefix or suffix Yes Multiply by 1000 and show as per mille value
    ¤ (\u00A4) Prefix or suffix No Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If present in a pattern, the monetary decimal separator is used instead of the decimal separator.
    ' Prefix or suffix No Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock".

    科学计数法

    科学记数法中的数字表示为尾数和10的幂的乘积，例如，1234可表示为1.234×10 ^ 3。 尾数通常在1.0≤x<10.0的范围内，但不一定是。 可以指示DecimalFormat 仅通过模式格式化和解析科学记数法; 目前没有工厂方法可以创建科学记数法格式。 在模式中，紧跟一个或多个数字字符的指数字符表示科学记数法。 示例： "0.###E0"将数字1234格式化为"1.234E3" 。

    • 指数字符后面的数字字符数给出最小指数位数。 没有最大值。 使用局部减号格式化负指数， 而不是模式中的前缀和后缀。 这允许诸如"0.###E0 m/s"模式。
    • 最小和最大整数位数一起解释：
      • 如果最大整数位数大于其最小数且大于1，则强制指数为最大整数位数的倍数，并将最小整数位数解释为1.最常见的使用它来生成工程符号 ，其中指数是三的倍数，例如"##0.#####E0" 。 使用此模式，数字12345格式为"12.345E3"格式为"123.456E3" 。
      • 否则，通过调整指数来实现最小整数位数。 示例：0.00123格式化为"00.###E0"得到"12.3E-4" 。
    • 尾数中的有效位数是最小整数和最大小数位的总和，不受最大整数位数的影响。 例如，使用"##0.##E0"格式化的12345是"12.3E3" 。 要显示所有数字，请将有效数字计数设置为零。 有效位数不会影响解析。
    • 指数模式可能不包含分组分隔符。

    四舍五入

    DecimalFormat提供了RoundingMode中定义的舍入模式，用于格式化。 默认情况下，它使用RoundingMode.HALF_EVEN 。

    数字

    对于格式化， DecimalFormat使用以DecimalFormatSymbols对象中定义的本地化零数字开头的十个连续字符作为数字。 对于解析，可识别这些数字以及由Character.digit定义的所有Unicode十进制数字。

    特殊价值观

    NaN被格式化为字符串，通常具有单个字符\uFFFD 。 该字符串由DecimalFormatSymbols对象确定。 这是不使用前缀和后缀的唯一值。

    Infinity被格式化为字符串，通常具有单个字符\u221E ，其中应用了正或负前缀和后缀。 无穷大字符串由DecimalFormatSymbols对象确定。

    负零（ "-0" ）解析为

    • BigDecimal(0)如果isParseBigDecimal()是真的，
    • Long(0)如果isParseBigDecimal()为假且isParseIntegerOnly()为真，
    • Double(-0.0)如果两个isParseBigDecimal()和isParseIntegerOnly()都是假的。

    Synchronization

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

    例 

     <strong>// Print out a number using the localized number, integer, currency, // and percent format for each locale</strong> Locale[] locales = NumberFormat.getAvailableLocales(); double myNumber = -1234.56; NumberFormat form; for (int j = 0; j < 4; ++j) {     System.out.println("FORMAT");     for (int i = 0; i < locales.length; ++i) {         if (locales[i].getCountry().length() == 0) {            continue; // Skip language-only locales         }         System.out.print(locales[i].getDisplayName());         switch (j) {         case 0:             form = NumberFormat.getInstance(locales[i]); break;         case 1:             form = NumberFormat.getIntegerInstance(locales[i]); break;         case 2:             form = NumberFormat.getCurrencyInstance(locales[i]); break;         default:             form = NumberFormat.getPercentInstance(locales[i]); break;         }         if (form instanceof DecimalFormat) {             System.out.print(": " + ((DecimalFormat) form).toPattern());         }         System.out.print(" -> " + form.format(myNumber));         try {             System.out.println(" -> " + form.parse(form.format(myNumber)));         } catch (ParseException e) {}     } }
    从以下版本开始：
    1.1
    另请参见：
    Java Tutorial ， NumberFormat ， DecimalFormatSymbols ， ParsePosition ， Serialized Form

    • 方法详细信息

      • format

        public final StringBuffer format​(Object number,                                 StringBuffer toAppendTo,                                 FieldPosition pos)
        格式化数字并将结果文本附加到给定的字符串缓冲区。 该数字可以是Number的任何子类。

        此实现使用允许的最大精度。

        重写：
        format在课程 NumberFormat
        参数
        number - 要格式化的数字
        toAppendTo - 要附加格式化文本的 StringBuffer
        pos - 跟踪返回字符串中字段的位置。 例如，要格式化Locale.US语言环境中的数字1234567.89 ，如果给定的fieldPosition是NumberFormat.INTEGER_FIELD ，则对于输出字符串1,234,567.89 ，开始索引和结束索引fieldPosition将分别设置为0和9。
        结果
        传入的值为 toAppendTo
        异常
        IllegalArgumentException - 如果 number为null或不是 Number的实例。
        NullPointerException - 如果 toAppendTo或 pos为空
        ArithmeticException - 如果舍入模式设置为RoundingMode需要舍入 ArithmeticException
        另请参见：
        FieldPosition

      • format

        public StringBuffer format​(double number,                           StringBuffer result,                           FieldPosition fieldPosition)
        格式化double以生成字符串。
        Specified by:
        format in class NumberFormat
        参数
        number - 要格式化的双 number
        result - 要附加文本的位置
        fieldPosition - 跟踪返回字符串中字段的位置。 例如，对于格式化Locale.US区域设置中的数字1234567.89 ，如果给定的fieldPosition是NumberFormat.INTEGER_FIELD ，则对于输出字符串1,234,567.89 ，开始索引和结束索引fieldPosition将分别设置为0和9。
        结果
        格式化的数字字符串
        异常
        NullPointerException - 如果 result或 fieldPosition是 null
        ArithmeticException - 如果舍入模式设置为RoundingMode需要舍入 ArithmeticException
        另请参见：
        FieldPosition

      • format

        public StringBuffer format​(long number,                           StringBuffer result,                           FieldPosition fieldPosition)
        格式化long以生成字符串。
        Specified by:
        format在课程 NumberFormat
        参数
        number - 格式化的长
        result - 要附加文本的位置
        fieldPosition - 跟踪返回字符串中字段的位置。 例如，要格式化Locale.US语言环境中的数字123456789 ，如果给定的fieldPosition为NumberFormat.INTEGER_FIELD ，则对于输出字符串123,456,789 ，开始索引和结束索引fieldPosition将分别设置为0和11。
        结果
        格式化的数字字符串
        异常
        NullPointerException - 如果 result或 fieldPosition是 null
        ArithmeticException - 如果舍入模式设置为RoundingMode，则需要舍入 ArithmeticException
        另请参见：
        FieldPosition

      • formatToCharacterIterator

        public AttributedCharacterIterator formatToCharacterIterator​(Object obj)
        格式化一个生成AttributedCharacterIterator的对象。 您可以使用返回的AttributedCharacterIterator来构建生成的String，以及确定有关生成的String的信息。

        AttributedCharacterIterator的每个属性键的类型为NumberFormat.Field ，其属性值与属性键相同。

        重写：
        formatToCharacterIterator ，课程 Format
        参数
        obj - 要格式化的对象
        结果
        AttributedCharacterIterator描述格式化的值。
        异常
        NullPointerException - 如果obj为null。
        IllegalArgumentException - 格式无法格式化给定对象时。
        ArithmeticException - 如果舍入模式设置为RoundingMode需要舍入 ArithmeticException
        从以下版本开始：
        1.4

      • parse

        public Number parse​(String text,                    ParsePosition pos)
        从字符串解析文本以生成Number 。

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

        返回的子类取决于isParseBigDecimal()的值以及要解析的字符串。

        • 如果isParseBigDecimal()为false（默认值），则大多数整数值将作为Long对象返回，无论它们如何写入： "17"和"17.000"都解析为Long(17) 。 无法容纳Long将返回为Double s。 这包括具有小数部分，无限值， NaN和值-0.0的值。 DecimalFormat 未根据源字符串中是否存在小数分隔符来决定是返回Double还是Long 。 这样做可以防止溢出双尾数的整数（例如"-9,223,372,036,854,775,808.00" ）被准确解析。

          呼叫者可以使用Number方法doubleValue ， longValue ，等等，以获得他们想要的类型。

        • 如果isParseBigDecimal()为true，则返回BigDecimal对象。 这些值是由BigDecimal(String)为与语言环境无关的格式的相应字符串构造的值。 特殊情况的负和正无穷大和NaN返回为Double实例，其中包含相应的Double常量的值。

        DecimalFormat解析表示十进制数字的所有Unicode字符，如Character.digit()所定义。 此外， DecimalFormat还将以DecimalFormatSymbols对象中定义的本地化零数字开头的十个连续字符识别为数字。

        Specified by:
        parse在课程 NumberFormat
        参数
        text - 要解析的字符串
        pos - 具有 ParsePosition索引和错误索引信息的 ParsePosition对象。
        结果
        解析后的值，如果解析失败 null
        异常
        NullPointerException - 如果 text或 pos为空。
        另请参见：
        NumberFormat.isParseIntegerOnly() ， Format.parseObject(java.lang.String, java.text.ParsePosition)

      • getDecimalFormatSymbols

        public DecimalFormatSymbols getDecimalFormatSymbols()
        返回十进制格式符号的副本，通常程序员或用户不会更改。
        结果
        所需DecimalFormatSymbols的副本
        另请参见：
        DecimalFormatSymbols

      • setDecimalFormatSymbols

        public void setDecimalFormatSymbols​(DecimalFormatSymbols newSymbols)
        设置十进制格式符号，程序员或用户通常不会更改这些符号。
        参数
        newSymbols - 所需的DecimalFormatSymbols
        另请参见：
        DecimalFormatSymbols

      • getPositivePrefix

        public String getPositivePrefix()
        获得正面前缀。

        示例：+123，$ 123，sFr123

        结果
        正面的前缀

      • setPositivePrefix

        public void setPositivePrefix​(String newValue)
        设置正前缀。

        示例：+123，$ 123，sFr123

        参数
        newValue - 新的正前缀

      • getNegativePrefix

        public String getNegativePrefix()
        获取否定前缀。

        示例：-123，（$ 123）（带后缀为负数），sFr-123

        结果
        否定前缀

      • setNegativePrefix

        public void setNegativePrefix​(String newValue)
        设置否定前缀。

        示例：-123，（$ 123）（带后缀为负数），sFr-123

        参数
        newValue - 新的否定前缀

      • getPositiveSuffix

        public String getPositiveSuffix()
        获得正后缀。

        示例：123％

        结果
        正后缀

      • setPositiveSuffix

        public void setPositiveSuffix​(String newValue)
        设置正后缀。

        示例：123％

        参数
        newValue - 新的正后缀

      • getNegativeSuffix

        public String getNegativeSuffix()
        获得否定后缀。

        示例：-123％，（$ 123）（带有正后缀）

        结果
        负后缀

      • setNegativeSuffix

        public void setNegativeSuffix​(String newValue)
        设置负后缀。

        示例：123％

        参数
        newValue - 新的负后缀

      • getMultiplier

        public int getMultiplier()
        获取以百分比，每千米和类似格式使用的乘数。
        结果
        乘数
        另请参见：
        setMultiplier(int)

      • setMultiplier

        public void setMultiplier​(int newValue)
        设置以百分比，每千米和类似格式使用的乘数。 对于百分比格式，将乘数设置为100，将后缀设置为'％'（对于阿拉伯语，使用阿拉伯语百分号）。 对于每千米格式，将乘数设置为1000，将后缀设置为'\ u2030'。

        示例：使用乘数100，将1.23格式化为“123”，将“123”解析为1.23。

        参数
        newValue - 新的乘数
        另请参见：
        getMultiplier()

      • isDecimalSeparatorAlwaysShown

        public boolean isDecimalSeparatorAlwaysShown()
        允许您使用整数获取小数分隔符的行为。 （小数点分隔符将始终显示小数。）

        示例：十进制ON：12345→12345。 OFF：12345→12345

        结果
        true如果始终显示小数点分隔符; 否则为false

      • setDecimalSeparatorAlwaysShown

        public void setDecimalSeparatorAlwaysShown​(boolean newValue)
        允许您使用整数设置小数分隔符的行为。 （小数点分隔符将始终显示小数。）

        示例：十进制ON：12345→12345。 OFF：12345→12345

        参数
        newValue - true如果始终显示小数点分隔符; 否则为false

      • clone

        public Object clone()
        标准覆盖; 语义没有变化。
        重写：
        clone in class NumberFormat
        结果
        这个实例的克隆。
        另请参见：
        Cloneable

      • equals

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

      • toLocalizedPattern

        public String toLocalizedPattern()
        合成表示此Format对象的当前状态的本地化模式字符串。
        结果
        本地化的模式字符串
        另请参见：
        applyPattern(java.lang.String)

      • applyPattern

        public void applyPattern​(String pattern)
        将给定的模式应用于此Format对象。 模式是各种格式属性的简写规范。 这些属性也可以通过各种setter方法单独更改。

        此例程设置的整数位数没有限制，因为这是典型的最终用户需求; 如果要设置实际值，请使用setMaximumInteger。 对于负数，请使用以分号分隔的第二个模式

        例"#,#00.0#" →1,234.56

        这意味着至少2个整数位，1个小数位，最多2个小数位。

        示例： "#,#00.0#;(#,#00.0#)"用于括号中的否定。

        在负模式中，忽略最小和最大计数; 假设这些被设定为正模式。

        参数
        pattern - 一种新模式
        异常
        NullPointerException - 如果 pattern为空
        IllegalArgumentException - 如果给定的模式无效。

      • applyLocalizedPattern

        public void applyLocalizedPattern​(String pattern)
        将给定的模式应用于此Format对象。 假设该模式采用局部表示法。 模式是各种格式属性的简写规范。 这些属性也可以通过各种setter方法单独更改。

        此例程设置的整数位数没有限制，因为这是典型的最终用户需求; 如果要设置实际值，请使用setMaximumInteger。 对于负数，请使用以分号分隔的第二个模式

        例"#,#00.0#" →1,234.56

        这意味着至少2个整数位，1个小数位，最多2个小数位。

        示例： "#,#00.0#;(#,#00.0#)"用于括号中的底片。

        在负模式中，忽略最小和最大计数; 假设这些被设定为正模式。

        参数
        pattern - 一种新模式
        异常
        NullPointerException - 如果 pattern为空
        IllegalArgumentException - 如果给定的模式无效。

      • setMaximumIntegerDigits

        public void setMaximumIntegerDigits​(int newValue)
        设置数字整数部分允许的最大位数。 对于格式化BigInteger和BigDecimal对象以外的数字，使用较低的newValue和309。 负输入值替换为0。
        重写：
        setMaximumIntegerDigits在课程 NumberFormat
        参数
        newValue - 要显示的最大整数位数; 如果小于零，则使用零。 具体子类可以对适合于格式化的数字类型的此值强制执行上限。
        另请参见：
        NumberFormat.setMaximumIntegerDigits(int)

      • setMinimumIntegerDigits

        public void setMinimumIntegerDigits​(int newValue)
        设置数字整数部分允许的最小位数。 对于格式化BigInteger和BigDecimal对象以外的数字，使用较低的newValue和309。 负输入值替换为0。
        重写：
        setMinimumIntegerDigits在课程 NumberFormat
        参数
        newValue - 要显示的最小整数位数; 如果小于零，则使用零。 具体子类可以对适合于格式化的数字类型的此值强制执行上限。
        另请参见：
        NumberFormat.setMinimumIntegerDigits(int)

      • setMaximumFractionDigits

        public void setMaximumFractionDigits​(int newValue)
        设置数字小数部分允许的最大位数。 对于格式化BigInteger和BigDecimal对象以外的数字，使用较低的newValue和340。 负输入值替换为0。
        重写：
        setMaximumFractionDigits在课程 NumberFormat
        参数
        newValue - 要显示的最大小数位数; 如果小于零，则使用零。 具体子类可以对适合于格式化的数字类型的此值强制执行上限。
        另请参见：
        NumberFormat.setMaximumFractionDigits(int)

      • setMinimumFractionDigits

        public void setMinimumFractionDigits​(int newValue)
        设置数字小数部分允许的最小位数。 对于格式化BigInteger和BigDecimal对象以外的数字，使用较低的newValue和340。 负输入值替换为0。
        重写：
        setMinimumFractionDigits在课程 NumberFormat
        参数
        newValue - 要显示的最小分数位数; 如果小于零，则使用零。 具体子类可以对适合于格式化的数字类型的此值强制执行上限。
        另请参见：
        NumberFormat.setMinimumFractionDigits(int)

      • getMaximumIntegerDigits

        public int getMaximumIntegerDigits()
        获取数字整数部分允许的最大位数。 对于格式化BigInteger和BigDecimal对象以外的数字，将使用返回值和309中的较低者。
        重写：
        getMaximumIntegerDigits ，课程 NumberFormat
        结果
        最大位数
        另请参见：
        setMaximumIntegerDigits(int)

      • getMinimumIntegerDigits

        public int getMinimumIntegerDigits()
        获取数字整数部分允许的最小位数。 对于格式化BigInteger和BigDecimal对象以外的数字，将使用返回值和309中的较低者。
        重写：
        getMinimumIntegerDigits在课程 NumberFormat
        结果
        最小位数
        另请参见：
        setMinimumIntegerDigits(int)

      • getMaximumFractionDigits

        public int getMaximumFractionDigits()
        获取数字小数部分允许的最大位数。 对于格式化BigInteger和BigDecimal对象以外的数字，将使用返回值和340的较低值。
        重写：
        getMaximumFractionDigits in class NumberFormat
        结果
        最大位数。
        另请参见：
        setMaximumFractionDigits(int)

      • getMinimumFractionDigits

        public int getMinimumFractionDigits()
        获取数字小数部分中允许的最小位数。 对于格式化BigInteger和BigDecimal对象以外的数字，将使用返回值和340的较低值。
        重写：
        getMinimumFractionDigits在课程 NumberFormat
        结果
        最小位数
        另请参见：
        setMinimumFractionDigits(int)

      • getCurrency

        public Currency getCurrency()
        获取格式化货币值时此十进制格式使用的货币。 通过使用此数字格式的符号调用DecimalFormatSymbols.getCurrency获得货币。
        重写：
        getCurrency在课程 NumberFormat
        结果
        此十进制格式使用的货币，或 null
        从以下版本开始：
        1.4

      • setCurrency

        public void setCurrency​(Currency currency)
        设置货币值格式时设置此数字格式使用的货币。 这不会更新数字格式使用的最小或最大小数位数。 通过在此数字格式的符号上调用DecimalFormatSymbols.setCurrency来设置货币。
        重写：
        setCurrency in class NumberFormat
        参数
        currency - 此十进制格式使用的新货币
        异常
        NullPointerException - 如果 currency为空
        从以下版本开始：
        1.4