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