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

Print this page

        

*** 73,83 **** * <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}. * 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. --- 73,83 ---- * <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}. * 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,112 **** --- 103,113 ---- /** * 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,150 **** * {@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) { try { temporal.plus(1, this); return true; } catch (RuntimeException ex) { try { --- 141,151 ---- * {@link Temporal#plus(long, TemporalUnit)}. * * @param temporal the temporal object to check, not null * @return true if the unit is supported */ ! public default boolean isSupportedBy(Temporal temporal) { try { temporal.plus(1, this); return true; } catch (RuntimeException ex) { try {
*** 167,220 **** * 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 = 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. * <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 * @return the adjusted temporal object, not null * @throws DateTimeException if the period cannot be added */ ! <R extends Temporal> R doPlus(R dateTime, long periodToAdd); //----------------------------------------------------------------------- /** ! * 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. * <p> ! * The result can be queried for the {@link SimplePeriod#getAmount() amount}, the ! * {@link SimplePeriod#getUnit() unit} and used directly in addition/subtraction: * <pre> ! * date = date.minus(MONTHS.between(start, end)); * </pre> * ! * @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 * @return the period between datetime1 and datetime2 in terms of this unit; ! * positive if datetime2 is later than datetime1, not null */ ! <R extends Temporal> SimplePeriod between(R dateTime1, R dateTime2); //----------------------------------------------------------------------- /** * Outputs this unit as a {@code String} using the name. * --- 168,247 ---- * 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.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 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 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 addTo(R temporal, long amount); //----------------------------------------------------------------------- /** ! * Calculates the period in terms of this unit between two temporal objects ! * of the same type. * <p> ! * 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> ! * 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> ! * 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, negative if earlier ! * @throws DateTimeException if the period cannot be calculated ! * @throws ArithmeticException if numeric overflow occurs */ ! long between(Temporal temporal1, Temporal temporal2); //----------------------------------------------------------------------- /** * Outputs this unit as a {@code String} using the name. *