Skip to content

Commit

Permalink
more documentation
Browse files Browse the repository at this point in the history 
see issue #851
  • Loading branch information
@MenoData
MenoData committed Jul 14, 2020
1 parent 9ca38bc commit 03b5350
Show file tree
Hide file tree
Showing 4 changed files with 119 additions and 57 deletions.
83 changes: 79 additions & 4 deletions base/src/main/java/net/time4j/calendar/hindu/HinduCalendar.java
View file
Expand Up @@ -86,8 +86,16 @@
* <p>The traditional Hindu calendar which exists in many regional variants throughout the Indian
* subcontinent. </p>
*
* <p>This version actually supports the {@link AryaSiddhanta old Hindu calendar} only. Following elements
* which are declared as constants are registered by this class: </p>
* <p>This version actually supports all algorithmic variants including the {@link AryaSiddhanta old Hindu calendar}.
* These variants are described in the book &quot;Calendrical Calculations&quot; by Dershowitz/Reingold. Real
* Hindu calendars published on websites can nevertheless deviate in detail. Users who wish to support modern
* Hindu calendars can start with the enum {@link HinduRule} in order to construct a suitable variant. For example,
* it is possible to set the default era for all calendar objects by {@link HinduVariant#with(HinduEra) setting
* the desired era} on the variant. </p>
*
* <h4>Supported elements</h4>
*
* <p>Following elements which are declared as constants are registered by this class: </p>
*
* <ul>
* <li>{@link #DAY_OF_WEEK}</li>
Expand All @@ -101,10 +109,38 @@
* <p>Furthermore, all elements defined in {@code EpochDays} and {@code CommonElements.RELATED_GREGORIAN_YEAR}
* are supported. </p>
*
* <h4>Calendar arithmetic and time units</h4>
*
* <p>A date arithmetic using units beyond the class {@link net.time4j.engine.CalendarDays} is not offered.
* But there are methods like {@code previousMonth()} or {@code nextYear()}. About years, user can also use
* expressions like {@code with(YEAR_OF_ERA, getYear() + amount)}. </p>
*
* <h4>Formatting and parsing</h4>
*
* <p>This calendar can deploy the same localized resources like the Indian national calendar. Example: </p>
*
* <pre>
* ChronoFormatter&lt;HinduCalendar&gt; f =
* ChronoFormatter.ofPattern(
* &quot;G, d. MMMM yyyy&quot;,
* PatternType.CLDR,
* Locale.ENGLISH,
* HinduCalendar.family());
* HinduCalendar cal = HinduCalendar.ofOldSolar(3101, HinduMonth.of(IndianMonth.MAGHA).getRasi(), 19);
* assertThat(
* f.print(cal),
* is(&quot;K.Y, 19. Magha 3101&quot;));
* </pre>
*
* <h4>Oddities</h4>
*
* <p>The Hindu calendar knows <i>lost days</i> and leap days. And the lunisolar variants also know <i>lost months</i>
* (rare) and leap months. This is the main reason why days and months are not modelled as integers. So users cannot
* rely on simple home grown integer arithmetic to look for example for the next valid day but must use the existing
* element queries, element manipulations and expressions based on the available methods like {@code nextDay()} or
* {@code nextMonth()}. Any date input in doubt should also be validated using
* {@link #isValid(HinduVariant, HinduEra, int, HinduMonth, HinduDay)}. </p>
*
* @author Meno Hochschild
* @since 5.6
* @doctags.concurrency {immutable}
Expand All @@ -113,8 +149,17 @@
* <p>Der traditionelle Hindukalender, der in vielen verschiedenen regionalen Varianten auf dem indischen
* Subkontinent existiert. </p>
*
* <p>Aktuell wird nur der {@link AryaSiddhanta alte Hindukalender} unterst&uuml;tzt. Folgende als Konstanten
* deklarierte Elemente werden von dieser Klasse registriert: </p>
* <p>Aktuell werden alle algorithmischen Varianten einschlie&szlig;lich des {@link AryaSiddhanta alten Hindukalender}
* unterst&uuml;tzt. Diese Varianten sind im Buch &quot;Calendrical Calculations&quot; von Dershowitz/Reingold
* beschrieben. Reale Hindukalender, die auf Webseiten ver&ouml;ffentlicht sind, k&ouml;nnen dennoch im Detail
* abweichen. Anwender, die moderne Hindu-Kalender verwenden m&ouml;chten, k&ouml;nnen das Enum {@link HinduRule}
* als Ausgangspunkt zum Konstruieren einer geeigneten Kalendervariante benutzen. Zum Beispiel ist es m&ouml;glich,
* die Standard&auml;ra f&uuml;r alle Kalenderobjekte zu setzen, indem die gew&uuml;nschte &Auml;ra mittels
* {@link HinduVariant#with(HinduEra) auf der Variante gesetzt} wird. </p>
*
* <h4>Unterst&uuml;tzte Elemente</h4>
*
* <p>Folgende als Konstanten deklarierte Elemente werden von dieser Klasse registriert: </p>
*
* <ul>
* <li>{@link #DAY_OF_WEEK}</li>
Expand All @@ -128,10 +173,40 @@
* <p>Au&slig;erdem werden alle Elemente von {@code EpochDays} und {@code CommonElements.RELATED_GREGORIAN_YEAR}
* unterst&uuml;tzt. </p>
*
* <h4>Kalenderarithmetik mit Zeiteinheiten</h4>
*
* <p>Eine Datumsarithmetik mittels Zeiteinheiten wird au&szlig;er der Klasse {@link net.time4j.engine.CalendarDays}
* nicht angeboten. Aber es gibt Methoden wie {@code previousMonth()} oder {@code nextYear()}. Was Jahre angeht,
* k&ouml;nnen Anwender auch Ausdr&uuml;cke wie {@code with(YEAR_OF_ERA, getYear() + amount)} verwenden. </p>
*
* <h4>Formatierung</h4>
*
* <p>Dieser Kalender kann die gleichen sprachabh&auml;ngigen Textressourcen wie der indische Nationalkalender
* aussch&ouml;pfen. Beispiel: </p>
*
* <pre>
* ChronoFormatter&lt;HinduCalendar&gt; f =
* ChronoFormatter.ofPattern(
* &quot;G, d. MMMM yyyy&quot;,
* PatternType.CLDR,
* Locale.ENGLISH,
* HinduCalendar.family());
* HinduCalendar cal = HinduCalendar.ofOldSolar(3101, HinduMonth.of(IndianMonth.MAGHA).getRasi(), 19);
* assertThat(
* f.print(cal),
* is(&quot;K.Y, 19. Magha 3101&quot;));
* </pre>
*
* <h4>Besonderheiten</h4>
*
* <p>Der Hindukalender kennt <i>verlorene Tage</i> und Schalttage. Und die lunisolaren Varianten kennen
* entsprechend <i>verlorene Monate</i> (selten) und Schaltmonate. Das ist der Hauptgrund, warum Tage und
* Monate nicht als einfache Zahlen modelliert werden k&ouml;nnen. Somit k&ouml;nnen Anwender sich nicht
* auf einfache selbst gestrickte Integerarithmetik verlassen, um etwa den n&auml;chsten Tag zu suchen,
* sondern m&uuml;ssen sich auf die vorhandenen Elementabfragen, Elementmanipulationen und Ausdr&uuml;cke
* wie {@code nextDay()} oder {@code nextMonth()} st&uuml;tzen. Zweifelhafte Eingaben sind dabei mittels
* {@link #isValid(HinduVariant, HinduEra, int, HinduMonth, HinduDay)} zu pr&uuml;fen. </p>
*
* @author Meno Hochschild
* @since 5.6
* @doctags.concurrency {immutable}
Expand Down
59 changes: 33 additions & 26 deletions base/src/main/java/net/time4j/calendar/hindu/HinduRule.java
View file
Expand Up @@ -125,29 +125,6 @@ HinduEra getDefaultEra() {
}
},

/**
* <p>A solar calendar which is used in West Bengal, Assam and Tripura. </p>
*
* <p>We follow the details given by Vinod K. Mishra in his script &quot;The calendars of India&quot;
* which say: When the samkranti occurs between the sunrise and the following midnight then the
* month begins on the next day. If samkranti occurs after midnight then the month begins on the
* day following the next day, i.e. on the third day. </p>
*/
/*[deutsch]
* <p>Ein Sonnenkalender, der in West Bengal, Assam and Tripura verwendet wird. </p>
*
* <p>Wir folgen den Details gegeben durch Vinod K. Mishra in seinem Buch &quot;The calendars of India&quot;,
* die besagen: Wenn Samkranti zwischen Sonnenaufgang und der folgenden Mitternacht eintritt, dann f&auml;ngt
* der Monat am n&auml;chsten Tag an. Wenn Samkranti nach Mitternacht eintritt, dann f&auml;ngt der Monat am
* Tag nach dem n&auml;chsten Tag an, also am dritten Tag. </p>
*/
BENGAL() { // TODO: improve javadoc (tabular data with other range!)
@Override
HinduEra getDefaultEra() {
return HinduEra.BENGAL;
}
},

/**
* <p>The amanta scheme is a lunisolar calendar based on the new moon cycle
* and starting the year with the month Chaitra. </p>
Expand Down Expand Up @@ -226,20 +203,50 @@ HinduEra getDefaultEra() {
/**
* <p>The purnimanta scheme is a lunisolar calendar based on the full moon cycle. </p>
*
* <p>It is shifted for about two weeks compared with the amanta scheme. </p>
* <p>It is shifted for about two weeks compared with the amanta scheme. The first days (in the
* waning fortnight) from full moon to new moon have the numbers 16, 17, ..., 30 and then
* the numbers 1, 2, ..., 15 (waxing fortnight). Lost days and leap days are possible so users
* cannot expect continuous numbering sequences. </p>
*/
/*[deutsch]
* <p>Das Purnimanta-Schema ist ein lunisolarer Kalender, der auf dem Vollmondzyklus
* basiert. </p>
*
* <p>Es ist im Vergleich zum Amanta-Schema um ungef&auml;hr zwei Wochen versetzt. </p>
* <p>Es ist im Vergleich zum Amanta-Schema um ungef&auml;hr zwei Wochen versetzt. Die ersten Tage
* (dunkle Monatsh&auml;lfte) von Vollmond zu Neumond haben die Nummern 16, 17, ..., 30 und dann
* die Zahlen 1, 2, ..., 15 (helle Monatsh&auml;lfte). Verlorene Tage und Schalttage sind weiterhin
* m&ouml;glich, so da&szlig; Anwender keine kontinuierliche Z&auml;hlung erwarten k&ouml;nnen. </p>
*/
PURNIMANTA() {
@Override
HinduEra getDefaultEra() {
return HinduEra.VIKRAMA;
}
};
}

// /**
// * <p>A solar calendar which is used in West Bengal, Assam and Tripura. </p>
// *
// * <p>We follow the details given by Vinod K. Mishra in his script &quot;The calendars of India&quot;
// * which say: When the samkranti occurs between the sunrise and the following midnight then the
// * month begins on the next day. If samkranti occurs after midnight then the month begins on the
// * day following the next day, i.e. on the third day. </p>
// */
// /*[deutsch]
// * <p>Ein Sonnenkalender, der in West Bengal, Assam and Tripura verwendet wird. </p>
// *
// * <p>Wir folgen den Details gegeben durch Vinod K. Mishra in seinem Buch &quot;The calendars of India&quot;,
// * die besagen: Wenn Samkranti zwischen Sonnenaufgang und der folgenden Mitternacht eintritt, dann f&auml;ngt
// * der Monat am n&auml;chsten Tag an. Wenn Samkranti nach Mitternacht eintritt, dann f&auml;ngt der Monat am
// * Tag nach dem n&auml;chsten Tag an, also am dritten Tag. </p>
// */
// BENGAL() { // TODO: improve javadoc (tabular data with other range!)
// @Override
// HinduEra getDefaultEra() {
// return HinduEra.BENGAL;
// }
// }
;

//~ Methoden ----------------------------------------------------------

Expand Down
32 changes: 7 additions & 25 deletions base/src/main/java/net/time4j/calendar/hindu/HinduVariant.java
View file
Expand Up @@ -357,11 +357,6 @@ public boolean isOld() {
return (this.type < 0);
}

// Kerala region only
boolean prefersRasiNames() {
return (this.type == HinduRule.MADRAS.ordinal()) || (this.type == HinduRule.MALAYALI.ordinal());
}

/**
* <p>Does this variant use elapsed years? </p>
*
Expand Down Expand Up @@ -653,16 +648,12 @@ public HinduVariant withAlternativeLocation(GeoLocation location) {
return new HinduVariant(this.type, this.defaultEra, this.elapsedMode, this.depressionAngle, location);
}

/**
* <p>Obtains the associated calendar system. </p>
*
* @return calendar system for this variant of Hindu calendar
*/
/*[deutsch]
* <p>Liefert das zu dieser Variante passende Kalendersystem. </p>
*
* @return calendar system for this variant of Hindu calendar
*/
// Kerala region only
boolean prefersRasiNames() {
return (this.type == HinduRule.MADRAS.ordinal()) || (this.type == HinduRule.MALAYALI.ordinal());
}

// obtains the associated calendar system
HinduCS getCalendarSystem() {
switch (this.type) {
case TYPE_OLD_SOLAR:
Expand All @@ -674,16 +665,7 @@ HinduCS getCalendarSystem() {
}
}

/**
* <p>Obtains the number of the first month of Hindu year. </p>
*
* @return int
*/
/*[deutsch]
* <p>Liefert die Nummer des ersten Monats des Hindu-Jahres. </p>
*
* @return int
*/
// obtains the number of the first month of Hindu year
int getFirstMonthOfYear() {
if (this.isOld()) {
return 1;
Expand Down
2 changes: 0 additions & 2 deletions base/src/test/java/net/time4j/calendar/hindu/HinduVariantTest.java
View file
Expand Up @@ -5,7 +5,6 @@
import net.time4j.PlainTimestamp;
import net.time4j.Weekday;
import net.time4j.calendar.IndianMonth;
import net.time4j.calendar.astro.GeoLocation;
import net.time4j.calendar.astro.SolarTime;
import net.time4j.engine.CalendarSystem;
import net.time4j.engine.EpochDays;
Expand Down Expand Up @@ -35,7 +34,6 @@ public void isSolar() {
case TAMIL:
case MALAYALI:
case MADRAS:
case BENGAL:
assertThat(
rule.variant().isSolar(),
is(true));
Expand Down

0 comments on commit 03b5350

Please sign in to comment.