java.text

接口
类
异常

java.text
类 DateFormat

java.lang.Object
  继承者 java.text.Format
      继承者 java.text.DateFormat
所有已实现的接口：
Serializable, Cloneable
直接已知子类：
SimpleDateFormat 
public abstract class DateFormat
     

      extends 
      Format

DateFormat 是日期/时间格式化子类的抽象类，它以与语言无关的方式格式化并解析日期或时间。日期/时间格式化子类（如 SimpleDateFormat）允许进行格式化（也就是日期 -> 文本）、解析（文本-> 日期）和标准化。将日期表示为 Date 对象，或者表示为从 GMT（格林尼治标准时间）1970 年 1 月 1 日 00:00:00 这一刻开始的毫秒数。

DateFormat 提供了很多类方法，以获得基于默认或给定语言环境和多种格式化风格的默认日期/时间 Formatter。格式化风格包括 FULL、LONG、MEDIUM 和 SHORT。方法描述中提供了使用这些风格的更多细节和示例。

DateFormat 可帮助进行格式化并解析任何语言环境的日期。对于月、星期，甚至日历格式（阴历和阳历），其代码可完全与语言环境的约定无关。

要格式化一个当前语言环境下的日期，可使用某个静态工厂方法： 

  myString = DateFormat.getDateInstance().format(myDate);

如果格式化多个日期，那么获取该格式并多次使用它是更为高效的做法，这样系统就不必多次获取有关环境语言和国家/地区约定的信息了。 

  DateFormat df = DateFormat.getDateInstance();
  for (int i = 0; i < myDate.length; ++i) {
    output.println(df.format(myDate[i]) + "; ");
  }

要格式化不同语言环境的日期，可在 getDateInstance() 的调用中指定它。 

  DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);

还可使用 DateFormat 进行解析。 

  myDate = df.parse(myString);

使用 getDateInstance 来获取该国家/地区的标准日期格式。另外还提供了一些其他静态工厂方法。使用 getTimeInstance 可获取该国家/地区的时间格式。使用 getDateTimeInstance 可获取日期和时间格式。可以将不同选项传入这些工厂方法，以控制结果的长度（从 SHORT 到 MEDIUM 到 LONG 再到 FULL）。确切的结果取决于语言环境，但是通常：

  • SHORT 完全为数字，如 12.13.52 或 3:30pm
  • MEDIUM 较长，如 Jan 12, 1952
  • LONG 更长，如 January 12, 1952 或 3:30:32pm
  • FULL 是完全指定，如 Tuesday、April 12、1952 AD 或 3:30:42pm PST。

如果愿意，还可以在格式上设置时区。如果想对格式化或解析施加更多的控制（或者给予用户更多的控制），可以尝试将从工厂方法所获取的 DateFormat 强制转换为 SimpleDateFormat。这适用于大多数国家/地区；只是要记住将其放入一个 try 代码块中，以防遇到特殊的格式。

还可以使用借助 ParsePosition 和 FieldPosition 的解析和格式化方法形式来

  • 逐步地解析字符串的各部分。
  • 对齐任意特定的字段，或者找出字符串在屏幕上的选择位置。

同步

日期格式不是同步的。建议为每个线程创建独立的格式实例。如果多个线程同时访问一个格式，则它必须保持外部同步。

另请参见：
Format, NumberFormat, SimpleDateFormat, Calendar, GregorianCalendar, TimeZone, 序列化表格

嵌套类摘要
static class DateFormat.Field
          定义了各种常量，这些常量用作 DateFormat.formatToCharacterIterator 所返回的 AttributedCharacterIterator 中的属性键和 FieldPosition 中的字段标识符。
 
字段摘要
static int AM_PM_FIELD
          用于对齐 AM_PM 字段的有用常量。
protected  Calendar calendar
          DateFormat 使用 calendar 来生成实现日期和时间格式化所需的时间字段值。
static int DATE_FIELD
          用于对齐 DATE 字段的有用常量。
static int DAY_OF_WEEK_FIELD
          用于对齐 DAY_OF_WEEK 字段的有用常量。
static int DAY_OF_WEEK_IN_MONTH_FIELD
          用于对齐 DAY_OF_WEEK_IN_MONTH 字段的有用常量。
static int DAY_OF_YEAR_FIELD
          用于对齐 DAY_OF_YEAR 字段的有用常量。
static int DEFAULT
          用于默认模式的常量。
static int ERA_FIELD
          用于对齐 ERA 字段的有用常量。
static int FULL
          用于 FULL 模式的常量。
static int HOUR_OF_DAY0_FIELD
          用于对齐从 0 开始的 HOUR_OF_DAY 字段的有用常量。
static int HOUR_OF_DAY1_FIELD
          用于对齐从 1 开始的 HOUR_OF_DAY 字段的有用常量。
static int HOUR0_FIELD
          用于对齐从 0 开始的 HOUR 字段的有用常量。
static int HOUR1_FIELD
          用于对齐从 1 开始的 HOUR 字段的有用常量。
static int LONG
          用于 LONG 模式的常量。
static int MEDIUM
          用于 MEDIUM 模式的常量。
static int MILLISECOND_FIELD
          用于对齐 MILLISECOND 字段的有用常量。
static int MINUTE_FIELD
          用于对齐 MINUTE 字段的有用常量。
static int MONTH_FIELD
          用于对齐 MONTH 字段的有用常量。
protected  NumberFormat numberFormat
          数字格式器，DateFormat 用其来格式化日期和时间中的数字。
static int SECOND_FIELD
          用于对齐 SECOND 字段的有用常量。
static int SHORT
          用于 SHORT 模式的常量。
static int TIMEZONE_FIELD
          用于对齐 TIMEZONE 字段的有用常量。
static int WEEK_OF_MONTH_FIELD
          用于对齐 WEEK_OF_MONTH 字段的有用常量。
static int WEEK_OF_YEAR_FIELD
          用于对齐 WEEK_OF_YEAR 字段的有用常量。
static int YEAR_FIELD
          用于对齐 YEAR 字段的有用常量。
 
构造方法摘要
protected DateFormat()
          创建一个新的 DateFormat。
 
方法摘要
 Object clone()
          重写 Cloneable
 boolean equals(Object obj)
          重写 equals
 String format(Date date)
          将一个 Date 格式化为日期/时间字符串。
abstract  StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition fieldPosition)
          将一个 Date 格式化为日期/时间字符串。
 StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition fieldPosition)
          重写 Format。
static Locale[] getAvailableLocales()
          返回所有语言环境的数组，此类的 get*Instance 方法可以为其返回已本地化的实例。
 Calendar getCalendar()
          获取与此日期/时间格式器关联的日历。
static DateFormat getDateInstance()
          获取日期格式器，该格式器具有默认语言环境的默认格式化风格。
static DateFormat getDateInstance(int style)
          获取日期格式器，该格式器具有默认语言环境的给定格式化风格。
static DateFormat getDateInstance(int style, Locale aLocale)
          获取日期格式器，该格式器具有给定语言环境的给定格式化风格。
static DateFormat getDateTimeInstance()
          获取日期/时间格式器，该格式器具有默认语言环境的默认格式化风格。
static DateFormat getDateTimeInstance(int dateStyle, int timeStyle)
          获取日期/时间格式器，该格式器具有默认语言环境的给定日期和时间格式化风格。
static DateFormat getDateTimeInstance(int dateStyle, int timeStyle, Locale aLocale)
          获取日期/时间格式器，该格式器具有给定语言环境的给定格式化风格。
static DateFormat getInstance()
          获取为日期和时间使用 SHORT 风格的默认日期/时间格式器。
 NumberFormat getNumberFormat()
          获取此日期/时间格式器用于格式化和解析时间的数字格式器。
static DateFormat getTimeInstance()
          获取时间格式器，该格式器具有默认语言环境的默认格式化风格。
static DateFormat getTimeInstance(int style)
          获取时间格式器，该格式器具有默认语言环境的给定格式化风格。
static DateFormat getTimeInstance(int style, Locale aLocale)
          获取时间格式器，该格式器具有给定语言环境的给定格式化风格。
 TimeZone getTimeZone()
          获取时区。
 int hashCode()
          重写 hashCode
 boolean isLenient()
          判断日期/时间解析是否为不严格的。
 Date parse(String source)
          从给定字符串的开始解析文本，以生成一个日期。
abstract  Date parse(String source, ParsePosition pos)
          根据给定的解析位置开始解析日期/时间字符串。
 Object parseObject(String source, ParsePosition pos)
          解析字符串中的文本，以生成一个 Date。
 void setCalendar(Calendar newCalendar)
          设置此日期格式所使用的日历。
 void setLenient(boolean lenient)
          指定日期/时间解析是否不严格。
 void setNumberFormat(NumberFormat newNumberFormat)
          允许用户设置数字格式器。
 void setTimeZone(TimeZone zone)
          为此 DateFormat 对象的日历设置时区。
 
从类 java.text.Format 继承的方法
format, formatToCharacterIterator, parseObject
 
从类 java.lang.Object 继承的方法
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

字段详细信息

calendar

protected Calendar calendar
DateFormat 使用 calendar 来生成实现日期和时间格式化所需的时间字段值。子类应将此 calendar 初始化为适合于与此 DateFormat 关联的语言环境的日历。

numberFormat

protected NumberFormat numberFormat
数字格式器， DateFormat 用其来格式化日期和时间中的数字。子类应将此数字格式器初始化为适合于与此 DateFormat 关联的语言环境的数字格式。

ERA_FIELD

public static final int ERA_FIELD
用于对齐 ERA 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

YEAR_FIELD

public static final int YEAR_FIELD
用于对齐 YEAR 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

MONTH_FIELD

public static final int MONTH_FIELD
用于对齐 MONTH 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

DATE_FIELD

public static final int DATE_FIELD
用于对齐 DATE 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

HOUR_OF_DAY1_FIELD

public static final int HOUR_OF_DAY1_FIELD
用于对齐从 1 开始的 HOUR_OF_DAY 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。HOUR_OF_DAY1_FIELD 用于从 1 开始的 24 小时时钟。例如，23:59 ＋ 01:00 的结果是 24:59。

另请参见：
常量字段值

HOUR_OF_DAY0_FIELD

public static final int HOUR_OF_DAY0_FIELD
用于对齐从 0 开始的 HOUR_OF_DAY 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。HOUR_OF_DAY0_FIELD 用于从 0 开始的 24 小时时钟。例如，23:59 ＋ 01:00 的结果是 00:59。

另请参见：
常量字段值

MINUTE_FIELD

public static final int MINUTE_FIELD
用于对齐 MINUTE 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

SECOND_FIELD

public static final int SECOND_FIELD
用于对齐 SECOND 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

MILLISECOND_FIELD

public static final int MILLISECOND_FIELD
用于对齐 MILLISECOND 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

DAY_OF_WEEK_FIELD

public static final int DAY_OF_WEEK_FIELD
用于对齐 DAY_OF_WEEK 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

DAY_OF_YEAR_FIELD

public static final int DAY_OF_YEAR_FIELD
用于对齐 DAY_OF_YEAR 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

DAY_OF_WEEK_IN_MONTH_FIELD

public static final int DAY_OF_WEEK_IN_MONTH_FIELD
用于对齐 DAY_OF_WEEK_IN_MONTH 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

WEEK_OF_YEAR_FIELD

public static final int WEEK_OF_YEAR_FIELD
用于对齐 WEEK_OF_YEAR 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

WEEK_OF_MONTH_FIELD

public static final int WEEK_OF_MONTH_FIELD
用于对齐 WEEK_OF_MONTH 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

AM_PM_FIELD

public static final int AM_PM_FIELD
用于对齐 AM_PM 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

HOUR1_FIELD

public static final int HOUR1_FIELD
用于对齐从 1 开始的 HOUR 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。HOUR1_FIELD 用于从 1 开始的 12 小时时钟。例如，11:30 PM ＋ 1 小时的结果是 12:30 AM。

另请参见：
常量字段值

HOUR0_FIELD

public static final int HOUR0_FIELD
用于对齐从 0 开始的 HOUR 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。HOUR0_FIELD 用于从 0 开始的 12 小时时钟。例如，11:30 PM ＋ 1 小时的结果是 00:30 AM。

另请参见：
常量字段值

TIMEZONE_FIELD

public static final int TIMEZONE_FIELD
用于对齐 TIMEZONE 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见：
常量字段值

FULL

public static final int FULL
用于 FULL 模式的常量。

另请参见：
常量字段值

LONG

public static final int LONG
用于 LONG 模式的常量。

另请参见：
常量字段值

MEDIUM

public static final int MEDIUM
用于 MEDIUM 模式的常量。

另请参见：
常量字段值

SHORT

public static final int SHORT
用于 SHORT 模式的常量。

另请参见：
常量字段值

DEFAULT

public static final int DEFAULT
用于默认模式的常量。其值为 MEDIUM。

另请参见：
常量字段值
构造方法详细信息

DateFormat

protected DateFormat()
创建一个新的 DateFormat。

方法详细信息

format

public final StringBuffer format(Object obj,
                                 StringBuffer toAppendTo,
                                 FieldPosition fieldPosition)
重写 Format。将时间对象格式化为时间字符串。时间对象的示例有以毫秒表示的时间值和 Date 对象。

指定者：
类 Format 中的 format
参数：
obj - 必须为 Number 或 Date。
toAppendTo - 用于返回的时间字符串的字符串缓冲区。
fieldPosition - 跟踪返回字符串中字段的位置。输入时：如果需要，是一个对齐字段。输出时：对齐字段的偏移量。例如，在给定时间文本 "1996.07.10 AD at 15:08:56 PDT" 的情况下，如果给定的 fieldPosition 是 DateFormat.YEAR_FIELD，则将 fieldPosition 的开始索引和结束索引分别设置为 0 和 4。注意，如果在一个模式中多次出现同一时间字段，则为第一次出现的该时间字段设置 fieldPosition。例如，使用模式 "h a z (zzzz)" 和对齐字段 DateFormat.TIMEZONE_FIELD 将某个 Date 格式化为时间字符串 "1 PM PDT (Pacific Daylight Time)" 时，针对时区模式字符 'z' 的首个匹配项，将 fieldPosition 的开始索引和结束索引分别设置为 5 和 8。
返回：
作为 toAppendTo 进行传入的字符串缓冲区，添加上已格式化的文本。
另请参见：
Format

format

public abstract StringBuffer format(Date date,
                                    StringBuffer toAppendTo,
                                    FieldPosition fieldPosition)
将一个 Date 格式化为日期/时间字符串。

参数：
date - 要格式化为日期/时间字符串的 Date。
toAppendTo - 用于返回的日期/时间字符串的字符串缓冲区。
fieldPosition - 跟踪返回字符串中字段的位置。输入时：如果需要，是一个对齐字段。输出时：对齐字段的偏移量。例如，在给定时间文本 "1996.07.10 AD at 15:08:56 PDT" 的情况下，如果给定的 fieldPosition 是 DateFormat.YEAR_FIELD，则将 fieldPosition 的开始索引和结束索引分别设置为 0 和 4。注意，如果在一个模式中多次出现同一时间字段，则为该时间字段的首个匹配项设置 fieldPosition。例如，使用模式 "h a z (zzzz)" 和对齐字段 DateFormat.TIMEZONE_FIELD 将某个 Date 格式化为时间字符串 "1 PM PDT (Pacific Daylight Time)" 时，针对时区模式字符 'z' 的首个匹配项，将 fieldPosition 的开始索引和结束索引分别设置为 5 和 8。
返回：
作为 toAppendTo 进行传入的字符串缓冲区，添加上已格式化的文件。

format

public final String format(Date date)
将一个 Date 格式化为日期/时间字符串。

参数：
date - 要格式化为时间字符串的时间值。
返回：
已格式化的时间字符串。

parse

public Date parse(String source)
           throws ParseException
从给定字符串的开始解析文本，以生成一个日期。该方法不使用给定字符串的整个文本。

有关日期解析的更多信息，请参阅 parse(String, ParsePosition) 方法。

参数：
source - 一个 String，应从其开始处进行解析。
返回：
解析字符串得到的 Date。
抛出：
ParseException - 如果无法解析指定字符串的开始处。

parse

public abstract Date parse(String source,
                           ParsePosition pos)
根据给定的解析位置开始解析日期/时间字符串。例如，时间文本 "07/10/96 4:5 PM, PDT" 会解析成等同于 Date(837039928046) 的 Date。

在默认情况下，进行的解析是不严格的：如果输入的形式不是此对象的格式化方法使用的形式，但仍可作为日期进行解析，则解析将获得成功。客户端可能通过调用 setLenient(false) 来强调严格遵守该格式。

参数：
source - 要解析的日期/时间字符串
pos - 输入时，是开始进行解析的位置；输出时，是解析终止的位置，如果解析失败，则为开始位置。
返回：
一个 Date，如果无法解析输入，则为 null
另请参见：
setLenient(boolean)

parseObject

public Object parseObject(String source,
                          ParsePosition pos)
解析字符串中的文本，以生成一个 Date。

该方法试图从 pos 所给定的索引处开始解析文本。如果解析成功，则将 pos 的索引更新为所用最后一个字符后面的索引（解析过程不一定使用到字符串末尾为止的所有字符），并返回解析得到的日期。可以使用更新后的 pos 指示下一次调用此方法的开始点。如果发生错误，则不更改 pos 的索引，并将 pos 的错误索引设置为发生错误处的字符索引，并且返回 null。

有关日期解析的更多信息，请参阅 parse(String, ParsePosition) 方法。

指定者：
类 Format 中的 parseObject
参数：
source - 一个 String，应解析其中的部分内容。
pos - 具有索引和上述错误索引信息的 ParsePosition 对象。
返回：
解析字符串得到的 Date。在出现错误的情况下返回 null。
抛出：
NullPointerException - 如果 pos 为 null。

getTimeInstance

public static final DateFormat getTimeInstance()
获取时间格式器，该格式器具有默认语言环境的默认格式化风格。

返回：
时间格式器。

getTimeInstance

public static final DateFormat getTimeInstance(int style)
获取时间格式器，该格式器具有默认语言环境的给定格式化风格。

参数：
style - 给定的格式化风格。例如，SHORT 用于 US 语言环境中的 "h:mm a"。
返回：
时间格式器。

getTimeInstance

public static final DateFormat getTimeInstance(int style,
                                               Locale aLocale)
获取时间格式器，该格式器具有给定语言环境的给定格式化风格。

参数：
style - 给定的格式化风格。例如，SHORT 用于 US 语言环境中的 "h:mm a"。
aLocale - 给定的语言环境。
返回：
时间格式器。

getDateInstance

public static final DateFormat getDateInstance()
获取日期格式器，该格式器具有默认语言环境的默认格式化风格。

返回：
日期格式器。

getDateInstance

public static final DateFormat getDateInstance(int style)
获取日期格式器，该格式器具有默认语言环境的给定格式化风格。

参数：
style - 给定的格式化风格。例如，SHORT 用于 US 语言环境中的 "M/d/yy"。
返回：
日期格式器。

getDateInstance

public static final DateFormat getDateInstance(int style,
                                               Locale aLocale)
获取日期格式器，该格式器具有给定语言环境的给定格式化风格。

参数：
style - 给定的格式化风格。例如，SHORT 用于 US 语言环境中的 "M/d/yy"。
aLocale - 给定的语言环境。
返回：
日期格式器。

getDateTimeInstance

public static final DateFormat getDateTimeInstance()
获取日期/时间格式器，该格式器具有默认语言环境的默认格式化风格。

返回：
日期/时间格式器。

getDateTimeInstance

public static final DateFormat getDateTimeInstance(int dateStyle,
                                                   int timeStyle)
获取日期/时间格式器，该格式器具有默认语言环境的给定日期和时间格式化风格。

参数：
dateStyle - 给定的日期格式化风格。例如，SHORT 用于 US 语言环境中的 "M/d/yy"。
timeStyle - 给定的时间格式化风格。例如，SHORT 用于 US 语言环境中的 "h:mm a"。
返回：
日期/时间格式器。

getDateTimeInstance

public static final DateFormat getDateTimeInstance(int dateStyle,
                                                   int timeStyle,
                                                   Locale aLocale)
获取日期/时间格式器，该格式器具有给定语言环境的给定格式化风格。

参数：
dateStyle - 给定的日期格式化风格。
timeStyle - 给定的时间格式化风格。
aLocale - 给定的语言环境。
<