net.time4j.engine.Calendrical Maven / Gradle / Ivy
/*
* -----------------------------------------------------------------------
* Copyright © 2013-2017 Meno Hochschild, Abstract base class of all plain calendar date types which are
* convertible via their day epoch numbers.
*
* @param generic type of time unit compatible to {@link ChronoUnit})
* @param generic type of self reference
* @author Meno Hochschild
* @serial exclude
*/
/*[deutsch]
* Abstrakte Basisklasse aller reinen Datumstypen, die über ihre
* Epochentage ineinander konvertierbar sind.
*
* @param generic type of time unit compatible to {@link ChronoUnit})
* @param generic type of self reference
* @author Meno Hochschild
* @serial exclude
*/
public abstract class Calendrical>
extends TimePoint
implements CalendarDate {
//~ Methoden ----------------------------------------------------------
@Override
public boolean isBefore(CalendarDate date) {
return (this.compareByTime(date) < 0);
}
@Override
public boolean isAfter(CalendarDate date) {
return (this.compareByTime(date) > 0);
}
@Override
public boolean isSimultaneous(CalendarDate date) {
return ((this == date) || (this.compareByTime(date) == 0));
}
/**
* Defines a total respective natural order.
*
* This implementation first evaluates the temporal position on the
* common timeline, that is the epoch day numbers. Only date objects
* of the same calendrical type are comparable. The order is consistent
* with {@code equals()} as long as subclasses don't define further
* state attributes. If objects of different calendrical type are to be
* compared on the timeline only applications can either use an
* {@code EpochDays}-instance as {@code Comparator} or use one of
* the {@code Temporal}-methods {@code isAfter()}, {@code isBefore()}
* and {@code isSimultaneous()}.
*
* @throws ClassCastException if there are different date types
* @see EpochDays#compare(ChronoDisplay, ChronoDisplay)
* @see #isBefore(CalendarDate)
* @see #isAfter(CalendarDate)
*/
/*[deutsch]
* Definiert eine totale respektive eine natürliche Ordnung.
*
* Diese Implementierung wertet die zeitliche Position auf dem
* gemeinsamen Zeitstrahl aus, also die Epochentage. Nur Datumsobjekte
* gleichen Kalendertyps können miteinander verglichen werden.
* Die Sortierung ist daher konsistent mit {@code equals()}, solange
* Subklassen nicht weitere Zustandsattribute definieren. Sollen garantiert
* Datumsobjekte verschiedenen Typs nur zeitlich verglichen werden, kann
* entweder eine {@code EpochDays}-Instanz als {@code Comparator}
* oder eine der {@code Temporal}-Methoden {@code isAfter()},
* {@code isBefore()} und {@code isSimultaneous()} verwendet werden.
*
* @throws ClassCastException if there are different date types
* @see EpochDays#compare(ChronoDisplay, ChronoDisplay)
* @see #isBefore(CalendarDate)
* @see #isAfter(CalendarDate)
*/
@Override
public int compareTo(D date) {
Class t1 = this.getChronology().getChronoType();
Class t2 = date.getChronology().getChronoType();
if (t1 != t2) {
throw new ClassCastException(
"Cannot compare different types of dates, "
+ "use instance of EpochDays as comparator instead.");
}
return this.compareByTime(date);
}
/**
* Based on the epoch day number and the calendar system.
*
* In other words: Two date object are equal if they have the
* same temporal position on the local timeline and have the same
* calendrical type. Subclasses which define further state attributes
* must override this method.
*
* If an only temporal comparison is required then the method
* {@link #isSimultaneous(CalendarDate)} is to be used.
*
* @see Chronology#getChronoType()
*/
/*[deutsch]
* Basiert auf den Epochentagen und dem Kalendersystem.
*
* Mit anderen Worten: Zwei Datumsobjekte sind genau dann gleich, wenn
* sie zeitlich gleich UND vom selben Kalendertyp sind. Subklassen, die
* weitere Zustandsattribute definieren, müssen diese Methode
* geeignet überschreiben.
*
* Soll ein rein zeitlicher Vergleich sichergestellt sein, dann
* ist stattdessen die Methode {@link #isSimultaneous(CalendarDate)}
* zu verwenden.
*
* @see Chronology#getChronoType()
*/
@Override
public boolean equals(Object obj) {
if (this == obj) {
return true;
} else if (obj == null) {
return false;
} else if (obj instanceof Calendrical) {
Calendrical that = (Calendrical) obj;
Class t1 = this.getChronology().getChronoType();
Class t2 = that.getChronology().getChronoType();
return (
(t1 == t2)
&& (this.getDaysSinceEpochUTC() == that.getDaysSinceEpochUTC())
);
} else {
return false;
}
}
/**
* Based on the epoch day number.
*/
/*[deutsch]
* Basiert auf den Epochentagen.
*/
@Override
public int hashCode() {
long days = this.getDaysSinceEpochUTC();
return (int) (days ^ (days >>> 32));
}
/**
* Adds given calendar days to this instance.
*
* @param days calendar days to be added
* @return result of addition
* @throws ArithmeticException in case of numerical overflow
* @since 3.4/4.3
*/
/*[deutsch]
* Addiert die angegebenen Kalendertage zu dieser Instanz.
*
* @param days calendar days to be added
* @return result of addition
* @throws ArithmeticException in case of numerical overflow
* @since 3.4/4.3
*/
public D plus(CalendarDays days) {
long result = Math.addExact(this.getDaysSinceEpochUTC(), days.getAmount());
try {
return this.getChronology().getCalendarSystem().transform(result);
} catch (IllegalArgumentException iae) {
ArithmeticException ex = new ArithmeticException("Out of range: " + result);
ex.initCause(iae);
throw ex;
}
}
/**
* Subtracts given calendar days from this instance.
*
* @param days calendar days to be subtracted
* @return result of subtraction
* @throws ArithmeticException in case of numerical overflow
* @since 3.4/4.3
*/
/*[deutsch]
* Subtrahiert die angegebenen Kalendertage von dieser Instanz.
*
* @param days calendar days to be subtracted
* @return result of subtraction
* @throws ArithmeticException in case of numerical overflow
* @since 3.4/4.3
*/
public D minus(CalendarDays days) {
return this.plus(CalendarDays.of(Math.negateExact(days.getAmount())));
}
@Override
public long getDaysSinceEpochUTC() {
return this.getChronology().getCalendarSystem().transform(this.getContext());
}
/**
* Definiert eine rein zeitliche Ordnung.
*
* Diese Implementierung wertet die zeitliche Position auf dem
* gemeinsamen Zeitstrahl aus, also die Epochentage.
*
* @param date another date to be compared with
* @return negative, zero or positive integer if this instance is earlier,
* simultaneous or later than given date
*/
protected int compareByTime(CalendarDate date) {
long d1 = this.getDaysSinceEpochUTC();
long d2 = date.getDaysSinceEpochUTC();
return ((d1 < d2) ? -1 : ((d1 == d2) ? 0 : 1));
}
}