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

クラスCompactNumberFormat

  • すべての実装されたインタフェース:
    Serializable, Cloneable
    public final class CompactNumberFormat
extends NumberFormat

    CompactNumberFormatは、コンパクト形式で小数を書式設定するNumberFormatの具体的なサブクラスです。 コンパクト数値書式設定は、スペースが限られている環境では設計され、その限られたスペースに書式設定された文字列を表示できます。 これは、「コンパクト数値書式設定」のLDML仕様で定義されています。 コンパクト数値書式設定とは、特定のロケールに用意されているパターンに基づいて、短い形式で数値を表現することです。

    例えば:
    US localeでは、1000は"1K"として書式設定でき、1000000はstyleに応じて"1M"として書式設定できます。
    "hi_IN"のロケールでは、1000は"1 हज़ार"としてフォーマットでき、50000000は"5 क."としてフォーマットできます。これは、styleに応じて異なります。

    ロケールのCompactNumberFormatを取得するには、NumberFormatによって提供されているファクトリ・メソッドのいずれかを使用して、完全な数値書式設定を行います。 例: NumberFormat.getCompactNumberInstance(Locale, Style)。 

     NumberFormat fmt = NumberFormat.getCompactNumberInstance(
                             new Locale("hi", "IN"), NumberFormat.Style.SHORT);
 String result = fmt.format(1000);

    Style

    数値は、SHORTとLONGという2つの異なるスタイルを使用してコンパクト形式で書式設定できます。 SHORTまたはLONGコンパクト形式で数値をフォーマットおよび解析するためにNumberFormat.getCompactNumberInstance(Locale, Style)を使用します。指定したStyleパラメータが目的の形式をリクエストします。 US localeのSHORTスタイル・コンパクト数値インスタンスは、"10K"として10000をフォーマットします。 ただし、LONGスタイルのインスタンスは、"10 thousand"と同じロケール形式10000です。

    コンパクト数値パターン

    コンパクト数値のパターンは一連のパターンで表され、各パターンは、数値の範囲を書式設定するのに使用されます。 US localeのSHORTスタイル・コンパクト数値パターンは、{"", "", "", "0K", "00K", "000K", "0M", "00M", "000M", "0B", "00B", "000B", "0T", "00T", "000T"}で、100から1014の範囲です。 パターンはいくつでも作成でき、厳密には100の範囲から開始するインデックスに基づいています。 たとえば、前述のパターンでは、インデックス3 ("0K")のパターンがnumber >= 1000 and number < 10000の書式設定に使用され、インデックス4 ("00K")のパターンがnumber >= 10000 and number < 100000の書式設定に使用されます。 ほとんどのロケールで、100-102の範囲パターンで空の文字列であり、暗黙的に特殊なパターン"0"を意味します。 特殊パターン"0"は、コンパクト・パターンが含まれていない範囲で使用されます。 この特殊なパターンは、特定の範囲に対して明示的に指定したり、空の文字列のデフォルト・パターンとみなすことができます。

    コンパクト・パターンには、次の構文があります: 

     Pattern:
         PositivePattern
         PositivePattern [; NegativePattern]optional
 PositivePattern:
         Prefixoptional MinimumInteger Suffixoptional
 NegativePattern:
        Prefixoptional MinimumInteger Suffixoptional
 Prefix:
      Any Unicode characters except \uFFFE, \uFFFF, and
      special characters
 Suffix:
      Any Unicode characters except \uFFFE, \uFFFF, and
      special characters
 MinimumInteger:
      0
      0 MinimumInteger
    コンパクト・パターンには、"0K;-0K"のように、サブパターンの境界文字';' (U+003B)によって区切られた、プラスおよびマイナスのサブパターンが含まれます。 各サブパターンには、プレフィクス、最小整数桁およびサフィクスが含まれます。 マイナスのサブパターンはオプションです。このサブパターンがない場合、プラスのサブパターンの先頭にマイナス記号('-' U+002D HYPHEN-MINUS)が付きます。 つまり、"0K"単独は"0K;-0K"と同等です。 明示的にマイナスのサブパターンを指定した場合、このサブパターンは単にマイナスのプリフィクスとサフィックスを指定するために使用されます。 最小整数桁数およびその他の特性は、すべてプラス・パターンと同じです。 つまり、"0K;-00K"では"0K;-0K"と正確に同じ動作が生成されます。

    コンパクト・パターンの多くの文字は文字どおりに使用され、解析中に照合され、書式設定中は変更されません。 「特殊文字」は、一方、その他の文字、文字列またはクラスを表す文字です。 特に明記されていない場合は、先頭またはサフィクスにリテラルとして表示されるときには、一重引用符' (U+0027)を使用して引用符を囲む必要があります。 たとえば、0क'.'。

    書式設定

    デフォルトの書式設定動作は、小数を持たない書式設定された文字列を返しますが、ユーザーはsetMinimumFractionDigits(int)メソッドを使用して小数部分を含めることができます。 数値1000.0または1000は、(US localeの) "1K"として("1.00K"ではなく)書式設定されます。 このため、書式設定用に指定するパターンには、最小整数桁、プレフィクスまたはサフィクスのみが含まれますが、小数部は含まれません。 たとえば、使用されるパターンは{"", "", "", 0K, 00K, ...}です。 数値を書式設定するために選択したパターンが"0" (特殊パターン)の場合は、指定したロケールに関してDecimalFormatによって提供される一般的な数値書式設定が使用されます。

    解析

    デフォルトの解析動作では、グループ化セパレータは、setGroupingUsed(boolean)を使用してtrueに設定されるまでグループ化できません。 小数部分の解析は、isParseIntegerOnly()によって異なります。 たとえば、解析整数のみがtrueに設定されている場合、小数部分はスキップされます。

    丸め

    CompactNumberFormatには、RoundingModeで定義されたフォーマット用の丸めモードがあります。 デフォルトでは、RoundingMode.HALF_EVENが使用されます。
    導入されたバージョン:
    12
    関連項目:
    NumberFormat.Style, NumberFormat, DecimalFormat, 「直列化されたフォーム」

    • コンストラクタの詳細

      • CompactNumberFormat

        public CompactNumberFormat​(String decimalPattern,
                           DecimalFormatSymbols symbols,
                           String[] compactPatterns)
        指定された小数点パターン、小数点フォーマット記号およびコンパクト・パターンを使用してCompactNumberFormatを作成します。 LocaleおよびStyleの標準的なコンパクト・パターンを使用してCompactNumberFormatのインスタンスを取得する場合は、NumberFormatで指定されるファクトリ・メソッドを使用して、コンパクト数値書式設定を行うことをお薦めします。 例: NumberFormat.getCompactNumberInstance(Locale, Style)。
        パラメータ:
        decimalPattern - 一般的な数値書式設定の小数点パターン
        symbols - 使用する記号セット
        compactPatterns - 「コンパクト数値パターン」の配列
        例外:
        NullPointerException - 指定された引数のいずれかがnullの場合
        IllegalArgumentException - 指定されたdecimalPatternまたはcompactPatterns配列に無効なパターンが含まれている場合、またはnullがコンパクト・パターンの配列に表示される場合
        関連項目:
        DecimalFormat(java.lang.String, DecimalFormatSymbols), DecimalFormatSymbols

    • メソッドの詳細

      • format

        public final StringBuffer format​(Object number,
                                 StringBuffer toAppendTo,
                                 FieldPosition fieldPosition)
        数値を書式設定して、コンパクト形式を表す文字列を生成します。 指定可能な数値は、Numberの任意のサブクラスです。
        オーバーライド:
        format、クラス: NumberFormat
        パラメータ:
        number - フォーマットする数値
        toAppendTo - フォーマット後のテキストを追加するStringBuffer
        fieldPosition - 返された文字列内のフィールドの位置を追跡します。 たとえば、US localeの数値123456789を書式設定する場合、指定したfieldPositionがNumberFormat.INTEGER_FIELDの場合、fieldPositionの開始索引と終了索引はそれぞれ0および3に設定され、出力文字列123Mになります。 同様に、プレフィクス・フィールドとフィールドの位置は、それぞれNumberFormat.Field.PREFIXとNumberFormat.Field.SUFFIXを使用して取得できます。
        戻り値:
        toAppendToとして渡されるStringBuffer
        例外:
        IllegalArgumentException - numberがnullの場合、またはNumberのインスタンスでない場合
        NullPointerException - toAppendToまたはfieldPositionがnullの場合
        ArithmeticException - 丸めモードがRoundingMode.UNNECESSARYに設定されている場合、丸め処理が必要
        関連項目:
        FieldPosition

      • format

        public StringBuffer format​(double number,
                           StringBuffer result,
                           FieldPosition fieldPosition)
        doubleをフォーマットして、コンパクトな形式を表す文字列を生成します。
        定義:
        format、クラス: NumberFormat
        パラメータ:
        number - フォーマットするdouble数値
        result - テキストを追加する位置
        fieldPosition - 返された文字列内のフィールドの位置を追跡します。 たとえば、指定されたfieldPositionがNumberFormat.INTEGER_FIELDの場合、US localeの数値1234567.89を書式設定するには、fieldPositionの開始索引と終了索引がそれぞれ0および1に設定され、出力文字列1Mに対して使用されます。 同様に、プレフィクス・フィールドとフィールドの位置は、それぞれNumberFormat.Field.PREFIXとNumberFormat.Field.SUFFIXを使用して取得できます。
        戻り値:
        resultとして渡されるStringBuffer
        例外:
        NullPointerException - resultまたはfieldPositionがnullの場合
        ArithmeticException - 丸めモードがRoundingMode.UNNECESSARYに設定されている場合、丸め処理が必要
        関連項目:
        FieldPosition

      • format

        public StringBuffer format​(long number,
                           StringBuffer result,
                           FieldPosition fieldPosition)
        longをフォーマットして、そのコンパクトな形式を表す文字列を生成します。
        定義:
        format、クラス: NumberFormat
        パラメータ:
        number - フォーマットするlong数値
        result - テキストを追加する位置
        fieldPosition - 返された文字列内のフィールドの位置を追跡します。 たとえば、US localeの数値123456789を書式設定する場合、指定したfieldPositionがNumberFormat.INTEGER_FIELDの場合、fieldPositionの開始索引と終了索引はそれぞれ0および3に設定され、出力文字列123Mになります。 同様に、プレフィクス・フィールドとフィールドの位置は、それぞれNumberFormat.Field.PREFIXとNumberFormat.Field.SUFFIXを使用して取得できます。
        戻り値:
        resultとして渡されるStringBuffer
        例外:
        NullPointerException - resultまたはfieldPositionがnullの場合
        ArithmeticException - 丸めモードがRoundingMode.UNNECESSARYに設定されている場合、丸め処理が必要
        関連項目:
        FieldPosition

      • formatToCharacterIterator

        public AttributedCharacterIterator formatToCharacterIterator​(Object obj)
        Objectをフォーマットし、AttributedCharacterIteratorを生成します。 返されるAttributedCharacterIteratorを使用して、結果の文字列を作成したり、結果の文字列に関する情報を決定したりできます。

        AttributedCharacterIteratorの各属性キーは、NumberFormat.Field型になり、属性値が属性キーと同じになります。 返されるイテレータ(存在する場合)のプレフィクスとサフィクスの部分は、それぞれ属性NumberFormat.Field.PREFIXとNumberFormat.Field.SUFFIXによって表されます。

        オーバーライド:
        formatToCharacterIterator、クラス: Format
        パラメータ:
        obj - フォーマットするオブジェクト
        戻り値:
        AttributedCharacterIterator(書式設定された値を記述)
        例外:
        NullPointerException - objがnullである場合
        IllegalArgumentException - 指定されたオブジェクトをFormatでフォーマットできない場合
        ArithmeticException - 丸めモードがRoundingMode.UNNECESSARYに設定されている場合、丸め処理が必要

      • parse

        public Number parse​(String text,
                    ParsePosition pos)
        文字列からコンパクト形式をパースしてNumberを生成します。

        メソッドはposによって指定されたインデックスを開始位置としてテキストの解析を試みます。 解析が完了すると、posのインデックスは、使用された最後の文字(解析では、文字列の最後までのすべての文字が使用されるとは限らない)のあとのインデックスに更新され、解析された数値が返されます。 更新されたposは、このメソッドの次の呼出しの開始点を示すのに使用できます。 エラーが発生した場合、posのインデックスは変更されず、posのエラー・インデックスはエラーが発生した文字のインデックスに設定され、nullが返されます。

        値は、指定されたテキストの数値部分に接着する(例: US locale内の"K" = 1000)と同等の数値を乗算した値です。 返されるサブクラスは、isParseBigDecimal()の値によって異なります。

        • isParseBigDecimal()がfalse (デフォルト)の場合、書込み方法に関係なく、ほとんどの整数値がLongオブジェクトとして返されます。: "17K"と"17.000K"の両方の解析からLong.valueOf(17000)へ。 値がLongに収まらない場合、結果はDoubleとして返されます。 これには小数部分を持つ値、無限大の値、NaN、および値 -0.0などが含まれます。

          呼出し元は、NumberのメソッドdoubleValueやlongValueを用いることで、値を必要な型として取得できます。

        • isParseBigDecimal()がtrueの場合、BigDecimalオブジェクトとして値が戻されます。 ただし、特殊な値(正負の無限大やNaNなど)は、対応するDouble定数値を含むDoubleインスタンスとして返されます。

        CompactNumberFormatは、Character.digit()により定義された10進数を表すすべてのUnicode文字を解析します。 さらに、CompactNumberFormatは、DecimalFormatSymbolsオブジェクトで定義された0桁のローカライズ・ゼロから始まる10桁の連続文字としても認識します。

        CompactNumberFormat解析では科学表記法の解析は許可されません。 たとえば、'E'文字でUS localeブレークの文字列"1.05E4K"を解析し、1.05を返します。

        定義:
        parse、クラス: NumberFormat
        パラメータ:
        text - 解析される文字列
        pos - 前述のように、インデックス情報とエラー・インデックス情報を持つParsePositionオブジェクト
        戻り値:
        解析された値。解析が失敗した場合はnull
        例外:
        NullPointerException - textまたはposがnullの場合
        関連項目:
        NumberFormat.isParseIntegerOnly(), Format.parseObject(java.lang.String, java.text.ParsePosition)

      • setMaximumIntegerDigits

        public void setMaximumIntegerDigits​(int newValue)
        数値の整数部分の最大桁数を設定します。 最大許容整数範囲は309です。newValue > 309,の場合、最大整数桁数は309に設定されます。 負の入力値は0に置き換えられます。
        オーバーライド:
        setMaximumIntegerDigits、クラス: NumberFormat
        パラメータ:
        newValue - 表示される最大整数桁数
        関連項目:
        NumberFormat.getMaximumIntegerDigits()

      • setMinimumIntegerDigits

        public void setMinimumIntegerDigits​(int newValue)
        数値の整数部分の最小桁数を設定します。 最大許容整数範囲は309で、newValue > 309,の場合、最小整数桁数は309に設定されます。 負の入力値は0に置き換えられます。
        オーバーライド:
        setMinimumIntegerDigits、クラス: NumberFormat
        パラメータ:
        newValue - 表示される整数の最小桁数
        関連項目:
        NumberFormat.getMinimumIntegerDigits()

      • setMinimumFractionDigits

        public void setMinimumFractionDigits​(int newValue)
        数値の小数部分の最小桁数を設定します。 最大許容小数範囲は340で、newValue > 340,の場合、最小小数桁数は340に設定されます。 負の入力値は0に置き換えられます。
        オーバーライド:
        setMinimumFractionDigits、クラス: NumberFormat
        パラメータ:
        newValue - 表示される小数点以下の最小桁数
        関連項目:
        NumberFormat.getMinimumFractionDigits()

      • setMaximumFractionDigits

        public void setMaximumFractionDigits​(int newValue)
        数値の小数部分の最大桁数を設定します。 最大許容小数範囲は340で、newValue > 340,の場合、最大小数桁数は340に設定されます。 負の入力値は0に置き換えられます。
        オーバーライド:
        setMaximumFractionDigits、クラス: NumberFormat
        パラメータ:
        newValue - 表示される小数点以下の最大桁数
        関連項目:
        NumberFormat.getMaximumFractionDigits()

      • setGroupingSize

        public void setGroupingSize​(int newValue)
        グループ化サイズを設定します。 グループ化サイズとは、数値の整数部分における区切り文字と区切り文字の間の桁数です。 たとえば、US localeのコンパクト数値"12,347 trillion"ではグループ化サイズは3です。 グループ化サイズは、ゼロ以上127以下である必要があります。
        パラメータ:
        newValue - 新しいグループ化サイズ
        例外:
        IllegalArgumentException - newValueが負の場合または127より大きい場合
        関連項目:
        getGroupingSize(), NumberFormat.setGroupingUsed(boolean), DecimalFormatSymbols.setGroupingSeparator(char)

      • isGroupingUsed

        public boolean isGroupingUsed()
        このフォーマットでグループ化が使用される場合に、trueを返します。 たとえば、グループ化とグループ化のサイズを3に設定し、数値12346567890987654は、US locale内で"12,347 trillion"のようにフォーマットできます。 グループ化セパレータはロケールに依存します。
        オーバーライド:
        クラスNumberFormatのisGroupingUsed
        戻り値:
        グループ化を使用している場合はtrue、そうでない場合はfalse
        関連項目:
        setGroupingUsed(boolean)

      • setGroupingUsed

        public void setGroupingUsed​(boolean newValue)
        グループ化をこの形式で使用するかどうかを設定します。
        オーバーライド:
        setGroupingUsed、クラス: NumberFormat
        パラメータ:
        newValue - グループ化を使用している場合はtrue、そうでない場合はfalse
        関連項目:
        isGroupingUsed()

      • isParseIntegerOnly

        public boolean isParseIntegerOnly()
        この書式がコンパクト数値の数値コンポーネントから整数のみを解析する場合、trueを返します。 整数を解析すると、数値コンポーネントの整数のみが考慮され、結果の出力が引き続きコンピュートされます。 たとえば、US localeで、このメソッドがtrueを返す場合、文字列"1234.78 thousand"は値1234000 (1234 (整数部分) * 1000 (thousand))として解析され、部分はスキップされます。 解析操作で受け入れられる正確な形式は、ロケールに依存します。
        オーバーライド:
        クラスNumberFormatのisParseIntegerOnly
        戻り値:
        trueコンパクト数値を整数のみとして解析する場合、falseそれ以外の場合

      • setParseIntegerOnly

        public void setParseIntegerOnly​(boolean value)
        この書式設定でコンパクト数値のコンポーネントから整数のみを解析するかどうかを設定します。
        オーバーライド:
        クラスNumberFormatのsetParseIntegerOnly
        パラメータ:
        value - trueコンパクト数値を整数のみとして解析する場合はtrue; それ以外の場合はfalse
        関連項目:
        isParseIntegerOnly()

      • isParseBigDecimal

        public boolean isParseBigDecimal()
        parse(String, ParsePosition)メソッドがBigDecimalを返すかどうかを返します。 デフォルト値はfalseです。
        戻り値:
        この解析メソッドがBigDecimalを返す場合はtrue、そうでない場合はfalse
        関連項目:
        setParseBigDecimal(boolean)

      • setParseBigDecimal

        public void setParseBigDecimal​(boolean newValue)
        parse(String, ParsePosition)メソッドがBigDecimalを返すかどうかを設定します。
        パラメータ:
        newValue - この解析メソッドがBigDecimalを返す場合はtrue、そうでない場合はfalse
        関連項目:
        isParseBigDecimal()

      • equals

        public boolean equals​(Object obj)
        このCompactNumberFormatが指定されたobjと等しいかどうかをチェックします。 CompactNumberFormat型のオブジェクトが比較されるため、他の型はfalseを返し、Object.equalsの一般的な契約に従います。
        オーバーライド:
        equals、クラス: NumberFormat
        パラメータ:
        obj - 比較対象のオブジェクト
        戻り値:
        これが他方のCompactNumberFormatと等しい場合はtrue
        関連項目:
        Object.hashCode()、HashMap

      • clone

        public CompactNumberFormat clone()
        このCompactNumberFormatインスタンスのコピーを作成して返します。
        オーバーライド:
        clone、クラス: NumberFormat
        戻り値:
        このインスタンスの複製
        関連項目:
        Cloneable