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);