JavaTM Platform
Standard Ed. 6

java.text
类 SimpleDateFormat

java.lang.Object
  继承者 java.text.Format
      继承者 java.text.DateFormat
          继承者 java.text.SimpleDateFormat
所有已实现的接口:
Serializable, Cloneable

public class SimpleDateFormat
     
extends DateFormat

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

SimpleDateFormat 使得可以选择任何用户定义的日期-时间格式的模式。但是,仍然建议通过 DateFormat 中的 getTimeInstancegetDateInstancegetDateTimeInstance 来创建日期-时间格式器。每一个这样的类方法都能够返回一个以默认格式模式初始化的日期/时间格式器。可以根据需要使用 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
模式字母通常是重复的,其数量确定其精确表示: 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

同步

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

另请参见:
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 - 在解析时,两位数年份将被置于 startDatestartDate + 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 - 如果 textpos 为 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

JavaTM Platform
Standard Ed. 6

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

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策