模块  java.base
软件包  java.time.chrono

Interface ChronoZonedDateTime<D extends ChronoLocalDate>

  • 参数类型
    D - 此日期时间日期的具体类型
    All Superinterfaces:
    Comparable<ChronoZonedDateTime<?>>TemporalTemporalAccessor
    所有已知实现类:
    ZonedDateTime

    public interface ChronoZonedDateTime<D extends ChronoLocalDate>
    extends Temporal, Comparable<ChronoZonedDateTime<?>>
    用于高级全球化用例的具有任意时间顺序的时区的日期时间。

    大多数应用程序应将方法签名,字段和变量声明为ZonedDateTime ,而不是此接口。

    ChronoZonedDateTime是偏移日期时间的抽象表示,其中Chronology chronology或日历系统是可插入的。 日期时间是由TemporalField表示的字段定义的,其中最常见的实现在ChronoField中定义。 年表定义了日历系统的运作方式和标准字段的含义。

    何时使用此界面

    API的设计鼓励使用ZonedDateTime而不是此接口,即使在应用程序需要处理多个日历系统的情况下也是如此。 ChronoLocalDate中详细探讨了其基本原理。

    在使用此界面之前,请确保已阅读并理解ChronoLocalDate中的讨论。

    实现要求:
    必须小心实现此接口,以确保其他类正常运行。 可以实例化的所有实现必须是最终的,不可变的和线程安全的。 只要有可能,子类应该是Serializable。
    从以下版本开始:
    1.8
    • 方法详细信息

      • from

        static ChronoZonedDateTime<?> from​(TemporalAccessor temporal)
        从时态对象获得ChronoZonedDateTime的实例。

        这将根据指定的时间创建分区日期时间。 TemporalAccessor表示一组任意日期和时间信息,该工厂将其转换为ChronoZonedDateTime的实例。

        转换从时间对象中提取并组合年表,日期,时间和区域。 该行为相当于将Chronology.zonedDateTime(TemporalAccessor)与提取的年表一起使用。 允许实现执行优化,例如访问与相关对象等效的那些字段。

        该方法匹配功能接口TemporalQuery的签名,允许其通过方法参考ChronoZonedDateTime::from用作查询。

        参数
        temporal - 要转换的时态对象,而不是null
        结果
        日期时间,不为空
        异常
        DateTimeException - 如果无法转换为 ChronoZonedDateTime
        另请参见:
        Chronology.zonedDateTime(TemporalAccessor)
      • toLocalDate

        default D toLocalDate()
        获取此日期时间的本地日期部分。

        这将返回与此日期时间相同的年,月和日的本地日期。

        结果
        此日期时间的日期部分,不为空
      • toLocalTime

        default LocalTime toLocalTime()
        获取此日期时间的本地时间部分。

        这将返回与此日期时间相同的小时,分钟,秒和纳秒的本地时间。

        结果
        此日期时间的时间部分,不为空
      • toLocalDateTime

        ChronoLocalDateTime<D> toLocalDateTime()
        获取此日期时间的本地日期时间部分。

        这将返回与此日期时间相同的年,月和日的本地日期。

        结果
        此日期时间的本地日期时间部分,不为空
      • getChronology

        default Chronology getChronology()
        获取此日期时间的年表。

        Chronology表示正在使用的日历系统。 ChronoField中的时代和其他领域由年表定义。

        结果
        年表,不是空的
      • getOffset

        ZoneOffset getOffset()
        获取区域偏移量,例如“+01:00”。

        这是本地日期时间与UTC /格林威治的偏移量。

        结果
        区域偏移,不为空
      • getZone

        ZoneId getZone()
        获取区域ID,例如“Europe / Paris”。

        这将返回用于确定时区规则的存储时区ID。

        结果
        区域ID,不为空
      • withEarlierOffsetAtOverlap

        ChronoZonedDateTime<D> withEarlierOffsetAtOverlap()
        返回此日期时间的副本,将区域偏移更改为本地时间线重叠处的两个有效偏移中较早的一个。

        当本地时间线重叠时,例如在秋季夏令时切换时,此方法仅具有任何效果。 在这种情况下,本地日期时间有两个有效的偏移量。 调用此方法将返回一个分区日期时间,其中包含所选的两个中的较早者。

        如果在不重叠时调用此方法,则返回this

        此实例是不可变的,不受此方法调用的影响。

        结果
        基于此日期时间的 ChronoZonedDateTime ,具有较早的偏移量,不为空
        异常
        DateTimeException - 如果找不到该区域的规则
        DateTimeException - 如果此日期时间没有规则有效
      • withLaterOffsetAtOverlap

        ChronoZonedDateTime<D> withLaterOffsetAtOverlap()
        返回此日期时间的副本,将区域偏移更改为本地时间线重叠处的两个有效偏移中的较晚者。

        当本地时间线重叠时,例如在秋季夏令时切换时,此方法仅具有任何效果。 在这种情况下,本地日期时间有两个有效的偏移量。 调用此方法将返回一个分区日期时间,其中包含所选择的两个日期时间。

        如果在不重叠时调用此方法,则返回this

        此实例是不可变的,不受此方法调用的影响。

        结果
        基于此日期时间的 ChronoZonedDateTime ,后面的偏移量,不为空
        异常
        DateTimeException - 如果找不到该区域的规则
        DateTimeException - 如果此日期时间没有规则有效
      • withZoneSameLocal

        ChronoZonedDateTime<D> withZoneSameLocal​(ZoneId zone)
        使用不同的时区返回此日期时间的副本,如果可能,保留本地日期时间。

        此方法更改时区并保留本地日期时间。 仅当本地日期时间对新区域无效时,才会更改本地日期时间。

        要更改区域并调整本地日期时间,请使用withZoneSameInstant(ZoneId)

        此实例是不可变的,不受此方法调用的影响。

        参数
        zone - 要更改为的时区,而不是null
        结果
        a ChronoZonedDateTime基于此日期时间与请求的区域,不为空
      • withZoneSameInstant

        ChronoZonedDateTime<D> withZoneSameInstant​(ZoneId zone)
        使用不同的时区返回此日期时间的副本,保留该瞬间。

        此方法更改时区并保留瞬间。 这通常会导致本地日期时间发生变化。

        该方法基于保留相同的瞬间,因此本地时间线中的间隙和重叠对结果没有影响。

        要在保持当地时间的同时更改偏移量,请使用withZoneSameLocal(ZoneId)

        参数
        zone - 要更改为的时区,而不是null
        结果
        a ChronoZonedDateTime基于此日期时间与请求的区域,不为空
        异常
        DateTimeException - 如果结果超出支持的日期范围
      • isSupported

        boolean isSupported​(TemporalField field)
        检查是否支持指定的字段。

        这将检查是否可以在此日期时间查询指定的字段。 如果是假,然后调用rangegetwith(TemporalField, long)方法会抛出异常。

        支持的字段集由年表定义,通常包括所有ChronoField字段。

        如果该字段不是ChronoField ,则通过调用this作为参数调用TemporalField.isSupportedBy(TemporalAccessor)获得此方法的结果。 字段是否受支持由字段确定。

        Specified by:
        isSupported in interface TemporalAccessor
        参数
        字段 - 要检查的字段,null返回false
        结果
        如果可以查询该字段,则为true,否则为false
      • isSupported

        default boolean isSupported​(TemporalUnit unit)
        检查指定的单元是否受支持。

        这将检查是否可以在此日期时间中添加或减去指定的单位。 如果为false,则调用plus(long, TemporalUnit)minus方法将引发异常。

        支持的单位集由年表定义,通常包括除FOREVER以外的所有ChronoUnit单位。

        如果单位不是ChronoUnit ,则通过调用this作为参数调用TemporalUnit.isSupportedBy(Temporal)获得此方法的结果。 设备是否受支持由设备决定。

        Specified by:
        isSupported在界面 Temporal
        参数
        unit - 要检查的单位,null返回false
        结果
        如果可以添加/减去单位,则为true,否则为false
      • with

        default ChronoZonedDateTime<D> with​(TemporalAdjuster adjuster)
        返回与此对象相同类型的调整对象,并进行调整。

        这将根据指定调整程序的规则调整此日期时间。 简单的调整器可能只是设置其中一个字段,例如年份字段。 更复杂的调整器可能会将日期设置为该月的最后一天。 TemporalAdjusters提供了一些常见调整。 这些包括找到“月的最后一天”和“下周三”。 理算员负责处理特殊情况,例如不同长度的月份和闰年。

        一些示例代码指示使用此方法的方式和原因:

          date = date.with(Month.JULY);        // most key classes implement TemporalAdjuster
          date = date.with(lastDayOfMonth());  // static import from Adjusters
          date = date.with(next(WEDNESDAY));   // static import from Adjusters and DayOfWeek 
        Specified by:
        with in interface Temporal
        参数
        adjuster - 要使用的调整器,不为null
        结果
        具有指定调整的相同类型的对象,而不是null
        异常
        DateTimeException - 如果无法进行调整
        ArithmeticException - 如果发生数字溢出
      • with

        ChronoZonedDateTime<D> with​(TemporalField field,
                                    long newValue)
        返回与此对象相同类型的对象,并更改指定的字段。

        这将返回基于此对象的新对象,并更改指定字段的值。 例如,在LocalDate ,这可用于设置年,月或日。 返回的对象将具有与此对象相同的可观察类型。

        在某些情况下,未完全定义更改字段。 例如,如果目标对象是代表1月31日的日期,那么将月份更改为2月将不清楚。 在这种情况下,该字段负责解析结果。 通常,它会选择上一个有效日期,这个日期是本例中2月的最后一个有效日期。

        Specified by:
        with在界面 Temporal
        参数
        字段 - 要在结果中设置的字段,不为null
        newValue - 结果中字段的新值
        结果
        具有指定字段集的相同类型的对象,不为null
        异常
        DateTimeException - 如果无法设置该字段
        ArithmeticException - 如果发生数字溢出
      • plus

        default ChronoZonedDateTime<D> plus​(TemporalAmount amount)
        返回与此对象相同类型的对象,并添加一个量。

        这会调整此时间,根据指定数量的规则添加。 该数量通常为Period但可以是实现TemporalAmount接口的任何其他类型,例如Duration

        一些示例代码指示使用此方法的方式和原因:

          date = date.plus(period);                // add a Period instance
          date = date.plus(duration);              // add a Duration instance
          date = date.plus(workingDays(6));        // example user-written workingDays method 

        请注意,不能保证调用plus后跟minus返回相同的日期时间。

        Specified by:
        plus在界面 Temporal
        参数
        amount - 要添加的金额,不为空
        结果
        具有指定调整的相同类型的对象,而不是null
        异常
        DateTimeException - 如果无法添加
        ArithmeticException - 如果发生数字溢出
      • plus

        ChronoZonedDateTime<D> plus​(long amountToAdd,
                                    TemporalUnit unit)
        返回与此对象具有相同类型的对象,并添加指定的句点。

        此方法返回基于此对象的新对象,并添加指定的时间段。 例如,在LocalDate ,这可用于添加若干年,月或日。 返回的对象将具有与此对象相同的可观察类型。

        在某些情况下,未完全定义更改字段。 例如,如果目标对象是表示1月31日的日期,则添加一个月将不清楚。 在这种情况下,该字段负责解析结果。 通常,它会选择上一个有效日期,这个日期是本例中2月的最后一个有效日期。

        Specified by:
        plus ,界面 Temporal
        参数
        amountToAdd - 要添加的指定单位的数量,可能为负数
        unit - 要添加的金额的单位,而不是空
        结果
        添加了指定期间的相同类型的对象,而不是null
        异常
        DateTimeException - 如果无法添加本机
        ArithmeticException - 如果发生数字溢出
      • minus

        default ChronoZonedDateTime<D> minus​(TemporalAmount amount)
        返回与此对象相同类型的对象,并减去一定量。

        这会调整此时间,根据指定数量的规则减去。 该数量通常为Period但可以是实现TemporalAmount接口的任何其他类型,例如Duration

        一些示例代码指示使用此方法的方式和原因:

          date = date.minus(period);               // subtract a Period instance
          date = date.minus(duration);             // subtract a Duration instance
          date = date.minus(workingDays(6));       // example user-written workingDays method 

        请注意,不能保证调用plus后跟minus返回相同的日期时间。

        Specified by:
        minus在界面 Temporal
        参数
        amount - 要减去的金额,而不是空
        结果
        具有指定调整的相同类型的对象,而不是null
        异常
        DateTimeException - 如果无法进行减法
        ArithmeticException - 如果发生数字溢出
      • minus

        default ChronoZonedDateTime<D> minus​(long amountToSubtract,
                                             TemporalUnit unit)
        返回与此对象相同类型的对象,并减去指定的时间段。

        此方法返回基于此对象的新对象,并减去指定的时间段。 例如,在LocalDate ,这可用于减去若干年,月或日。 返回的对象将具有与此对象相同的可观察类型。

        在某些情况下,未完全定义更改字段。 例如,如果目标对象是表示3月31日的日期,则减去一个月将不清楚。 在这种情况下,该字段负责解析结果。 通常,它会选择上一个有效日期,这个日期是本例中2月的最后一个有效日期。

        Specified by:
        minus在界面 Temporal
        参数
        amountToSubtract - 要减去的指定单位的数量,可能是负数
        unit - 要减去的金额的单位,而不是空
        结果
        减去指定时间段的相同类型的对象,不为null
        异常
        DateTimeException - 如果无法减去单位
        ArithmeticException - 如果发生数字溢出
      • query

        default <R> R query​(TemporalQuery<R> query)
        使用指定的查询查询此日期时间。

        这将使用指定的查询策略对象查询此日期时间。 TemporalQuery对象定义用于获取结果的逻辑。 阅读查询文档以了解此方法的结果。

        通过在指定的查询上调用TemporalQuery.queryFrom(TemporalAccessor)方法作为参数传递this来获得此方法的结果。

        Specified by:
        query在界面 TemporalAccessor
        参数类型
        R - 结果的类型
        参数
        query - 要调用的查询,而不是null
        结果
        查询结果,可以返回null(由查询定义)
        异常
        DateTimeException - 如果无法查询(由查询定义)
        ArithmeticException - 如果发生数字溢出(由查询定义)
      • format

        default String format​(DateTimeFormatter formatter)
        使用指定的格式化程序格式化此日期时间。

        此日期时间将传递给格式化程序以生成字符串。

        默认实现必须如下所示:

          return formatter.format(this); 
        参数
        formatter - 要使用的格式化程序,而不是null
        结果
        格式化的日期时间字符串,不为空
        异常
        DateTimeException - 如果在打印期间发生错误
      • toInstant

        default Instant toInstant()
        将此日期时间转换为Instant

        这将返回一个Instant表示时间线上与此日期时间相同的点。 该计算结合了local date-timeoffset

        结果
        Instant表示同一时刻,不为空
      • toEpochSecond

        default long toEpochSecond()
        将此日期时间转换为1970-01-01T00:00:00Z纪元的秒数。

        这使用local date-timeoffset来计算纪元秒值,该值是1970-01-01T00:00:00Z的经过秒数。 在时代之后的时间线上的实例是正的,之前是负的。

        结果
        1970-01-01T00:00:00Z时代的秒数
      • compareTo

        default int compareTo​(ChronoZonedDateTime<?> other)
        将此日期时间与另一个日期时间进行比较,包括年表。

        比较首先基于瞬间,然后是本地日期时间,然后是区域ID,然后是年表。 它与“等于”一致,如Comparable所定义。

        如果要比较的所有日期时间对象都是相同的年表,则不需要额外的时间顺序阶段。

        此默认实现执行上面定义的比较。

        Specified by:
        compareTo in interface Comparable<D extends ChronoLocalDate>
        参数
        other - 要比较的其他日期时间,而不是null
        结果
        比较器值,如果更小则为负,如果更大则为正
      • isBefore

        default boolean isBefore​(ChronoZonedDateTime<?> other)
        检查此日期时间的瞬间是否在指定日期时间之前。

        该方法与compareTo(java.time.chrono.ChronoZonedDateTime<?>)中的比较的不同之处在于它仅比较日期时间的瞬间。 这相当于使用dateTime1.toInstant().isBefore(dateTime2.toInstant());

        此默认实现基于epoch-second和nano-of-秒执行比较。

        参数
        other - 要比较的其他日期时间,而不是null
        结果
        如果此点在指定的日期时间之前,则为true
      • isAfter

        default boolean isAfter​(ChronoZonedDateTime<?> other)
        检查此日期时间的瞬间是否在指定日期时间之后。

        该方法与compareTo(java.time.chrono.ChronoZonedDateTime<?>)中的比较的不同之处在于它仅比较日期时间的瞬间。 这相当于使用dateTime1.toInstant().isAfter(dateTime2.toInstant());

        此默认实现基于epoch-second和nano-of-秒执行比较。

        参数
        other - 要比较的其他日期时间,而不是null
        结果
        如果这是在指定的日期时间之后,则为true
      • isEqual

        default boolean isEqual​(ChronoZonedDateTime<?> other)
        检查此日期时间的瞬间是否等于指定日期时间的瞬间。

        该方法与compareTo(java.time.chrono.ChronoZonedDateTime<?>)equals(java.lang.Object)中的比较的不同之处在于它仅比较日期时间的瞬间。 这相当于使用dateTime1.toInstant().equals(dateTime2.toInstant());

        此默认实现基于epoch-second和nano-of-秒执行比较。

        参数
        other - 要比较的其他日期时间,而不是null
        结果
        如果瞬间等于指定日期时间的瞬间,则为true
      • equals

        boolean equals​(Object obj)
        检查此日期时间是否等于另一个日期时间。

        比较基于偏移日期时间和区域。 要比较时间线上的同一时刻,请使用compareTo(java.time.chrono.ChronoZonedDateTime<?>) 仅比较类型为ChronoZonedDateTime对象,其他类型返回false。

        重写:
        equals在课程 Object
        参数
        obj - 要检查的对象,null返回false
        结果
        如果这等于其他日期时间,则为true
        另请参见:
        Object.hashCode()HashMap
      • toString

        String toString()
        输出此日期时间为String

        输出将包括完整的分区日期时间。

        重写:
        toString在课程 Object
        结果
        此日期时间的字符串表示形式,不为null