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

Print this page

        

*** 79,98 **** * 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}. * 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. * * <h3>When to implement</h3> * <p> * A class should implement this interface if it meets three criteria: * <p><ul> --- 79,98 ---- * 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 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 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,191 **** * 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)} * 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. --- 181,191 ---- * 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.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,212 **** //----------------------------------------------------------------------- /** * 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}. * <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 --- 200,212 ---- //----------------------------------------------------------------------- /** * 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 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,241 **** * 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); * </pre> * ! * @param adder the adder to use, 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); } /** * Returns an object of the same type as this object with the specified period added. * <p> --- 222,241 ---- * 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 amount.addTo(this); * </pre> * ! * @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(TemporalAmount amount) { ! return amount.addTo(this); } /** * Returns an object of the same type as this object with the specified period added. * <p>
*** 256,266 **** * 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)} * 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. --- 256,266 ---- * 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.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,287 **** //----------------------------------------------------------------------- /** * 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}. * <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 --- 275,287 ---- //----------------------------------------------------------------------- /** * 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 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,316 **** * 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); * </pre> * ! * @param subtractor the subtractor to use, 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); } /** * Returns an object of the same type as this object with the specified period subtracted. * <p> --- 297,316 ---- * 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 amount.subtractFrom(this); * </pre> * ! * @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(TemporalAmount amount) { ! return amount.subtractFrom(this); } /** * Returns an object of the same type as this object with the specified period subtracted. * <p>
*** 364,380 **** * 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: * <pre> ! * long period = start.periodUntil(end, HOURS); // this method ! * dateTime.plus(HOURS.between(start, end)); // use in plus/minus * </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. --- 364,389 ---- * 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 TemporalUnit#between(Temporal, Temporal)}: * <pre> ! * // 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,409 **** * // 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(); * </pre> * <p> ! * The target object must not be altered by this method. * * @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 * @throws DateTimeException if the period cannot be calculated * @throws ArithmeticException if numeric overflow occurs */ long periodUntil(Temporal endTemporal, TemporalUnit unit); --- 401,420 ---- * // 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, endTemporal); * </pre> * <p> ! * 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 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);