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

クラスNumberFormat

  • すべての実装されたインタフェース:
    Serializable, Cloneable
    直系の既知のサブクラス:
    ChoiceFormat, DecimalFormat
    public abstract class NumberFormat
extends Format
    NumberFormatは、すべての数値フォーマットに対するabstract基底クラスです。 このクラスは、数値のフォーマットと解析のためのインタフェースです。 さらにNumberFormatは、数値フォーマットがどのロケールにあり、その名前が何であるかを知るためのメソッドを提供します。

    NumberFormatを使うと、任意のロケールの数値を簡単にフォーマットしたり解析したりできるようになります。 ユーザーのコードは、10進数の小数点、1000の区切り、使用する特定の10進数字に対するロケールのルールだけでなく、数字フォーマットが10進数かどうかということさえも、まったく意識せずに作成できます。

    現行ロケールの数値をフォーマットする場合は、ファクトリ・クラス・メソッドの1つを使用します。 

    
 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" (numbers)および/または"rg" (リージョン・オーバーライド) 「Unicode拡張」が含まれている場合、小数点および/または書式設定に使用される国がオーバーライドされます。 "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とともに使用すれば、次のことが可能です。

    • 文字列のそれぞれの部分を段階的に解析する
    • 小数点などの区域を位置合わせする
    たとえば、複数の数値を2つの方法で位置合わせすることができます。
    1. モノスペース・フォントを使い、位置合わせにスペースを入れる場合には、フォーマット呼出しでFieldPositionを渡すことができます。このとき、field = INTEGER_FIELDとします。 出力では、getEndIndexが、整数の最後の文字と小数点の間のオフセットに設定されます。 文字列の前に(desiredSpaceCount - getEndIndex)のスペースを追加してください。
    2. プロポーショナル・フォントを使う場合には、スペースを追加する代わりに、文字列の幅をその始めからgetEndIndexまでピクセル単位で測ります。 次に、テキストを描く前に、(desiredPixelWidth - widthToAlignmentPoint)だけペンを移動します。 これは、小数点を扱うことはできませんが、終わりに追加の文字がある場合にも有効です。たとえば、-12を"(12)"にするように、負の数に括弧を付ける場合です。

    Synchronization

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

    実装要件:
    format(double, StringBuffer, FieldPosition)、format(long, StringBuffer, FieldPosition)およびparse(String, ParsePosition)メソッドは、NullPointerExceptionのいずれかがnullの場合、NullPointerExceptionをスローすることがあります。 サブクラスは、NullPointerExceptionに関する独自の実装と仕様を提供することができます。

    デフォルトの実装では、数値の書式設定のためにRoundingModeで定義された丸めモードが提供されます。 それは「ラウンド半偶数アルゴリズム」を使用します。 丸めモードを変更するには、setRoundingModeを使用します。 静的ファクトリ・メソッドによって返されたNumberFormatは、書式構成のために半角丸め(RoundingMode.HALF_EVENを参照してください)を使用して浮動小数点数を丸めるように構成されています。

    導入されたバージョン:
    1.1
    関連項目:
    DecimalFormat、ChoiceFormat、直列化された形式

    • ネストされたクラスのサマリー

      ネストされたクラス 
      修飾子と型 クラス 説明
      static class  NumberFormat.Field
      NumberFormat.formatToCharacterIteratorから返されたAttributedCharacterIterator内の属性キー、およびFieldPosition内のフィールド識別子として使用する定数を定義します。

    • フィールドのサマリー

      フィールド 
      修飾子と型 フィールド 説明
      static int FRACTION_FIELD
      FieldPositionオブジェクトを構築するためのフィールド定数です。
      static int INTEGER_FIELD
      FieldPositionオブジェクトを構築するためのフィールド定数です。

    • コンストラクタのサマリー

      コンストラクタ 
      修飾子 コンストラクタ 説明
      protected NumberFormat()
      唯一のコンストラクタです。

    • フィールドの詳細

      • INTEGER_FIELD

        public static final int INTEGER_FIELD
        FieldPositionオブジェクトを構築するためのフィールド定数です。 フォーマットされた数値の整数部分の位置を返すように指定します。
        関連項目:
        FieldPosition、定数フィールド値

      • FRACTION_FIELD

        public static final int FRACTION_FIELD
        FieldPositionオブジェクトを構築するためのフィールド定数です。 フォーマットされた数値の小数部分の位置を返すように指定します。
        関連項目:
        FieldPosition、定数フィールド値

    • コンストラクタの詳細

      • NumberFormat

        protected NumberFormat()
        唯一のコンストラクタです。 サブクラスのコンストラクタによる呼出し用で、通常は暗黙的に呼び出されます。

    • メソッドの詳細

      • format

        public StringBuffer format​(Object number,
                           StringBuffer toAppendTo,
                           FieldPosition pos)
        数値をフォーマットし、その結果のテキストを指定された文字列バッファに追加します。 指定可能な数値は、Numberの任意のサブクラスです。

        この実装は、numberから値を抽出する際に、情報の損失なしにlongに変換可能な整数型の値に対しては、Number.longValue()を使用します。bit lengthが64未満のBigInteger値もこれに該当します。その他の型に対しては、Number.doubleValue()を使用します。 続いて、format(long,java.lang.StringBuffer,java.text.FieldPosition)またはformat(double,java.lang.StringBuffer,java.text.FieldPosition)を呼び出します。 ただしBigDecimal値とBigInteger値の場合は、これにより、その絶対値情報や精度が失われる可能性があります。

        定義:
        format、クラス: Format
        パラメータ:
        number - フォーマットする数値
        toAppendTo - フォーマット後のテキストを追加するStringBuffer
        pos - 返された文字列内のフィールドの位置を追跡します。 たとえば、Locale.USロケールの番号1234567.89をフォーマットする場合、指定されたfieldPositionがINTEGER_FIELDである場合、fieldPositionのbeginインデックスとendインデックスは、それぞれ出力文字列1,234,567.89に対して0と9に設定されます。
        戻り値:
        toAppendToとして渡された値
        例外:
        IllegalArgumentException - numberがnullであるか、Numberのインスタンスでない場合。
        NullPointerException - toAppendToまたはposがnullの場合
        ArithmeticException - 丸め処理が必要な場合に丸めモードがRoundingMode.UNNECESSARYに設定されているとき
        関連項目:
        FieldPosition

      • parseObject

        public final Object parseObject​(String source,
                                ParsePosition pos)
        文字列からテキストを解析してNumberを生成します。

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

        数値の解析の詳細については、parse(String, ParsePosition)メソッドを参照してください。

        定義:
        parseObject、クラス: Format
        パラメータ:
        source - 部分的に解析されるString。
        pos - 上記のインデックスおよびエラー・インデックス情報を持つParsePositionオブジェクト
        戻り値:
        文字列から解析されるNumber。 エラーの場合はnullを返す。
        例外:
        NullPointerException - sourceまたはposがnullの場合。

      • format

        public final String format​(double number)
        フォーマットの特殊化です。
        パラメータ:
        number - フォーマットするdouble数値
        戻り値:
        フォーマットされたString
        例外:
        ArithmeticException - 丸め処理が必要な場合に丸めモードがRoundingMode.UNNECESSARYに設定されているとき
        関連項目:
        Format.format(java.lang.Object)

      • format

        public final String format​(long number)
        フォーマットの特殊化です。
        パラメータ:
        number - フォーマットするlong数値
        戻り値:
        フォーマットされたString
        例外:
        ArithmeticException - 丸め処理が必要な場合に丸めモードがRoundingMode.UNNECESSARYに設定されているとき
        関連項目:
        Format.format(java.lang.Object)

      • format

        public abstract StringBuffer format​(double number,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)
        フォーマットの特殊化です。
        パラメータ:
        number - フォーマットするdouble数値
        toAppendTo - フォーマット後のテキストを付加するStringBuffer
        pos - 返された文字列内のフィールドの位置を追跡します。 たとえば、Locale.USロケールの番号1234567.89をフォーマットする場合、指定されたfieldPositionがINTEGER_FIELDである場合、fieldPositionのbeginインデックスとendインデックスは、それぞれ出力文字列1,234,567.89に対して0と9に設定されます。
        戻り値:
        フォーマットされたStringBuffer
        例外:
        ArithmeticException - 丸め処理が必要な場合に丸めモードがRoundingMode.UNNECESSARYに設定されているとき
        関連項目:
        Format.format(java.lang.Object)

      • format

        public abstract StringBuffer format​(long number,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)
        フォーマットの特殊化です。
        パラメータ:
        number - フォーマットするlong数値
        toAppendTo - フォーマット後のテキストを付加するStringBuffer
        pos - 返された文字列内のフィールドの位置を追跡します。 たとえば、Locale.USロケールの番号123456789をフォーマットする場合、指定されたfieldPositionがINTEGER_FIELDである場合、fieldPositionのbeginインデックスとendインデックスは、それぞれ出力文字列123,456,789に対して0と11に設定されます。
        戻り値:
        フォーマットされたStringBuffer
        例外:
        ArithmeticException - 丸め処理が必要な場合に丸めモードがRoundingMode.UNNECESSARYに設定されているとき
        関連項目:
        Format.format(java.lang.Object)

      • parse

        public abstract Number parse​(String source,
                             ParsePosition parsePosition)
        可能な場合([Long.MIN_VALUE, Long.MAX_VALUE]の範囲で、小数部分がない場合など)はLongを、そうでない場合は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メソッドがローカライズされたインスタンスを返すことのできるロケールすべての配列を返します。 返される配列は、JavaランタイムおよびインストールされているNumberFormatProvider実装によってサポートされているロケールの和集合を表します。 これには、Locale.USと等価なLocaleインスタンスが少なくとも1つ含まれている必要があります。
        戻り値:
        ローカライズされたNumberFormatインスタンスを使用可能なロケールの配列。

      • equals

        public boolean equals​(Object obj)
        equalsをオーバーライドします。
        オーバーライド:
        equals 、クラス:  Object
        パラメータ:
        obj - 比較対象の参照オブジェクト。
        戻り値:
        このオブジェクトがobj引数と同じである場合はtrue、それ以外の場合はfalse。
        関連項目:
        Object.hashCode()、HashMap

      • clone

        public Object clone()
        Cloneableをオーバーライドします。
        オーバーライド:
        clone、クラス: 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の新しい値がmaximumIntegerDigitsの現在の値よりも小さい場合、minimumIntegerDigitsもこの新しい値に設定されます。
        パラメータ:
        newValue - 整数の最大表示桁数。0より小さい場合は0が使用される。 具象サブクラスでは、この値の上限を、フォーマットされる数値の種類に適した値に強制できる。
        関連項目:
        getMaximumIntegerDigits()

      • getMinimumIntegerDigits

        public int getMinimumIntegerDigits()
        数値の整数部分として可能な最小桁数を返します。
        戻り値:
        最小桁数
        関連項目:
        setMinimumIntegerDigits(int)

      • setMinimumIntegerDigits

        public void setMinimumIntegerDigits​(int newValue)
        数値の整数部分で許可される最小桁数を返します。minimumIntegerDigitsは、maximumIntegerDigits以下である必要があります。 minimumIntegerDigitsの新しい値がmaximumIntegerDigitsの現在の値よりも大きい場合、maximumIntegerDigitsもこの新しい値に設定されます。
        パラメータ:
        newValue - 整数の最小表示桁数。0より小さい場合は0が使用される。 具象サブクラスでは、この値の上限を、フォーマットされる数値の種類に適した値に強制できる。
        関連項目:
        getMinimumIntegerDigits()

      • getMaximumFractionDigits

        public int getMaximumFractionDigits()
        数値の小数部分として可能な最大桁数を返します。
        戻り値:
        最大桁数。
        関連項目:
        setMaximumFractionDigits(int)

      • setMaximumFractionDigits

        public void setMaximumFractionDigits​(int newValue)
        数値の小数部分で許可される最大桁数を設定します。maximumFractionDigitsは、minimumFractionDigits以上である必要があります。 maximumFractionDigitsの新しい値がminimumFractionDigitsの現在の値よりも小さい場合、minimumFractionDigitsもこの新しい値に設定されます。
        パラメータ:
        newValue - 小数部の最大表示桁数。0より小さい場合は0が使用される。 具象サブクラスでは、この値の上限を、フォーマットされる数値の種類に適した値に強制できる。
        関連項目:
        getMaximumFractionDigits()

      • getMinimumFractionDigits

        public int getMinimumFractionDigits()
        数値の小数部分として可能な最小桁数を返します。
        戻り値:
        最小桁数
        関連項目:
        setMinimumFractionDigits(int)

      • setMinimumFractionDigits

        public void setMinimumFractionDigits​(int newValue)
        数値の小数部分で許可される最小桁数を設定します。minimumFractionDigitsは、maximumFractionDigits以下である必要があります。 minimumFractionDigitsの新しい値がmaximumFractionDigitsの現在の値よりも大きい場合、maximumFractionDigitsもこの新しい値に設定されます。
        パラメータ:
        newValue - 小数部の最小表示桁数。0より小さい場合は0が使用される。 具象サブクラスでは、この値の上限を、フォーマットされる数値の種類に適した値に強制できる。
        関連項目:
        getMinimumFractionDigits()

      • getCurrency

        public Currency getCurrency()
        通貨値のフォーマット時に、この数値フォーマットが使用する通貨を取得します。 初期値はロケールに依存する方法で得られます。 有効な通貨が判定されず、setCurrencyを使用して設定された通貨がない場合、nullが返されます。

        デフォルト実装はUnsupportedOperationExceptionをスローします。

        戻り値:
        この数値フォーマットで使用される通貨、またはnull
        例外:
        UnsupportedOperationException - 数値フォーマットのクラスが通貨フォーマットを実装しない場合
        導入されたバージョン:
        1.4

      • setCurrency

        public void setCurrency​(Currency currency)
        通貨値のフォーマット時に、この数値フォーマットが使用する通貨を設定します。 これは、数値フォーマットが使用する最小小数桁数または最大小数桁数を更新するものではありません。

        デフォルト実装はUnsupportedOperationExceptionをスローします。

        パラメータ:
        currency - この数値フォーマットで使用する新しい通貨
        例外:
        UnsupportedOperationException - 数値フォーマットのクラスが通貨フォーマットを実装しない場合
        NullPointerException - currencyがnullである場合
        導入されたバージョン:
        1.4

      • getRoundingMode

        public RoundingMode getRoundingMode()
        このNumberFormatで使用されるRoundingModeを取得します。 NumberFormatのこのメソッドのデフォルト実装は、常にUnsupportedOperationExceptionをスローします。 さまざまな丸めモードを処理するサブクラスは、このメソッドをオーバーライドする必要があります。
        戻り値:
        このNumberFormatに使用されるRoundingMode。
        例外:
        UnsupportedOperationException - デフォルトの実装は常にこの例外をスローする
        導入されたバージョン:
        1.6
        関連項目:
        setRoundingMode(RoundingMode)

      • setRoundingMode

        public void setRoundingMode​(RoundingMode roundingMode)
        このNumberFormatで使用されるRoundingModeを設定します。 NumberFormatのこのメソッドのデフォルト実装は、常にUnsupportedOperationExceptionをスローします。 さまざまな丸めモードを処理するサブクラスは、このメソッドをオーバーライドする必要があります。
        パラメータ:
        roundingMode - 使用されるRoundingMode
        例外:
        UnsupportedOperationException - デフォルトの実装は常にこの例外をスローする
        NullPointerException - roundingModeがnullである場合
        導入されたバージョン:
        1.6
        関連項目:
        getRoundingMode()