SimpleDateFormat

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 5.0

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

java.text
类 SimpleDateFormat

java.lang.Object
  java.text.Format
      java.text.DateFormat
          java.text.SimpleDateFormat

所有已实现的接口：: Serializable, Cloneable

public class SimpleDateFormat
extends DateFormat
extends DateFormat

SimpleDateFormat 是一个以与语言环境相关的方式来格式化和分析日期的具体类。它允许进行格式化（日期 -> 文本）、分析（文本 -> 日期）和规范化。

SimpleDateFormat 使得可以选择任何用户定义的日期-时间格式的模式。但是，仍然建议通过 DateFormat 中的 getTimeInstance、getDateInstance 或 getDateTimeInstance 来新的创建日期-时间格式化程序。每一个这样的类方法都能够返回一个以默认格式模式初始化的日期/时间格式化程序。可以根据需要使用 applyPattern 方法来修改格式模式。有关使用这些方法的更多信息，请参阅 DateFormat。

日期和时间模式

日期和时间格式由日期和时间模式 字符串指定。在日期和时间模式字符串中，未加引号的字母 'A' 到 'Z' 和 'a' 到 'z' 被解释为模式字母，用来表示日期或时间字符串元素。文本可以使用单引号 (') 引起来，以免进行解释。"''" 表示单引号。所有其他字符均不解释；只是在格式化时将它们简单复制到输出字符串，或者在分析时与输入字符串进行匹配。

定义了以下模式字母（所有其他字符 'A' 到 'Z' 和 'a' 到 'z' 都被保留）：

字母日期或时间元素表示示例
G Era 标志符 Text AD
y 年 Year 1996; 96
M 年中的月份 Month July; Jul; 07
w 年中的周数 Number 27
W 月份中的周数 Number 2
D 年中的天数 Number 189
d 月份中的天数 Number 10
F 月份中的星期 Number 2
E 星期中的天数 Text Tuesday; Tue
a Am/pm 标记 Text PM
H 一天中的小时数（0-23） Number 0
k 一天中的小时数（1-24） Number 24
K am/pm 中的小时数（0-11） Number 0
h am/pm 中的小时数（1-12） Number 12
m 小时中的分钟数 Number 30
s 分钟中的秒数 Number 55
S 毫秒数 Number 978
z 时区 General time zone Pacific Standard Time; PST; GMT-08:00
Z 时区 RFC 822 time zone -0800

字母	日期或时间元素	表示	示例
`G`	Era 标志符	Text	`AD`
`y`	年	Year	`1996`; `96`
`M`	年中的月份	Month	`July`; `Jul`; `07`
`w`	年中的周数	Number	`27`
`W`	月份中的周数	Number	`2`
`D`	年中的天数	Number	`189`
`d`	月份中的天数	Number	`10`
`F`	月份中的星期	Number	`2`
`E`	星期中的天数	Text	`Tuesday`; `Tue`
`a`	Am/pm 标记	Text	`PM`
`H`	一天中的小时数（0-23）	Number	`0`
`k`	一天中的小时数（1-24）	Number	`24`
`K`	am/pm 中的小时数（0-11）	Number	`0`
`h`	am/pm 中的小时数（1-12）	Number	`12`
`m`	小时中的分钟数	Number	`30`
`s`	分钟中的秒数	Number	`55`
`S`	毫秒数	Number	`978`
`z`	时区	General time zone	`Pacific Standard Time`; `PST`; `GMT-08:00`
`Z`	时区	RFC 822 time zone	`-0800`

模式字母通常是重复的，其数量确定其精确表示：

Text: 对于格式化来说，如果模式字母的数量大于或等于 4，则使用完全形式；否则，在可用的情况下使用短形式或缩写形式。对于分析来说，两种形式都是可接受的，与模式字母的数量无关。
Number: 对于格式化来说，模式字母的数量是最小的数位，如果数位不够，则用 0 填充以达到此数量。对于分析来说，模式字母的数量被忽略，除非必须分开两个相邻字段。
Year: 对于格式化来说，如果模式字母的数量为 2，则年份截取为 2 位数,否则将年份解释为 number。
对于分析来说，如果模式字母的数量大于 2，则年份照字面意义进行解释，而不管数位是多少。因此使用模式 "MM/dd/yyyy"，将 "01/11/12" 分析为公元 12 年 1 月 11 日。
在分析缩写年份模式（"y" 或 "yy"）时，SimpleDateFormat 必须相对于某个世纪来解释缩写的年份。这通过将日期调整为 SimpleDateFormat 实例创建之前的 80 年和之后 20 年范围内来完成。例如，在 "MM/dd/yy" 模式下，如果 SimpleDateFormat 实例是在 1997 年 1 月 1 日创建的，则字符串 "01/11/12" 将被解释为 2012 年 1 月 11 日，而字符串 "05/04/64" 将被解释为 1964 年 5 月 4 日。在分析时，只有恰好由两位数字组成的字符串（如 Character.isDigit(char) 所定义的）被分析为默认的世纪。其他任何数字字符串将照字面意义进行解释，例如单数字字符串，3 个或更多数字组成的字符串，或者不都是数字的两位数字字符串（例如"-1"）。因此，在相同的模式下， "01/02/3" 或 "01/02/003" 解释为公元 3 年 1 月 2 日。同样，"01/02/-3" 分析为公元前 4 年 1 月 2 日。
Month: 如果模式字母的数量为 3 或大于 3，则将月份解释为 text；否则解释为 number。

General time zone: 如果时区有名称，则将它们解释为 text。对于表示 GMT 偏移值的时区，使用以下语法：

     GMTOffsetTimeZone:
             GMT Sign Hours : Minutes
     Sign: one of
             + -
     Hours:
             Digit
             Digit Digit
     Minutes:
             Digit Digit
     Digit: one of
             0 1 2 3 4 5 6 7 8 9

Hours 必须在 0 到 23 之间，Minutes 必须在 00 到 59 之间。格式是与语言环境无关的，并且数字必须取自 Unicode 标准的 Basic Latin 块。

对于分析来说，RFC 822 time zones 也是可接受的。

RFC 822 time zone: 对于格式化来说，使用 RFC 822 4-digit 时区格式：
```
     RFC822TimeZone:
             Sign TwoDigitHours Minutes
     TwoDigitHours:
             Digit Digit
```
TwoDigitHours 必须在 00 和 23 之间。其他定义请参阅 general time zones。
对于分析来说，general time zones 也是可接受的。

SimpleDateFormat 还支持本地化日期和时间模式 字符串。在这些字符串中，以上所述的模式字母可以用其他与语言环境有关的模式字母来替换。SimpleDateFormat 不处理除模式字母之外的文本本地化；而由类的客户端来处理。

示例

以下示例显示了如何在美国语言环境中解释日期和时间模式。给定的日期和时间为美国太平洋时区的本地时间 2001-07-04 12:08:56。

日期和时间模式结果
"yyyy.MM.dd G 'at' HH:mm:ss z" 2001.07.04 AD at 12:08:56 PDT
"EEE, MMM d, ''yy" Wed, Jul 4, '01
"h:mm a" 12:08 PM
"hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time
"K:mm a, z" 0:08 PM, PDT
"yyyyy.MMMMM.dd GGG hh:mm aaa" 02001.July.04 AD 12:08 PM
"EEE, d MMM yyyy HH:mm:ss Z" Wed, 4 Jul 2001 12:08:56 -0700
"yyMMddHHmmssZ" 010704120856-0700
"yyyy-MM-dd'T'HH:mm:ss.SSSZ" 2001-07-04T12:08:56.235-0700

日期和时间模式	结果
`"yyyy.MM.dd G 'at' HH:mm:ss z"`	`2001.07.04 AD at 12:08:56 PDT`
`"EEE, MMM d, ''yy"`	`Wed, Jul 4, '01`
`"h:mm a"`	`12:08 PM`
`"hh 'o''clock' a, zzzz"`	`12 o'clock PM, Pacific Daylight Time`
`"K:mm a, z"`	`0:08 PM, PDT`
`"yyyyy.MMMMM.dd GGG hh:mm aaa"`	`02001.July.04 AD 12:08 PM`
`"EEE, d MMM yyyy HH:mm:ss Z"`	`Wed, 4 Jul 2001 12:08:56 -0700`
`"yyMMddHHmmssZ"`	`010704120856-0700`
`"yyyy-MM-dd'T'HH:mm:ss.SSSZ"`	`2001-07-04T12:08:56.235-0700`

同步

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

另请参见：: Java Tutorial, Calendar, TimeZone, DateFormat, DateFormatSymbols, 序列化表格

嵌套类摘要

从类 java.text.DateFormat 继承的嵌套类/接口
`DateFormat.Field`

字段摘要

从类 java.text.DateFormat 继承的字段
`AM_PM_FIELD, calendar, DATE_FIELD, DAY_OF_WEEK_FIELD, DAY_OF_WEEK_IN_MONTH_FIELD, DAY_OF_YEAR_FIELD, DEFAULT, ERA_FIELD, FULL, HOUR_OF_DAY0_FIELD, HOUR_OF_DAY1_FIELD, HOUR0_FIELD, HOUR1_FIELD, LONG, MEDIUM, MILLISECOND_FIELD, MINUTE_FIELD, MONTH_FIELD, numberFormat, SECOND_FIELD, SHORT, TIMEZONE_FIELD, WEEK_OF_MONTH_FIELD, WEEK_OF_YEAR_FIELD, YEAR_FIELD`

构造方法摘要
`SimpleDateFormat()` 用默认的模式和默认语言环境的日期格式符号构造 `SimpleDateFormat`。
`SimpleDateFormat(String pattern)` 用给定的模式和默认语言环境的日期格式符号构造 `SimpleDateFormat`。
`SimpleDateFormat(String pattern, DateFormatSymbols formatSymbols)` 用给定的模式和日期符号构造 `SimpleDateFormat`。
`SimpleDateFormat(String pattern, Locale locale)` 用给定的模式和给定语言环境的默认日期格式符号构造 `SimpleDateFormat`。

方法摘要
`void`	`applyLocalizedPattern(String pattern)` 将给定的本地化模式字符串应用于此日期格式。
`void`	`applyPattern(String pattern)` 将给定模式字符串应用于此日期格式。
`Object`	`clone()` 创建此 `SimpleDateFormat` 的一个副本。
`boolean`	`equals(Object obj)` 比较给定对象与此 `SimpleDateFormat` 的相等性。
`StringBuffer`	`format(Date date, StringBuffer toAppendTo, FieldPosition pos)` 将给定的 `Date` 格式化为日期/时间字符串，并将结果追加到给定的 `StringBuffer`。
`AttributedCharacterIterator`	`formatToCharacterIterator(Object obj)` 格式化生成 `AttributedCharacterIterator` 的对象。
`Date`	`get2DigitYearStart()` 返回在 100 年周期内被解释的两位数字年份的开始日期。
`DateFormatSymbols`	`getDateFormatSymbols()` 获取此日期格式的日期和时间格式符号的一个副本。
`int`	`hashCode()` 返回此 `SimpleDateFormat` 对象的哈希码值。
`Date`	`parse(String text, ParsePosition pos)` 分析字符串的文本，生成 `Date`。
`void`	`set2DigitYearStart(Date startDate)` 设置 100 年周期的两位数年份，该年份将被解释为从用户指定的日期开始。
`void`	`setDateFormatSymbols(DateFormatSymbols newFormatSymbols)` 设置此日期格式的日期和时间格式符号。
`String`	`toLocalizedPattern()` 返回描述此日期格式的本地化模式字符串。
`String`	`toPattern()` 返回描述此日期格式的模式字符串。

从类 java.text.DateFormat 继承的方法
`format, format, getAvailableLocales, getCalendar, getDateInstance, getDateInstance, getDateInstance, getDateTimeInstance, getDateTimeInstance, getDateTimeInstance, getInstance, getNumberFormat, getTimeInstance, getTimeInstance, getTimeInstance, getTimeZone, isLenient, parse, parseObject, setCalendar, setLenient, setNumberFormat, setTimeZone`

从类 java.text.Format 继承的方法
`format, parseObject`

从类 java.lang.Object 继承的方法
`finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

构造方法详细信息

SimpleDateFormat

public SimpleDateFormat()

用默认的模式和默认语言环境的日期格式符号构造 SimpleDateFormat。注：此构造方法可能不支持所有语言环境。要覆盖所有地区，请使用 DateFormat 类中的工厂方法。

SimpleDateFormat

public SimpleDateFormat(String pattern)

用给定的模式和默认语言环境的日期格式符号构造 SimpleDateFormat。注：此构造方法可能不支持所有语言环境。要覆盖所有语言环境，请使用 DateFormat 类中的工厂方法。

参数：: pattern - 描述日期和时间格式的模式
抛出：: NullPointerException - 如果给定的模式为 null; IllegalArgumentException - 如果给定的模式无效

SimpleDateFormat

public SimpleDateFormat(String pattern,
                        Locale locale)

用给定的模式和给定语言环境的默认日期格式符号构造 SimpleDateFormat。注：此构造方法可能不支持所有语言环境。要覆盖所有语言环境，请使用 DateFormat 类中的工厂方法。

参数：: pattern - 描述日期和时间格式的模式; locale - 其日期格式符号要被使用的语言环境
抛出：: NullPointerException - 如果给定的模式为 null; IllegalArgumentException - 如果给定的模式无效

SimpleDateFormat

public SimpleDateFormat(String pattern,
                        DateFormatSymbols formatSymbols)

用给定的模式和日期符号构造 SimpleDateFormat。

参数：: pattern - 描述日期和时间格式的模式; formatSymbols - 要用来格式化的日期格式符号
抛出：: NullPointerException - 如果给定的模式或 formatSymbols 为 null; IllegalArgumentException - 如果给定的模式无效

方法详细信息

set2DigitYearStart

public void set2DigitYearStart(Date startDate)

设置 100 年周期的两位数年份，该年份将被解释为从用户指定的日期开始。

参数：: startDate - 在分析时，两位数年份将被置于 startDate 和 startDate + 100 years 之间的范围内。
从以下版本开始：: 1.2
另请参见：: get2DigitYearStart()

get2DigitYearStart

public Date get2DigitYearStart()

返回在 100 年周期内被解释的两位数字年份的开始日期。

返回：: 在 100 年周期内被分析的两位数字年份的开始日期
从以下版本开始：: 1.2
另请参见：: set2DigitYearStart(java.util.Date)

format

public StringBuffer format(Date date,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

将给定的 Date 格式化为日期/时间字符串，并将结果追加到给定的 StringBuffer。

指定者：: 类 DateFormat 中的 format

参数：: date - 要被格式化为日期-时间字符串的日期-时间值。; toAppendTo - 新的日期-时间文本被追加的位置。; pos - 格式化的位置。输入时：如果需要，是一个对齐字段。输出时：为对齐字段的偏移量。
返回：: 格式化的日期-时间字符串。
抛出：: NullPointerException - 如果给定的日期为 null

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

格式化生成 AttributedCharacterIterator 的对象。可以使用返回的 AttributedCharacterIterator 来生成所得的字符串，以及确定关于所得字符串的信息。

AttributedCharacterIterator 的每个属性键都是 DateFormat.Field 类型的，对应的属性值与属性键相同。

覆盖：: 类 Format 中的 formatToCharacterIterator

参数：: obj - 要格式化的对象
返回：: 描述格式化的值的 AttributedCharacterIterator。
抛出：: NullPointerException - 如果 obj 为 null。; IllegalArgumentException - 如果 Format 不能格式化给定的对象，或者 Format 的模式字符串无效。
从以下版本开始：: 1.4

parse

public Date parse(String text,
                  ParsePosition pos)

分析字符串的文本，生成 Date。

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

指定者：: 类 DateFormat 中的 parse

参数：: text - 应该分析其中一部分的 String。; pos - 具有以上所述的索引和错误索引信息的 ParsePosition 对象。
返回：: 从字符串进行分析的 Date。如果发生错误，则返回 null。
抛出：: NullPointerException - 如果 text 或 pos 为 null。
另请参见：: DateFormat.setLenient(boolean)

toPattern

public String toPattern()

返回描述此日期格式的模式字符串。

返回：: 描述此日期格式的模式字符串。

toLocalizedPattern

public String toLocalizedPattern()

返回描述此日期格式的本地化模式字符串。

返回：: 描述此日期格式的本地化模式字符串。

applyPattern

public void applyPattern(String pattern)

将给定模式字符串应用于此日期格式。

参数：: pattern - 此日期格式的新的日期和时间模式
抛出：: NullPointerException - 如果给定的模式为 null; IllegalArgumentException - 如果给定的模式无效

applyLocalizedPattern

public void applyLocalizedPattern(String pattern)

将给定的本地化模式字符串应用于此日期格式。

参数：: pattern - 要被映射到此格式的新的日期和时间格式模式的字符串
抛出：: NullPointerException - 如果给定的模式为 null; IllegalArgumentException - 如果给定的模式无效

getDateFormatSymbols

public DateFormatSymbols getDateFormatSymbols()

获取此日期格式的日期和时间格式符号的一个副本。

返回：: 此日期格式的日期和时间格式符号
另请参见：: setDateFormatSymbols(java.text.DateFormatSymbols)

setDateFormatSymbols

public void setDateFormatSymbols(DateFormatSymbols newFormatSymbols)

设置此日期格式的日期和时间格式符号。

参数：: newFormatSymbols - 新的日期和时间格式符号
抛出：: NullPointerException - 如果给定的 newFormatSymbols 为 null
另请参见：: getDateFormatSymbols()

clone

public Object clone()

创建此 SimpleDateFormat 的一个副本。此复制也将克隆格式的日期格式符号。

覆盖：: 类 DateFormat 中的 clone

返回：: 此 SimpleDateFormat 的一个克隆
另请参见：: Cloneable

hashCode

public int hashCode()

返回此 SimpleDateFormat 对象的哈希码值。

覆盖：: 类 DateFormat 中的 hashCode

返回：: 此 SimpleDateFormat 对象的哈希码值。
另请参见：: Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)

比较给定对象与此 SimpleDateFormat 的相等性。

覆盖：: 类 DateFormat 中的 equals

参数：: obj - 要与之比较的引用对象。
返回：: true 如果给定对象与此 SimpleDateFormat 相等
另请参见：: Object.hashCode(), Hashtable

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 5.0

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。