模块  java.base
软件包  java.text

Class DecimalFormat

  • 实现的所有接口
    SerializableCloneable

    public class DecimalFormat
    extends 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 TutorialNumberFormatDecimalFormatSymbolsParsePositionSerialized Form
    • 方法详细信息

      • format

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

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

        重写:
        format在课程 NumberFormat
        参数
        number - 要格式化的数字
        toAppendTo - 要附加格式化文本的 StringBuffer
        pos - 跟踪返回字符串中字段的位置。 例如,要格式化Locale.US语言环境中的数字1234567.89 ,如果给定的fieldPositionNumberFormat.INTEGER_FIELD ,则对于输出字符串1,234,567.89 ,开始索引和结束索引fieldPosition将分别设置为0和9。
        结果
        传入的值为 toAppendTo
        异常
        IllegalArgumentException - 如果 number为null或不是 Number的实例。
        NullPointerException - 如果 toAppendTopos为空
        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 ,如果给定的fieldPositionNumberFormat.INTEGER_FIELD ,则对于输出字符串1,234,567.89 ,开始索引和结束索引fieldPosition将分别设置为0和9。
        结果
        格式化的数字字符串
        异常
        NullPointerException - 如果 resultfieldPositionnull
        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 ,如果给定的fieldPositionNumberFormat.INTEGER_FIELD ,则对于输出字符串123,456,789 ,开始索引和结束索引fieldPosition将分别设置为0和11。
        结果
        格式化的数字字符串
        异常
        NullPointerException - 如果 resultfieldPositionnull
        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方法doubleValuelongValue ,等等,以获得他们想要的类型。

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

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

        Specified by:
        parse在课程 NumberFormat
        参数
        text - 要解析的字符串
        pos - 具有 ParsePosition索引和错误索引信息的 ParsePosition对象。
        结果
        解析后的值,如果解析失败 null
        异常
        NullPointerException - 如果 textpos为空。
        另请参见:
        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)
        设置数字整数部分允许的最大位数。 对于格式化BigIntegerBigDecimal对象以外的数字,使用较低的newValue和309。 负输入值替换为0。
        重写:
        setMaximumIntegerDigits在课程 NumberFormat
        参数
        newValue - 要显示的最大整数位数; 如果小于零,则使用零。 具体子类可以对适合于格式化的数字类型的此值强制执行上限。
        另请参见:
        NumberFormat.setMaximumIntegerDigits(int)
      • setMinimumIntegerDigits

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

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

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

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

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

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

        public int getMinimumFractionDigits()
        获取数字小数部分中允许的最小位数。 对于格式化BigIntegerBigDecimal对象以外的数字,将使用返回值和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