- java.lang.Object
-
- java.time.format.DateTimeFormatter
-
public final class DateTimeFormatter extends Object
用于打印和解析日期时间对象的格式化程序。此类提供打印和解析的主要应用程序入口点,并提供
DateTimeFormatter
常见实现:- 使用预定义常量,例如
ISO_LOCAL_DATE
- 使用模式字母,例如
uuuu-MMM-dd
- 使用本地化样式,例如
long
或medium
更复杂的格式化器由
DateTimeFormatterBuilder
提供。主日期时间类提供两种方法 - 一种用于格式化,
format(DateTimeFormatter formatter)
,一种用于解析,parse(CharSequence text, DateTimeFormatter formatter)
。例如:
LocalDate date = LocalDate.now(); String text = date.format(formatter); LocalDate parsedDate = LocalDate.parse(text, formatter);
除格式外,还可以使用所需的Locale,Chronology,ZoneId和DecimalStyle创建格式化程序。
withLocale
方法返回一个覆盖语言环境的新格式化程序。 语言环境影响格式化和解析的某些方面。 例如,ofLocalizedDate
提供了使用特定于语言环境的日期格式的格式化程序。withChronology
方法返回一个覆盖年表的新格式化程序。 如果被覆盖,则在格式化之前将日期时间值转换为年表。 在解析期间,日期时间值将在返回之前转换为年表。withZone
方法返回一个覆盖该区域的新格式化程序。 如果被覆盖,则在格式化之前将日期时间值转换为带有请求的ZoneId的ZonedDateTime。 在解析期间,在返回值之前应用ZoneId。withDecimalStyle
方法返回一个覆盖DecimalStyle
的新格式化程序。 DecimalStyle符号用于格式化和解析。某些应用程序可能需要使用较旧的
java.text.Format
类进行格式化。 该toFormat()
方法返回的实现java.text.Format
。预定义的格式化程序
Predefined Formatters Formatter Description ExampleofLocalizedDate(dateStyle)
Formatter with date style from the locale '2011-12-03'ofLocalizedTime(timeStyle)
Formatter with time style from the locale '10:15:30'ofLocalizedDateTime(dateTimeStyle)
Formatter with a style for date and time from the locale '3 Jun 2008 11:05:30'ofLocalizedDateTime(dateStyle,timeStyle)
Formatter with date and time styles from the locale '3 Jun 2008 11:05'BASIC_ISO_DATE
Basic ISO date '20111203'ISO_LOCAL_DATE
ISO Local Date '2011-12-03'ISO_OFFSET_DATE
ISO Date with offset '2011-12-03+01:00'ISO_DATE
ISO Date with or without offset '2011-12-03+01:00'; '2011-12-03'ISO_LOCAL_TIME
Time without offset '10:15:30'ISO_OFFSET_TIME
Time with offset '10:15:30+01:00'ISO_TIME
Time with or without offset '10:15:30+01:00'; '10:15:30'ISO_LOCAL_DATE_TIME
ISO Local Date and Time '2011-12-03T10:15:30'ISO_OFFSET_DATE_TIME
Date Time with Offset '2011-12-03T10:15:30+01:00'ISO_ZONED_DATE_TIME
Zoned Date Time '2011-12-03T10:15:30+01:00[Europe/Paris]'ISO_DATE_TIME
Date and time with ZoneId '2011-12-03T10:15:30+01:00[Europe/Paris]'ISO_ORDINAL_DATE
Year and day of year '2012-337'ISO_WEEK_DATE
Year and Week '2012-W48-6'ISO_INSTANT
Date and Time of an Instant '2011-12-03T10:15:30Z'RFC_1123_DATE_TIME
RFC 1123 / RFC 822 'Tue, 3 Jun 2008 11:05:30 GMT'格式化和解析的模式
模式基于简单的字母和符号序列。 模式用于使用ofPattern(String)
和ofPattern(String, Locale)
方法创建Formatter。 例如,"d MMM uuuu"
将2011-12-03格式化为“2011年12月3日”。 从模式创建的格式化程序可以根据需要多次使用,它是不可变的并且是线程安全的。例如:
LocalDate date = LocalDate.now(); DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd"); String text = date.format(formatter); LocalDate parsedDate = LocalDate.parse(text, formatter);
所有字母'A'到'Z'和'a'到'z'都保留为模式字母。 定义了以下模式字母:
Pattern Letters and Symbols Symbol Meaning Presentation Examples G era text AD; Anno Domini; A u year year 2004; 04 y year-of-era year 2004; 04 D day-of-year number 189 M/L month-of-year number/text 7; 07; Jul; July; J d day-of-month number 10 g modified-julian-day number 2451334 Q/q quarter-of-year number/text 3; 03; Q3; 3rd quarter Y week-based-year year 1996; 96 w week-of-week-based-year number 27 W week-of-month number 4 E day-of-week text Tue; Tuesday; T e/c localized day-of-week number/text 2; 02; Tue; Tuesday; T F day-of-week-in-month number 3 a am-pm-of-day text PM h clock-hour-of-am-pm (1-12) number 12 K hour-of-am-pm (0-11) number 0 k clock-hour-of-day (1-24) number 24 H hour-of-day (0-23) number 0 m minute-of-hour number 30 s second-of-minute number 55 S fraction-of-second fraction 978 A milli-of-day number 1234 n nano-of-second number 987654321 N nano-of-day number 1234000000 V time-zone ID zone-id America/Los_Angeles; Z; -08:30 v generic time-zone name zone-name Pacific Time; PT z time-zone name zone-name Pacific Standard Time; PST O localized zone-offset offset-O GMT+8; GMT+08:00; UTC-08:00 X zone-offset 'Z' for zero offset-X Z; -08; -0830; -08:30; -083015; -08:30:15 x zone-offset offset-x +0000; -08; -0830; -08:30; -083015; -08:30:15 Z zone-offset offset-Z +0000; -0800; -08:00 p pad next pad modifier 1 ' escape for text delimiter '' single quote literal ' [ optional section start ] optional section end # reserved for future use { reserved for future use } reserved for future use模式字母的数量决定了格式。
文本 :文本样式根据使用的模式字母数确定。 少于4个模式字母将使用
short form
。 正好4个模式字母将使用full form
。 正好5个模式字母将使用narrow form
。 模式字母'L','c'和'q'指定文本样式的独立形式。Number :如果字母数为1,则使用最小位数输出该值,不进行填充。 否则,将使用位数作为输出字段的宽度,并根据需要将值填充为零。 以下模式字母对字母数量有约束。 只能指定一个'c'和'F'字母。 最多可以指定两个字母“d”,“H”,“h”,“K”,“k”,“m”和“s”。 最多可以指定三个字母'D'。
数字/文本 :如果模式字母的数量为3或更大,请使用上面的文本规则。 否则使用上面的数字规则。
分数 :以秒为单位输出纳秒级字段。 纳秒值具有九位数,因此模式字母的数量从1到9.如果小于9,则截断纳秒值,仅输出最高有效数字。
年份 :字母数决定了使用填充的最小字段宽度。 如果字母数为2,则使用
reduced
两位数形式。 对于打印,这将输出最右边的两位数字。 对于解析,这将使用2000的基值进行解析,从而产生2000到2099(包括2000和2099)范围内的一年。 如果字母数小于4(但不是2),则符号仅按负SignStyle.NORMAL
输出。 否则,如果超过焊盘宽度,则输出符号,如SignStyle.EXCEEDS_PAD
所示 。ZoneId :输出时区ID,例如“Europe / Paris”。 如果字母数为2,则输出时区ID。 任何其他计数的字母抛出
IllegalArgumentException
。区域名称 :输出时区ID的显示名称。 如果模式字母为“z”,则输出为夏令时感知区域名称。 如果没有足够的信息来确定是否适用DST,则将使用忽略夏令时的名称。 如果字母数为一,二或三,则输出短名称。 如果字母数为4,则输出全名。 五个或更多的字母抛出
IllegalArgumentException
。如果模式字母为“v”,则输出提供区域名称,忽略夏令时。 如果字母数为1,则输出短名称。 如果字母数为4,则输出全名。 两个,三个和五个或更多的字母抛出
IllegalArgumentException
。偏移X和x :根据模式字母的数量格式化偏移。 一个字母仅输出小时,例如'+01',除非分钟非零,在这种情况下分钟也输出,例如'+0130'。 两个字母输出小时和分钟,没有冒号,例如'+0130'。 三个字母输出小时和分钟,带有冒号,例如'+01:30'。 四个字母输出小时和分钟以及可选秒,没有冒号,例如'+013015'。 五个字母输出小时和分钟,可选秒输出冒号,例如'+01:30:15'。 六个或更多的字母抛出
IllegalArgumentException
。 当要输出的偏移量为零时,模式字母“X”(大写)将输出“Z”,而模式字母“x”(小写)将输出“+00”,“+ 0000”或“+00” :00' 。偏移O :根据模式字母的数量格式化局部偏移。 一个字母输出short形式的局部偏移,它是局部偏移文本,例如'GMT',小时不带前导零,可选2位数分钟,第二个非零,和冒号,例如'GMT + 8 ”。 四个字母输出full表格,它是本地化的偏移文本,例如'GMT,具有2位小时和分钟字段,可选的第二字段(如果非零)和冒号,例如'GMT + 08:00'。 任何其他计数的字母抛出
IllegalArgumentException
。偏移Z :根据模式字母的数量格式化偏移。 一个,两个或三个字母输出小时和分钟,没有冒号,例如'+0130'。 当偏移量为零时,输出将为“+0000”。 四个字母输出full形式的局部偏移,相当于Offset-O的四个字母。 如果偏移为零,则输出将是相应的本地化偏移文本。 五个字母输出小时,分钟,可选第二个,如果非零,则使用冒号。 如果偏移量为零,则输出“Z”。 六个或更多的字母抛出
IllegalArgumentException
。可选部分 :可选部分标记的工作方式与调用
DateTimeFormatterBuilder.optionalStart()
和DateTimeFormatterBuilder.optionalEnd()
完全相同 。填充修饰符 :修改紧跟其后用空格填充的模式。 垫宽度由图案字母的数量决定。 这与致电
DateTimeFormatterBuilder.padNext(int)
相同。例如,'ppH'输出左边填充的小时,空格宽度为2。
任何无法识别的字母都是错误的。 任何非字母字符,除了'[',']','{','}','#'和单引号都将直接输出。 尽管如此,建议在要直接输出的所有字符周围使用单引号,以确保将来的更改不会破坏您的应用程序。
解决
解析实现为两阶段操作。 首先,使用格式化程序定义的布局解析文本,生成Map
字段值,ZoneId
和Chronology
。 其次,分析的数据解析 ,通过验证,合并和简化了各领域到更多有用的。这个类提供了五种解析方法。 其中四个执行解析和解析阶段。 第五种方法
parseUnresolved(CharSequence, ParsePosition)
仅执行第一阶段,结果未解析。 因此,它本质上是一种低级操作。解析阶段由在此类上设置的两个参数控制。
ResolverStyle
是一个枚举,提供三种不同的方法,严格,智能和宽松。 智能选项是默认选项。 可以使用withResolverStyle(ResolverStyle)
进行设置。withResolverFields(TemporalField...)
参数允许在解析启动之前过滤要解析的字段集。 例如,如果格式化程序已经解析了年,月,日,年和日,则有两种方法可以解决日期:(年+月+日)和(年+天的年)。 解析器字段允许选择两种方法中的一种。 如果未设置解析器字段,则两种方法必须生成相同的日期。解析单独的字段以形成完整的日期和时间是一个复杂的过程,其行为分布在许多类中。 它遵循以下步骤:
- 年表确定。 结果的年表是要解析的年表,或者如果没有解析年表,则是在此类上设置的年表,或者如果为空,则为
IsoChronology
。 -
ChronoField
日期字段已解决。 这是使用Chronology.resolveDate(Map, ResolverStyle)
实现的。 有关字段解析的文档位于Chronology
的实现中。 -
ChronoField
时间字段已解决。 这记录在ChronoField
上,并且对于所有年表都是相同的。 - 处理不是
ChronoField
任何字段。 这是使用TemporalField.resolve(Map, TemporalAccessor, ResolverStyle)
实现的。 有关字段解析的文档位于TemporalField
的实现中。 - 将重新解析
ChronoField
日期和时间字段。 这允许第四步中的字段生成ChronoField
值,并将它们处理为日期和时间。 - 如果至少有一个小时的可用时间,则形成
LocalTime
。 这涉及提供分钟,秒和小数秒的默认值。 - 任何剩余的未解析字段将根据已解决的任何日期和/或时间进行交叉检查。 因此,较早阶段将解决(年+月+日)到某个日期,此阶段将检查该星期几对该日期是否有效。
- 如果解析了excess number of days ,则在日期可用时将其添加到日期。
- 如果存在基于秒的字段,但未解析
LocalTime
,则解析器确保可以使用毫秒,微秒和纳秒值来满足ChronoField
的合同。 如果遗漏,这些将被设置为零。 - 如果同时解析了日期和时间并且存在偏移或区域,则会创建字段
ChronoField.INSTANT_SECONDS
。 如果解析了偏移量,则偏移量将与LocalDateTime
组合以形成瞬间,忽略任何区域。 如果ZoneId
在没有偏移,则区分析将与合并LocalDateTime
形成使用规则的即时ChronoLocalDateTime.atZone(ZoneId)
。
- 实现要求:
- 这个类是不可变的和线程安全的。
- 从以下版本开始:
- 1.8
- 使用预定义常量,例如
-
-
字段汇总
字段 变量和类型 字段 描述 static DateTimeFormatter
BASIC_ISO_DATE
ISO日期格式化程序,用于格式化或解析没有偏移的日期,例如“20111203”。static DateTimeFormatter
ISO_DATE
ISO日期格式化程序,使用偏移量格式化或解析日期(如“2011-12-03”或“2011-12-03 + 01:00”)。static DateTimeFormatter
ISO_DATE_TIME
类似ISO的日期时格式化程序,使用偏移量和区域(如果可用)格式化或解析日期时间,例如“2011-12-03T10:15:30”,“2011-12-03T10:15:30 + 01 :00'或'2011-12-03T10:15:30 + 01:00 [欧洲/巴黎]'。static DateTimeFormatter
ISO_INSTANT
ISO即时格式化程序,用于格式化或解析UTC中的瞬间,例如“2011-12-03T10:15:30Z”。static DateTimeFormatter
ISO_LOCAL_DATE
ISO日期格式化程序,用于格式化或解析没有偏移的日期,例如“2011-12-03”。static DateTimeFormatter
ISO_LOCAL_DATE_TIME
ISO日期时格式化程序,用于格式化或解析没有偏移的日期时间,例如“2011-12-03T10:15:30”。static DateTimeFormatter
ISO_LOCAL_TIME
ISO时间格式化程序,用于格式化或解析没有偏移的时间,例如“10:15”或“10:15:30”。static DateTimeFormatter
ISO_OFFSET_DATE
ISO日期格式化程序,用于格式化或解析具有偏移量的日期,例如“2011-12-03 + 01:00”。static DateTimeFormatter
ISO_OFFSET_DATE_TIME
ISO日期时格格式器,用于格式化或解析具有偏移的日期时间,例如“2011-12-03T10:15:30 + 01:00”。static DateTimeFormatter
ISO_OFFSET_TIME
ISO时间格式化程序,使用偏移格式化或解析时间,例如'10:15 + 01:00'或'10:15:30 + 01:00'。static DateTimeFormatter
ISO_ORDINAL_DATE
ISO日期格式化程序,用于格式化或解析没有偏移的序数日期,例如“2012-337”。static DateTimeFormatter
ISO_TIME
ISO时间格式化程序,用于格式化或解析时间,如果可用,则为偏移量,例如“10:15”,“10:15:30”或“10:15:30 + 01:00”。static DateTimeFormatter
ISO_WEEK_DATE
ISO日期格式化程序,用于格式化或解析没有偏移的基于周的日期,例如“2012-W48-6”。static DateTimeFormatter
ISO_ZONED_DATE_TIME
类似ISO的日期时格格式器,用于格式化或解析具有偏移和区域的日期时间,例如“2011-12-03T10:15:30 + 01:00 [欧洲/巴黎]”。static DateTimeFormatter
RFC_1123_DATE_TIME
RFC-1123日期时间格式化程序,例如'Tue,2008年6月3日11:05:30 GMT'。
-
方法摘要
所有方法 静态方法 实例方法 具体的方法 变量和类型 方法 描述 String
format(TemporalAccessor temporal)
使用此格式化程序格式化日期时间对象。void
formatTo(TemporalAccessor temporal, Appendable appendable)
使用此格式化程序将日期时间对象格式化为Appendable
。Chronology
getChronology()
获取格式化期间要使用的重写年代表。DecimalStyle
getDecimalStyle()
获取格式化期间要使用的DecimalStyle。Locale
getLocale()
获取格式化期间要使用的语言环境。Set<TemporalField>
getResolverFields()
获取解析期间要使用的解析器字段。ResolverStyle
getResolverStyle()
获取解析期间要使用的解析器样式。ZoneId
getZone()
获取格式化期间要使用的覆盖区域。DateTimeFormatter
localizedBy(Locale locale)
返回此格式化程序的副本,其中包含区域设置,日历,区域,小数样式和/或时区的本地化值,它们取代此格式化程序中的值。static DateTimeFormatter
ofLocalizedDate(FormatStyle dateStyle)
返回ISO年表的特定于语言环境的日期格式。static DateTimeFormatter
ofLocalizedDateTime(FormatStyle dateTimeStyle)
返回ISO年表的特定于语言环境的日期时间格式化程序。static DateTimeFormatter
ofLocalizedDateTime(FormatStyle dateStyle, FormatStyle timeStyle)
返回ISO年表的特定于语言环境的日期和时间格式。static DateTimeFormatter
ofLocalizedTime(FormatStyle timeStyle)
返回ISO年表的特定于语言环境的时间格式。static DateTimeFormatter
ofPattern(String pattern)
使用指定的模式创建格式化程序。static DateTimeFormatter
ofPattern(String pattern, Locale locale)
使用指定的模式和语言环境创建格式化程序。TemporalAccessor
parse(CharSequence text)
完全解析生成临时对象的文本。TemporalAccessor
parse(CharSequence text, ParsePosition position)
使用此格式化程序解析文本,提供对文本位置的控制。<T> T
parse(CharSequence text, TemporalQuery<T> query)
完全解析生成指定类型对象的文本。TemporalAccessor
parseBest(CharSequence text, TemporalQuery<?>... queries)
完全解析生成指定类型之一的对象的文本。static TemporalQuery<Period>
parsedExcessDays()
一个查询,提供对已解析的超出天数的访问权限。static TemporalQuery<Boolean>
parsedLeapSecond()
提供对是否解析闰秒的访问的查询。TemporalAccessor
parseUnresolved(CharSequence text, ParsePosition position)
使用此格式化程序解析文本,而不解析结果,用于高级用例。Format
toFormat()
将此格式化程序作为java.text.Format
实例返回。Format
toFormat(TemporalQuery<?> parseQuery)
将此格式化程序作为将使用指定查询进行分析的java.text.Format
实例返回。String
toString()
返回底层格式化程序的描述。DateTimeFormatter
withChronology(Chronology chrono)
返回此格式化程序的副本,其中包含新的覆盖时间顺序。DateTimeFormatter
withDecimalStyle(DecimalStyle decimalStyle)
使用新的DecimalStyle返回此formatter的副本。DateTimeFormatter
withLocale(Locale locale)
返回具有新语言环境的此formatter的副本。DateTimeFormatter
withResolverFields(TemporalField... resolverFields)
返回此格式化程序的副本,其中包含一组新的解析程序字段。DateTimeFormatter
withResolverFields(Set<TemporalField> resolverFields)
返回此格式化程序的副本,其中包含一组新的解析程序字段。DateTimeFormatter
withResolverStyle(ResolverStyle resolverStyle)
使用新的解析程序样式返回此formatter的副本。DateTimeFormatter
withZone(ZoneId zone)
使用新的覆盖区域返回此格式化程序的副本。
-
-
-
字段详细信息
-
ISO_LOCAL_DATE
public static final DateTimeFormatter ISO_LOCAL_DATE
ISO日期格式化程序,用于格式化或解析没有偏移的日期,例如“2011-12-03”。这将返回一个不可变格式化程序,它能够格式化和解析ISO-8601扩展本地日期格式。 格式包括:
-
year
的四位数或更多位数。 0000到9999范围内的年份将预先填充为零,以确保四位数。 超出该范围的年份将具有带前缀的正面或负面符号。 - 破折号
- 两位数为
month-of-year
。 这是预先填充零以确保两位数。 - 破折号
-
day-of-month
的两位数字。 这是预先填充零以确保两位数。
返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
STRICT
解析器样式。 -
-
ISO_OFFSET_DATE
public static final DateTimeFormatter ISO_OFFSET_DATE
ISO日期格式化程序,用于格式化或解析具有偏移量的日期,例如“2011-12-03 + 01:00”。这将返回一个不可变格式化程序,它能够格式化和解析ISO-8601扩展偏移日期格式。 格式包括:
-
ISO_LOCAL_DATE
-
offset ID
。 如果偏移量为秒,则即使这不是ISO-8601标准的一部分,也会处理它们。 解析不区分大小写。
返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
STRICT
解析器样式。 -
-
ISO_DATE
public static final DateTimeFormatter ISO_DATE
ISO日期格式化程序,使用偏移量格式化或解析日期(如“2011-12-03”或“2011-12-03 + 01:00”)。这将返回一个能够格式化和解析ISO-8601扩展日期格式的不可变格式化程序。 格式包括:
-
ISO_LOCAL_DATE
- 如果偏移量不可用,则格式完成。
-
offset ID
。 如果偏移量为秒,则即使这不是ISO-8601标准的一部分,也会处理它们。 解析不区分大小写。
由于此格式化程序具有可选元素,因此可能需要使用
parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)
进行解析。返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
STRICT
解析器样式。 -
-
ISO_LOCAL_TIME
public static final DateTimeFormatter ISO_LOCAL_TIME
ISO时间格式化程序,用于格式化或解析没有偏移的时间,例如“10:15”或“10:15:30”。这将返回一个不可变格式化程序,它能够格式化和解析ISO-8601扩展本地时间格式。 格式包括:
- 两位数为
hour-of-day
。 这是预先填充零以确保两位数。 - 结肠
- 两位数为
minute-of-hour
。 这是预先填充零以确保两位数。 - 如果第二分钟不可用,则格式完成。
- 结肠
- 两位数为
second-of-minute
。 这是预先填充零以确保两位数。 - 如果纳秒为零或不可用,则格式完成。
- 小数点
-
nano-of-second
的一到九位数字。 根据需要输出许多数字。
返回的格式化程序没有覆盖年表或区域。 它使用了
STRICT
解析器样式。 - 两位数为
-
ISO_OFFSET_TIME
public static final DateTimeFormatter ISO_OFFSET_TIME
ISO时间格式化程序,使用偏移格式化或解析时间,例如'10:15 + 01:00'或'10:15:30 + 01:00'。这将返回一个不可变格式化程序,能够格式化和解析ISO-8601扩展偏移时间格式。 格式包括:
-
ISO_LOCAL_TIME
-
offset ID
。 如果偏移量为秒,则即使这不是ISO-8601标准的一部分,也会处理它们。 解析不区分大小写。
返回的格式化程序没有覆盖年表或区域。 它使用
STRICT
解析器样式。 -
-
ISO_TIME
public static final DateTimeFormatter ISO_TIME
ISO时间格式化程序,用于格式化或解析时间,如果可用,则为偏移量,例如“10:15”,“10:15:30”或“10:15:30 + 01:00”。这将返回一个不可变格式化程序,能够格式化和解析ISO-8601扩展偏移时间格式。 格式包括:
-
ISO_LOCAL_TIME
- 如果偏移量不可用,则格式完成。
-
offset ID
。 如果偏移量为秒,则即使这不是ISO-8601标准的一部分,也会处理它们。 解析不区分大小写。
由于此格式化程序具有可选元素,因此可能需要使用
parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)
进行解析。返回的格式化程序没有覆盖年表或区域。 它使用
STRICT
解析器样式。 -
-
ISO_LOCAL_DATE_TIME
public static final DateTimeFormatter ISO_LOCAL_DATE_TIME
ISO日期时格式化程序,用于格式化或解析没有偏移的日期时间,例如“2011-12-03T10:15:30”。这将返回一个不可变格式化程序,它能够格式化和解析ISO-8601扩展偏移日期时间格式。 格式包括:
-
ISO_LOCAL_DATE
- 字母'T'。 解析不区分大小写。
-
ISO_LOCAL_TIME
返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
STRICT
解析器样式。 -
-
ISO_OFFSET_DATE_TIME
public static final DateTimeFormatter ISO_OFFSET_DATE_TIME
ISO日期时格格式器,用于格式化或解析具有偏移的日期时间,例如“2011-12-03T10:15:30 + 01:00”。这将返回一个不可变格式化程序,它能够格式化和解析ISO-8601扩展偏移日期时间格式。 格式包括:
-
ISO_LOCAL_DATE_TIME
-
offset ID
。 如果偏移量为秒,则即使这不是ISO-8601标准的一部分,也会处理它们。 偏移解析是宽松的,这允许分钟和秒是可选的。 解析不区分大小写。
返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
STRICT
解析器样式。 -
-
ISO_ZONED_DATE_TIME
public static final DateTimeFormatter ISO_ZONED_DATE_TIME
类似ISO的日期时格格式器,用于格式化或解析具有偏移和区域的日期时间,例如“2011-12-03T10:15:30 + 01:00 [欧洲/巴黎]”。这将返回一个不可变格式化程序,它能够格式化和解析扩展ISO-8601扩展偏移日期时间格式的格式以添加时区。 方括号中的部分不是ISO-8601标准的一部分。 格式包括:
-
ISO_OFFSET_DATE_TIME
- 如果区域ID不可用或者是
ZoneOffset
则格式完成。 - 一个开放的方括号'['。
-
zone ID
。 这不是ISO-8601标准的一部分。 解析区分大小写。 - 一个紧密的方括号']'。
返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
STRICT
解析器样式。 -
-
ISO_DATE_TIME
public static final DateTimeFormatter ISO_DATE_TIME
类似ISO的日期时格式化程序,使用偏移量和区域(如果可用)格式化或解析日期时间,例如“2011-12-03T10:15:30”,“2011-12-03T10:15:30 + 01 :00'或'2011-12-03T10:15:30 + 01:00 [欧洲/巴黎]'。这将返回一个不可变格式化程序,它能够格式化和解析ISO-8601扩展本地或偏移日期时间格式,以及指定时区的扩展非ISO格式。 格式包括:
-
ISO_LOCAL_DATE_TIME
- 如果无法格式化或解析偏移量,则格式完成。
-
offset ID
。 如果偏移量为秒,则即使这不是ISO-8601标准的一部分,也会处理它们。 - 如果区域ID不可用或者是
ZoneOffset
则格式完成。 - 一个开放的方括号'['。
-
zone ID
。 这不是ISO-8601标准的一部分。 解析区分大小写。 - 一个紧密的方括号']'。
由于此格式化程序具有可选元素,因此可能需要使用
parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)
进行解析。返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
STRICT
解析器样式。 -
-
ISO_ORDINAL_DATE
public static final DateTimeFormatter ISO_ORDINAL_DATE
ISO日期格式化程序,用于格式化或解析没有偏移的序数日期,例如“2012-337”。这将返回一个不可变格式化程序,它能够格式化和解析ISO-8601扩展序数日期格式。 格式包括:
-
year
的四位数或更多位数。 0000到9999范围内的年份将预先填充为零,以确保四位数。 超出该范围的年份将具有带前缀的正面或负面符号。 - 破折号
-
day-of-year
的三位数字。 这是预先填充零以确保三位数。 - 如果无法格式化或解析偏移量,则格式完成。
-
offset ID
。 如果偏移量为秒,则即使这不是ISO-8601标准的一部分,也会处理它们。 解析不区分大小写。
由于此格式化程序具有可选元素,因此可能需要使用
parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)
进行解析。返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
STRICT
解析器样式。 -
-
ISO_WEEK_DATE
public static final DateTimeFormatter ISO_WEEK_DATE
ISO日期格式化程序,用于格式化或解析没有偏移的基于周的日期,例如“2012-W48-6”。这将返回一个不可变的格式化程序,它能够格式化和解析ISO-8601扩展的基于周的日期格式。 格式包括:
-
week-based-year
的四位数或更多位数。 0000到9999范围内的年份将预先填充为零,以确保四位数。 超出该范围的年份将具有带前缀的正面或负面符号。 - 破折号
- 字母'W'。 解析不区分大小写。
- 两位数为
week-of-week-based-year
。 这是预先填充零以确保三位数。 - 破折号
-
day-of-week
的一位数字。 该值从星期一(1)到星期日(7)。 - 如果无法格式化或解析偏移量,则格式完成。
-
offset ID
。 如果偏移量为秒,则即使这不是ISO-8601标准的一部分,也会处理它们。 解析不区分大小写。
由于此格式化程序具有可选元素,因此可能需要使用
parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)
进行解析。返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
STRICT
解析器样式。 -
-
ISO_INSTANT
public static final DateTimeFormatter ISO_INSTANT
ISO即时格式化程序,用于格式化或解析UTC中的瞬间,例如“2011-12-03T10:15:30Z”。这将返回一个能够格式化和解析ISO-8601即时格式的不可变格式化程序。 格式化时,始终输出秒的分钟。 毫秒秒根据需要输出零,三,六或九位数。 解析时,至少需要秒时间字段。 解析从零到九的小数秒。 未使用本地化的十进制样式。
这是一种特殊情况格式化程序,旨在允许
Instant
的人类可读形式。Instant
类仅用于表示某个时间点,并在内部存储一个以纳秒为单位的值,该值为1970-01-01Z的固定时期。 因此,如果没有提供某种形式的时区,则无法将Instant
格式化为日期或时间。 此格式化允许Instant
到通过提供一种使用合适的转化被格式化,ZoneOffset.UTC
。格式包括:
-
ISO_OFFSET_DATE_TIME
其中,即时转换为ChronoField.INSTANT_SECONDS
和ChronoField.NANO_OF_SECOND
,使用UTC
偏移量。 解析不区分大小写。
返回的格式化程序没有覆盖年表或区域。 它使用
STRICT
解析器样式。 -
-
BASIC_ISO_DATE
public static final DateTimeFormatter BASIC_ISO_DATE
ISO日期格式化程序,用于格式化或解析没有偏移的日期,例如“20111203”。这将返回一个不可变格式化程序,它能够格式化和解析ISO-8601基本本地日期格式。 格式包括:
- 四位数为
year
。 仅支持0000至9999范围内的年份。 - 两位数为
month-of-year
。 这是预先填充零以确保两位数。 - 两位数为
day-of-month
。 这是预先填充零以确保两位数。 - 如果无法格式化或解析偏移量,则格式完成。
-
offset ID
没有冒号。 如果偏移量为秒,则即使这不是ISO-8601标准的一部分,也会处理它们。 偏移解析是宽松的,这允许分钟和秒是可选的。 解析不区分大小写。
由于此格式化程序具有可选元素,因此可能需要使用
parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)
进行解析。返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
STRICT
解析器样式。 - 四位数为
-
RFC_1123_DATE_TIME
public static final DateTimeFormatter RFC_1123_DATE_TIME
RFC-1123日期时间格式化程序,例如'Tue,2008年6月3日11:05:30 GMT'。这将返回一个不可变的格式化程序,能够格式化和解析大多数RFC-1123格式。 RFC-1123更新RFC-822将年份从两位数改为四位。 此实施需要四位数年份。 此实施也不处理北美或军区名称,仅处理'GMT'和抵消金额。
格式包括:
- 如果星期几无法格式化或解析,则跳转到日期。
- 三个字母
day-of-week
英文。 - 一个逗号
- 空间
-
day-of-month
的一位或两位数字。 - 空间
- 三个字母
month-of-year
英文。 - 空间
- 四位数为
year
。 仅支持0000至9999范围内的年份。 - 空间
- 两位数为
hour-of-day
。 这是预先填充零以确保两位数。 - 结肠
- 两位数为
minute-of-hour
。 这是预先填充零以确保两位数。 - 如果第二分钟不可用,则跳转到下一个空格。
- 结肠
- 两位数为
second-of-minute
。 这是预先填充零以确保两位数。 - 空间
-
offset ID
没有冒号或秒。 零偏移使用“GMT”。 不处理北美地区名称和军事区域名称。
解析不区分大小写。
返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
SMART
解析器样式。
-
-
方法详细信息
-
ofPattern
public static DateTimeFormatter ofPattern(String pattern)
使用指定的模式创建格式化程序。此方法将基于类文档中描述的简单pattern of letters and symbols创建格式化程序。 例如,
d MMM uuuu
将2011-12-03格式化为“2011年12月3日”。格式化程序将使用
default FORMAT locale
。 这可以使用返回的格式化程序上的withLocale(Locale)
进行更改。 或者,使用此方法的ofPattern(String, Locale)
变体。返回的格式化程序没有覆盖年表或区域。 它使用
SMART
旋转变压器样式。- 参数
-
pattern
- 要使用的模式,而不是null - 结果
- 基于模式的格式化程序,不是null
- 异常
-
IllegalArgumentException
- 如果模式无效 - 另请参见:
-
DateTimeFormatterBuilder.appendPattern(String)
-
ofPattern
public static DateTimeFormatter ofPattern(String pattern, Locale locale)
使用指定的模式和语言环境创建格式化程序。此方法将基于类文档中描述的简单pattern of letters and symbols创建格式化程序。 例如,
d MMM uuuu
将2011-12-03格式化为“2011年12月3日”。格式化程序将使用指定的语言环境。 这可以使用返回的格式化程序上的
withLocale(Locale)
进行更改。返回的格式化程序没有覆盖年表或区域。 它使用
SMART
解析器样式。- 参数
-
pattern
- 要使用的模式,而不是null -
locale
- 要使用的语言环境,而不是null - 结果
- 基于模式的格式化程序,不是null
- 异常
-
IllegalArgumentException
- 如果模式无效 - 另请参见:
-
DateTimeFormatterBuilder.appendPattern(String)
-
ofLocalizedDate
public static DateTimeFormatter ofLocalizedDate(FormatStyle dateStyle)
返回ISO年表的特定于语言环境的日期格式。这将返回格式化程序,该格式化程序将格式化或解析日期。 使用的确切格式模式因区域设置而异。
语言环境由格式化程序确定。 通过此方法直接返回的格式化程序将使用
default FORMAT locale
。 可以使用withLocale(Locale)
在此方法的结果上控制区域设置。请注意,本地化模式是懒惰地查找的。 此
DateTimeFormatter
包含所需的样式和区域设置,查找所需的模式。返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
SMART
解析器样式。- 参数
-
dateStyle
- 要获取的格式化程序样式,而不是null - 结果
- 日期格式化程序,不是null
-
ofLocalizedTime
public static DateTimeFormatter ofLocalizedTime(FormatStyle timeStyle)
返回ISO年表的特定于语言环境的时间格式。这将返回格式化程序,该格式化程序将格式化或解析时间。 使用的确切格式模式因区域设置而异。
语言环境由格式化程序确定。 直接通过此方法返回的格式化程序将使用
default FORMAT locale
。 可以使用withLocale(Locale)
对此方法的结果控制区域设置。请注意,本地化模式是懒惰地查找的。 这个
DateTimeFormatter
拥有所需的样式和区域设置,查找所需的模式。返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
SMART
解析器样式。FULL
和LONG
样式通常需要时区。 当使用这些风格格式化,一ZoneId
必须是可用的,无论是使用ZonedDateTime
或withZone(java.time.ZoneId)
。- 参数
-
timeStyle
- 要获取的格式化程序样式,而不是null - 结果
- 时间格式化程序,不是null
-
ofLocalizedDateTime
public static DateTimeFormatter ofLocalizedDateTime(FormatStyle dateTimeStyle)
返回ISO年表的特定于语言环境的日期时间格式化程序。这将返回格式化程序,该格式化程序将格式化或解析日期时间。 使用的确切格式模式因区域设置而异。
语言环境由格式化程序确定。 通过此方法直接返回的格式化程序将使用
default FORMAT locale
。 可以使用withLocale(Locale)
在此方法的结果上控制区域设置。请注意,本地化模式是懒惰地查找的。 此
DateTimeFormatter
包含所需的样式和区域设置,查找所需的模式。返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
SMART
解析器样式。FULL
和LONG
样式通常需要时区。 当使用这些风格格式化,一ZoneId
必须是可用的,无论是使用ZonedDateTime
或withZone(java.time.ZoneId)
。- 参数
-
dateTimeStyle
- 要获取的格式化程序样式,而不是null - 结果
- 日期时格格式器,不是null
-
ofLocalizedDateTime
public static DateTimeFormatter ofLocalizedDateTime(FormatStyle dateStyle, FormatStyle timeStyle)
返回ISO年表的特定于语言环境的日期和时间格式。这将返回格式化程序,该格式化程序将格式化或解析日期时间。 使用的确切格式模式因区域设置而异。
语言环境由格式化程序确定。 通过此方法直接返回的格式化程序将使用
default FORMAT locale
。 可以使用此方法的结果使用withLocale(Locale)
控制区域设置。请注意,本地化模式是懒惰地查找的。 此
DateTimeFormatter
包含所需的样式和区域设置,查找所需的模式。返回的格式化程序具有ISO设置的年表,以确保正确转换其他日历系统中的日期。 它没有覆盖区域并使用
SMART
解析器样式。FULL
和LONG
样式通常需要时区。 当使用这些风格格式化,一ZoneId
必须是可用的,无论是使用ZonedDateTime
或withZone(java.time.ZoneId)
。- 参数
-
dateStyle
- 要获取的日期格式化程序样式,而不是null -
timeStyle
- 要获取的时间格式器样式,而不是null - 结果
- 日期,时间或日期时间格式化程序,不为空
-
parsedExcessDays
public static final TemporalQuery<Period> parsedExcessDays()
一个查询,提供对已解析的超出天数的访问权限。这将返回单例query ,该单元提供对解析中的其他信息的访问。 查询始终返回非null周期,返回零周期而不是null。
有两种情况,此查询可能返回非零周期。
- 如果
ResolverStyle
是LENIENT
并且解析时间没有日期,那么解析的完整结果包括LocalTime
和超过Period
天。 - 如果
ResolverStyle
是SMART
并且解析时间没有时间为24:00:00的日期,那么解析的完整结果包括LocalTime
的00:00:00和超过Period
的一天。
在这两种情况下,如果解析完整的
ChronoLocalDateTime
或Instant
,则将多余的天数添加到日期部分。 因此,此查询将返回零周期。SMART
行为处理常见的“一天结束”24:00值。LENIENT
模式下的处理也会产生相同的结果:Text to parse Parsed object Excess days "2012-12-03T00:00" LocalDateTime.of(2012, 12, 3, 0, 0) ZERO "2012-12-03T24:00" LocalDateTime.of(2012, 12, 4, 0, 0) ZERO "00:00" LocalTime.of(0, 0) ZERO "24:00" LocalTime.of(0, 0) Period.ofDays(1)
查询可以使用如下:TemporalAccessor parsed = formatter.parse(str); LocalTime time = parsed.query(LocalTime::from); Period extraDays = parsed.query(DateTimeFormatter.parsedExcessDays());
- 结果
- 一个查询,提供对已解析的超出天数的访问权限
- 如果
-
parsedLeapSecond
public static final TemporalQuery<Boolean> parsedLeapSecond()
提供对是否解析闰秒的访问的查询。这将返回一个单例query ,它可以从解析中访问其他信息。 查询始终返回非null布尔值,如果解析看到闰秒,则返回true,否则返回false。
即时解析处理'23:59:60'的特殊“闰秒”时间。 闰秒发生在UTC时区的“23:59:60”,但是在不同时区的其他本地时间。 为避免这种潜在的歧义,闰秒的处理仅限于
DateTimeFormatterBuilder.appendInstant()
,因为该方法始终使用UTC区域偏移量解析瞬间。如果收到时间'23:59:60',则应用简单转换,用59替换60分钟的第二分钟。可以在解析结果上使用此查询来确定闰秒调整是否为制作。 该查询将返回
true
,如果它没有调整去除闰秒,而false
如果不是。 请注意,应用闰秒平滑机制(如UTC-SLS)是应用程序的责任,如下所示:TemporalAccessor parsed = formatter.parse(str); Instant instant = parsed.query(Instant::from); if (parsed.query(DateTimeFormatter.parsedLeapSecond())) { // validate leap-second is correct and apply correct smoothing }
- 结果
- 一个查询,提供对是否解析闰秒的访问权限
-
getLocale
public Locale getLocale()
获取格式化期间要使用的语言环境。这用于查找需要特定本地化的格式化程序的任何部分,例如文本或本地化模式。
- 结果
- 此格式化程序的语言环境,不为null
-
withLocale
public DateTimeFormatter withLocale(Locale locale)
返回具有新语言环境的此formatter的副本。这用于查找需要特定本地化的格式化程序的任何部分,例如文本或本地化模式。
语言环境存储为传入,无需进一步处理。 如果语言环境具有Unicode extensions ,则稍后可以在文本处理中使用它们。 要从unicode扩展设置年表,时区和小数形式,请参阅
localizedBy()
。此实例是不可变的,不受此方法调用的影响。
- 参数
-
locale
- 新的语言环境,不为null - 结果
- 基于此格式化程序的格式化程序,具有请求的语言环境,而不是null
- 另请参见:
-
localizedBy(Locale)
-
localizedBy
public DateTimeFormatter localizedBy(Locale locale)
返回此格式化程序的副本,其中包含区域设置,日历,区域,小数样式和/或时区的本地化值,它们取代此格式化程序中的值。这用于查找需要特定本地化的格式化程序的任何部分,例如文本或本地化模式。 如果区域设置包含“ca”(日历),“nu”(编号系统),“rg”(区域覆盖)和/或“tz”(时区) Unicode extensions ,则年表,编号系统和/或区域为覆盖。 如果同时指定了“ca”和“rg”,则来自“ca”扩展名的时间顺序将取代“rg”扩展名中的隐式值。 “nu”扩展也是如此。
与
withLocale
方法不同, 对此方法的调用可能会产生不同的格式化程序,具体取决于与其他withXXXX()方法链接的方法的顺序。此实例是不可变的,不受此方法调用的影响。
- 参数
-
locale
- 语言环境,不为null - 结果
- 基于此格式化程序的格式化程序,具有日历,小数形式和/或时区的本地化值,取代此格式化程序中的值。
- 从以下版本开始:
- 10
- 另请参见:
-
withLocale(Locale)
-
getDecimalStyle
public DecimalStyle getDecimalStyle()
获取格式化期间要使用的DecimalStyle。- 结果
- 此格式化程序的语言环境,不为null
-
withDecimalStyle
public DateTimeFormatter withDecimalStyle(DecimalStyle decimalStyle)
使用新的DecimalStyle返回此formatter的副本。此实例是不可变的,不受此方法调用的影响。
- 参数
-
decimalStyle
- 新的DecimalStyle,不为null - 结果
- 基于此格式化程序的格式化程序,具有请求的DecimalStyle,而不是null
-
getChronology
public Chronology getChronology()
获取格式化期间要使用的重写年代表。这将返回覆盖年表,用于转换日期。 默认情况下,格式化程序没有覆盖时间顺序,返回null。 有关覆盖的更多详细信息,请参见
withChronology(Chronology)
。- 结果
- 此格式化程序的重写时间顺序,如果没有重写,则返回null
-
withChronology
public DateTimeFormatter withChronology(Chronology chrono)
返回此格式化程序的副本,其中包含新的覆盖时间顺序。这将返回一个格式化程序,该格式化程序具有与此格式化程序类似的状态,但设置了覆盖时间顺 默认情况下,格式化程序没有覆盖时间顺序,返回null。
如果添加了覆盖,则格式化或解析的任何日期都将受到影响。
格式化时,如果时态对象包含日期,则它将转换为覆盖年表中的日期。 是否包含日期是通过查询
EPOCH_DAY
字段来确定的。 除非被覆盖,否则任何时间或区域都将保持不变。如果临时对象不包含日期,但包含一个或多个
ChronoField
日期字段,则抛出DateTimeException
。 在所有其他情况下,覆盖年表被添加到时间,替换任何先前的年表,但不更改日期/时间。解析时,需要考虑两种不同的情况。 如果直接从文本中解析了年表,可能是因为使用了
DateTimeFormatterBuilder.appendChronologyId()
,那么这个覆盖年表没有任何效果。 如果未解析任何区域,则将使用此覆盖年表按照年表的日期解析规则将ChronoField
值解释为日期。此实例是不可变的,不受此方法调用的影响。
- 参数
-
chrono
- 新的年表,如果没有覆盖则为null - 结果
- 基于此格式化程序的格式化程序,具有请求的覆盖时间顺序,而不是null
-
getZone
public ZoneId getZone()
获取格式化期间要使用的覆盖区域。这将返回覆盖区域,用于转换瞬间。 默认情况下,格式化程序没有覆盖区域,返回null。 有关覆盖的更多详细信息,请参见
withZone(ZoneId)
。- 结果
- 此格式化程序的覆盖区域,如果没有覆盖,则返回null
-
withZone
public DateTimeFormatter withZone(ZoneId zone)
使用新的覆盖区域返回此格式化程序的副本。这将返回一个格式化程序,其状态与此格式化程序类似,但设置了覆盖区域。 默认情况下,格式化程序没有覆盖区域,返回null。
如果添加了覆盖,则任何格式化或解析的瞬间都将受到影响。
格式化时,如果临时对象包含瞬间,则使用覆盖区域将其转换为分区日期时间。 是否瞬时是通过查询
INSTANT_SECONDS
字段来确定的。 如果输入具有时间顺序,那么除非被覆盖,否则它将被保留。 如果输入没有年表,例如Instant
,那么将使用ISO年表。如果临时对象不包含瞬间,但确实包含偏移量,则进行额外检查。 如果规范化的覆盖区域是与时间偏移不同的偏移,则抛出
DateTimeException
。 在所有其他情况下,覆盖区域将添加到时间,替换任何以前的区域,但不更改日期/时间。解析时,需要考虑两种不同的情况。 如果区域已直接从文本中解析,可能是因为使用了
DateTimeFormatterBuilder.appendZoneId()
,则此覆盖区域无效。 如果没有解析区域,则此覆盖区域将包含在解析结果中,可用于构建时刻和日期时间。此实例是不可变的,不受此方法调用的影响。
- 参数
-
zone
- 新的覆盖区域,如果没有覆盖,则为null - 结果
- 基于此格式化程序的格式化程序,具有请求的覆盖区域,而不是null
-
getResolverStyle
public ResolverStyle getResolverStyle()
获取解析期间要使用的解析器样式。这将返回解析器样式,在解析第二阶段时将字段解析为日期和时间。 默认情况下,格式化程序具有
SMART
解析程序样式。 有关详细信息,请参见withResolverStyle(ResolverStyle)
。- 结果
- 此格式化程序的解析器样式,不为null
-
withResolverStyle
public DateTimeFormatter withResolverStyle(ResolverStyle resolverStyle)
使用新的解析程序样式返回此formatter的副本。这将返回一个格式化程序,其状态与此格式化程序类似,但设置了解析程序样式。 默认情况下,格式化程序具有
SMART
解析程序样式。更改解析程序样式仅在解析期间有效。 解析文本字符串分两个阶段进行。 阶段1是根据添加到构建器的字段的基本文本解析。 阶段2将解析的字段 - 值对解析为日期和/或时间对象。 解析器样式用于控制阶段2解析的发生方式。 有关可用选项的更多信息,请参见
ResolverStyle
。此实例是不可变的,不受此方法调用的影响。
- 参数
-
resolverStyle
- 新的解析器样式,不为null - 结果
- 基于此格式化程序的格式化程序,具有请求的解析程序样式,而不是null
-
getResolverFields
public Set<TemporalField> getResolverFields()
获取解析期间要使用的解析器字段。这将返回解析器字段,在解析第二阶段时将字段解析为日期和时间。 默认情况下,格式化程序没有解析器字段,因此返回null。 有关详细信息,请参见
withResolverFields(Set)
。- 结果
- 此格式化程序的不可变的解析程序字段集,如果没有字段则为null
-
withResolverFields
public DateTimeFormatter withResolverFields(TemporalField... resolverFields)
返回此格式化程序的副本,其中包含一组新的解析程序字段。这将返回一个格式化程序,其状态与此格式化程序类似,但设置了解析程序字段。 默认情况下,格式化程序没有解析程序字段。
更改解析程序字段仅在解析期间有效。 解析文本字符串分两个阶段进行。 阶段1是根据添加到构建器的字段的基本文本解析。 阶段2将解析的字段 - 值对解析为日期和/或时间对象。 解析器字段用于过滤阶段1和阶段2之间的字段 - 值对。
这可用于在两种或更多种方式之间进行选择,以便解决日期或时间。 例如,如果格式化程序包含年,月,日,日和年,则有两种方法可以解决日期问题。 使用参数
YEAR
和DAY_OF_YEAR
调用此方法将确保使用年份和日期解析日期,这实际上意味着在解决阶段忽略月份和日期。以类似的方式,该方法可用于忽略否则将被交叉检查的辅助字段。 例如,如果格式化程序包含年,月,日,星期和星期几,那么只有一种方法可以解决日期,但是星期几的解析值将被交叉检查反对解决的日期。 调用此方法与参数
YEAR
,MONTH_OF_YEAR
和DAY_OF_MONTH
将确保日期是正确解决,但没有任何交叉检查的某一天的一周。在实现方面,该方法表现如下。 解析阶段的结果可以被认为是字段到值的映射。 此方法的行为是使该映射在阶段1和阶段2之间进行过滤,删除除指定为此方法的参数之外的所有字段。
此实例是不可变的,不受此方法调用的影响。
- 参数
-
resolverFields
- 新的解析程序字段集,如果没有字段,则为null - 结果
- 基于此格式化程序的格式化程序,具有请求的解析程序样式,而不是null
-
withResolverFields
public DateTimeFormatter withResolverFields(Set<TemporalField> resolverFields)
返回此格式化程序的副本,其中包含一组新的解析程序字段。这将返回一个格式化程序,其状态与此格式化程序类似,但设置了解析程序字段。 默认情况下,格式化程序没有解析程序字段。
更改解析程序字段仅在解析期间有效。 解析文本字符串分两个阶段进行。 阶段1是根据添加到构建器的字段的基本文本解析。 阶段2将解析的字段 - 值对解析为日期和/或时间对象。 解析器字段用于过滤阶段1和阶段2之间的字段 - 值对。
这可用于在两种或更多种方式之间进行选择,以便解决日期或时间。 例如,如果格式化程序包含年,月,日,日和年,则有两种方法可以解决日期问题。 使用参数
YEAR
和DAY_OF_YEAR
调用此方法将确保使用年份和年份解析日期,这实际上意味着在解析阶段忽略月份和日期。以类似的方式,该方法可用于忽略否则将被交叉检查的辅助字段。 例如,如果格式化程序包含年,月,日,星期和星期几,那么只有一种方法可以解决日期,但是星期几的解析值将被交叉检查反对解决的日期。 调用此方法与参数
YEAR
,MONTH_OF_YEAR
和DAY_OF_MONTH
将确保日期是正确解决,但没有任何交叉检查的某一天的一周。在实现方面,该方法表现如下。 解析阶段的结果可以被认为是字段到值的映射。 此方法的行为是使该映射在阶段1和阶段2之间进行过滤,删除除指定为此方法的参数之外的所有字段。
此实例是不可变的,不受此方法调用的影响。
- 参数
-
resolverFields
- 新的解析器字段集,如果没有字段,则为null - 结果
- 基于此格式化程序的格式化程序,具有请求的解析程序样式,而不是null
-
format
public String format(TemporalAccessor temporal)
使用此格式化程序格式化日期时间对象。这使用格式化程序的规则将日期时间格式化为String。
- 参数
-
temporal
- 要格式化的时态对象,而不是null - 结果
- 格式化的字符串,不是null
- 异常
-
DateTimeException
- 如果格式化期间发生错误
-
formatTo
public void formatTo(TemporalAccessor temporal, Appendable appendable)
使用此格式化程序将日期时间对象格式化为Appendable
。这会将格式化的日期时间输出到指定的目的地。
Appendable
是受所有键字符输出类别,包括实现一个通用接口StringBuffer
,StringBuilder
,PrintStream
和Writer
。虽然
Appendable
方法抛出IOException
,但这种方法没有。 相反,任何IOException
都包含在运行时异常中。- 参数
-
temporal
- 要格式化的时态对象,而不是null -
appendable
- 可以格式化为,不为null - 异常
-
DateTimeException
- 如果格式化期间发生错误
-
parse
public TemporalAccessor parse(CharSequence text)
完全解析生成临时对象的文本。这会解析生成临时对象的整个文本。 使用
parse(CharSequence, TemporalQuery)
通常更有用。 此方法的结果是TemporalAccessor
已经解决,应用基本验证检查以帮助确保有效的日期时间。如果解析完成而没有读取文本的整个长度,或者在解析或合并期间出现问题,则抛出异常。
- 参数
-
text
- 要解析的文本,而不是null - 结果
- 解析的时态对象,而不是null
- 异常
-
DateTimeParseException
- 如果无法解析请求的结果
-
parse
public TemporalAccessor parse(CharSequence text, ParsePosition position)
使用此格式化程序解析文本,提供对文本位置的控制。这解析文本而不要求解析从字符串的开头开始或在结束时完成。 此方法的结果是
TemporalAccessor
已经解决,应用基本验证检查以帮助确保有效的日期时间。该文本将从指定的开始
ParsePosition
解析。 无需解析文本的整个长度,ParsePosition
将在解析结束时使用索引进行更新。该方法的操作与在
java.text.Format
上使用ParsePosition
类似方法略有不同。 该类将使用ParsePosition
上的错误索引返回错误。 相反,如果发生错误,此方法将抛出DateTimeParseException
,异常包含错误索引。 由于此API中解析和解析日期/时间的复杂性增加,因此这种行为更改是必要的。如果格式化程序使用不同的值多次解析同一字段,则结果将是错误。
- 参数
-
text
- 要解析的文本,而不是null -
position
- 要解析的位置,使用已解析的长度和任何错误的索引进行更新,而不是null - 结果
- 解析的时态对象,而不是null
- 异常
-
DateTimeParseException
- 如果无法解析请求的结果 -
IndexOutOfBoundsException
- 如果头寸无效
-
parse
public <T> T parse(CharSequence text, TemporalQuery<T> query)
完全解析生成指定类型对象的文本。大多数应用程序应该使用此方法进行解析。 它解析整个文本以生成所需的日期时间。 该查询通常是对
from(TemporalAccessor)
方法的方法引用。 例如:LocalDateTime dt = parser.parse(str, LocalDateTime::from);
如果解析完成而没有读取文本的整个长度,或者在解析或合并期间出现问题,则抛出异常。- 参数类型
-
T
- 已解析日期时间的类型 - 参数
-
text
- 要解析的文本,而不是null -
query
- 定义要解析的类型的查询,而不是null - 结果
- 解析的日期时间,而不是null
- 异常
-
DateTimeParseException
- 如果无法解析请求的结果
-
parseBest
public TemporalAccessor parseBest(CharSequence text, TemporalQuery<?>... queries)
完全解析生成指定类型之一的对象的文本。当解析器可以处理可选元素时,此解析方法很方便使用。 例如,'uuuu-MM-dd HH.mm [VV]'的模式可以完全解析为
ZonedDateTime
,或部分解析为LocalDateTime
。 必须按顺序指定查询,从最佳匹配的完全解析选项开始,以最差匹配的最小解析选项结束。 该查询通常是对from(TemporalAccessor)
方法的方法引用。结果与成功解析的第一个类型相关联。 通常,应用程序将使用
instanceof
来检查结果。 例如:TemporalAccessor dt = parser.parseBest(str, ZonedDateTime::from, LocalDateTime::from); if (dt instanceof ZonedDateTime) { ... } else { ... }
如果解析完成而没有读取文本的整个长度,或者在解析或合并期间出现问题,则抛出异常。- 参数
-
text
- 要解析的文本,而不是null -
queries
- 定义要尝试解析的类型的查询,必须实现TemporalAccessor
,而不是null - 结果
- 解析的日期时间,而不是null
- 异常
-
IllegalArgumentException
- 如果指定的类型少于2种 -
DateTimeParseException
- 如果无法解析请求的结果
-
parseUnresolved
public TemporalAccessor parseUnresolved(CharSequence text, ParsePosition position)
使用此格式化程序解析文本,而不解析结果,用于高级用例。解析实现为两阶段操作。 首先,使用格式化程序定义的布局解析文本,生成
Map
字段值,ZoneId
和Chronology
。 其次,分析的数据解析 ,通过验证,合并和简化了各领域到更多有用的。 此方法执行解析阶段但不执行解析阶段。该方法的结果是
TemporalAccessor
,它表示输入中看到的数据。 未验证值,因此解析日期字符串'2012-00-65'将导致具有三个字段的时间 - '2012'年,'0'月和'65'月日。该文本将从指定的开始
ParsePosition
解析。 无需解析文本的整个长度,ParsePosition
将在解析结束时使用索引进行更新。使用
ParsePosition
的错误索引字段而不是DateTimeParseException
返回错误。 返回的错误索引将设置为指示错误的索引。 在使用结果之前,呼叫者必须检查错误。如果格式化程序使用不同的值多次解析同一字段,则结果将是错误。
此方法适用于在解析期间需要访问内部状态的高级用例。 典型的应用程序代码应使用
parse(CharSequence, TemporalQuery)
或目标类型的解析方法。- 参数
-
text
- 要解析的文本,而不是null -
position
- 要解析的位置,使用已解析的长度和任何错误的索引进行更新,而不是null - 结果
- 解析后的文本,如果解析导致错误,则返回null
- 异常
-
DateTimeException
- 如果在解析过程中出现问题 -
IndexOutOfBoundsException
- 如果头寸无效
-
toFormat
public Format toFormat()
将此格式化程序作为java.text.Format
实例返回。返回的
Format
实例将格式化任何TemporalAccessor
并解析为已解析的TemporalAccessor
。例外情况将遵循
Format
的定义,有关IllegalArgumentException
期间ParseException
和ParseException
详细信息,请参阅这些方法,或者在解析期间ParseException
null。 格式不支持归属返回的格式字符串。- 结果
- 此格式化程序作为经典格式实例,不为null
-
toFormat
public Format toFormat(TemporalQuery<?> parseQuery)
将此格式化程序作为将使用指定查询进行分析的java.text.Format
实例返回。返回的
Format
实例将格式化任何TemporalAccessor
并解析为指定的类型。 该类型必须是parse(java.lang.CharSequence)
支持的类型 。例外将遵循
Format
的定义,有关IllegalArgumentException
期间ParseException
和ParseException
详细信息,请参阅这些方法,或者在解析期间ParseException
null。 格式不支持归属返回的格式字符串。- 参数
-
parseQuery
- 定义要解析的类型的查询,而不是null - 结果
- 此格式化程序作为经典格式实例,不为null
-
-