モジュール java.base
パッケージ java.text

クラスDecimalFormat

java.lang.Object
java.text.Format
java.text.NumberFormat
java.text.DecimalFormat
すべての実装されたインタフェース:
Serializable, Cloneable
public class DecimalFormat extends NumberFormat
DecimalFormatはNumberFormatの具象サブクラスであり、10進数の書式を設定します。 これには、西欧、アラビア、およびインド数字に対するサポートを含むさまざまな機能が用意されており、任意のロケールで数値の解析とフォーマットが実行できるよう設計されています。 また、整数(123)、固定小数値(123.4)、科学表記法(1.23E4)、パーセント(12%)、および通貨金額($123)などのさまざまな種類の数値もサポートしています。 これらはすべてローカライズができます。

デフォルトのロケールなどの特定のロケールのNumberFormatを取得するためには、getInstance()などのNumberFormatのファクトリ・メソッドの1つを呼び出します。 通常、NumberFormatファクトリ・メソッドはDecimalFormat以外のサブクラスを返す場合があるため、DecimalFormatコンストラクタを直接呼び出しません。 フォーマット・オブジェクトをカスタマイズする必要がある場合は、次のように実行します。 

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

DecimalFormatはパターンおよび記号のセットで構成されます。 パターンの設定はapplyPattern()を使用して直接行うか、またはAPIメソッドを使用して間接的に行います。 記号はDecimalFormatSymbolsオブジェクトに格納されます。 NumberFormatファクトリ・メソッドを使用している場合、パターンと記号はローカライズされたResourceBundleから読み込まれます。

パターン

ノート: 任意のDecimalFormatパターンについて、パターンが科学表記でない場合、整数桁の最大数はパターンから導出されず、かわりにInteger.MAX_VALUEに設定されます。 それ以外の場合、パターンが科学的な表記法であれば、整数の最大桁数がパターンから導出されます。 この導出の詳細は、Scientific Notationの項を参照してください。 この動作は、一般的なエンド・ユーザーの要望です。setMaximumIntegerDigits(int)を使用して、整数の最大桁数を手動で調整できます。

DecimalFormatの構文を次に示します。 

 Pattern:
         PositivePattern
         PositivePattern ; NegativePattern
 PositivePattern:
         Prefixopt Number Suffixopt
 NegativePattern:
         Prefixopt Number Suffixopt
 Prefix:
         Any characters except the special pattern characters
 Suffix:
         Any characters except the special pattern 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)"などの、正と負のサブパターンがあります。 各サブパターンには、プリフィクス、数値部分およびサフィックスが含まれます。 負のサブパターンはオプションです。指定しない場合、マイナス記号('-' U+002D HYPHEN-MINUS)が先頭に付いた正のサブパターンが負のサブパターンとして使用されます。 つまり、単独の"0.00"は"0.00;-0.00"と等価になります。 明示的なマイナスのサブパターンがある場合は、マイナスの接頭辞と接尾辞を指定するだけです。桁数、最小桁数、その他の属性はすべてプラスのパターンと同じです。 これは"#,##0.0#;(#)"は"#,##0.0#;(#,##0.0#)"と正確に同じ結果になることを意味します。

無限大、数字、グルーピング・セパレータ、小数点などに使用されるプレフィクス、サフィクスおよび様々な記号は、任意の値に設定でき、書式設定時に正しく表示されます。 ただし、記号と文字列が矛盾しないように注意をしないと、解析は信頼性を持ちません。 たとえば、DecimalFormat.parse()で正の値と負の値を区別できるように、正と負の接頭辞や接尾辞は異なる必要があります。 同一であると、DecimalFormatは負のサブパターンが指定されていないものとして動作します。 別の例として、小数点セパレータとグループ・セパレータは個別の文字にする必要があり、そうしないと解析できません。

グループ区切り子は一般に1000ごとに区切るために使用しますが、国によっては10000ごとに使用するところもあります。 グループ区切りのサイズとは、100,000,000の場合は3、1,0000,0000の場合は4というように、グループ区切り文字間の一定の桁数です。 複数のグループ区切り文字を持つパターンを指定すると、最後の区切り文字と末尾の整数との間が、この間隔として使用されます。 したがって、"#,##,###,####" == "######,####" == "##,####,####"となります。

特殊パターン文字

パターン内の多くの文字は文字どおりに取得されます。このような文字は解析中に一致すると、フォーマット中にそのまま出力されます。 一方、特殊文字はほかの文字、文字列、または文字のクラスを表します。 特殊文字は、接頭辞や接尾辞にリテラルとして表示する場合は、特に指示がないかぎり、引用符で囲む必要があります。

次にリストする文字は、ローカライズされていないパターンで使用されます。 ローカライズされていないパターンでは、代わりにこのフォーマッタのDecimalFormatSymbolsオブジェクトから取得した対応する文字を使用すると、これらの文字は特殊な状態ではなくなります。 2つの例外はローカライズされていない通貨記号と引用符です。

記号、位置、ローカライズ、および意味を示すチャート。
記号 位置 ローカライズの有無 意味
0 Number あり 数字
# Number あり 数字。ゼロだと表示されない
. Number あり 数値桁区切り子または通貨桁区切り子
- Number あり マイナス記号
, Number あり グループ化セパレータまたは通貨グループ化セパレータ
E Number あり 科学表記法の仮数と指数を区切る。 接頭辞や接尾辞内に引用符を付ける必要はない。
; サブパターン境界 あり 正と負のサブパターンを区切る
% 接頭辞または接尾辞 あり 100倍してパーセントを表す
U+2030 接頭辞または接尾辞 あり 1000倍してパーミル値を表す
¤ (U+00A4) 接頭辞または接尾辞 なし 通貨記号で置換される通貨符号。 2つの場合は、国際通貨記号で置換される。 パターンに含まれている場合は、小数点/グループ・セパレータのかわりに通貨小数点/グループ・セパレータが使用されます。
' 接頭辞または接尾辞 なし 接頭辞や接尾辞内の特殊文字を引用符で囲む場合に使用される。たとえば、"'#'#"を使用すると123は"#123"にフォーマットされる。 単一引用符自体を作成するには、1行に2つ引用符を使用する("#o''clock")。

科学表記法

科学表記法の数値は仮数と10の累乗の結果として表されます。たとえば、1234は1.234 x 10^3として表されます。 仮数の多くは1.0 ≤ x < 10.0の範囲内ですが、必ずしもこの範囲内である必要はありません。 DecimalFormatには、パターンだけを介して科学表記法をフォーマットおよび解析するよう指示できます。現在、科学表記法形式を作成するファクトリ・メソッドはありません。 パターンでは、指数文字の直後に1つ以上の数字を続けて科学表記法を示します。 例:"0.###E0"では、1234は"1.234E3"のようにフォーマットされます。

  • 指数文字の後ろの数字の個数は、指数の最小桁数を示します。 最大桁数はありません。 負の指数は、パターンによる接頭辞や接尾辞ではなく、ローカライズされたマイナス記号を使用してフォーマットされます。 これによって、"0.###E0 m/s"などのパターンが許可されます。
  • 「最大整数」桁は、小数点の前にある'0'sと'#'sの合計です。 「最小整数」桁は、小数点の前にある0の合計です。 「最大分数」および「最小小数」桁は同じルールに従いますが、指数の前にある小数点の後の桁に適用されます。 たとえば、次のパターンです: "#00.0####E0"には、最小整数桁数= 2("00")、最大整数桁数= 3("#00")を指定します。 最小小数桁数= 1("0")、最大小数桁数= 5("0####")になります。
  • 整数の最小桁数と最大桁数は同時に解釈されます。
    • 整数の最大桁数がその最小桁数より大きく、1より大きい場合、指数は整数の最大桁数の倍数になり、整数の最小桁数は1として解釈されます。 これは、技術表記法の場合によく使用されます。この場合、指数は"##0.#####E0"などのように3の倍数になります。 このパターンを使用すると、数値12345は"12.345E3"に、123456は"123.456E3"にフォーマットされます。
    • そうでない場合、整数の最小桁数は指数を調整することによって得られます。 例: 0.00123は"00.###E0"を使用して"12.3E-4"とフォーマットされます。
  • 特定の数値について、マンティッサの有効桁数を次のように計算できます 
     Mantissa Digits:
         min(max(Minimum Pattern Digits, Original Number Digits), Maximum Pattern Digits)
 Minimum pattern Digits:
         Minimum Integer Digits + Minimum Fraction Digits
 Maximum pattern Digits:
         Maximum Integer Digits + Maximum Fraction Digits
 Original Number Digits:
         The amount of significant digits in the number to be formatted
    これは、元の数値自体に十分な有効桁がある場合、通常、mantissaには最大で整数と小数桁が結合されることを意味します。 ただし、元の数値の有効桁数よりもパターンの最小桁数が多い場合、mantissaには、最小整数と小数桁数の合計に等しい有効桁数が設定されます。 有効桁数は解析に影響しません。

    マンティサの整数部は、精度であるか、または結合された最小桁の合計金額を満たすかに関係なく、小数部分に余分な桁を与えることに注意してください。

    この動作は、次の例で確認できます。 

        DecimalFormat df = new DecimalFormat("#000.000##E0");
    df.format(12); // returns "12.0000E0"
    df.format(123456789) // returns "1.23456789E8"
  • 指数パターンにはグループ区切り子が含まれない場合があります。

丸め

DecimalFormatは、RoundingModeで定義されている丸めモードをフォーマット処理に提供します。 デフォルトでは、RoundingMode.HALF_EVENが使用されます。

Digits

DecimalFormatは、フォーマットにDecimalFormatSymbolsオブジェクトで定義されている、ローカライズされたゼロ数字で始まる10個の連続した文字を数字として使用します。 解析では、これらの数字とともに、Character.digitの定義によるすべてのUnicode 10進数を認識します。

特殊な値

Number(NaN)は文字列として書式設定されていません。通常、文字列には単一の文字U+FFFDがあります。 この文字列はDecimalFormatSymbolsオブジェクトによって判定されます。 これは、接頭辞と接尾辞が使用されない唯一の値です。

無限大は文字列として書式設定され、通常は1文字のU+221Eが含まれ、プレフィクスとして正または負のプレフィクスとサフィクスが適用されます。 無限大文字列はDecimalFormatSymbolsオブジェクトによって判定されます。

負のゼロ("-0")は、

  • isParseBigDecimal()がtrueである場合はBigDecimal(0)と解析され、
  • isParseBigDecimal()がfalse、isParseIntegerOnly()がtrueである場合はLong(0)と解析され、
  • isParseBigDecimal()とisParseIntegerOnly()がどちらもfalseである場合はDouble(-0.0)と解析されます。

Synchronization

decimalフォーマットは同期化されません。 スレッドごとに別のフォーマット・インスタンスを作成することをお薦めします。 複数のスレッドがフォーマットに並行してアクセスする場合は、外部的に同期化する必要があります。

例

// Print out a number using the localized number, integer, currency,
// and percent format for each locale
Locale[] locales = NumberFormat.getAvailableLocales();
double myNumber = -1234.56;
NumberFormat form;
for (int j = 0; j < 4; ++j) {
    System.out.println("FORMAT");
    for (Locale locale : locales) {
        if (locale.getCountry().length() == 0) {
            continue; // Skip language-only locales
        }
        System.out.print(locale.getDisplayName());
        form = switch (j) {
            case 0 -> NumberFormat.getInstance(locale);
            case 1 -> NumberFormat.getIntegerInstance(locale);
            case 2 -> NumberFormat.getCurrencyInstance(locale);
            default -> NumberFormat.getPercentInstance(locale);
        };
        if (form instanceof DecimalFormat decForm) {
            System.out.print(": " + decForm.toPattern());
        }
        System.out.print(" -> " + form.format(myNumber));
        try {
            System.out.println(" -> " + form.parse(form.format(myNumber)));
        } catch (ParseException e) {}
    }
}
導入されたバージョン:
1.1
関連項目: