* This is the base interface type for date, time and offset objects that * are complete enough to be manipulated using plus and minus. * It is implemented by those classes that can provide and manipulate information * as {@link TemporalField fields} or {@link TemporalQuery queries}. * See {@link TemporalAccessor} for the read-only version of this interface. *
* Most date and time information can be represented as a number. * These are modeled using {@code TemporalField} with the number held using * 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. *
* Two pieces of date/time information cannot be represented by numbers, * the {@link Chronology chronology} and the {@link ZoneId time-zone}. * These can be accessed via {@link #query(TemporalQuery) queries} using * the static methods defined on {@link TemporalQueries}. *
* 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. * *
* A class should implement this interface if it meets three criteria: *
*
* Four examples make this clear: *
* *
* This checks if the date-time can be queried for the specified unit. * If false, then calling the {@link #plus(TemporalAmount) plus} and {@link #minus(TemporalAmount) minus} * methods will throw an exception. * *
* If the field is not a {@code ChronoUnit}, then the result of this method * is obtained by invoking {@code TemporalUnit.isSupportedBy(Temporal)} * passing {@code this} as the argument. *
* Implementations must not alter this object. * * @param unit the unit to check, null returns false * @return true if this date-time can be queried for the unit, false if not */ boolean isSupported(TemporalUnit unit); /** * Returns an adjusted object of the same type as this object with the adjustment made. *
* This adjusts this date-time according to the rules of the specified adjuster. * A simple adjuster might simply set the one of the fields, such as the year field. * A more complex adjuster might set the date to the last day of the month. * A selection of common adjustments is provided in {@link TemporalAdjusters}. * These include finding the "last day of the month" and "next Wednesday". * The adjuster is responsible for handling special cases, such as the varying * lengths of month and leap years. *
* Some example code indicating how and why this method is used: *
* date = date.with(Month.JULY); // most key classes implement TemporalAdjuster
* date = date.with(lastDayOfMonth()); // static import from TemporalAdjusters
* date = date.with(next(WEDNESDAY)); // static import from TemporalAdjusters and DayOfWeek
*
*
* * This returns a new object based on this one with the value for the specified field changed. * For example, on a {@code LocalDate}, this could be used to set the year, month or day-of-month. * The returned object will have the same observable type as this object. *
* In some cases, changing a field is not fully defined. For example, if the target object is * a date representing the 31st January, then changing the month to February would be unclear. * In cases like this, the field is responsible for resolving the result. Typically it will choose * the previous valid date, which would be the last valid day of February in this example. * *
* 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. *
* 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. * * @param field the field to set in the result, not null * @param newValue the new value of the field in the result * @return an object of the same type with the specified field set, not null * @throws DateTimeException if the field cannot be set * @throws ArithmeticException if numeric overflow occurs */ Temporal with(TemporalField field, long newValue); //----------------------------------------------------------------------- /** * Returns an object of the same type as this object with an amount added. *
* This adjusts this temporal, adding according to the rules of the specified amount. * The amount is typically a {@link Period} but may be any other type implementing * the {@link TemporalAmount} interface, such as {@link Duration}. *
* Some example code indicating how and why this method is used: *
* date = date.plus(period); // add a Period instance
* date = date.plus(duration); // add a Duration instance
* date = date.plus(workingDays(6)); // example user-written workingDays method
*
* * Note that calling {@code plus} followed by {@code minus} is not guaranteed to * return the same date-time. * *
* This method returns a new object based on this one with the specified period added. * For example, on a {@code LocalDate}, this could be used to add a number of years, months or days. * The returned object will have the same observable type as this object. *
* In some cases, changing a field is not fully defined. For example, if the target object is * a date representing the 31st January, then adding one month would be unclear. * In cases like this, the field is responsible for resolving the result. Typically it will choose * the previous valid date, which would be the last valid day of February in this example. *
* If the implementation represents a date-time that has boundaries, such as {@code LocalTime}, * then the permitted units must include the boundary unit, but no multiples of the boundary unit. * For example, {@code LocalTime} must accept {@code DAYS} but not {@code WEEKS} or {@code MONTHS}. * *
* 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. *
* 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. * * @param amountToAdd the amount of the specified unit to add, may be negative * @param unit the unit of the period to add, not null * @return an object of the same type with the specified period added, not null * @throws DateTimeException if the unit cannot be added * @throws ArithmeticException if numeric overflow occurs */ Temporal plus(long amountToAdd, TemporalUnit unit); //----------------------------------------------------------------------- /** * Returns an object of the same type as this object with an amount subtracted. *
* This adjusts this temporal, subtracting according to the rules of the specified amount. * The amount is typically a {@link Period} but may be any other type implementing * the {@link TemporalAmount} interface, such as {@link Duration}. *
* Some example code indicating how and why this method is used: *
* date = date.minus(period); // subtract a Period instance
* date = date.minus(duration); // subtract a Duration instance
* date = date.minus(workingDays(6)); // example user-written workingDays method
*
* * Note that calling {@code plus} followed by {@code minus} is not guaranteed to * return the same date-time. * *
* This method returns a new object based on this one with the specified period subtracted. * For example, on a {@code LocalDate}, this could be used to subtract a number of years, months or days. * The returned object will have the same observable type as this object. *
* In some cases, changing a field is not fully defined. For example, if the target object is * a date representing the 31st March, then subtracting one month would be unclear. * In cases like this, the field is responsible for resolving the result. Typically it will choose * the previous valid date, which would be the last valid day of February in this example. *
* If the implementation represents a date-time that has boundaries, such as {@code LocalTime}, * then the permitted units must include the boundary unit, but no multiples of the boundary unit. * For example, {@code LocalTime} must accept {@code DAYS} but not {@code WEEKS} or {@code MONTHS}. * *
* 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. * * @param amountToSubtract the amount of the specified unit to subtract, may be negative * @param unit the unit of the period to subtract, not null * @return an object of the same type with the specified period subtracted, not null * @throws DateTimeException if the unit cannot be subtracted * @throws ArithmeticException if numeric overflow occurs */ Temporal minus(long amountToSubtract, TemporalUnit unit); //----------------------------------------------------------------------- /** * Calculates the period between this temporal and another temporal in * terms of the specified unit. *
* This calculates the period between two temporals in terms of a single unit. * The start and end points are {@code this} and the specified temporal. * 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 startTime.until(endTime, HOURS)}. *
* 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. *
* 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)}: *
* // these two lines are equivalent
* between = thisUnit.between(start, end);
* between = start.until(end, thisUnit);
*
* The choice should be made based on which makes the code more readable.
* * For example, this method allows the number of days between two dates to be calculated: *
* long daysBetween = DAYS.between(start, end);
* // or alternatively
* long daysBetween = start.until(end, DAYS);
*
*
* * If the unit is not a {@code ChronoUnit}, then the result of this method * is obtained by invoking {@code TemporalUnit.between(Temporal, Temporal)} * passing {@code this} as the first argument and the input temporal as * the second argument. *
* In summary, implementations must behave in a manner equivalent to this code: *
* // 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);
*
* * 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 until(Temporal endTemporal, TemporalUnit unit); }