java.text
クラス NumberFormat

java.lang.Object
  |
  +--java.text.Format
        |
        +--java.text.NumberFormat

すべての実装インタフェース:

Cloneable, Serializable

直系の既知のサブクラス:

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 < a.length; ++i) {
     output.println(nf.format(myNumber[i]) + "; ");
 }
 

異なるロケールの数値をフォーマットする場合は、getInstance を呼び出すときにそれを指定します。

 NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
 

さらに、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)" にするように、負の数に括弧を付ける場合です。

同期

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

関連項目:

DecimalFormat, ChoiceFormat, 直列化された形式

入れ子クラスの概要

static class

NumberFormat.Field NumberFormat.formatToCharacterIterator から返された AttributedCharacterIterator 内の属性キー、および FieldPosition 内のフィールド識別子として使用する定数を定義します。

クラス java.text.Format から継承した入れ子クラス

フィールドの概要

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

コンストラクタの概要

NumberFormat()

メソッドの概要

Object	clone() Cloneable をオーバーライドします。
boolean	equals(Object obj) equals をオーバーライドします。
String	format(double number) フォーマットの特殊化です。
abstract StringBuffer	format(double number, StringBuffer toAppendTo, FieldPosition pos) フォーマットの特殊化です。
String	format(long number) フォーマットの特殊化です。
abstract StringBuffer	format(long number, StringBuffer toAppendTo, FieldPosition pos) フォーマットの特殊化です。
StringBuffer	format(Object number, StringBuffer toAppendTo, FieldPosition pos) オブジェクトをフォーマットして文字列を作成します。
static Locale[]	getAvailableLocales() NumberFormat が導入されているロケールセットを取得します。
Currency	getCurrency() 通貨値をフォーマットするときに、この数値フォーマットで使用される通貨を取得します。
static NumberFormat	getCurrencyInstance() 現在のデフォルトロケールに対する通貨フォーマットを返します。
static NumberFormat	getCurrencyInstance(Locale inLocale) 指定されたロケールに対する通貨フォーマットを返します。
static NumberFormat	getInstance() 現在のデフォルトロケールに対するデフォルトの数値フォーマットを返します。
static NumberFormat	getInstance(Locale inLocale) 指定されたロケールに対するデフォルトの数値フォーマットを返します。
static NumberFormat	getIntegerInstance() 現在のデフォルトロケールに対する整数型数値フォーマットを返します。
static NumberFormat	getIntegerInstance(Locale inLocale) 指定されたロケールに対する整数型数値フォーマットを返します。
int	getMaximumFractionDigits() 数値の小数部分として可能な最大桁数を返します。
int	getMaximumIntegerDigits() 数値の整数部分として可能な最大桁数を返します。
int	getMinimumFractionDigits() 数値の小数部分として可能な最小桁数を返します。
int	getMinimumIntegerDigits() 数値の整数部分として可能な最小桁数を返します。
static NumberFormat	getNumberInstance() 現在のデフォルトロケールに対する汎用数値フォーマットを返します。
static NumberFormat	getNumberInstance(Locale inLocale) 指定されたロケールに対する汎用数値フォーマットを返します。
static NumberFormat	getPercentInstance() 現在のデフォルトロケールに対するパーセントフォーマットを返します。
static NumberFormat	getPercentInstance(Locale inLocale) 指定されたロケールに対するパーセントフォーマットを返します。
int	hashCode() hashCode をオーバーライドします。
boolean	isGroupingUsed() このフォーマットでグループ化が使用される場合に、true を返します。
boolean	isParseIntegerOnly() このフォーマットが数値を整数としてのみ解析する場合に、true を返します。
Number	parse(String source) 指定された文字列の先頭からテキストを解析して数値を生成します。
abstract Number	parse(String source, ParsePosition parsePosition) 可能な場合 (たとえば、[Long.MIN_VALUE, Long.MAX_VALUE] の範囲で、小数部分がない場合) は Long を、そうでない場合は Double を返します。
Object	parseObject(String source, ParsePosition pos) 文字列からテキストを解析して Number を生成します。
void	setCurrency(Currency currency) 通貨値をフォーマットするときに、この数値フォーマットで使用される通貨を設定します。
void	setGroupingUsed(boolean newValue) このフォーマットでグループ化を使用するかどうかを設定します。
void	setMaximumFractionDigits(int newValue) 数値の小数部分として可能な最大桁数を設定します。
void	setMaximumIntegerDigits(int newValue) 数値の整数部分として可能な最大桁数を設定します。
void	setMinimumFractionDigits(int newValue) 数値の小数部分として可能な最小桁数を設定します。
void	setMinimumIntegerDigits(int newValue) 数値の整数部分として可能な最小桁数を返します。
void	setParseIntegerOnly(boolean value) 数値を整数としてのみ解析するかどうかを設定します。

クラス java.text.Format から継承したメソッド

format, formatToCharacterIterator, parseObject

クラス java.lang.Object から継承したメソッド

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

フィールドの詳細

INTEGER_FIELD

public static final int INTEGER_FIELD

FieldPosition オブジェクトを構築するためのフィールド定数です。フォーマットされた数値の整数部分の位置を返すように指定します。

関連項目:

FieldPosition, 定数フィールド値

FRACTION_FIELD

public static final int FRACTION_FIELD

FieldPosition オブジェクトを構築するためのフィールド定数です。フォーマットされた数値の小数部分の位置を返すように指定します。

関連項目:

FieldPosition, 定数フィールド値

コンストラクタの詳細

NumberFormat

public NumberFormat()

メソッドの詳細

format

public final StringBuffer format(Object number,
                                 StringBuffer toAppendTo,
                                 FieldPosition pos)

オブジェクトをフォーマットして文字列を作成します。この汎用ルーチンによって、オブジェクトに対するさまざまな解析とフォーマットが可能になります。

定義:

クラス Format 内の format

パラメータ:

toAppendTo - テキストを追加する位置

pos - 入力の場合は位置合わせフィールド (必要な場合)。出力の場合は位置合わせフィールドのオフセット

number - フォーマットするオブジェクト

戻り値:

toAppendTo として渡される値 (これによって、StringBuffer.append() と同じようにチェーンが可能になる)

例外:

IllegalArgumentException - 指定されたオブジェクトを Format でフォーマットできない場合

関連項目:

FieldPosition

parseObject

public final Object parseObject(String source,
                                ParsePosition pos)

文字列からテキストを解析して Number を生成します。

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

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

定義:

クラス Format 内の parseObject

パラメータ:

source - 部分的に解析される String

pos - 上記のインデックスおよびエラーインデックス情報を持つ ParsePosition オブジェクト

戻り値:

文字列から解析された Number。エラーの場合は null

例外:

NullPointerException - pos が null の場合

format

public final String format(double number)

フォーマットの特殊化です。

関連項目:

Format.format(java.lang.Object)

format

public final String format(long number)

フォーマットの特殊化です。

関連項目:

Format.format(java.lang.Object)

format

public abstract StringBuffer format(double number,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)

フォーマットの特殊化です。

関連項目:

Format.format(java.lang.Object)

format

public abstract StringBuffer format(long number,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)

フォーマットの特殊化です。

関連項目:

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 の後で止まる)。例外はスローしません。オブジェクトが解析できない場合、インデックスは変わりません。

関連項目:

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 のサブクラスによって決まります。

setParseIntegerOnly

public void setParseIntegerOnly(boolean value)

数値を整数としてのみ解析するかどうかを設定します。

関連項目:

isParseIntegerOnly()

getInstance

public static final NumberFormat getInstance()

現在のデフォルトロケールに対するデフォルトの数値フォーマットを返します。デフォルトのフォーマットは、他のファクトリメソッド getNumberInstance、getIntegerInstance、getCurrencyInstance、または getPercentInstance で提供されるスタイルの 1 つです。正確には、どれであるかはロケールに依存します。

getInstance

public static NumberFormat getInstance(Locale inLocale)

指定されたロケールに対するデフォルトの数値フォーマットを返します。デフォルトのフォーマットは、他のファクトリメソッド getNumberInstance、getIntegerInstance、getCurrencyInstance、または getPercentInstance で提供されるスタイルの 1 つです。正確には、どれであるかはロケールに依存します。

getNumberInstance

public static final NumberFormat getNumberInstance()

現在のデフォルトロケールに対する汎用数値フォーマットを返します。

getNumberInstance

public static NumberFormat getNumberInstance(Locale inLocale)

指定されたロケールに対する汎用数値フォーマットを返します。

getIntegerInstance

public static final NumberFormat getIntegerInstance()

現在のデフォルトロケールに対する整数型数値フォーマットを返します。返された数値フォーマットは、フォーマットするために、IEEE の最近値方向への丸めモードを (ROUND_HALF_EVEN を参照) 使って、浮動小数点数値をもっとも近い整数値に丸め、入力文字列の整数部分だけを解析する (isParseIntegerOnly を参照) ように設定されます。

戻り値:

整数値に対する数値フォーマット

導入されたバージョン:

1.4

getIntegerInstance

public static NumberFormat getIntegerInstance(Locale inLocale)

指定されたロケールに対する整数型数値フォーマットを返します。返された数値フォーマットは、フォーマットするために、IEEE の最近値方向への丸めモードを (ROUND_HALF_EVEN を参照) 使って、浮動小数点数値をもっとも近い整数値に丸め、入力文字列の整数部分だけを解析する (isParseIntegerOnly を参照) ように設定されます。

パラメータ:

inLocale - 数値フォーマットを必要とするロケール

戻り値:

整数値に対する数値フォーマット

導入されたバージョン:

1.4

getCurrencyInstance

public static final NumberFormat getCurrencyInstance()

現在のデフォルトロケールに対する通貨フォーマットを返します。

getCurrencyInstance

public static NumberFormat getCurrencyInstance(Locale inLocale)

指定されたロケールに対する通貨フォーマットを返します。

getPercentInstance

public static final NumberFormat getPercentInstance()

現在のデフォルトロケールに対するパーセントフォーマットを返します。

getPercentInstance

public static NumberFormat getPercentInstance(Locale inLocale)

指定されたロケールに対するパーセントフォーマットを返します。

getAvailableLocales

public static Locale[] getAvailableLocales()

NumberFormat が導入されているロケールセットを取得します。

戻り値:

使用可能なロケール

hashCode

public int hashCode()

hashCode をオーバーライドします。

オーバーライド:

クラス Object 内の hashCode

戻り値:

このオブジェクトのハッシュコード値

関連項目:

Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)

equals をオーバーライドします。

オーバーライド:

クラス Object 内の equals

パラメータ:

obj - 比較対象の参照オブジェクト

戻り値:

obj 引数に指定されたオブジェクトとこのオブジェクトが等しい場合は true、そうでない場合は false

関連項目:

Object.hashCode(), Hashtable

clone

public Object clone()

Cloneable をオーバーライドします。

オーバーライド:

クラス Format 内の clone

戻り値:

このインスタンスの複製

isGroupingUsed

public boolean isGroupingUsed()

このフォーマットでグループ化が使用される場合に、true を返します。たとえば、英語ロケールでグループ化がオンのとき、数値 1234567 は、"1,234,567" のようにフォーマットされます。グループ区切り子と各グループのサイズは、ロケールに依存し、NumberFormat のサブクラスによって決まります。

関連項目:

setGroupingUsed(boolean)

setGroupingUsed

public void setGroupingUsed(boolean newValue)

このフォーマットでグループ化を使用するかどうかを設定します。

関連項目:

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)

数値の整数部分として可能な最小桁数を返します。minimuIntegerDigits は、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