Module java.base
Package java.time.temporal

Class TemporalQueries

java.lang.Object
java.time.temporal.TemporalQueries
public final class TemporalQueries extends Object
TemporalQuery的常见实现。

这个类提供了TemporalQuery的常见实现。这些在这里定义是因为它们必须是常量，而使用lambda表达式并不能保证这一点。通过在这里分配它们一次，它们就变成了'普通'的Java常量。

查询是从时间对象中提取信息的关键工具。它们存在是为了外部化查询过程，允许不同的方法，就像策略设计模式一样。例如，一个查询可能检查日期是否是闰年中2月29日的前一天，或者计算距离你下一个生日还有多少天。

TemporalField接口提供了另一种查询时间对象的机制。该接口仅限于返回一个long。相比之下，查询可以返回任何类型。

有两种等效的使用TemporalQuery的方式。第一种是直接在这个接口上调用方法。第二种是使用TemporalAccessor.query(TemporalQuery)：

   // 这两行是等效的，但第二种方法是推荐的
   temporal = thisQuery.queryFrom(temporal);
   temporal = temporal.query(thisQuery);
推荐使用第二种方法query(TemporalQuery)，因为在代码中更清晰易读。

最常见的实现是方法引用，比如LocalDate::from和ZoneId::from。还提供了额外的常见查询来返回：

  • 一个年表（Chronology），
  • 一个本地日期（LocalDate），
  • 一个本地时间（LocalTime），
  • 一个区域偏移（ZoneOffset），
  • 一个精度（precision），
  • 一个区域，或
  • 一个区域ID。
自版本:
1.8

  • Method Details

    • zoneId

      public static TemporalQuery<ZoneId> zoneId()
      一个严格的用于ZoneId的查询。

      这个查询从TemporalAccessor中查询区域。只有当日期时间概念上包含ZoneId时，才会返回区域。如果日期时间仅在概念上具有ZoneOffset，则不会返回区域。因此，ZonedDateTime将返回getZone()的结果，但OffsetDateTime将返回null。

      在大多数情况下，应用程序应该使用zone()，因为这个查询太严格了。

      JDK类实现TemporalAccessor的结果如下：
      LocalDate返回null
      LocalTime返回null
      LocalDateTime返回null
      ZonedDateTime返回关联的区域
      OffsetTime返回null
      OffsetDateTime返回null
      ChronoLocalDate返回null
      ChronoLocalDateTime返回null
      ChronoZonedDateTime返回关联的区域
      Era返回null
      DayOfWeek返回null
      Month返回null
      Year返回null
      YearMonth返回null
      MonthDay返回null
      ZoneOffset返回null
      Instant返回null

      返回:
      一个可以获取时间区域ID的查询，非null

    • chronology

      public static TemporalQuery<Chronology> chronology()
      一个用于Chronology的查询。

      这个查询从TemporalAccessor中查询年表。如果目标TemporalAccessor表示日期或日期的一部分，则应返回日期所表示的年表。由于这个定义，仅表示时间的对象，比如LocalTime，将返回null。

      JDK类实现TemporalAccessor的结果如下：
      LocalDate返回IsoChronology.INSTANCE
      LocalTime返回null（不表示日期）
      LocalDateTime返回IsoChronology.INSTANCE
      ZonedDateTime返回IsoChronology.INSTANCE
      OffsetTime返回null（不表示日期）
      OffsetDateTime返回IsoChronology.INSTANCE
      ChronoLocalDate返回关联的年表
      ChronoLocalDateTime返回关联的年表
      ChronoZonedDateTime返回关联的年表
      Era返回关联的年表
      DayOfWeek返回null（跨年表共享）
      Month返回IsoChronology.INSTANCE
      Year返回IsoChronology.INSTANCE
      YearMonth返回IsoChronology.INSTANCE
      MonthDay返回null IsoChronology.INSTANCE
      ZoneOffset返回null（不表示日期）
      Instant返回null（不表示日期）

      方法Chronology.from(TemporalAccessor)可以通过方法引用Chronology::from用作TemporalQuery。该方法与此查询等效，只是如果无法获取年表，则会抛出异常。

      返回:
      一个可以获取时间年表的查询，非null

    • precision

      public static TemporalQuery<TemporalUnit> precision()
      一个用于最小支持单位的查询。

      这个查询从TemporalAccessor中查询时间精度。如果目标TemporalAccessor表示一致或完整的日期时间、日期或时间，则必须返回实际支持的最小精度。请注意，诸如NANO_OF_DAY和NANO_OF_SECOND之类的字段被定义为始终返回，忽略精度，因此这是找到实际支持的最小单位的唯一方法。例如，如果GregorianCalendar实现了TemporalAccessor，它将返回MILLIS的精度。

      JDK类实现TemporalAccessor的结果如下：
      LocalDate返回DAYS
      LocalTime返回NANOS
      LocalDateTime返回NANOS
      ZonedDateTime返回NANOS
      OffsetTime返回NANOS
      OffsetDateTime返回NANOS
      ChronoLocalDate返回DAYS
      ChronoLocalDateTime返回NANOS
      ChronoZonedDateTime返回NANOS
      Era返回ERAS
      DayOfWeek返回DAYS
      Month返回MONTHS
      Year返回YEARS
      YearMonth返回MONTHS
      MonthDay返回null（不表示完整的日期或时间）
      ZoneOffset返回null（不表示日期或时间）
      Instant返回NANOS

      返回:
      一个可以获取时间精度的查询，非null

    • zone

      public static TemporalQuery<ZoneId> zone()
      一个宽松的用于ZoneId的查询，回退到ZoneOffset。

      这个查询从TemporalAccessor中查询区域。它首先尝试获取区域，使用zoneId()。如果找不到，它会尝试获取offset()。因此，ZonedDateTime将返回getZone()的结果，而OffsetDateTime将返回getOffset()的结果。

      在大多数情况下，应用程序应该使用这个查询，而不是#zoneId()。

      方法ZoneId.from(TemporalAccessor)可以通过方法引用ZoneId::from用作TemporalQuery。该方法与此查询等效，只是如果无法获取区域，则会抛出异常。

      返回:
      一个可以获取时间区域ID或偏移的查询，非null

    • offset

      public static TemporalQuery<ZoneOffset> offset()
      一个用于ZoneOffset的查询，如果找不到则返回null。

      这返回一个TemporalQuery，可用于查询时间对象的偏移量。如果时间对象无法提供偏移量，则查询将返回null。

      查询实现检查OFFSET_SECONDS字段，并使用它创建一个ZoneOffset。

      方法ZoneOffset.from(TemporalAccessor)可以通过方法引用ZoneOffset::from用作TemporalQuery。如果时间对象包含偏移量，则此查询和ZoneOffset::from将返回相同的结果。如果时间对象不包含偏移量，则方法引用将抛出异常，而此查询将返回null。

      返回:
      一个可以获取时间偏移的查询，非null

    • localDate

      public static TemporalQuery<LocalDate> localDate()
      一个用于LocalDate的查询，如果找不到则返回null。

      这返回一个TemporalQuery，可用于查询时间对象的本地日期。如果时间对象无法提供本地日期，则查询将返回null。

      查询实现检查EPOCH_DAY字段，并使用它创建一个LocalDate。

      方法LocalDate.from(TemporalAccessor)可以通过方法引用LocalDate::from用作TemporalQuery。如果时间对象包含日期，则此查询和LocalDate::from将返回相同的结果。如果时间对象不包含日期，则方法引用将抛出异常，而此查询将返回null。

      返回:
      一个可以获取时间日期的查询，非null

    • localTime

      public static TemporalQuery<LocalTime> localTime()
      查询LocalTime，如果未找到则返回null。

      这将返回一个TemporalQuery，可用于查询时间对象的本地时间。如果时间对象无法提供本地时间，则查询将返回null。

      查询实现会检查NANO_OF_DAY字段，并使用它创建一个LocalTime。

      方法LocalTime.from(TemporalAccessor)可以通过方法引用LocalTime::from用作TemporalQuery。如果时间对象包含时间，则此查询和LocalTime::from将返回相同的结果。如果时间对象不包含时间，则方法引用将引发异常，而此查询将返回null。

      返回：
      可获取时间对象时间的查询，非null