Module  java.base
软件包  java.time.chrono

Interface ChronoZonedDateTime<D extends ChronoLocalDate>

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

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

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

    A ChronoZonedDateTime是Chronology chronology或日历系统可插拔的偏移日期时间的抽象表示。 日期时间由TemporalField表示的字段定义，其中大多数常见实现在ChronoField中定义。 年表定义日历系统的运行方式和标准字段的含义。

    何时使用此界面

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

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

    实现要求：
    该接口必须小心实施，以确保其他类正确运行。 可以实例化的所有实现必须是最终的，不可变的和线程安全的。 子类应尽可能可序列化。
    从以下版本开始：
    1.8

    • 方法详细信息

      • from

        static ChronoZonedDateTime<?> from​(TemporalAccessor temporal)
        从时间对象获取一个ChronoZonedDateTime的实例。

        这将根据指定的时间创建一个划区的日期时间。 A TemporalAccessor表示一个任意的日期和时间信息集，该工厂转换为ChronoZonedDateTime一个实例。

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

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

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

      • range

        default ValueRange range​(TemporalField field)
        描述从接口TemporalAccessor复制
        获取指定字段的有效值的范围。

        所有字段可以表示为long整数。 此方法返回描述该值的有效范围的对象。 该时间对象的值用于提高返回范围的精度。 如果日期时间无法返回范围，因为该字段不受支持或由于其他原因，将抛出异常。

        请注意，结果仅描述最小和最大有效值，重要的是不要太多读取它们。 例如，可以在该范围内的值对该字段无效。

        Specified by:
        range在接口 TemporalAccessor
        参数
        field - 查询范围的字段，不为null
        结果
        字段的有效值的范围不为null

      • get

        default int get​(TemporalField field)
        描述从接口TemporalAccessor复制
        获取指定字段的int 。

        这将查询指定字段的值的日期时间。 返回的值将始终在该字段的值的有效范围内。 如果日期时间不能返回值，因为该字段不受支持或由于其他原因，将抛出异常。

        Specified by:
        get在接口 TemporalAccessor
        参数
        field - 要获取的字段，不为null
        结果
        该字段的值在值的有效范围内

      • getLong

        default long getLong​(TemporalField field)
        说明从接口TemporalAccessor复制
        获取指定字段的long 。

        这将查询指定字段的值的日期时间。 返回的值可能在该字段的值的有效范围之外。 如果日期时间不能返回值，因为该字段不受支持或由于其他原因，将抛出异常。

        Specified by:
        getLong在接口 TemporalAccessor
        参数
        field - 要获取的字段，不为null
        结果
        该字段的值

      • toLocalDate

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

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

        结果
        此日期时间的日期部分不为null

      • toLocalTime

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

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

        结果
        这个日期时间的一部分，不是null

      • toLocalDateTime

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

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

        结果
        这个日期时间的本地日期时间部分，不为空

      • getChronology

        default Chronology getChronology​()
        获得这个日期时间的年表。

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

        结果
        年表，不为空

      • getOffset

        ZoneOffset getOffset​()
        获取区域偏移量，例如“+01：00”。

        这是当地时间与UTC /格林威治的抵消。

        结果
        区域偏移，不为空

      • getZone

        ZoneId getZone​()
        获取区域ID，例如“欧洲/巴黎”。

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

        结果
        区域ID，不为空

      • withEarlierOffsetAtOverlap

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

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

        如果在不重叠的情况下调用此方法，则返回this 。

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

        结果
        一个 ChronoZonedDateTime基于这个日期时间与较早的偏移量，不为null
        异常
        DateTimeException - 如果没有找到该区域的规则
        DateTimeException - 如果没有规则在此日期时间内有效

      • withLaterOffsetAtOverlap

        ChronoZonedDateTime<D> withLaterOffsetAtOverlap​()
        返回此日期的副本，将区域偏移更改为本地时间线重叠的两个有效偏移量的后面。

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

        如果在不重叠的情况下调用此方法，则返回this 。

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

        结果
        一个 ChronoZonedDateTime基于这个日期时间与稍后的偏移量，不为null
        异常
        DateTimeException - 如果没有找到该区域的规则
        DateTimeException - 如果没有规则在此日期时间内有效

      • withZoneSameLocal

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

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

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

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

        参数
        zone - 要更改的时区，不为空
        结果
        一个 ChronoZonedDateTime基于此日期时间与请求的区域，不为null

      • withZoneSameInstant

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

        该方法更改时区并保留即时。 这通常会导致本地日期时间的更改。

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

        要保持本地时间更改偏移量，请使用withZoneSameLocal(ZoneId) 。

        参数
        zone - 要更改的时区，不为空
        结果
        一个 ChronoZonedDateTime基于这个日期时间与请求的区域，不为null
        异常
        DateTimeException - 如果结果超出支持的日期范围

      • isSupported

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

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

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

        如果该字段是不是一个ChronoField ，则此方法的结果是通过调用得到TemporalField.isSupportedBy(TemporalAccessor)传递this作为参数。 字段是否受支持由字段决定。

        Specified by:
        isSupported在接口 TemporalAccessor
        参数
        field - 要检查的字段，null返回false
        结果
        如果可以查询该字段，则为true，否则为false

      • isSupported

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

        这将检查是否可以从此日期时间添加或减去指定的单位。 如果是false，那么调用plus(long, TemporalUnit)和minus方法会抛出异常。

        支持单位的集合由年表定义，通常包括除了FOREVER之外的所有ChronoUnit单位。

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

        Specified by:
        isSupported在接口 Temporal
        参数
        unit - 要检查的单位，null返回false
        结果
        如果可以添加/减去单位，则为真，否则为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在接口 Temporal
        参数
        adjuster - 调整器使用，不为空
        结果
        具有指定调整的相同类型的对象，不为null
        异常
        DateTimeException - 如果无法进行调整
        ArithmeticException - 如果发生数字溢出

      • with

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

        这将返回一个基于该对象的新对象，其中指定字段的值已更改。 例如，在LocalDate ，这可以用于设置年，月或月的日期。 返回的对象将具有与该对象相同的可观察类型。

        在某些情况下，更改字段尚未完全定义。 例如，如果目标对象是代表1月31日的日期，则将月份更改为2月份将不清楚。 在这种情况下，该领域负责解决结果。 通常，它将选择先前的有效日期，这将是本例中最后一个有效的二月份。

        Specified by:
        with在接口 Temporal
        参数
        field - 要在结果中设置的字段，不为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
        结果
        具有指定调整的相同类型的对象，不为null
        异常
        DateTimeException - 如果不能添加
        ArithmeticException - 如果发生数字溢出

      • plus

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

        此方法基于添加了指定句点的新对象。 例如，在LocalDate ，这可以用来添加几年，几个月或几天。 返回的对象将具有与该对象相同的可观察类型。

        在某些情况下，更改字段尚未完全定义。 例如，如果目标对象是代表1月31日的日期，则添加一个月将不清楚。 在这种情况下，该领域负责解决结果。 通常，它将选择先前的有效日期，这将是本例中最后一个有效的二月份。

        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日的日期，则减去一个月将不清楚。 在这种情况下，该领域负责解决结果。 通常，它将选择先前的有效日期，这将是本例中最后一个有效的二月份。

        Specified by:
        minus在接口 Temporal
        参数
        amountToSubtract - 扣除指定单位的金额，可能为负数
        unit - 减去量的单位，不为空
        结果
        与指定周期相同类型的对象减去，不为空
        异常
        DateTimeException - 如果不能减去单位
        ArithmeticException - 如果发生数字溢出

      • query

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

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

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

        Specified by:
        query在接口 TemporalAccessor
        参数类型
        R - 结果的类型
        参数
        query - 要调用的查询，不为空
        结果
        查询结果可能返回null（由查询定义）
        异常
        DateTimeException - 如果无法查询（由查询定义）
        ArithmeticException - 如果发生数字溢出（由查询定义）

      • format

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

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

        默认实现必须如下所示： 

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

      • toInstant

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

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

        结果
        一个 Instant代表同一时刻，不为空

      • toEpochSecond

        default long toEpochSecond​()
        将此日期时间转换为从1970-01-01T00：00：00Z的时期开始的秒数。

        这使用local date-time和offset来计算历时秒值，这是从1970-01-01T00：00：00Z起经过的秒数。 时代之后的时代的实体是积极的，较早的是负的。

        结果
        从1970-01-01T00：00：00Z的时代开始的秒数

      • compareTo

        default int compareTo​(ChronoZonedDateTime<?> other)
        将此日期时间与其他日期时间进行比较，包括年表。

        比较首先在瞬间，然后在当地的日期时间，然后在区域ID，然后在时间顺序。 它与“等于”一致，由Comparable定义。

        如果所有被比较的日期时间对象都在相同的年表中，则不需要额外的年表。

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

        Specified by:
        compareTo在接口 Comparable<D extends ChronoLocalDate>
        参数
        other - 其他日期时间来比较，不为null
        结果
        比较器值为负，如果较小，则如果较大则为正

      • isBefore

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

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

        该默认实现基于第二纪和第二秒执行比较。

        参数
        other - 与之对比的其他日期时间，不为空
        结果
        如果这一点在指定的日期时间之前，则为true

      • isAfter

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

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

        该默认实现基于第二纪和第二秒执行比较。

        参数
        other - 与之对比的其他日期时间，不为空
        结果
        如果这是指定的日期时间后，则为true

      • isEqual

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

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

        该默认实现基于第二纪和第二秒执行比较。

        参数
        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