java.text
類別 Format

java.lang.Object
  java.text.Format

所有已實作的介面：

Serializable, Cloneable

直接已知子類別：

DateFormat, MessageFormat, NumberFormat

public abstract class Format
extends Object
implements Serializable, Cloneable

Format 是一個用於格式化語言環境敏感的資訊（如日期、訊息和數字）的抽象基礎類別。

Format 定義了程式介面，用於將語言環境敏感的物件格式化為 String（使用 format 方法）和將 String 重新解析為物件（使用 parseObject 方法）。

通常，一個 format 的 parseObject 方法必須能解析任何由其 format 方法格式化的字元串。不過，也可能存在不能解析的異常情況。例如，format 方法可能創建中間無分隔符的兩個相鄰整數，在這種情況下，parseObject 無法判斷哪個數字屬於哪個數。

子類別化

Java 平臺為格式化日期、訊息和數字分別提供了三個特殊的 Format 的子類別：DateFormat、MessageFormat 和 NumberFormat。

具體的子類別必須實作三個方法：

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 方法來獲取特殊的數字格式器。

Format 的子類別如果允許開發人員能為不同語言環境（比如用 getInstance(Locale) ）創建物件，必須實作以下類別方法：

 public static Locale[] getAvailableLocales()
 

最後子類別定義一個常數集合來標識格式輸出中的不同欄位。這些常數用於創建一個 FieldPosition 物件，該物件標識欄位中所包含的資訊及其在格式化結果中的位置。這些常數應當命名為item _FIELD，其中item 標識了該欄位。有關這些常數的例子，請參閱 ERA_FIELD 及其在 DateFormat 中的同類別。

同步

格式通常不是同步的。建議為每個執行緒創建獨立的格式實例。如果多個執行緒同時存取一個格式，其它必須保持外部同步。

另請參見：

ParsePosition, FieldPosition, NumberFormat, DateFormat, MessageFormat, 序列化表格

巢狀類別摘要

static class

Format.Field 定義在 AttributedCharacterIterator（從 Format.formatToCharacterIterator 返回）中用作屬性鍵和在 FieldPosition 中用作欄位標識符的常數。

建構子摘要

protected

Format() 單獨的建構子。

方法摘要

Object	clone() 創建並返回此物件的一個副本。
String	format(Object obj) 格式化一個物件以產生一個字元串。
abstract StringBuffer	format(Object obj, StringBuffer toAppendTo, FieldPosition pos) 格式化一個物件，並將得到的文本添加到給定的字元緩衝區。
AttributedCharacterIterator	formatToCharacterIterator(Object obj) 格式化一個物件，產生一個 AttributedCharacterIterator。
Object	parseObject(String source) 從給定字元串的開始處解析文本以產生一個物件。
abstract Object	parseObject(String source, ParsePosition pos) 解析字元串文本，產生一個物件。

從類別 java.lang.Object 繼承的方法

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

建構子詳細資訊

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 參數標識了一個由 format 使用的欄位，那麼其索引就設置為第一次出現的此類別欄位的起始和結束索引。

參數：

obj - 要格式化的物件

toAppendTo - 文本要添加的位置

pos - 標識格式化文本中欄位的一個 FieldPosition。

返回：

添加了格式化文本並作為 toAppendTo 傳入的字元串緩衝區

拋出：

NullPointerException - 如果 toAppendTo 或 pos 為 null

IllegalArgumentException - 如果 Format 不能格式化給定的物件

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

格式化一個物件，產生一個 AttributedCharacterIterator。可以使用返回的 AttributedCharacterIterator 來產生得到的 String，並確定與得到的 String 有關的資訊。

AttributedCharacterIterator 的每一個屬性鍵都是 Field 型別的。由每個 Format 實作為 AttributedCharacterIterator 中的每個屬性定義其合法值，但是通常屬性鍵也用作屬性值。

預設的實作創建了一個沒有任何屬性的 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 - 如果 pos 為 null。

parseObject

public Object parseObject(String source)
                   throws ParseException

從給定字元串的開始處解析文本以產生一個物件。此方法不可以使用給定字元串的全部文本。

參數：

source - 必須解析其開頭的 String。

返回：

從字元串進行解析的一個 Object。

拋出：

ParseException - 如果無法解析指定字元串的開頭。

clone

public Object clone()

創建並返回此物件的一個副本。

覆寫：

類別 Object 中的 clone

返回：

此實例的一個副本。

另請參見：

Cloneable