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

Interface ChronoLocalDateTime<D extends ChronoLocalDate>

  • 参数类型
    D - 此日期时间日期的具体类型
    All Superinterfaces:
    Comparable<ChronoLocalDateTime<?>> ， Temporal ， TemporalAccessor ， TemporalAdjuster
    所有已知实现类：
    LocalDateTime 
    public interface ChronoLocalDateTime<D extends ChronoLocalDate>
extends Temporal, TemporalAdjuster, Comparable<ChronoLocalDateTime<?>>
    用于高级全球化用例的任意时间顺序中没有时区的日期时间。

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

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

    何时使用此界面

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

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

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

    • 方法详细信息

      • from

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

        这基于指定的时间获得本地日期时间。 TemporalAccessor表示一组任意日期和时间信息，该工厂将其转换为ChronoLocalDateTime的实例。

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

        此方法匹配功能接口TemporalQuery的签名，允许通过方法引用ChronoLocalDateTime::from将其用作查询。

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

      • getChronology

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

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

        结果
        年表，不是空的

      • toLocalDate

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

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

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

      • toLocalTime

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

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

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

      • isSupported

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

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

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

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

        Specified by:
        isSupported in interface TemporalAccessor
        参数
        字段 - 要检查的字段，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
        结果
        如果可以添加/减去单位，则为true，否则为false

      • with

        default ChronoLocalDateTime<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
        结果
        具有指定调整的相同类型的对象，而不是null
        异常
        DateTimeException - 如果无法进行调整
        ArithmeticException - 如果发生数字溢出

      • with

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

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

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

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

      • plus

        default ChronoLocalDateTime<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 in interface Temporal
        参数
        amount - 要添加的金额，而不是空
        结果
        具有指定调整的相同类型的对象，而不是null
        异常
        DateTimeException - 如果无法添加
        ArithmeticException - 如果发生数字溢出

      • plus

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

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

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

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

      • minus

        default ChronoLocalDateTime<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 ChronoLocalDateTime<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 - 如果发生数字溢出（由查询定义）

      • adjustInto

        default Temporal adjustInto​(Temporal temporal)
        调整指定的时态对象以使其具有与此对象相同的日期和时间。

        这将返回与输入相同的可观察类型的时间对象，并将日期和时间更改为与此相同。

        调整相当于使用Temporal.with(TemporalField, long)两次，将ChronoField.EPOCH_DAY和ChronoField.NANO_OF_DAY作为字段。

        在大多数情况下，使用Temporal.with(TemporalAdjuster)更清楚地反转调用模式： 

          // these two lines are equivalent, but the second approach is recommended
   temporal = thisLocalDateTime.adjustInto(temporal);
   temporal = temporal.with(thisLocalDateTime);

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

        Specified by:
        adjustInto ，接口 TemporalAdjuster
        参数
        temporal - 要调整的目标对象，而不是null
        结果
        调整后的对象，不为空
        异常
        DateTimeException - 如果无法进行调整
        ArithmeticException - 如果发生数字溢出

      • format

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

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

        默认实现必须如下所示： 

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

      • atZone

        ChronoZonedDateTime<D> atZone​(ZoneId zone)
        将此时间与时区相结合以创建ChronoZonedDateTime 。

        这将返回在指定时区的此日期时间形成的ChronoZonedDateTime 。 结果将尽可能与此日期时间匹配。 时区规则（例如夏令时）意味着并非每个本地日期时间对指定区域都有效，因此可以调整本地日期时间。

        本地日期时间在时间线上解析为单个瞬间。 这是通过从区域ID的rules定义的本地日期时间中找到UTC / Greenwich的有效偏移量来实现的。

        在大多数情况下，本地日期时间只有一个有效的偏移量。 在重叠的情况下，时钟被设置回来，有两个有效的偏移。 该方法使用通常对应于“夏天”的较早偏移。

        在间隙的情况下，时钟向前跳跃，没有有效的偏移。 相反，将本地日期时间调整为稍后的间隙长度。 对于典型的一小时夏令时变化，本地日期时间将在一小时后移动到通常对应于“夏天”的偏移量。

        要在重叠期间获得稍后的偏移量，请对此方法的结果调用ChronoZonedDateTime.withLaterOffsetAtOverlap() 。

        参数
        zone - 要使用的时区，不为空
        结果
        从此日期时间形成的分区日期时间，而不是null

      • toInstant

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

        这将本地日期时间和指定的偏移量组合在一起形成Instant 。

        此默认实现从日期的时间段和时间的第二天开始计算。

        参数
        offset - 用于转换的偏移量，不为null
        结果
        Instant表示同一时刻，不为空

      • toEpochSecond

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

        这将此本地日期时间和指定的偏移量组合在一起，以计算纪元秒值，即从1970-01-01T00：00：00Z开始经过的秒数。 在时代之后的时间线上的实例是正的，之前是负的。

        此默认实现从日期的时间段和时间的第二天开始计算。

        参数
        offset - 用于转换的偏移量，不为null
        结果
        1970-01-01T00：00：00Z时代的秒数

      • compareTo

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

        比较首先基于潜在的时间线日期时间，然后是年表。 它与“等于”一致，如Comparable所定义。

        例如，以下是比较器顺序：

        1. 2012-12-03T12:00 (ISO)
        2. 2012-12-04T12:00 (ISO)
        3. 2555-12-04T12:00 (ThaiBuddhist)
        4. 2012-12-05T12:00 (ISO)
        值＃2和＃3表示时间线上的相同日期时间。 当两个值表示相同的日期时间时，将比较年表ID以区分它们。 需要此步骤以使排序“与equals一致”。

        如果要比较的所有日期时间对象都是相同的年表，则不需要附加的年表阶段，只使用本地日期时间。

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

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

      • isAfter

        default boolean isAfter​(ChronoLocalDateTime<?> other)
        检查此日期时间是否在指定的日期时间之后，忽略年表。

        该方法与compareTo(java.time.chrono.ChronoLocalDateTime<?>)中的比较不同之处在于它仅比较基础日期时间而非年表。 这允许基于时间线位置比较不同日历系统中的日期。

        此默认实现基于纪元日和纳米日执行比较。

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

      • isBefore

        default boolean isBefore​(ChronoLocalDateTime<?> other)
        检查此日期时间是否在指定的日期时间之前，忽略年表。

        该方法与compareTo(java.time.chrono.ChronoLocalDateTime<?>)中的比较不同之处在于它仅比较基础日期时间而非年表。 这允许基于时间线位置比较不同日历系统中的日期。

        此默认实现基于纪元日和纳米日执行比较。

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

      • isEqual

        default boolean isEqual​(ChronoLocalDateTime<?> other)
        检查此日期时间是否等于指定的日期时间，忽略年表。

        该方法与compareTo(java.time.chrono.ChronoLocalDateTime<?>)中的比较不同之处在于它仅比较基础日期和时间而不是年表。 这允许基于时间线位置比较不同日历系统中的日期时间。

        此默认实现基于纪元日和纳米日执行比较。

        参数
        other - 要比较的其他日期时间，而不是null
        结果
        如果基础日期时间等于时间轴上的指定日期时间，则为true

      • equals

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

        将此日期时间与另一个日期时间进行比较，确保日期时间和年表相同。

        重写：
        equals在课程 Object
        参数
        obj - 要检查的对象，null返回false
        结果
        如果这等于另一个日期，则为true
        另请参见：
        Object.hashCode() ， HashMap

      • toString

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

        输出将包括完整的本地日期时间。

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