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

クラスFormat

  • すべての実装されたインタフェース:
    Serializable, Cloneable
    直系の既知のサブクラス:
    DateFormat, MessageFormat, NumberFormat
    public abstract class Format
extends Object
implements Serializable, Cloneable
    Formatは、日付、メッセージ、数字などのロケールに依存する情報をフォーマットするabstract基底クラスです。

    Formatは、ロケールに依存する情報をStringにフォーマットするため(formatメソッド)、およびStringを解析してオブジェクトに戻すため(parseObjectメソッド)のプログラミング・インタフェースを定義するものです。

    通常、formatのparseObjectメソッドは、そのformatメソッドによってフォーマットされた任意の文字列を解析できる必要があります。 ただし、これが可能でない例外的な場合があります。 たとえば、formatメソッドは間に区切り文字がない2つの隣接する整数値を生成する場合があります。この場合、parseObjectは各数字がどの数値に属するのかを示すことができません。

    サブクラス化

    Javaプラットフォームでは、日付、メッセージ、数字をそれぞれフォーマットするため、3つの特殊なサブクラスDateFormat、MessageFormat、NumberFormatがFormatに用意されています。

    具象サブクラスには、次の3つのメソッドを実装しなければいけません。

    1. format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
    2. formatToCharacterIterator(Object obj)
    3. parseObject(String source, ParsePosition pos)
    これらの一般的なメソッドによって、オブジェクトのさまざまな解析とフォーマットが可能になります。これらのメソッドはMessageFormatなどによって使用されます。 サブクラスは多くの場合、特定の入力タイプのための追加のformatメソッドや特定の結果タイプのためのparseメソッドも提供します。 ParsePosition引数をとらないparseは、要求されたフォーマットのテキストが入力テキストの先頭にない場合、ParseExceptionをスローします。

    ほとんどのサブクラスには、さらに次のファクトリ・メソッドが実装されます。

    1. getInstanceは、現在のロケールに適した便利なフォーマット・オブジェクトを取得するためのものです。
    2. getInstance(Locale)は、指定されたロケールに適した便利なフォーマット・オブジェクトを取得するためのものです。
    また、サブクラスによっては、さらに特殊な制御のために、ほかのgetXxxxInstanceメソッドを実装する場合もあります。 たとえば、NumberFormatクラスには、特殊な数字フォーマッタを得るためのgetPercentInstanceおよびgetCurrencyInstanceメソッドがあります。

    ロケール用のオブジェクトをプログラマが生成できるようにする場合(getInstance(Locale)など)は、Formatのサブクラスにさらに次のクラス・メソッドの実装が必要です。 

     public static Locale[] getAvailableLocales()

    最後に、サブクラスには、フォーマットされたさまざまな出力フィールドを識別するために、1組の定数を定義することができます。 これらの定数は、FieldPositionオブジェクトを作成するために使われます。このオブジェクトは、フォーマットされた結果でのフィールドの情報とその位置を識別します。 これらの定数の名前は、item_FIELDでなければいけません。itemはそのフィールドを示します。 これらの定数の例については、DateFormatのERA_FIELDなどを参照してください。

    Synchronization

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

    導入されたバージョン:
    1.1
    関連項目:
    ParsePosition, FieldPosition, NumberFormat, DateFormat, MessageFormat, 直列化された形式

    • コンストラクタの詳細

      • Format

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

    • メソッドの詳細

      • format

        public final String format​(Object obj)
        オブジェクトをフォーマットして文字列を作成します。 これは次の記述と同等です。
        format(obj, new StringBuffer(), new FieldPosition(0)).toString();
        パラメータ:
        obj - フォーマットするオブジェクト
        戻り値:
        フォーマットされた文字列。
        例外:
        IllegalArgumentException - 指定されたオブジェクトをFormatでフォーマットできない場合

      • format

        public abstract StringBuffer format​(Object obj,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)
        オブジェクトをフォーマットし、指定された文字列バッファに結果のテキストを追加します。 pos引数がフォーマットによって使用されるフィールドを識別する場合は、その引数のインデックスは最初に検出されたフィールドの開始と終了に設定されます。
        パラメータ:
        obj - フォーマットするオブジェクト
        toAppendTo - テキストを追加する位置
        pos - フォーマットされたテキスト内のフィールドを識別するFieldPosition
        戻り値:
        toAppendToとして渡される文字列バッファ。フォーマットされたテキストが追加される
        例外:
        NullPointerException - toAppendToまたはposがnullの場合
        IllegalArgumentException - 指定されたオブジェクトをFormatでフォーマットできない場合

      • formatToCharacterIterator

        public AttributedCharacterIterator formatToCharacterIterator​(Object obj)
        Objectをフォーマットし、AttributedCharacterIteratorを生成します。 返されたAttributedCharacterIteratorを使用すると、結果のStringを構築できるとともに、結果のStringについての情報を判定できます。

        AttributedCharacterIteratorの各属性キーはField型です。 AttributedCharacterIterator内の各属性に対する正当な値の定義は、それぞれのFormat実装に依存しますが、通常、属性キーは属性値としても使用されます。

        デフォルトの実装では、属性なしのAttributedCharacterIteratorが生成されます。 フィールドをサポートするサブクラスはこれをオーバーライドし、有効な属性を持つAttributedCharacterIteratorを生成します。

        パラメータ:
        obj - フォーマットするオブジェクト
        戻り値:
        フォーマットされた値を説明するAttributedCharacterIterator。
        例外:
        NullPointerException - objがnullの場合。
        IllegalArgumentException - 指定されたオブジェクトをFormatでフォーマットできない場合。
        導入されたバージョン:
        1.4

      • parseObject

        public abstract Object parseObject​(String source,
                                   ParsePosition pos)
        文字列からテキストを解析してオブジェクトを生成します。

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

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

      • parseObject

        public Object parseObject​(String source)
                   throws ParseException
        指定された文字列の先頭からテキストを解析してオブジェクトを生成します。 メソッドは指定された文字列のテキスト全体に使用されない場合もあります。
        パラメータ:
        source - 先頭が解析されるString。
        戻り値:
        文字列から解析されるObject。
        例外:
        ParseException - 指定された文字列の先頭が解析できない場合。
        NullPointerException - sourceがnullである場合

      • clone

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