jdk-sandbox: comparison jdk/src/share/classes/java/time/temporal/TemporalUnit.java

equal deleted inserted replaced

-:c588664d547e
+:55b829ca2334
 * <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.
 /**
 * 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.
 * {@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 {
 * 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 temporal  the temporal object to adjust, not null
-* @param periodToAdd  the period of this unit to add, positive or negative
+* @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
-* <p>
+* of the same type.
-* The period will be positive if the second date-time is after the first, and
+* <p>
-* negative if the second date-time is before the first.
+* This calculates the period between two temporals in terms of this unit.
-* Call {@link SimplePeriod#abs() abs()} on the result to ensure that the result
+* The start and end points are supplied as temporal objects and must be
-* is always positive.
+* of the same type.
-* <p>
+* The result will be negative if the end is before the start.
-* The result can be queried for the {@link SimplePeriod#getAmount() amount}, the
+* For example, the period in hours between two temporal objects can be
-* {@link SimplePeriod#getUnit() unit} and used directly in addition/subtraction:
+* 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>
+* 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>
-*  date = date.minus(MONTHS.between(start, end));
+*   // 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.
-* @param <R>  the type of the Temporal object; the two date-times must be of the same type
+* <p>
-* @param dateTime1  the base temporal object, not null
+* For example, this method allows the number of days between two dates to
-* @param dateTime2  the other temporal object, not null
+* be calculated:
+* <pre>
+*  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 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
-<R extends Temporal> SimplePeriod between(R dateTime1, R dateTime2);
+* @throws ArithmeticException if numeric overflow occurs
+*/
+long between(Temporal temporal1, Temporal temporal2);
 //-----------------------------------------------------------------------
 /**
 * Outputs this unit as a {@code String} using the name.
 *

changeset 15658	55b829ca2334
parent 15289	3ac550392e43
child 16852	60207b2b4b42