src/share/classes/java/time/temporal/TemporalUnit.java

Print this page

        

@@ -73,11 +73,11 @@
  * <p>
  * An instance of this interface represents the unit itself, rather than an amount of the unit.
  * See {@link Period} for a class that represents an amount in terms of the common units.
  * <p>
  * The most commonly used units are defined in {@link ChronoUnit}.
- * Further units are supplied in {@link ISOFields}.
+ * Further units are supplied in {@link IsoFields}.
  * Units can also be written by application code by implementing this interface.
  * <p>
  * The unit works using double dispatch. Client code calls methods on a date-time like
  * {@code LocalDateTime} which check if the unit is a {@code ChronoUnit}.
  * If it is, then the date-time must handle it.

@@ -103,10 +103,11 @@
 
     /**
      * Gets the duration of this unit, which may be an estimate.
      * <p>
      * All units return a duration measured in standard nanoseconds from this method.
+     * The duration will be positive and non-zero.
      * For example, an hour has a duration of {@code 60 * 60 * 1,000,000,000ns}.
      * <p>
      * Some units may return an accurate duration while others return an estimate.
      * For example, days have an estimated duration due to the possibility of
      * daylight saving time changes.

@@ -140,11 +141,11 @@
      * {@link Temporal#plus(long, TemporalUnit)}.
      *
      * @param temporal  the temporal object to check, not null
      * @return true if the unit is supported
      */
-    public default boolean isSupported(Temporal temporal) {
+    public default boolean isSupportedBy(Temporal temporal) {
         try {
             temporal.plus(1, this);
             return true;
         } catch (RuntimeException ex) {
             try {

@@ -167,54 +168,80 @@
      * There are two equivalent ways of using this method.
      * The first is to invoke this method directly.
      * The second is to use {@link Temporal#plus(long, TemporalUnit)}:
      * <pre>
      *   // these two lines are equivalent, but the second approach is recommended
-     *   temporal = thisUnit.doPlus(temporal);
+     *   temporal = thisUnit.addTo(temporal);
      *   temporal = temporal.plus(thisUnit);
      * </pre>
      * It is recommended to use the second approach, {@code plus(TemporalUnit)},
      * as it is a lot clearer to read in code.
      * <p>
      * Implementations should perform any queries or calculations using the units
      * available in {@link ChronoUnit} or the fields available in {@link ChronoField}.
-     * If the field is not supported a {@code DateTimeException} must be thrown.
+     * If the unit is not supported a {@code DateTimeException} must be thrown.
      * <p>
      * Implementations must not alter the specified temporal object.
      * Instead, an adjusted copy of the original must be returned.
      * This provides equivalent, safe behavior for immutable and mutable implementations.
      *
      * @param <R>  the type of the Temporal object
-     * @param dateTime  the temporal object to adjust, not null
-     * @param periodToAdd  the period of this unit to add, positive or negative
+     * @param temporal  the temporal object to adjust, not null
+     * @param amount  the amount of this unit to add, positive or negative
      * @return the adjusted temporal object, not null
      * @throws DateTimeException if the period cannot be added
      */
-    <R extends Temporal> R doPlus(R dateTime, long periodToAdd);
+    <R extends Temporal> R addTo(R temporal, long amount);
 
     //-----------------------------------------------------------------------
     /**
-     * Calculates the period in terms of this unit between two temporal objects of the same type.
+     * Calculates the period in terms of this unit between two temporal objects
+     * of the same type.
      * <p>
-     * The period will be positive if the second date-time is after the first, and
-     * negative if the second date-time is before the first.
-     * Call {@link SimplePeriod#abs() abs()} on the result to ensure that the result
-     * is always positive.
+     * This calculates the period between two temporals in terms of this unit.
+     * The start and end points are supplied as temporal objects and must be
+     * of the same type.
+     * The result will be negative if the end is before the start.
+     * For example, the period in hours between two temporal objects can be
+     * calculated using {@code HOURS.between(startTime, endTime)}.
+     * <p>
+     * The calculation returns a whole number, representing the number of
+     * complete units between the two temporals.
+     * For example, the period in hours between the times 11:30 and 13:29
+     * will only be one hour as it is one minute short of two hours.
      * <p>
-     * The result can be queried for the {@link SimplePeriod#getAmount() amount}, the
-     * {@link SimplePeriod#getUnit() unit} and used directly in addition/subtraction:
+     * There are two equivalent ways of using this method.
+     * The first is to invoke this method directly.
+     * The second is to use {@link Temporal#periodUntil(Temporal, TemporalUnit)}:
+     * <pre>
+     *   // these two lines are equivalent
+     *   temporal = thisUnit.between(start, end);
+     *   temporal = start.periodUntil(end, thisUnit);
+     * </pre>
+     * The choice should be made based on which makes the code more readable.
+     * <p>
+     * For example, this method allows the number of days between two dates to
+     * be calculated:
      * <pre>
-     *  date = date.minus(MONTHS.between(start, end));
+     *  long daysBetween = DAYS.between(start, end);
+     *  // or alternatively
+     *  long daysBetween = start.periodUntil(end, DAYS);
      * </pre>
+     * <p>
+     * Implementations should perform any queries or calculations using the units
+     * available in {@link ChronoUnit} or the fields available in {@link ChronoField}.
+     * If the unit is not supported a {@code DateTimeException} must be thrown.
+     * Implementations must not alter the specified temporal objects.
      *
-     * @param <R>  the type of the Temporal object; the two date-times must be of the same type
-     * @param dateTime1  the base temporal object, not null
-     * @param dateTime2  the other temporal object, not null
+     * @param temporal1  the base temporal object, not null
+     * @param temporal2  the other temporal object, not null
      * @return the period between datetime1 and datetime2 in terms of this unit;
-     *      positive if datetime2 is later than datetime1, not null
+     *  positive if datetime2 is later than datetime1, negative if earlier
+     * @throws DateTimeException if the period cannot be calculated
+     * @throws ArithmeticException if numeric overflow occurs
      */
-    <R extends Temporal> SimplePeriod between(R dateTime1, R dateTime2);
+    long between(Temporal temporal1, Temporal temporal2);
 
     //-----------------------------------------------------------------------
     /**
      * Outputs this unit as a {@code String} using the name.
      *