Module java.base
Package java.text

Class 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 方法）的编程接口。

通常，格式的 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 标识字段。有关这些常量的示例，请参见 DateFormat 中的 ERA_FIELD 及其相关内容。

同步

通常情况下，格式不是同步的。建议为每个线程创建单独的格式实例。如果多个线程同时访问一个格式，必须在外部进行同步。

自版本:
1.1
参见:

  • Constructor Details

    • Format

      protected Format()
      唯一的构造函数。（通常由子类构造函数隐式调用。）

  • Method Details

    • format

      public final String format(Object obj)
      格式化对象以生成字符串。这等效于
      format(obj, new StringBuffer(), new FieldPosition(0)).toString();
      参数:
      obj - 要格式化的对象
      返回:
      格式化的字符串。
      抛出:
      IllegalArgumentException - 如果格式无法格式化给定对象

    • format

      public abstract StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
      格式化对象并将生成的文本附加到给定的字符串缓冲区。如果 pos 参数标识格式中使用的字段，则将其索引设置为遇到的第一个字段的开始和结束。
      参数:
      obj - 要格式化的对象
      toAppendTo - 要附加文本的位置
      pos - 一个标识格式文本中字段的 FieldPosition
      返回:
      传入的 toAppendTo 字符串缓冲区，附加了格式化的文本
      抛出:
      NullPointerException - 如果 toAppendTo 或 pos 为 null
      IllegalArgumentException - 如果格式无法格式化给定对象

    • formatToCharacterIterator

      public AttributedCharacterIterator formatToCharacterIterator(Object obj)
      格式化对象生成一个 AttributedCharacterIterator。您可以使用返回的 AttributedCharacterIterator 来构建生成的字符串，以及确定有关生成的字符串的信息。

      AttributedCharacterIterator 的每个属性键都将是 Field 类型。每个 Format 实现定义每个属性在 AttributedCharacterIterator 中的合法值，但通常属性键也用作属性值。

      默认实现创建一个没有属性的 AttributedCharacterIterator。支持字段的子类应覆盖此方法，并创建具有有意义属性的 AttributedCharacterIterator。

      参数:
      obj - 要格式化的对象
      返回:
      描述格式化值的 AttributedCharacterIterator。
      抛出:
      NullPointerException - 如果 obj 为 null。
      IllegalArgumentException - 当格式无法格式化给定对象时。
      自版本:
      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 中
      返回:
      此实例的克隆。
      参见: