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

クラスNumberFormat

java.lang.Object
java.text.Format
java.text.NumberFormat
すべての実装されたインタフェース:
Serializable, Cloneable
直系の既知のサブクラス:
ChoiceFormat, CompactNumberFormat, 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 (var myNumber : numbers) {
    output.println(nf.format(myNumber) + "; ");
}
異なるロケールの数値をフォーマットする場合は、getInstanceを呼び出すときにそれを指定します。 
NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);

ロケールに"nu" (numbers)または"rg" (リージョン・オーバーライド) 「Unicode拡張」(あるいはその両方)が含まれる場合、書式設定に使用される10進数または国(あるいはその両方)がオーバーライドされます。 "nu"と"rg"の両方が指定されている場合、"nu"拡張子の小数点は、"rg"拡張子の暗黙のものよりも優先されます。

さらに、NumberFormatを使って数値を解析することができます。 

myNumber = nf.parse(myString);
通常の数値フォーマットを得るには、getInstanceかgetNumberInstanceを使用します。 整数型数値フォーマットを得るには、getIntegerInstanceを使用します。 通貨数値フォーマットを得るには、getCurrencyInstanceを使用します。 getCompactNumberInstanceを使用して、数値をより短い形式で書式設定するために、コンパクト数値書式設定を取得します。 たとえば、2000はUS locale内で"2K"と書式設定できます。 getPercentInstanceを使用して、パーセンテージを表示するための書式を取得します。 このフォーマットを使うと、0.53などの小数点以下は53%のように表示されます。

さらに、setMinimumFractionDigitsなどのメソッドを使えば、数値の表示を制御することができます。 フォーマットや解析をより詳細に制御する必要がある場合や、ユーザーに詳細な制御を提供する必要がある場合は、使用するファクトリ・メソッドに応じて、ファクトリ・メソッドからDecimalFormatまたはCompactNumberFormatにNumberFormatをキャストすることをお薦めします。 これはほとんどのロケールで有効ですが、有効にならないロケールの場合に備えて、これは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
関連項目: