IslamicCalendar

public class IslamicCalendar
extends Calendar

java.lang.Object
   ↳ android.icu.util.Calendar
     ↳ android.icu.util.IslamicCalendar


IslamicCalendar is a subclass of Calendar that that implements the Islamic civil and religious calendars. It is used as the civil calendar in most of the Arab world and the liturgical calendar of the Islamic faith worldwide. This calendar is also known as the "Hijri" calendar, since it starts at the time of Mohammed's emigration (or "hijra") to Medinah on Thursday, July 15, 622 AD (Julian).

The Islamic calendar is strictly lunar, and thus an Islamic year of twelve lunar months does not correspond to the solar year used by most other calendar systems, including the Gregorian. An Islamic year is, on average, about 354 days long, so each successive Islamic year starts about 11 days earlier in the corresponding Gregorian year.

Each month of the calendar starts when the new moon's crescent is visible at sunset. However, in order to keep the time fields in this class synchronized with those of the other calendars and with local clock time, we treat days and months as beginning at midnight, roughly 6 hours after the corresponding sunset.

There are three main variants of the Islamic calendar in existence. The first is the civil calendar, which uses a fixed cycle of alternating 29- and 30-day months, with a leap day added to the last month of 11 out of every 30 years. This calendar is easily calculated and thus predictable in advance, so it is used as the civil calendar in a number of Arab countries. This is the default behavior of a newly-created IslamicCalendar object.

The Islamic religious calendar and Saudi Arabia's Umm al-Qura calendar, however, are based on the observation of the crescent moon. It is thus affected by the position at which the observations are made, seasonal variations in the time of sunset, the eccentricities of the moon's orbit, and even the weather at the observation site. This makes it impossible to calculate in advance, and it causes the start of a month in the religious calendar to differ from the civil calendar by up to three days.

Using astronomical calculations for the position of the sun and moon, the moon's illumination, and other factors, it is possible to determine the start of a lunar month with a fairly high degree of certainty. However, these calculations are extremely complicated and thus slow, so most algorithms, including the one used here, are only approximations of the true astronomical calculations. At present, the approximations used in this class are fairly simplistic; they will be improved in later versions of the code.

Like the Islamic religious calendar, Umm al-Qura is also based on the sighting method of the crescent moon but is standardized by Saudi Arabia.

The fixed-cycle civil calendar is used.

This class should not be subclassed.

IslamicCalendar usually should be instantiated using Calendar.getInstance(ULocale) passing in a ULocale with the tag "@calendar=islamic" or "@calendar=islamic-civil" or "@calendar=islamic-umalqura".

Summary

Constants

int DHU_AL_HIJJAH

Constant for Dhu al-Hijjah, the 12th month of the Islamic year.

int DHU_AL_QIDAH

Constant for Dhu al-Qi'dah, the 11th month of the Islamic year.

int JUMADA_1

Constant for Jumada al-awwal or (Jumada I), the 5th month of the Islamic year.

int JUMADA_2

Constant for Jumada al-thani or (Jumada II), the 6th month of the Islamic year.

int MUHARRAM

Constant for Muharram, the 1st month of the Islamic year.

int RABI_1

Constant for Rabi' al-awwal (or Rabi' I), the 3rd month of the Islamic year.

int RABI_2

Constant for Rabi' al-thani or (Rabi' II), the 4th month of the Islamic year.

int RAJAB

Constant for Rajab, the 7th month of the Islamic year.

int RAMADAN

Constant for Ramadan, the 9th month of the Islamic year.

int SAFAR

Constant for Safar, the 2nd month of the Islamic year.

int SHABAN

Constant for Sha'ban, the 8th month of the Islamic year.

int SHAWWAL

Constant for Shawwal, the 10th month of the Islamic year.

Inherited constants

Inherited fields

Public constructors

IslamicCalendar()

Constructs a default IslamicCalendar using the current time in the default time zone with the default FORMAT locale.

IslamicCalendar(TimeZone zone)

Constructs an IslamicCalendar based on the current time in the given time zone with the default FORMAT locale.

IslamicCalendar(Locale aLocale)

Constructs an IslamicCalendar based on the current time in the default time zone with the given locale.

IslamicCalendar(ULocale locale)

Constructs an IslamicCalendar based on the current time in the default time zone with the given locale.

IslamicCalendar(TimeZone zone, Locale aLocale)

Constructs an IslamicCalendar based on the current time in the given time zone with the given locale.

IslamicCalendar(TimeZone zone, ULocale locale)

Constructs an IslamicCalendar based on the current time in the given time zone with the given locale.

IslamicCalendar(Date date)

Constructs an IslamicCalendar with the given date set in the default time zone with the default FORMAT locale.

IslamicCalendar(int year, int month, int date)

Constructs an IslamicCalendar with the given date set in the default time zone with the default FORMAT locale.

IslamicCalendar(int year, int month, int date, int hour, int minute, int second)

Constructs an IslamicCalendar with the given date and time set for the default time zone with the default FORMAT locale.

Public methods

IslamicCalendar.CalculationType getCalculationType()

gets the calculation type for this calendar.

String getType()

[icu] Returns the calendar type name string for this Calendar object.

void setCalculationType(IslamicCalendar.CalculationType type)

sets the calculation type for this calendar.

Protected methods

void handleComputeFields(int julianDay)

Override Calendar to compute several fields specific to the Islamic calendar system.

int handleComputeMonthStart(int eyear, int month, boolean useMonth)

Returns the Julian day number of day before the first day of the given month in the given extended year.

int handleGetExtendedYear()

Returns the extended year defined by the current fields.

int handleGetLimit(int field, int limitType)

Subclass API for defining limits of different types.

int handleGetMonthLength(int extendedYear, int month)

Return the length (in days) of the given month.

int handleGetYearLength(int extendedYear)

Return the number of days in the given Islamic year

Inherited methods

Constants

DHU_AL_HIJJAH

Added in API level 24
public static final int DHU_AL_HIJJAH

Constant for Dhu al-Hijjah, the 12th month of the Islamic year.

Constant Value: 11 (0x0000000b)

DHU_AL_QIDAH

Added in API level 24
public static final int DHU_AL_QIDAH

Constant for Dhu al-Qi'dah, the 11th month of the Islamic year.

Constant Value: 10 (0x0000000a)

JUMADA_1

Added in API level 24
public static final int JUMADA_1

Constant for Jumada al-awwal or (Jumada I), the 5th month of the Islamic year.

Constant Value: 4 (0x00000004)

JUMADA_2

Added in API level 24
public static final int JUMADA_2

Constant for Jumada al-thani or (Jumada II), the 6th month of the Islamic year.

Constant Value: 5 (0x00000005)

MUHARRAM

Added in API level 24
public static final int MUHARRAM

Constant for Muharram, the 1st month of the Islamic year.

Constant Value: 0 (0x00000000)

RABI_1

Added in API level 24
public static final int RABI_1

Constant for Rabi' al-awwal (or Rabi' I), the 3rd month of the Islamic year.

Constant Value: 2 (0x00000002)

RABI_2

Added in API level 24
public static final int RABI_2

Constant for Rabi' al-thani or (Rabi' II), the 4th month of the Islamic year.

Constant Value: 3 (0x00000003)

RAJAB

Added in API level 24
public static final int RAJAB

Constant for Rajab, the 7th month of the Islamic year.

Constant Value: 6 (0x00000006)

RAMADAN

Added in API level 24
public static final int RAMADAN

Constant for Ramadan, the 9th month of the Islamic year.

Constant Value: 8 (0x00000008)

SAFAR

Added in API level 24
public static final int SAFAR

Constant for Safar, the 2nd month of the Islamic year.

Constant Value: 1 (0x00000001)

SHABAN

Added in API level 24
public static final int SHABAN

Constant for Sha'ban, the 8th month of the Islamic year.

Constant Value: 7 (0x00000007)

SHAWWAL

Added in API level 24
public static final int SHAWWAL

Constant for Shawwal, the 10th month of the Islamic year.

Constant Value: 9 (0x00000009)

Public constructors

IslamicCalendar

Added in API level 24
public IslamicCalendar ()

Constructs a default IslamicCalendar using the current time in the default time zone with the default FORMAT locale.

IslamicCalendar

Added in API level 24
public IslamicCalendar (TimeZone zone)

Constructs an IslamicCalendar based on the current time in the given time zone with the default FORMAT locale.

Parameters
zone TimeZone: the given time zone.

IslamicCalendar

Added in API level 24
public IslamicCalendar (Locale aLocale)

Constructs an IslamicCalendar based on the current time in the default time zone with the given locale.

Parameters
aLocale Locale: the given locale.

IslamicCalendar

Added in API level 24
public IslamicCalendar (ULocale locale)

Constructs an IslamicCalendar based on the current time in the default time zone with the given locale.

Parameters
locale ULocale: the given ulocale.

IslamicCalendar

Added in API level 24
public IslamicCalendar (TimeZone zone, 
                Locale aLocale)

Constructs an IslamicCalendar based on the current time in the given time zone with the given locale.

Parameters
zone TimeZone: the given time zone.

aLocale Locale: the given locale.

IslamicCalendar

Added in API level 24
public IslamicCalendar (TimeZone zone, 
                ULocale locale)

Constructs an IslamicCalendar based on the current time in the given time zone with the given locale.

Parameters
zone TimeZone: the given time zone.

locale ULocale: the given ulocale.

IslamicCalendar

Added in API level 24
public IslamicCalendar (Date date)

Constructs an IslamicCalendar with the given date set in the default time zone with the default FORMAT locale.

Parameters
date Date: The date to which the new calendar is set.

IslamicCalendar

Added in API level 24
public IslamicCalendar (int year, 
                int month, 
                int date)

Constructs an IslamicCalendar with the given date set in the default time zone with the default FORMAT locale.

Parameters
year int: the value used to set the YEAR time field in the calendar.

month int: the value used to set the MONTH time field in the calendar. Note that the month value is 0-based. e.g., 0 for Muharram.

date int: the value used to set the DATE time field in the calendar.

IslamicCalendar

Added in API level 24
public IslamicCalendar (int year, 
                int month, 
                int date, 
                int hour, 
                int minute, 
                int second)

Constructs an IslamicCalendar with the given date and time set for the default time zone with the default FORMAT locale.

Parameters
year int: the value used to set the YEAR time field in the calendar.

month int: the value used to set the MONTH time field in the calendar. Note that the month value is 0-based. e.g., 0 for Muharram.

date int: the value used to set the DATE time field in the calendar.

hour int: the value used to set the HOUR_OF_DAY time field in the calendar.

minute int: the value used to set the MINUTE time field in the calendar.

second int: the value used to set the SECOND time field in the calendar.

Public methods

getCalculationType

Added in API level 24
public IslamicCalendar.CalculationType getCalculationType ()

gets the calculation type for this calendar.

Returns
IslamicCalendar.CalculationType

getType

Added in API level 24
public String getType ()

[icu] Returns the calendar type name string for this Calendar object. The returned string is the legacy ICU calendar attribute value, for example, "gregorian" or "japanese".

See type="old type name" for the calendar attribute of locale IDs at http://www.unicode.org/reports/tr35/#Key_Type_Definitions

Returns
String legacy calendar type name string

setCalculationType

Added in API level 24
public void setCalculationType (IslamicCalendar.CalculationType type)

sets the calculation type for this calendar.

Parameters
type IslamicCalendar.CalculationType

Protected methods

handleComputeFields

Added in API level 24
protected void handleComputeFields (int julianDay)

Override Calendar to compute several fields specific to the Islamic calendar system. These are:

  • ERA
  • YEAR
  • MONTH
  • DAY_OF_MONTH
  • DAY_OF_YEAR
  • EXTENDED_YEAR
The DAY_OF_WEEK and DOW_LOCAL fields are already set when this method is called. The getGregorianXxx() methods return Gregorian calendar equivalents for the given Julian day.

Parameters
julianDay int

handleComputeMonthStart

Added in API level 24
protected int handleComputeMonthStart (int eyear, 
                int month, 
                boolean useMonth)

Returns the Julian day number of day before the first day of the given month in the given extended year. Subclasses should override this method to implement their calendar system.

Parameters
eyear int: the extended year

month int: the zero-based month, or 0 if useMonth is false

useMonth boolean: if false, compute the day before the first day of the given year, otherwise, compute the day before the first day of the given month

Returns
int the Julian day number of the day before the first day of the given month and year

handleGetExtendedYear

Added in API level 24
protected int handleGetExtendedYear ()

Returns the extended year defined by the current fields. This will use the EXTENDED_YEAR field or the YEAR and supra-year fields (such as ERA) specific to the calendar system, depending on which set of fields is newer.

Returns
int the extended year

handleGetLimit

Added in API level 24
protected int handleGetLimit (int field, 
                int limitType)

Subclass API for defining limits of different types. Subclasses must implement this method to return limits for the following fields:

ERA
 YEAR
 MONTH
 WEEK_OF_YEAR
 WEEK_OF_MONTH
 DAY_OF_MONTH
 DAY_OF_YEAR
 DAY_OF_WEEK_IN_MONTH
 YEAR_WOY
 EXTENDED_YEAR

Parameters
field int: one of the above field numbers

limitType int: one of MINIMUM, GREATEST_MINIMUM, LEAST_MAXIMUM, or MAXIMUM

Returns
int

handleGetMonthLength

Added in API level 24
protected int handleGetMonthLength (int extendedYear, 
                int month)

Return the length (in days) of the given month.

Parameters
extendedYear int: The hijri year

month int: The hijri month, 0-based

Returns
int

handleGetYearLength

Added in API level 24
protected int handleGetYearLength (int extendedYear)

Return the number of days in the given Islamic year

Parameters
extendedYear int

Returns
int