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

Interface Temporal

  • All Superinterfaces:
    TemporalAccessor
    All Known Subinterfaces:
    ChronoLocalDate ， ChronoLocalDateTime<D> ， ChronoZonedDateTime<D>
    所有已知实现类：
    HijrahDate ， Instant ， JapaneseDate ， LocalDate ， LocalDateTime ， LocalTime ， MinguoDate ， OffsetDateTime ， OffsetTime ， ThaiBuddhistDate ， Year ， YearMonth ， ZonedDateTime 

    public interface Temporal
extends TemporalAccessor
    定义对时间对象的读写访问的框架级接口，例如日期，时间，偏移或这些的一些组合。

    这是日期，时间和偏移对象的基本界面类型，其完整性足以使用加和减操作。 它由那些可以提供和操纵信息的类实现，如fields或queries 。 有关此接口的只读版本，请参阅TemporalAccessor 。

    大多数日期和时间信息可以表示为一个数字。 这些是使用模拟TemporalField使用保持的号码long处理大值。 年份，月份和日期是字段的简单示例，但它们还包括即时和偏移量。 有关标准的字段集，请参阅ChronoField 。

    两个日期/时间信息不能由数字chronology和time-zone表示 。 这些可以通过queries使用TemporalQuery上定义的静态方法访问 。

    该接口是一个框架级接口，不应该在应用程序代码中广泛使用。 相反，应用程序应该创建并传递具体类型的实例，例如LocalDate 。 这有很多原因，其中一部分是该接口的实现可能在除ISO之外的日历系统中。 有关这些问题的更全面的讨论，请参阅ChronoLocalDate 。

    何时实施

    如果一个类符合三个条件，则应该实现此接口：

    • 它提供访问日期/时间/偏移量信息，按照TemporalAccessor
    • 一组字段是从最大到最小的
    • 该集合的字段是完整的，使得不需要其他字段来定义表示的字段的值的有效范围

    四个例子说明如下：

    • LocalDate实现了这个接口，因为它代表了从几天到永远连续的一组字段，并且不需要外部信息来确定每个日期的有效性。 因此，可以正确地执行正/负。
    • LocalTime实现这个接口，因为它表示一组从nanos到几天的连续字段，并且不需要外部信息来确定有效性。 它能够正确地执行正/负，通过包裹在一天。
    • MonthDay ，月和日的组合不实现这个界面。 虽然组合是连续的，从几天到几个月内，组合没有足够的信息来定义月日的有效价值范围。 因此，无法正确执行正/负。
    • 星期几和星期几（“星期五13号”）的组合不应该实现这个界面。 它不代表连续的一组字段，因为几天到几个星期的重叠几天到几个月。
    实现要求：
    此接口对实现的可变性没有任何限制，但是强烈建议不变性。 所有实现都必须是Comparable 。
    从以下版本开始：
    1.8

    • 方法详细信息

      • isSupported

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

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

        实现要求：
        实施必须检查并处理ChronoUnit中定义的所有单位。 如果单位得到支持，则必须返回true，否则返回false。

        如果该字段是不是一个ChronoUnit ，则此方法的结果是通过调用得到TemporalUnit.isSupportedBy(Temporal)传递this作为参数。

        当这个只读方法被调用时，实现必须确保没有可观察的状态被改变。

        参数
        unit - 要检查的单位，null返回false
        结果
        如果可以添加/减去单位，则为真，否则为false

      • with

        default Temporal 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
        实现要求：

        实现不能改变这个对象或指定的时间对象。 相反，必须退还原件的调整副本。 这为不可变和可变的实现提供了相当的安全行为。

        默认实现必须与此代码相同： 

          return adjuster.adjustInto(this);
        参数
        adjuster - 调整器使用，不为空
        结果
        具有指定调整的相同类型的对象，不为null
        异常
        DateTimeException - 如果无法进行调整
        ArithmeticException - 如果发生数字溢出

      • with

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

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

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

        实现要求：
        实现必须检查并处理ChronoField中定义的所有字段。 如果该字段被支持，则必须进行调整。 如果不支持，则必须抛出UnsupportedTemporalTypeException 。

        如果该字段是不是一个ChronoField ，则此方法的结果是通过调用得到TemporalField.adjustInto(Temporal, long)传递this作为第一个参数。

        实现不能改变这个对象。 相反，必须退还原件的调整副本。 这为不可变和可变的实现提供了相当的安全行为。

        参数
        field - 要在结果中设置的字段，不为null
        newValue - 结果中字段的新值
        结果
        与指定字段集相同类型的对象，不为null
        异常
        DateTimeException - 如果字段无法设置
        UnsupportedTemporalTypeException - 如果该字段不被支持
        ArithmeticException - 如果发生数字溢出

      • plus

        default Temporal 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不保证返回相同的日期时间。

        实现要求：

        实现不能改变这个对象或指定的时间对象。 相反，必须退还原件的调整副本。 这为不可变和可变的实现提供了相当的安全行为。

        默认实现必须与此代码相同： 

          return amount.addTo(this);
        参数
        amount - 要添加的金额，不为null
        结果
        具有指定调整的相同类型的对象，不为null
        异常
        DateTimeException - 如果不能添加
        ArithmeticException - 如果发生数字溢出

      • plus

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

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

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

        实现要求：
        实施必须检查并处理ChronoUnit中定义的所有单位。 如果单元被支持，则必须执行添加。 如果不支持，则必须抛出一个UnsupportedTemporalTypeException 。

        如果该单元不是ChronoUnit ，则此方法的结果是通过调用得到TemporalUnit.addTo(Temporal, long)传递this作为第一个参数。

        实现不能改变这个对象。 相反，必须退还原件的调整副本。 这为不可变和可变的实现提供了相当的安全行为。

        参数
        amountToAdd - 要添加的指定单位的数量，可能为负数
        unit - 要添加的单位，不为null
        结果
        与指定期间相同类型的对象添加，不为空
        异常
        DateTimeException - 如果无法添加本机
        UnsupportedTemporalTypeException - 如果不支持本机
        ArithmeticException - 如果发生数字溢出

      • minus

        default Temporal 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不保证返回相同的日期时间。

        实现要求：

        实现不能改变这个对象或指定的时间对象。 相反，必须退还原件的调整副本。 这为不可变和可变的实现提供了相当的安全行为。

        默认实现必须与此代码相同： 

          return amount.subtractFrom(this);
        参数
        amount - 减去量，不为空
        结果
        具有指定调整的相同类型的对象，不为null
        异常
        DateTimeException - 如果不能进行减法
        ArithmeticException - 如果发生数字溢出

      • minus

        default Temporal minus​(long amountToSubtract,
                       TemporalUnit unit)
        返回与该对象相同类型的对象，并减去指定的时间段。

        该方法返回一个基于该对象的新对象，减去指定的时间段。 例如，在LocalDate ，这可以用来减去几年，几个月或几天的数量。 返回的对象将具有与该对象相同的可观察类型。

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

        实现要求：
        实现必须以与默认方法行为相当的庄园行为。

        实现不能改变这个对象。 相反，必须退还原件的调整副本。 这为不可变和可变的实现提供了相当的安全行为。

        默认实现必须与此代码相同： 

          return (amountToSubtract == Long.MIN_VALUE ?
      plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
        参数
        amountToSubtract - 扣除指定单位的金额，可能为负数
        unit - 减去量的单位，不为空
        结果
        与指定周期相同类型的对象减去，不为空
        异常
        DateTimeException - 如果不能减去单位
        UnsupportedTemporalTypeException - 如果不支持本机
        ArithmeticException - 如果发生数字溢出

      • until

        long until​(Temporal endExclusive,
           TemporalUnit unit)
        根据指定的单位计算直到另一个时间的时间量。

        这可以计算单个TemporalUnit之间的两个时间对象之间的时间量。 起点和终点是this和指定的时间。 如果不同，终点被转换为与起始点相同的类型。 如果结束在开始之前，结果将为负数。 例如，可以使用startTime.until(endTime, HOURS)计算两个时间对象之间的小时startTime.until(endTime, HOURS) 。

        计算返回一个整数，表示两个时间之间的完整单位数。 例如，11时30分至13时29分之间的小时数将只有1小时，因为距离两小时不到1分钟。

        使用这种方法有两种等效的方法。 第一个是直接调用这个方法。 二是使用TemporalUnit.between(Temporal, Temporal) ： 

          // these two lines are equivalent
   temporal = start.until(end, unit);
   temporal = unit.between(start, end);
        应该根据这种做法进行选择，使代码更易读。

        例如，该方法允许计算两个日期之间的天数： 

          long daysBetween = start.until(end, DAYS);
  // or alternatively
  long daysBetween = DAYS.between(start, end);
        实现要求：
        实现必须首先检查以确保输入的时间对象与实现具有相同的可观察类型。 然后，他们必须对所有ChronoUnit的实例进行计算。 一个UnsupportedTemporalTypeException必须抛出ChronoUnit情况下是不支持。

        如果该单元不是ChronoUnit ，则此方法的结果是通过调用得到TemporalUnit.between(Temporal, Temporal)传递this作为第一个参数和转换后的输入时间作为第二个参数。

        总而言之，实现必须以与此伪代码相同的方式表现： 

          // convert the end temporal to the same type as this class
  if (unit instanceof ChronoUnit) {
    // if unit is supported, then calculate and return result
    // else throw UnsupportedTemporalTypeException for unsupported units
  }
  return unit.between(this, convertedEndTemporal);

        请注意，如果两个时间对象具有与getClass()评估的完全相同的类型，则只能调用该单元的between方法。

        当这个只读方法被调用时，实现必须确保没有可观察的状态被改变。

        参数
        endExclusive - 结束时间，排他，转换为与此对象相同的类型，不为null
        unit - 衡量金额的单位，不为空
        结果
        在该时间对象与指定单位之间的时间量; 如果指定的对象晚于此值，则为正数，如果比此更早，则为负数
        异常
        DateTimeException - 如果不能计算金额，或者结束时间不能转换为与该时间相同的类型
        UnsupportedTemporalTypeException - 如果不支持本机
        ArithmeticException - 如果发生数字溢出