Package net.time4j.calendar

Class HijriCalendar

java.lang.Object
net.time4j.engine.ChronoEntity<D>
net.time4j.engine.CalendarVariant<HijriCalendar>
net.time4j.calendar.HijriCalendar
All Implemented Interfaces:
Serializable, Comparable<HijriCalendar>, CalendarDate, ChronoDisplay, Temporal<CalendarDate>, VariantSource, LocalizedPatternSupport
@CalendarType("islamic") public final class HijriCalendar extends CalendarVariant<HijriCalendar> implements LocalizedPatternSupport

Represents the Hijri calendar used in many islamic countries.

Introduction

It is a lunar calendar which exists in several variants and is mainly for religious purposes. The variant used in Saudi-Arabia is named "islamic-umalqura" and is based on data partially observed by sighting the new moon, partially by astronomical calculations/predictions. Note that the religious authorities in most countries often publish dates which deviate from such official calendars by one or two days.

The calendar year is divided into 12 islamic months. Every month usually has either 29 or 30 days. The length of the month in days shall reflect the date when the new moon appears. However, for every variant there are different data or rules how to determine if a month has 29 or 30 days. The Hijri calendar day starts in the evening. New variants can be configured by a file named "{variant-name}.data" in the data-subdirectory of resource class path (where hyphens are replaced by underscores). Format details see the file "islamic_umalqura.data".

Following elements which are declared as constants are registered by this class

Furthermore, all elements defined in EpochDays and CommonElements are supported.

Formatting and simple transformations

     // parse a Hijri-string and convert to a gregorian date
     ChronoFormatter<HijriCalendar> formatter =
       ChronoFormatter.setUp(HijriCalendar.class, Locale.ENGLISH)
       .addPattern("EEE, d. MMMM yy", PatternType.CLDR_DATE).build()
       .withCalendarVariant(HijriCalendar.VARIANT_UMALQURA)
       .with(Attributes.PIVOT_YEAR, 1500); // mapped to range 1400-1499

     HijriCalendar hijri = formatter.parse("Thu, 29. Ramadan 36");
     PlainDate date = hijri.transform(PlainDate.class);
     System.out.println(date); // 2015-07-16

     // determine actual Hijri date
     HijriCalendar today = // conversion valid at noon (not in the evening when next islamic day starts)
       SystemClock.inLocalView().today().transform(HijriCalendar.class, HijriCalendar.VARIANT_UMALQURA);

Exact handling of start of islamic day in the evening

     SolarTime meccaTime = SolarTime.ofLocation(21.4225, 39.826111);
     StartOfDay startOfDay = StartOfDay.definedBy(meccaTime.sunset());

     HijriCalendar todayExact =
       SystemClock.inLocalView().now(
         HijriCalendar.family(),
         HijriCalendar.VARIANT_UMALQURA,
         startOfDay
       ).toDate();

How to determine the valid calendar range

Note that the supported range of this class is limited compared with the gregorian counter-example. Users can apply following code to determine the exact variant-dependent range: 

     CalendarSystem<HijriCalendar> calsys =
       HijriCalendar.family().getCalendarSystem(HijriCalendar.VARIANT_UMALQURA);
     long min = calsys.getMinimumSinceUTC(); // -32556
     long max = calsys.getMaximumSinceUTC(); // 38671

     // same minimum and maximum displayed as Hijri calendar dates
     HijriCalendar minHijri = calsys.transform(min); // AH-1300-01-01[islamic-umalqura]
     HijriCalendar maxHijri = calsys.transform(max); // AH-1500-12-30[islamic-umalqura]

     // same minimum and maximum displayed as gregorian dates
     PlainDate minGregorian = PlainDate.of(min, EpochDays.UTC); // 1882-11-12
     PlainDate maxGregorian = PlainDate.of(max, EpochDays.UTC); // 2077-11-16

Support for unicode ca-extensions

     Locale locale = Locale.forLanguageTag("ar-SA-u-ca-islamic-umalqura");
     ChronoFormatter<CalendarDate> f = ChronoFormatter.ofGenericCalendarStyle(DisplayMode.FULL, locale);
     String today = f.format(SystemClock.inLocalView().today()); // conversion valid at noon
     // output in arabic language using the calendar of Saudi-Arabia
Since:
3.5/4.3
Author:
Meno Hochschild
See Also:
HijriEra, HijriMonth, HijriAlgorithm, HijriAdjustment, NumberSystem.ARABIC, NumberSystem.ARABIC_INDIC, NumberSystem.ARABIC_INDIC_EXT, StartOfDay.definedBy(ChronoFunction), SolarTime.sunset(), Serialized Form

  • Field Details

  • Method Details

    • of

      public static HijriCalendar of​(String variant, int hyear, HijriMonth hmonth, int hdom)

      Creates a new instance of a Hijri calendar date in given variant.

      Parameters:
      variant - calendar variant
      hyear - islamic year
      hmonth - islamic month
      hdom - islamic day of month
      Returns:
      new instance of HijriCalendar
      Throws:
      ChronoException - if given variant is not supported
      IllegalArgumentException - in case of any inconsistencies
      Since:
      3.5/4.3

    • of

      public static HijriCalendar of​(String variant, int hyear, int hmonth, int hdom)

      Creates a new instance of a Hijri calendar date in given variant.

      Parameters:
      variant - calendar variant
      hyear - islamic year
      hmonth - islamic month
      hdom - islamic day of month
      Returns:
      new instance of HijriCalendar
      Throws:
      ChronoException - if given variant is not supported
      IllegalArgumentException - in case of any inconsistencies
      Since:
      3.5/4.3

    • of

      public static HijriCalendar of​(VariantSource variantSource, int hyear, HijriMonth hmonth, int hdom)

      Creates a new instance of a Hijri calendar date in given variant.

      Parameters:
      variantSource - source of calendar variant
      hyear - islamic year
      hmonth - islamic month
      hdom - islamic day of month
      Returns:
      new instance of HijriCalendar
      Throws:
      ChronoException - if given variant is not supported
      IllegalArgumentException - in case of any inconsistencies
      Since:
      3.6/4.4

    • of

      public static HijriCalendar of​(VariantSource variantSource, int hyear, int hmonth, int hdom)

      Creates a new instance of a Hijri calendar date in given variant.

      Parameters:
      variantSource - source of calendar variant
      hyear - islamic year
      hmonth - islamic month
      hdom - islamic day of month
      Returns:
      new instance of HijriCalendar
      Throws:
      ChronoException - if given variant is not supported
      IllegalArgumentException - in case of any inconsistencies
      Since:
      3.6/4.4

    • ofUmalqura

      public static HijriCalendar ofUmalqura​(int hyear, HijriMonth hmonth, int hdom)

      Creates a new instance of a Hijri calendar date in the variant "islamic-umalqura" used in Saudi-Arabia.

      Parameters:
      hyear - islamic year
      hmonth - islamic month
      hdom - islamic day of month
      Returns:
      new instance of HijriCalendar
      Throws:
      ChronoException - if given variant is not supported
      IllegalArgumentException - in case of any inconsistencies
      Since:
      3.5/4.3

    • ofUmalqura

      public static HijriCalendar ofUmalqura​(int hyear, int hmonth, int hdom)

      Creates a new instance of a Hijri calendar date in the variant "islamic-umalqura" used in Saudi-Arabia.

      Parameters:
      hyear - islamic year
      hmonth - islamic month
      hdom - islamic day of month
      Returns:
      new instance of HijriCalendar
      Throws:
      ChronoException - if given variant is not supported
      IllegalArgumentException - in case of any inconsistencies
      Since:
      3.5/4.3

    • nowInSystemTime

      public static HijriCalendar nowInSystemTime​(String variant, StartOfDay startOfDay)

      Obtains the current calendar date in system time.

      Convenient short-cut for: SystemClock.inLocalView().now(HijriCalendar.family(), variant, startOfDay).toDate()).

      Parameters:
      variant - calendar variant
      startOfDay - determines the exact time of day when the calendar date will change (usually in the evening)
      Returns:
      current calendar date in system time zone using the system clock
      Since:
      3.23/4.19
      See Also:
      SystemClock.inLocalView(), ZonalClock.now(CalendarFamily, String, StartOfDay), StartOfDay.EVENING

    • nowInSystemTime

      public static HijriCalendar nowInSystemTime​(VariantSource variantSource, StartOfDay startOfDay)

      Obtains the current calendar date in system time.

      Convenient short-cut for: SystemClock.inLocalView().now(HijriCalendar.family(), variantSource, startOfDay).toDate()).

      Parameters:
      variantSource - source of calendar variant
      startOfDay - determines the exact time of day when the calendar date will change (usually in the evening)
      Returns:
      current calendar date in system time zone using the system clock
      Since:
      3.23/4.19
      See Also:
      SystemClock.inLocalView(), ZonalClock.now(CalendarFamily, VariantSource, StartOfDay), StartOfDay.EVENING

    • getEra

      public HijriEra getEra()

      Yields the islamic era.

      Returns:
      HijriEra.ANNO_HEGIRAE
      Since:
      3.5/4.3

    • getYear

      public int getYear()

      Yields the islamic year.

      Returns:
      int
      Since:
      3.5/4.3

    • getMonth

      public HijriMonth getMonth()

      Yields the islamic month.

      Returns:
      enum
      Since:
      3.5/4.3

    • getDayOfMonth

      public int getDayOfMonth()

      Yields the islamic day of month.

      Returns:
      int
      Since:
      3.5/4.3

    • getDayOfWeek

      public Weekday getDayOfWeek()

      Determines the day of week.

      The Hijri calendar also uses a 7-day-week.

      Returns:
      Weekday
      Since:
      3.5/4.3

    • getDayOfYear

      public int getDayOfYear()

      Yields the islamic day of year.

      Returns:
      int
      Since:
      3.5/4.3

    • getVariant

      public String getVariant()
      Description copied from interface: VariantSource

      Yields the variant name of a calendar system.

      Specified by:
      getVariant in interface VariantSource
      Returns:
      String which is empty if there are no variants

    • lengthOfMonth

      public int lengthOfMonth()

      Yields the length of current islamic month in days.

      Returns:
      int
      Since:
      3.6/4.4

    • lengthOfYear

      public int lengthOfYear()

      Yields the length of current islamic year in days.

      Returns:
      int
      Throws:
      ChronoException - if data are not available for the whole year (edge case)
      Since:
      3.6/4.4

    • isValid

      public static boolean isValid​(String variant, int yearOfEra, int month, int dayOfMonth)

      Queries if given parameter values form a well defined calendar date.

      Parameters:
      variant - the variant of the underlying calendar system
      yearOfEra - the year of era to be checked
      month - the month to be checked
      dayOfMonth - the day of month to be checked
      Returns:
      true if valid else false
      Since:
      3.34/4.29
      See Also:
      of(String, int, int, int)

    • nextYear

      public HijriCalendar nextYear()

      Convenient short form for with(YEAR_OF_ERA.incremented()).

      Returns:
      copy of this instance at next year
      Since:
      3.5/4.3

    • nextMonth

      public HijriCalendar nextMonth()

      Convenient short form for with(MONTH_OF_YEAR.incremented()).

      Returns:
      copy of this instance at next month
      Since:
      3.5/4.3

    • nextDay

      public HijriCalendar nextDay()

      Convenient short form for with(DAY_OF_MONTH.incremented()).

      Returns:
      copy of this instance at next day
      Since:
      3.5/4.3

    • at

      public GeneralTimestamp<HijriCalendar> at​(PlainTime time)

      Creates a new local timestamp with this date and given wall time.

      If the time T24:00 is used then the resulting timestamp will automatically be normalized such that the timestamp will contain the following day instead.

      Parameters:
      time - wall time
      Returns:
      general timestamp as composition of this date and given time
      Since:
      3.8/4.5

    • atTime

      public GeneralTimestamp<HijriCalendar> atTime​(int hour, int minute)

      Is equivalent to at(PlainTime.of(hour, minute)).

      Parameters:
      hour - hour of day in range (0-24)
      minute - minute of hour in range (0-59)
      Returns:
      general timestamp as composition of this date and given time
      Throws:
      IllegalArgumentException - if any argument is out of range
      Since:
      3.8/4.5

    • plus

      public HijriCalendar plus​(int amount, HijriCalendar.Unit unit)

      Adds given calendrical units to this instance.

      Parameters:
      amount - amount to be added (maybe negative)
      unit - calendrical unit
      Returns:
      result of addition as changed copy, this instance remains unaffected
      Throws:
      ArithmeticException - in case of numerical overflow
      Since:
      3.14/4.10

    • minus

      public HijriCalendar minus​(int amount, HijriCalendar.Unit unit)

      Subtracts given calendrical units from this instance.

      Parameters:
      amount - amount to be subtracted (maybe negative)
      unit - calendrical unit
      Returns:
      result of subtraction as changed copy, this instance remains unaffected
      Throws:
      ArithmeticException - in case of numerical overflow
      Since:
      3.14/4.10

    • equals

      public boolean equals​(Object obj)
      Description copied from class: CalendarVariant

      Compares the whole state of this instance with given object.

      Implementations will usually define their state based on the temporal position and the variant name. Exceptions from this rule should be explicitly documented and reasoned.

      Specified by:
      equals in class CalendarVariant<HijriCalendar>
      See Also:
      CalendarVariant.compareTo(CalendarVariant)

    • hashCode

      public int hashCode()
      Description copied from class: CalendarVariant

      Subclasses must redefine this method corresponding to the behaviour of equals().

      Specified by:
      hashCode in class CalendarVariant<HijriCalendar>

    • toString

      public String toString()
      Description copied from class: CalendarVariant

      Provides a complete textual representation of the state of this calendar variant.

      Specified by:
      toString in class CalendarVariant<HijriCalendar>

    • getDefaultWeekmodel

      public static Weekmodel getDefaultWeekmodel()

      Obtains the standard week model of this calendar.

      The Hijri calendar usually starts on Sunday, but with the weekend on Friday and Saturday (like in Saudi-Arabia).

      Returns:
      Weekmodel
      Since:
      3.24/4.20

    • family

      public static CalendarFamily<HijriCalendar> family()

      Returns the associated calendar family.

      Returns:
      chronology as calendar family
      Since:
      3.5/4.3

    • register

      public static void register​(HijriData hijriData)

      Registers a regional variant of the Hijri calendar.

      Repeated calls with the same variant will effectively update the existing registered variant.

      Parameters:
      hijriData - interface for regional Hijri variant
      Throws:
      IllegalStateException - if the initialization of Hijri data fails
      IllegalArgumentException - if the data are wrong
      Since:
      5.6

    • getVersion

      public static String getVersion​(String variant)

      Determines the data version of given variant.

      This method serves for data analysis only.

      Parameters:
      variant - name of islamic calendar variant
      Returns:
      version info (maybe empty if not relevant)
      Throws:
      ChronoException - if the variant is not recognized
      Since:
      3.9/4.6