net.time4j.engine.CalendarDate Maven / Gradle / Ivy
/*
* -----------------------------------------------------------------------
* Copyright © 2013-2017 Meno Hochschild, Represents a general calendar date.
*
* @author Meno Hochschild
* @since 3.8/4.5
*/
/*[deutsch]
* Repräsentiert ein allgemeines Kalenderdatum.
*
* @author Meno Hochschild
* @since 3.8/4.5
*/
public interface CalendarDate
extends Temporal {
//~ Methoden ----------------------------------------------------------
/**
* Counts the elapsed days since UTC epoch.
*
* @return count of days relative to UTC epoch [1972-01-01]
* @see EpochDays#UTC
* @since 3.8/4.5
*/
/*[deutsch]
* Zählt die seit der UTC-Epoche verstrichenen Tage.
*
* @return count of days relative to UTC epoch [1972-01-01]
* @see EpochDays#UTC
* @since 3.8/4.5
*/
long getDaysSinceEpochUTC();
/**
* Converts this calendar date to the given target chronology based on
* the count of days relative to UTC epoch [1972-01-01].
*
* The conversion occurs on the local timeline at noon. This
* reference time ensures that all date types remain convertible
* even if a calendar system defines dates not starting at midnight.
*
* @param generic target date type
* @param target chronology this date shall be converted to
* @return converted date of target type T
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
/*[deutsch]
* Konvertiert dieses Datum zur angegebenen Zielchronologie auf Basis der
* Anzahl der Tage relativ zur UTC-Epoche [1972-01-01].
*
* Die Konversion findet auf dem lokalen Zeitstrahl um 12 Uhr mittags
* als angenommener Referenzzeit statt. Diese Referenzzeit stellt sicher,
* daß alle Datumstypen konvertierbar bleiben, auch wenn in einem
* Kalendersystem ein Tag nicht um Mitternacht startet.
*
* @param generic target date type
* @param target chronology this date shall be converted to
* @return converted date of target type T
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
default > T transform(Chronology target) {
long utcDays = this.getDaysSinceEpochUTC();
CalendarSystem calsys = target.getCalendarSystem();
if ((calsys.getMinimumSinceUTC() > utcDays) || (calsys.getMaximumSinceUTC() < utcDays)) {
throw new ArithmeticException("Cannot transform <" + utcDays + "> to: " + target.getChronoType().getName());
} else {
return calsys.transform(utcDays);
}
}
/**
* Converts this calendar date to the given target chronology based on
* the count of days relative to UTC epoch [1972-01-01].
*
* The conversion occurs on the local timeline at noon. This
* reference time ensures that all date types remain convertible
* even if a calendar system defines dates not starting at midnight.
*
* @param generic target date type
* @param target chronology this date shall be converted to
* @param variant desired calendar variant
* @return converted date of target type T
* @throws ChronoException if given variant is not recognized
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
/*[deutsch]
* Konvertiert dieses Datum zur angegebenen Zielchronologie auf Basis der
* Anzahl der Tage relativ zur UTC-Epoche [1972-01-01].
*
* Die Konversion findet auf dem lokalen Zeitstrahl um 12 Uhr mittags
* als angenommener Referenzzeit statt. Diese Referenzzeit stellt sicher,
* daß alle Datumstypen konvertierbar bleiben, auch wenn in einem
* Kalendersystem ein Tag nicht um Mitternacht startet.
*
* @param generic target date type
* @param target chronology this date shall be converted to
* @param variant desired calendar variant
* @return converted date of target type T
* @throws ChronoException if given variant is not recognized
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
default > T transform(
CalendarFamily target,
String variant
) {
long utcDays = this.getDaysSinceEpochUTC();
CalendarSystem calsys = target.getCalendarSystem(variant);
if ((calsys.getMinimumSinceUTC() > utcDays) || (calsys.getMaximumSinceUTC() < utcDays)) {
throw new ArithmeticException("Cannot transform <" + utcDays + "> to: " + target.getChronoType().getName());
} else {
return calsys.transform(utcDays);
}
}
/**
* Converts this calendar date to the given target chronology based on
* the count of days relative to UTC epoch [1972-01-01].
*
* The conversion occurs on the local timeline at noon. This
* reference time ensures that all date types remain convertible
* even if a calendar system defines dates not starting at midnight.
*
* @param generic target date type
* @param target chronology this date shall be converted to
* @param variantSource source of desired calendar variant
* @return converted date of target type T
* @throws ChronoException if the variant of given source is not recognized
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
/*[deutsch]
* Konvertiert dieses Datum zur angegebenen Zielchronologie auf Basis der
* Anzahl der Tage relativ zur UTC-Epoche [1972-01-01].
*
* Die Konversion findet auf dem lokalen Zeitstrahl um 12 Uhr mittags
* als angenommener Referenzzeit statt. Diese Referenzzeit stellt sicher,
* daß alle Datumstypen konvertierbar bleiben, auch wenn in einem
* Kalendersystem ein Tag nicht um Mitternacht startet.
*
* @param generic target date type
* @param target chronology this date shall be converted to
* @param variantSource source of desired calendar variant
* @return converted date of target type T
* @throws ChronoException if the variant of given source is not recognized
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
default > T transform(
CalendarFamily target,
VariantSource variantSource
) {
return this.transform(target, variantSource.getVariant());
}
/**
* Converts this calendar date to the given target type based on
* the count of days relative to UTC epoch [1972-01-01].
*
* The conversion occurs on the local timeline at noon. This
* reference time ensures that all date types remain convertible
* even if a calendar system defines dates not starting at midnight.
*
* @param generic target date type
* @param target chronological type this date shall be converted to
* @return converted date of target type T
* @throws IllegalArgumentException if the target class does not have any chronology
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
/*[deutsch]
* Konvertiert dieses Datum zum angegebenen Zieltyp auf Basis der
* Anzahl der Tage relativ zur UTC-Epoche [1972-01-01].
*
* Die Konversion findet auf dem lokalen Zeitstrahl um 12 Uhr mittags
* als angenommener Referenzzeit statt. Diese Referenzzeit stellt sicher,
* daß alle Datumstypen konvertierbar bleiben, auch wenn in einem
* Kalendersystem ein Tag nicht um Mitternacht startet.
*
* @param generic target date type
* @param target chronological type this date shall be converted to
* @return converted date of target type T
* @throws IllegalArgumentException if the target class does not have any chronology
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
default > T transform(Class target) {
String ref = target.getName();
Chronology chronology = Chronology.lookup(target);
if (chronology == null) {
// kommt normal nie vor, weil sich jede Chrono selbst registriert
throw new IllegalArgumentException(
"Cannot find any chronology for given target type: " + ref);
}
long utcDays = this.getDaysSinceEpochUTC();
CalendarSystem calsys = chronology.getCalendarSystem();
if ((calsys.getMinimumSinceUTC() > utcDays) || (calsys.getMaximumSinceUTC() < utcDays)) {
throw new ArithmeticException("Cannot transform <" + utcDays + "> to: " + ref);
} else {
return calsys.transform(utcDays);
}
}
/**
* Converts this calendar date to the given target type based on
* the count of days relative to UTC epoch [1972-01-01].
*
* The conversion occurs on the local timeline at noon. This
* reference time ensures that all date types remain convertible
* even if a calendar system defines dates not starting at midnight.
*
* @param generic target date type
* @param target chronological type this date shall be converted to
* @param variant desired calendar variant
* @return converted date of target type T
* @throws ChronoException if given variant is not recognized
* @throws IllegalArgumentException if the target class does not have any chronology
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
/*[deutsch]
* Konvertiert dieses Datum zum angegebenen Zieltyp auf Basis der
* Anzahl der Tage relativ zur UTC-Epoche [1972-01-01].
*
* Die Konversion findet auf dem lokalen Zeitstrahl um 12 Uhr mittags
* als angenommener Referenzzeit statt. Diese Referenzzeit stellt sicher,
* daß alle Datumstypen konvertierbar bleiben, auch wenn in einem
* Kalendersystem ein Tag nicht um Mitternacht startet.
*
* @param generic target date type
* @param target chronological type this date shall be converted to
* @param variant desired calendar variant
* @return converted date of target type T
* @throws ChronoException if given variant is not recognized
* @throws IllegalArgumentException if the target class does not have any chronology
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
default > T transform(
Class target,
String variant
) {
String ref = target.getName();
Chronology chronology = Chronology.lookup(target);
if (chronology == null) {
// kommt normal nie vor, weil sich jede Chrono selbst registriert
throw new IllegalArgumentException(
"Cannot find any chronology for given target type: " + ref);
}
long utcDays = this.getDaysSinceEpochUTC();
CalendarSystem calsys = chronology.getCalendarSystem(variant);
if ((calsys.getMinimumSinceUTC() > utcDays) || (calsys.getMaximumSinceUTC() < utcDays)) {
throw new ArithmeticException("Cannot transform <" + utcDays + "> to: " + ref);
} else {
return calsys.transform(utcDays);
}
}
/**
* Converts this calendar date to the given target type based on
* the count of days relative to UTC epoch [1972-01-01].
*
* The conversion occurs on the local timeline at noon. This
* reference time ensures that all date types remain convertible
* even if a calendar system defines dates not starting at midnight.
*
* @param generic target date type
* @param target chronological type this date shall be converted to
* @param variantSource source of desired calendar variant
* @return converted date of target type T
* @throws ChronoException if the variant of given source is not recognized
* @throws IllegalArgumentException if the target class does not have any chronology
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
/*[deutsch]
* Konvertiert dieses Datum zum angegebenen Zieltyp auf Basis der
* Anzahl der Tage relativ zur UTC-Epoche [1972-01-01].
*
* Die Konversion findet auf dem lokalen Zeitstrahl um 12 Uhr mittags
* als angenommener Referenzzeit statt. Diese Referenzzeit stellt sicher,
* daß alle Datumstypen konvertierbar bleiben, auch wenn in einem
* Kalendersystem ein Tag nicht um Mitternacht startet.
*
* @param generic target date type
* @param target chronological type this date shall be converted to
* @param variantSource source of desired calendar variant
* @return converted date of target type T
* @throws ChronoException if the variant of given source is not recognized
* @throws IllegalArgumentException if the target class does not have any chronology
* @throws ArithmeticException in case of numerical overflow
* @since 4.27
*/
default > T transform(
Class target,
VariantSource variantSource
) {
return this.transform(target, variantSource.getVariant());
}
}