Added in API level 24

IslamicCalendar


open class IslamicCalendar : Calendar
kotlin.Any
   ↳ 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 android.icu.util.Calendar#getInstance(ULocale) passing in a ULocale with the tag "@calendar=islamic" or "@calendar=islamic-civil" or "@calendar=islamic-umalqura".

Summary

Nested classes

enumeration of available calendar calculation types

Constants
static Int

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

static Int

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

static Int

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

static Int

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

static Int

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

static Int

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

static Int

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

static Int

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

static Int

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

static Int

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

static Int

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

static Int

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

Inherited constants
Public constructors

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

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

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

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

IslamicCalendar(zone: TimeZone!, aLocale: Locale!)

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

IslamicCalendar(zone: TimeZone!, locale: ULocale!)

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

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

IslamicCalendar(year: Int, month: Int, date: Int)

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

IslamicCalendar(year: Int, month: Int, date: Int, hour: Int, minute: Int, second: Int)

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

Public methods
open IslamicCalendar.CalculationType!

gets the calculation type for this calendar.

open String!

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

open Unit

sets the calculation type for this calendar.

Protected methods
open Unit

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

open Int
handleComputeMonthStart(eyear: Int, month: Int, useMonth: Boolean)

open Int

open Int
handleGetLimit(field: Int, limitType: Int)

open Int
handleGetMonthLength(extendedYear: Int, month: Int)

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

open Int
handleGetYearLength(extendedYear: Int)

Return the number of days in the given Islamic year

Inherited functions
Inherited properties

Constants

DHU_AL_HIJJAH

Added in API level 24
static val DHU_AL_HIJJAH: Int

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

Value: 11

DHU_AL_QIDAH

Added in API level 24
static val DHU_AL_QIDAH: Int

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

Value: 10

JUMADA_1

Added in API level 24
static val JUMADA_1: Int

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

Value: 4

JUMADA_2

Added in API level 24
static val JUMADA_2: Int

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

Value: 5

MUHARRAM

Added in API level 24
static val MUHARRAM: Int

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

Value: 0

RABI_1

Added in API level 24
static val RABI_1: Int

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

Value: 2

RABI_2

Added in API level 24
static val RABI_2: Int

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

Value: 3

RAJAB

Added in API level 24
static val RAJAB: Int

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

Value: 6

RAMADAN

Added in API level 24
static val RAMADAN: Int

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

Value: 8

SAFAR

Added in API level 24
static val SAFAR: Int

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

Value: 1

SHABAN

Added in API level 24
static val SHABAN: Int

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

Value: 7

SHAWWAL

Added in API level 24
static val SHAWWAL: Int

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

Value: 9

Public constructors

IslamicCalendar

Added in API level 24
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
IslamicCalendar(zone: TimeZone!)

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
IslamicCalendar(aLocale: Locale!)

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
IslamicCalendar(locale: ULocale!)

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
IslamicCalendar(
    zone: TimeZone!,
    aLocale: 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.
aLocale Locale!: the given locale.

IslamicCalendar

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

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
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
IslamicCalendar(
    year: Int,
    month: Int,
    date: Int)

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
IslamicCalendar(
    year: Int,
    month: Int,
    date: Int,
    hour: Int,
    minute: Int,
    second: Int)

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
open fun getCalculationType(): IslamicCalendar.CalculationType!

gets the calculation type for this calendar.

getType

Added in API level 24
open fun getType(): String!

[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

Return
String! legacy calendar type name string

setCalculationType

Added in API level 24
open fun setCalculationType(type: IslamicCalendar.CalculationType!): Unit

sets the calculation type for this calendar.

Protected methods

handleComputeFields

Added in API level 24
protected open fun handleComputeFields(julianDay: Int): Unit

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.

handleComputeMonthStart

Added in API level 24
protected open fun handleComputeMonthStart(
    eyear: Int,
    month: Int,
    useMonth: Boolean
): Int
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
Return
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 open fun handleGetExtendedYear(): Int
Return
Int the extended year

handleGetLimit

Added in API level 24
protected open fun handleGetLimit(
    field: Int,
    limitType: Int
): Int
Parameters
field Int: one of the above field numbers
limitType Int: one of MINIMUM, GREATEST_MINIMUM, LEAST_MAXIMUM, or MAXIMUM

handleGetMonthLength

Added in API level 24
protected open fun handleGetMonthLength(
    extendedYear: Int,
    month: Int
): Int

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

Parameters
extendedYear Int: The hijri year
month Int: The hijri month, 0-based

handleGetYearLength

Added in API level 24
protected open fun handleGetYearLength(extendedYear: Int): Int

Return the number of days in the given Islamic year