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

Print this page

        

@@ -79,20 +79,20 @@
  * a {@code long} to handle large values. Year, month and day-of-month are
  * simple examples of fields, but they also include instant and offsets.
  * See {@link ChronoField} for the standard set of fields.
  * <p>
  * Two pieces of date/time information cannot be represented by numbers,
- * the {@linkplain Chrono chronology} and the {@linkplain ZoneId time-zone}.
+ * the {@linkplain java.time.chrono.Chronology chronology} and the {@linkplain ZoneId time-zone}.
  * These can be accessed via {@link #query(TemporalQuery) queries} using
  * the static methods defined on {@link Queries}.
  * <p>
  * This interface is a framework-level interface that should not be widely
  * used in application code. Instead, applications should create and pass
  * around instances of concrete types, such as {@code LocalDate}.
  * There are many reasons for this, part of which is that implementations
  * of this interface may be in calendar systems other than ISO.
- * See {@link ChronoLocalDate} for a fuller discussion of the issues.
+ * See {@link java.time.chrono.ChronoLocalDate} for a fuller discussion of the issues.
  *
  * <h3>When to implement</h3>
  * <p>
  * A class should implement this interface if it meets three criteria:
  * <p><ul>

@@ -181,11 +181,11 @@
      * Implementations must check and handle all fields defined in {@link ChronoField}.
      * If the field is supported, then the adjustment must be performed.
      * If unsupported, then a {@code DateTimeException} must be thrown.
      * <p>
      * If the field is not a {@code ChronoField}, then the result of this method
-     * is obtained by invoking {@code TemporalField.doWith(Temporal, long)}
+     * is obtained by invoking {@code TemporalField.adjustInto(Temporal, long)}
      * passing {@code this} as the first argument.
      * <p>
      * Implementations must not alter either this object or the specified temporal object.
      * Instead, an adjusted copy of the original must be returned.
      * This provides equivalent, safe behavior for immutable and mutable implementations.

@@ -200,13 +200,13 @@
 
     //-----------------------------------------------------------------------
     /**
      * Returns an object of the same type as this object with an amount added.
      * <p>
-     * This adjusts this temporal, adding according to the rules of the specified adder.
-     * The adder is typically a {@link java.time.Period} but may be any other type implementing
-     * the {@link TemporalAdder} interface, such as {@link java.time.Duration}.
+     * This adjusts this temporal, adding according to the rules of the specified amount.
+     * The amount is typically a {@link java.time.Period} but may be any other type implementing
+     * the {@link TemporalAmount} interface, such as {@link java.time.Duration}.
      * <p>
      * Some example code indicating how and why this method is used:
      * <pre>
      *  date = date.plus(period);                      // add a Period instance
      *  date = date.plus(duration);                    // add a Duration instance

@@ -222,20 +222,20 @@
      * Instead, an adjusted copy of the original must be returned.
      * This provides equivalent, safe behavior for immutable and mutable implementations.
      * <p>
      * The default implementation must behave equivalent to this code:
      * <pre>
-     *  return adder.addTo(this);
+     *  return amount.addTo(this);
      * </pre>
      *
-     * @param adder  the adder to use, not null
+     * @param amount  the amount to add, not null
      * @return an object of the same type with the specified adjustment made, not null
      * @throws DateTimeException if the addition cannot be made
      * @throws ArithmeticException if numeric overflow occurs
      */
-    public default Temporal plus(TemporalAdder adder) {
-        return adder.addTo(this);
+    public default Temporal plus(TemporalAmount amount) {
+        return amount.addTo(this);
     }
 
     /**
      * Returns an object of the same type as this object with the specified period added.
      * <p>

@@ -256,11 +256,11 @@
      * Implementations must check and handle all units defined in {@link ChronoUnit}.
      * If the unit is supported, then the addition must be performed.
      * If unsupported, then a {@code DateTimeException} must be thrown.
      * <p>
      * If the unit is not a {@code ChronoUnit}, then the result of this method
-     * is obtained by invoking {@code TemporalUnit.doPlus(Temporal, long)}
+     * is obtained by invoking {@code TemporalUnit.addTo(Temporal, long)}
      * passing {@code this} as the first argument.
      * <p>
      * Implementations must not alter either this object or the specified temporal object.
      * Instead, an adjusted copy of the original must be returned.
      * This provides equivalent, safe behavior for immutable and mutable implementations.

@@ -275,13 +275,13 @@
 
     //-----------------------------------------------------------------------
     /**
      * Returns an object of the same type as this object with an amount subtracted.
      * <p>
-     * This adjusts this temporal, subtracting according to the rules of the specified subtractor.
-     * The subtractor is typically a {@link java.time.Period} but may be any other type implementing
-     * the {@link TemporalSubtractor} interface, such as {@link java.time.Duration}.
+     * This adjusts this temporal, subtracting according to the rules of the specified amount.
+     * The amount is typically a {@link java.time.Period} but may be any other type implementing
+     * the {@link TemporalAmount} interface, such as {@link java.time.Duration}.
      * <p>
      * Some example code indicating how and why this method is used:
      * <pre>
      *  date = date.minus(period);                      // subtract a Period instance
      *  date = date.minus(duration);                    // subtract a Duration instance

@@ -297,20 +297,20 @@
      * Instead, an adjusted copy of the original must be returned.
      * This provides equivalent, safe behavior for immutable and mutable implementations.
      * <p>
      * The default implementation must behave equivalent to this code:
      * <pre>
-     *  return subtractor.subtractFrom(this);
+     *  return amount.subtractFrom(this);
      * </pre>
      *
-     * @param subtractor  the subtractor to use, not null
+     * @param amount  the amount to subtract, not null
      * @return an object of the same type with the specified adjustment made, not null
      * @throws DateTimeException if the subtraction cannot be made
      * @throws ArithmeticException if numeric overflow occurs
      */
-    public default Temporal minus(TemporalSubtractor subtractor) {
-        return subtractor.subtractFrom(this);
+    public default Temporal minus(TemporalAmount amount) {
+        return amount.subtractFrom(this);
     }
 
     /**
      * Returns an object of the same type as this object with the specified period subtracted.
      * <p>

@@ -364,17 +364,26 @@
      * 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>
-     * This method operates in association with {@link TemporalUnit#between}.
-     * The result of this method is a {@code long} representing the amount of
-     * the specified unit. By contrast, the result of {@code between} is an
-     * object that can be 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 TemporalUnit#between(Temporal, Temporal)}:
      * <pre>
-     *   long period = start.periodUntil(end, HOURS);   // this method
-     *   dateTime.plus(HOURS.between(start, end));      // use in plus/minus
+     *   // these two lines are equivalent
+     *   temporal = start.periodUntil(end, unit);
+     *   temporal = unit.between(start, end);
+     * </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>
+     *  long daysBetween = start.periodUntil(end, DAYS);
+     *  // or alternatively
+     *  long daysBetween = DAYS.between(start, end);
      * </pre>
      *
      * <h3>Specification for implementors</h3>
      * Implementations must begin by checking to ensure that the input temporal
      * object is of the same observable type as the implementation.

@@ -392,18 +401,20 @@
      *  // check input temporal is the same type as this class
      *  if (unit instanceof ChronoUnit) {
      *    // if unit is supported, then calculate and return result
      *    // else throw DateTimeException for unsupported units
      *  }
-     *  return unit.between(this, endTime).getAmount();
+     *  return unit.between(this, endTemporal);
      * </pre>
      * <p>
-     * The target object must not be altered by this method.
+     * Neither this object, nor the specified temporal, may be altered.
      *
      * @param endTemporal  the end temporal, of the same type as this object, not null
      * @param unit  the unit to measure the period in, not null
-     * @return the amount of the period between this and the end
+     * @return the period between this temporal object and the specified one in terms of
+     *  the unit; positive if the specified object is later than this one, negative if
+     *  it is earlier than this one
      * @throws DateTimeException if the period cannot be calculated
      * @throws ArithmeticException if numeric overflow occurs
      */
     long periodUntil(Temporal endTemporal, TemporalUnit unit);