Adds whole years, quarters or months to the fields of a naive datetime, keeping its time of day: the add/9 callback CalendarInterval steps an interval of a year or a month with. The date moves as shift/6 moves it, clamping the day into a shorter month.

Arguments

• year, month and day are the date's fields in this calendar.

• hour, minute, second and microsecond are the time of day, returned unchanged.

• precision is :year, :quarter or :month.

• step is the number of years, quarters or months to add, which may be negative.

Returns

• {year, month, day, hour, minute, second, microsecond}.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {year, month, day, 12, 30, 0, {0, 0}} =
...>   Calendrical.Islamic.Observational.add(date.year, date.month, date.day, 12, 30, 0, {0, 0}, :month, 1)
iex> {year, month, day} == Calendrical.Islamic.Observational.shift(date.year, date.month, date.day, :months, 1, [])
true

Returns what this calendar's year is built of, :month or :week, as its info/0 states.

Returns

• :week for a calendar whose year is built of weeks.

• :month otherwise.

Examples

iex> Calendrical.Islamic.Observational.calendar_base() in [:month, :week]
true

Returns the calendar module whose CLDR calendar type is the one given, whichever calendar is asked (Calendrical.calendar_from_cldr_calendar_type/1).

Arguments

• calendar_type is a CLDR calendar type as an atom or a string.

Returns

• {:ok, calendar_module}, or

• {:error, exception} for a calendar type no calendar module has.

Examples

iex> Calendrical.Islamic.Observational.calendar_from_cldr_calendar_type(:gregorian)
{:ok, Calendrical.Gregorian}

iex> {:error, %Localize.UnknownCalendarError{}} =
...>   Calendrical.Islamic.Observational.calendar_from_cldr_calendar_type(:not_a_calendar)

Returns the day a date is written with: the day of its written_date/3.

Arguments

• year, month and day are a date of this calendar.

Returns

• The day of the date's written_date/3, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {_year, _month, written_day} = Calendrical.Islamic.Observational.written_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.Observational.cardinal_day(date.year, date.month, date.day) == written_day
true

Returns the CLDR month a month of the year names without a year (Calendrical.Month.cldr_month/2).

Arguments

• month is a month of this calendar.

Returns

• The CLDR month the month is named in the year that holds 1 January 2000, the month itself in the Hebrew calendar, whose names depend on the year, and the month itself where the reference year has no such month.

Examples

iex> {:ok, date} = Date.convert(~D[2000-01-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.cardinal_month(1) == Calendrical.Islamic.Observational.cldr_month(date.year, 1)
true

Returns the year a date is written with: the year of its written_date/3.

Arguments

• year, month and day are a date of this calendar.

Returns

• The year of the date's written_date/3, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {written_year, _month, _day} = Calendrical.Islamic.Observational.written_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.Observational.cardinal_year(date.year, date.month, date.day) == written_year
true

Returns the CLDR calendar type whose data names this calendar's months, days and quarters, as its info/0 states.

Returns

• A CLDR calendar type such as :gregorian or :hebrew.

Examples

iex> Calendrical.Islamic.Observational.cldr_calendar_type() == Calendrical.Islamic.Observational.info().cldr_calendar_type
true

Returns the CLDR calendar type whose data names a date's months and days: the member in effect on the date in a composite calendar, and this calendar's own otherwise (Calendrical.Info.cldr_calendar_type/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• A CLDR calendar type.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> in_effect = Calendrical.Info.in_effect(Calendrical.Islamic.Observational, date.year, date.month, date.day)
iex> Calendrical.Islamic.Observational.cldr_calendar_type(date.year, date.month, date.day) == in_effect.cldr_calendar_type()
true

Returns the CLDR month of a month of a year (Calendrical.Month.cldr_month/3).

Arguments

• year and month are a month of this calendar.

Returns

• A CLDR month number, or {month, :leap} where the month's name has a leap form, or

• {:error, exception} for a month the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> cldr_month = Calendrical.Islamic.Observational.cldr_month(date.year, date.month)
iex> Calendrical.Islamic.Observational.written_month_from_cldr_month(date.year, cldr_month) ==
...>   Calendrical.Islamic.Observational.numeric_month(date.year, date.month, date.day)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Islamic.Observational.cldr_month(date.year, 99)

Returns the cyclic year of a date (Calendrical.Era.cyclic_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• The date's place in the sexagenary cycle, 1 to 60, in an East Asian calendar, and its year in a calendar whose years run in no such cycle, or

• {:error, %Calendrical.InvalidDateError{}} for a year the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for no year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> cyclic_year = Calendrical.Islamic.Observational.cyclic_year(date.year, date.month, date.day)
iex> cyclic_year in 1..60 or cyclic_year == date.year
true

iex> {:error, %Calendrical.MissingFieldsError{}} = Calendrical.Islamic.Observational.cyclic_year(nil, 1, 1)

@spec date_at(DateTime.t(), Keyword.t()) :: {:ok, Date.t()} | {:error, Exception.t()}

Returns the observational Hijri date in effect at a given instant, under a chosen day-start convention.

The Islamic day begins at sunset, so after sunset at the observation point (Cairo) the date is already the following day. This maps an absolute instant to the Hijri date, choosing the boundary with the :day_start option, always evaluated at Cairo (the calendar's reference location).

For the plain civil-day mapping (the calendar's default), convert a date directly with Date.convert/2 instead.

Arguments

• datetime is a DateTime.t/0 — an absolute instant. Its own time zone fixes the instant; the day boundary is always taken at Cairo.

Options

• :day_start selects the moment the day begins:

  • :midnight (the default) — 00:00 Cairo standard time, the ordinary civil-day mapping.

  • :evening — 18:00 Cairo standard time, the fixed-clock proxy for sunset.

  • :sunset — true sunset (Maghrib) at Cairo, computed via Astro.

Returns

• {:ok, date} — an observational Hijri Date.t/0.

• {:error, %Calendrical.InvalidOptionValueError{}} for an invalid :day_start or :nightfall_angle.

• {:error, %Calendrical.UnsupportedDateRangeError{}} for a date outside the range the calendar or the installed JPL ephemeris covers.

• {:error, %Calendrical.NoDuskError{}} where the sun does not set, or nightfall does not occur, at the location on that day.

Examples

iex> {:ok, date} = Calendrical.Islamic.Observational.date_at(~U[2025-03-01 06:00:00Z])
iex> date.calendar
Calendrical.Islamic.Observational

Returns the date of this calendar that written figures name (date_from_written_date/3), as fields.

Arguments

• year, month and day are the figures a date is written with, as written_date/3 returns them.

Returns

• {year, month, day}, the date of this calendar, or

• {:error, %Calendrical.InvalidDateError{}} where the figures name no date.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {year, month, day} = Calendrical.Islamic.Observational.written_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.Observational.date_from_cardinal_date(year, month, day) == {date.year, date.month, date.day}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.date_from_cardinal_date(date.year, 0, 1)

Returns the date of a day of a year, counted from the year's first day.

Arguments

• year is a year of this calendar.

• day_of_year is the day of the year, counted from 1.

Returns

• A Date.t/0 of this calendar, or

• {:error, %Calendrical.InvalidDateError{}} for a day the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> day_of_year = Calendrical.Islamic.Observational.day_of_year(date.year, date.month, date.day)
iex> Calendrical.Islamic.Observational.date_from_day_of_year(date.year, day_of_year) == date
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.date_from_day_of_year(date.year, 1000)

@spec date_from_iso_days(integer()) :: {year(), month(), day()}

Returns an observational Islamic {year, month, day} for the given ISO day number.

Arguments

• iso_days is an integer count of days since the proleptic ISO epoch.

Returns

• A three-tuple {year, month, day} in the observational Islamic calendar.

• Raises Calendrical.UnsupportedDateRangeError if iso_days falls outside the range of the underlying JPL ephemeris.

Examples

iex> Calendrical.Islamic.Observational.date_from_iso_days(739_252)
{1445, 6, 19}

Returns the date of a day of a week of a week-year (Calendrical.Week.date_from_week_date/4).

Arguments

• week_year is a week-year of this calendar.

• week is a week of the week-year.

• day is the day of the week, numbered from 1 for the day the calendar's weeks begin on.

Returns

• A Date.t/0 of this calendar, or

• {:error, %Calendrical.InvalidDateError{}} where the week has no such day.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {week_year, week, day} = Calendrical.Islamic.Observational.week_date_from_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.Observational.date_from_week_date(week_year, week, day) == date
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.date_from_week_date(date.year, 1, 8)

Returns the date of this calendar that written figures name: the inverse of written_date/3, the fields themselves where they are a date.

Arguments

• year, month and day are the figures a date is written with, as written_date/3 returns them.

Returns

• {:ok, {year, month, day}}, the date of this calendar, or

• {:error, :invalid_date} where the figures name no date.

The reason is an atom, not an exception: Localize's date parser reads it, as Calendrical.date_from_written_date/3 sets out.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {year, month, day} = Calendrical.Islamic.Observational.written_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.Observational.date_from_written_date(year, month, day) == {:ok, {date.year, date.month, date.day}}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.date_from_written_date(date.year, 0, 1)
{:error, :invalid_date}

@spec date_to_iso_days(year(), month(), day()) :: integer()

Returns the number of ISO days for the given observational Islamic year, month, and day.

Arguments

• year is any Hijri year as an integer.

• month is a Hijri month in the range 1..12.

• day is a Hijri day-of-month in the range 1..30.

Returns

• An integer count of days since the proleptic ISO epoch.

• Raises Calendrical.UnsupportedDateRangeError if the date falls outside the range of the underlying JPL ephemeris.

Examples

iex> Calendrical.Islamic.Observational.date_to_iso_days(1446, 1, 1)
739439

Returns the dates of this calendar, earliest first, whose month and day are those given and that fall in a Gregorian year.

Arguments

• gregorian_year is the Gregorian year to search within.

• month and day are a month and a day of this calendar.

Returns

• A list of zero, one or two Date.t/0 of this calendar, earliest first, since this calendar's years and the Gregorian years drift.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> date in Calendrical.Islamic.Observational.dates_in_gregorian_year(2024, date.month, date.day)
true

Returns the days a month of a year has, as runs of their numbers (Calendrical.Month.day_numbers/3).

Arguments

• year and month are a month of this calendar.

Returns

• A list of ranges: one from 1 in every month of every calendar but a composite, whose month a change of calendar falls in has the days that are left, and [] for a month the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.day_numbers(date.year, date.month) ==
...>   [1..Calendrical.Islamic.Observational.days_in_month(date.year, date.month)//1]
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.day_numbers(date.year, 99)
[]

Returns the day of era and era of a date (Calendrical.Era.day_of_era/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• {day_of_era, era}, where the day of the era counts from the era's first day, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for a missing field.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {day_of_era, era} = Calendrical.Islamic.Observational.day_of_era(date.year, date.month, date.day)
iex> {_year_of_era, year_era} = Calendrical.Islamic.Observational.year_of_era(date.year, date.month, date.day)
iex> day_of_era >= 1 and era == year_era
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.day_of_era(date.year, date.month, 0)

Returns the day of the week of a date (Calendrical.Week.day_of_week/5).

Arguments

• year, month and day are a date of this calendar.

• starting_on is :default for the day this calendar's weeks begin on, or the name of a weekday, :monday to :sunday.

Returns

• {day_of_week, 1, 7}, the day numbered from the day the week begins on, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for a missing field.

Examples

# 1 June 2024 is a Saturday
iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.day_of_week(date.year, date.month, date.day, :monday)
{6, 1, 7}

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.day_of_week(date.year, date.month, 0, :monday)

Returns the day of the year of a date (Calendrical.Period.day_of_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• The day of the year, counted from 1 for its first day, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for a missing field.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> first_day = Calendrical.Islamic.Observational.year(date.year).first
iex> Calendrical.Islamic.Observational.day_of_year(date.year, date.month, date.day) == Date.diff(date, first_day) + 1
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.day_of_year(date.year, date.month, 0)

Returns the number of days in a month without a year (Calendrical.Month.days_in_month/2).

Arguments

• month is a month of this calendar.

Returns

• The number of days where the month has as many in every year, or

• {:ambiguous, lengths} where its length depends on the year, the lengths a range or, where they are not consecutive, a list, or

• {:error, %Calendrical.NotDefinedError{}} for a month the calendar has in no year, or

• {:error, exception}, a Calendrical.MissingFieldsError, where the month is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {fewest, most} = Calendrical.Islamic.Observational.days_in_month_bounds(date.month)
iex> case Calendrical.Islamic.Observational.days_in_month(date.month) do
...>   days when is_integer(days) -> fewest == days and most == days
...>   {:ambiguous, lengths} -> Enum.min(lengths) == fewest and Enum.max(lengths) == most
...> end
true

iex> {:error, %Calendrical.NotDefinedError{}} = Calendrical.Islamic.Observational.days_in_month(99)

@spec days_in_month(Calendar.year(), Calendar.month()) ::
  Calendar.day() | {:error, Exception.t()}

@spec days_in_month(year(), month()) :: 29..30 | {:error, Exception.t()}

Returns the number of days in the given Hijri year and month (29 or 30, determined by actual crescent visibility).

Arguments

• year is any Hijri year as an integer.

• month is a Hijri month in the range 1..12.

Returns

• The number of days in the month (29 or 30), or

• {:error, %Calendrical.UnsupportedDateRangeError{}} for a month the installed ephemeris does not cover, or

• {:error, %Calendrical.InvalidMonthError{}} for a month that is not 1..12, or

• {:error, %Calendrical.MissingFieldsError{}} where the year or the month is nil.

Examples

iex> Calendrical.Islamic.Observational.days_in_month(1446, 1)
30

iex> Calendrical.Islamic.Observational.days_in_month(1446, 5)
29

Returns the fewest and the most days a month has in any year (Calendrical.Month.days_in_month_bounds/2).

Arguments

• month is a month of this calendar.

Returns

• {fewest, most}, or

• {:error, exception} for a month the calendar has in no year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {fewest, most} = Calendrical.Islamic.Observational.days_in_month_bounds(date.month)
iex> Calendrical.Islamic.Observational.days_in_month(date.year, date.month) in fewest..most
true

iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Islamic.Observational.days_in_month_bounds(99)

Returns the number of days in a week.

Returns

• 7.

Examples

iex> Calendrical.Islamic.Observational.days_in_week()
7

Returns the number of days in a year (Calendrical.Period.days_in_year/2).

Arguments

• year is a year of this calendar.

Returns

• The number of days, or

• {:error, %Calendrical.InvalidDateError{}} for a year the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for no year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.days_in_year(date.year) == Enum.count(Calendrical.Islamic.Observational.year(date.year))
true

iex> {:error, %Calendrical.MissingFieldsError{}} = Calendrical.Islamic.Observational.days_in_year(nil)

Returns the number of whole units between two dates, counted positionally.

Arguments

• from and to are dates of this calendar as {year, month, day} tuples.

• date_part is one of :years, :quarters, :months, :weeks or :days.

Returns

• The largest number of date_parts that can be added to from without passing to, negative where to is before from, or

• {:error, %Calendrical.InvalidDateError{}} for a from or to the calendar does not have, {:error, %Calendrical.MissingFieldsError{}} for one missing a field, or {:error, %Calendrical.InvalidPartError{}} for a date_part other than the five.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> from = {date.year, date.month, date.day}
iex> Calendrical.Islamic.Observational.diff(from, {date.year + 1, date.month, date.day}, :years)
1

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> later = Date.add(date, 10)
iex> Calendrical.Islamic.Observational.diff({later.year, later.month, later.day}, {date.year, date.month, date.day}, :days)
-10

Returns the epoch of this calendar: the ISO day number of its first day.

Returns

• The epoch as an integer number of days since the ISO epoch.

Examples

iex> Calendrical.Islamic.Observational.epoch() |> is_integer()
true

Returns the CLDR calendar type that names this calendar's eras, as its info/0 states.

Returns

• A CLDR calendar type such as :gregorian or :japanese.

Examples

iex> Calendrical.Islamic.Observational.era_calendar_type() == Calendrical.Islamic.Observational.info().era_calendar_type
true

Returns the extended year of a date (Calendrical.Era.extended_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• The year numbered without a gap at 0, so that in a calendar with no year 0 the year before 1 is 0, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for no year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.extended_year(date.year, date.month, date.day) == date.year
true

iex> {:error, %Calendrical.MissingFieldsError{}} = Calendrical.Islamic.Observational.extended_year(nil, 1, 1)

Returns the static facts about this calendar, as Calendrical.Info.t/0.

Returns

• A Calendrical.Info.t/0 describing this calendar.

Examples

iex> Calendrical.Islamic.Observational.info().calendar
Calendrical.Islamic.Observational

Returns the ISO 8601 week-year and week of the day a date names (Calendrical.Week.iso_week_of_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• {week_year, week} of ISO 8601, or

• {:error, exception} for a date the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.iso_week_of_year(date.year, date.month, date.day)
{2024, 22}

Returns the position of a year's leap month, or nil where the year has none.

Arguments

• year is a year of this calendar.

Returns

• The leap month's position in the year, or

• nil where the year has no leap month, as for anything but an integer year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> leap_month = Calendrical.Islamic.Observational.leap_month(date.year)
iex> is_nil(leap_month) or leap_month in 1..Calendrical.Islamic.Observational.months_in_year(date.year)
true

@spec leap_year?(year()) :: boolean()

Returns whether the given Hijri year is a 355-day year (the observational analogue of a "leap year").

Year length varies between 354 and 355 days depending on actual crescent sightings, so this must be computed by comparing the starts of two successive years.

Arguments

• year is any Hijri year as an integer.

Returns

• true if the year contains 355 days; otherwise false.

Examples

iex> Calendrical.Islamic.Observational.leap_year?(1447)
false

iex> Calendrical.Islamic.Observational.leap_year?(1446)
true

@spec location() :: Geo.PointZ.t()

Returns the geographic location used to determine crescent visibility for this calendar.

Returns

• A Geo.PointZ.t/0 for Cairo, Egypt (Reingold's canonical "Islamic location").

Examples

iex> Calendrical.Islamic.Observational.location().coordinates
{31.3, 30.1, 200.0}

Returns the traditional month at a position in a year (Calendrical.Month.traditional_month/3), or an error for a place the year does not have.

Arguments

• year and month are a month of this calendar.

Returns

• The month's traditional number, or {month, :leap} for a leap month, or

• {:error, %Calendrical.InvalidMonthError{}} for a month the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.lunar_month_of_year(date.year, date.month) ==
...>   Calendrical.Islamic.Observational.traditional_month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Islamic.Observational.lunar_month_of_year(date.year, 99)

Returns the days of a month of a year (Calendrical.Period.month/3).

Arguments

• year and month are a month of this calendar.

Returns

• A Date.Range.t/0, or

• {:error, %Calendrical.InvalidDateError{}} for a month the year does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for a missing year or month.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> date in Calendrical.Islamic.Observational.month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.month(date.year, 99)

Returns the position of a traditional month in a year (Calendrical.Month.month_from_traditional/3).

Arguments

• year is a year of this calendar.

• traditional_month is a month's traditional number, or {month, :leap} for a leap month.

Returns

• The month's position in the year, or

• {:error, exception} where the year has no such month.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> traditional_month = Calendrical.Islamic.Observational.traditional_month(date.year, date.month)
iex> Calendrical.Islamic.Observational.month_from_traditional(date.year, traditional_month) == date.month
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Islamic.Observational.month_from_traditional(date.year, 99)

Returns the months a year has, as runs of their numbers (Calendrical.Month.month_numbers/2).

Arguments

• year is a year of this calendar.

Returns

• A list of ranges: one from 1 in every year of every calendar but a composite, whose year a change of calendar falls in has the months that are left, and [] for a year the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.month_numbers(date.year) == [1..Calendrical.Islamic.Observational.months_in_year(date.year)//1]
true

Returns the CLDR month of a month of a year: the index of its name in this calendar's CLDR data, with {month, :leap} where the name has a leap form (Calendrical.Month.cldr_month/3).

Arguments

• year, month and day are a date of this calendar. The year and the day may be nil: a month's name needs only the month.

Returns

• A CLDR month number, or {month, :leap}, or

• {:error, %Calendrical.InvalidDateError{}} for a day the month does not have, or

• {:error, exception} for a month the year does not have, or a Calendrical.MissingFieldsError where the month is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.month_of_year(date.year, date.month, date.day) == Calendrical.Islamic.Observational.cldr_month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.month_of_year(date.year, date.month, 0)

Returns the number of months in a leap year: the most months a year of this calendar has.

Returns

• A positive integer.

Examples

iex> Calendrical.Islamic.Observational.months_in_leap_year() >= Calendrical.Islamic.Observational.months_in_ordinary_year()
true

Returns the number of months in an ordinary year: the fewest months a year of this calendar has.

Returns

• A positive integer.

Examples

iex> Calendrical.Islamic.Observational.months_in_ordinary_year() <= Calendrical.Islamic.Observational.months_in_leap_year()
true

Returns the number of months in a year without a year: the count where every year has as many, {:ambiguous, range} where a leap year has more, and {:error, %Calendrical.NotDefinedError{}} for a composite calendar (Calendrical.Info.months_in_year/1).

Returns

• The number of months where every year has as many, or

• {:ambiguous, fewest..most} where a leap year has more, or

• {:error, %Calendrical.NotDefinedError{}} for a composite calendar, whose bounds months_in_year_bounds/0 gives.

Examples

iex> case Calendrical.Islamic.Observational.months_in_year() do
...>   months when is_integer(months) -> months == Calendrical.Islamic.Observational.months_in_leap_year()
...>   {:ambiguous, fewest..most//1} -> {fewest, most} == Calendrical.Islamic.Observational.info().months_in_year
...>   {:error, %Calendrical.NotDefinedError{}} -> is_list(Calendrical.Islamic.Observational.info().members)
...> end
true

Returns the number of months in a given year.

Arguments

• year is the year in this calendar.

Returns

• The number of months in the year, as a positive integer, or

• {:error, %Calendrical.MissingFieldsError{}} where year is nil, or

• {:error, %Calendrical.InvalidDateError{}} where year is no integer.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.months_in_year(date.year) >= date.month
true

Returns the fewest and the most months a year has (Calendrical.Month.months_in_year_bounds/1).

Returns

• {fewest, most}, which in a composite calendar counts the months left in a year a change of calendar falls in.

Examples

iex> {fewest, most} = Calendrical.Islamic.Observational.months_in_year_bounds()
iex> fewest <= Calendrical.Islamic.Observational.months_in_ordinary_year() and
...>   most >= Calendrical.Islamic.Observational.months_in_leap_year()
true

Converts ISO days and a day fraction to a naive datetime of this calendar, as Calendar.naive_datetime_from_iso_days/1 asks.

Arguments

• iso_days is {days, {parts_in_day, parts_per_day}}, a day and a fraction of it.

Returns

• {year, month, day, hour, minute, second, microsecond} of this calendar.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {year, month, day, 12, 0, 0, {0, 6}} =
...>   Calendrical.Islamic.Observational.naive_datetime_from_iso_days({739403, {43200000000, 86400000000}})
iex> {year, month, day} == {date.year, date.month, date.day}
true

Converts a naive datetime of this calendar to ISO days and a day fraction, as Calendar.naive_datetime_to_iso_days/7 asks.

Arguments

• year, month and day are a date of this calendar.

• hour, minute, second and microsecond are a time of day, the microsecond as {microseconds, precision}.

Returns

• {iso_days, {parts_in_day, parts_per_day}}.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.naive_datetime_to_iso_days(date.year, date.month, date.day, 12, 0, 0, {0, 6})
{739403, {43200000000, 86400000000}}

Returns the days of a named month in a year (Calendrical.Month.named_month/3).

Arguments

• year is a year of this calendar.

• named_month is the CLDR month that names the month.

Returns

• A list of Date.Range.t/0, one for each counted month that carries the name, earliest first, and [] where none does.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> cldr_month = Calendrical.Islamic.Observational.cldr_month(date.year, date.month)
iex> Calendrical.Islamic.Observational.named_month(date.year, cldr_month) |> Enum.any?(&(date in &1))
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.named_month(date.year, 99)
[]

Returns the number a date's month is written with in figures: the month of its written_date/3.

Arguments

• year, month and day are a date of this calendar.

Returns

• The month of the date's written_date/3: a month number, or {month, :leap} for a leap month of a lunisolar calendar, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {_year, written_month, _day} = Calendrical.Islamic.Observational.written_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.Observational.numeric_month(date.year, date.month, date.day) == written_month
true

Returns the position in a year of a traditional month (Calendrical.Month.month_from_traditional/3), as {:ok, month}.

Arguments

• year is a year of this calendar.

• traditional_month is a month's traditional number, or {month, :leap} for a leap month.

Returns

• {:ok, month}, the month's position in the year, or

• {:error, %Calendrical.InvalidMonthError{}} for a month or a leap month the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> traditional_month = Calendrical.Islamic.Observational.traditional_month(date.year, date.month)
iex> Calendrical.Islamic.Observational.ordinal_month_from_traditional(date.year, traditional_month) == {:ok, date.month}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Islamic.Observational.ordinal_month_from_traditional(date.year, 99)

Parses a date written in this calendar's own notation.

Arguments

• string is a date written YYYY-MM-DD, with a leading - for a year before 1, or, in a calendar of weeks, YYYY-Www-D.

Returns

• {:ok, {year, month, day}}, or

• {:error, :invalid_format} where the text is not in that form or its fields are not digits, or

• {:error, :invalid_date} where the text names no date of this calendar.

The reason is an atom, not an exception, because Calendar.parse_date/1 requires one: Date.from_iso8601/2 reads it.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.parse_date(Date.to_string(date)) == {:ok, {date.year, date.month, date.day}}
true

iex> Calendrical.Islamic.Observational.parse_date("not a date")
{:error, :invalid_format}

Parses a naive datetime written in this calendar's own notation.

Arguments

• string is a date as parse_date/1 reads it, then T or a space and a time of day.

Returns

• {:ok, {year, month, day, hour, minute, second, microsecond}}, or

• {:error, reason}, such as :invalid_format or :invalid_date, where the text is no such datetime.

The reason is an atom, not an exception, because Calendar.parse_naive_datetime/1 requires one: NaiveDateTime.from_iso8601/2 reads it.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.parse_naive_datetime(Date.to_string(date) <> "T12:00:00") ==
...>   {:ok, {date.year, date.month, date.day, 12, 0, 0, {0, 0}}}
true

iex> Calendrical.Islamic.Observational.parse_naive_datetime("2024-06-01")
{:error, :invalid_format}

Parses a UTC datetime written in this calendar's own notation.

Arguments

• string is a date as parse_date/1 reads it, then T or a space, a time of day and an offset from UTC, Z or ±HH:MM.

Returns

• {:ok, {year, month, day, hour, minute, second, microsecond}, offset}, the datetime in UTC and the offset in seconds it was written with, or

• {:error, reason}, such as :invalid_format, :invalid_date or :missing_offset, where the text is no such datetime.

The reason is an atom, not an exception, because Calendar.parse_utc_datetime/1 requires one: DateTime.from_iso8601/2 reads it.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.parse_utc_datetime(Date.to_string(date) <> "T12:00:00Z") ==
...>   {:ok, {date.year, date.month, date.day, 12, 0, 0, {0, 0}}, 0}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.parse_utc_datetime(Date.to_string(date) <> "T12:00:00")
{:error, :missing_offset}

Returns the calendar a date written for this calendar is parsed in, as its info/0 states.

Returns

• A calendar module.

Examples

iex> Calendrical.Islamic.Observational.parsing_calendar() == Calendrical.Islamic.Observational.info().parsing_calendar
true

Returns the calendars a date written for this calendar may be written in: the members of a composite calendar, and this calendar alone otherwise (Calendrical.Info.parsing_calendars/1).

Returns

• A non-empty list of calendar modules, the members of a composite calendar in the order they take effect.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> in_effect = Calendrical.Info.in_effect(Calendrical.Islamic.Observational, date.year, date.month, date.day)
iex> in_effect in Calendrical.Islamic.Observational.parsing_calendars()
true

Returns the number of periods in a year: its months.

Arguments

• year is a year of this calendar.

Returns

• The number of months in the year, as months_in_year/1 returns it.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.periods_in_year(date.year) == Calendrical.Islamic.Observational.months_in_year(date.year)
true

Returns the days of a quadrimester of a year (Calendrical.Period.quadrimester/3).

Arguments

• year is a year of this calendar.

• quadrimester is the quadrimester, 1 to 3.

Returns

• A Date.Range.t/0, or

• {:error, %Calendrical.InvalidDateError{}} for a quadrimester or a year the calendar does not have, or

• {:error, %Calendrical.MissingFieldsError{}} where the year or the quadrimester is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.quadrimester(date.year, 1).first == Calendrical.Islamic.Observational.year(date.year).first
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.quadrimester(date.year, 4)

Returns the days of a quarter of a year (Calendrical.Period.quarter/3).

Arguments

• year is a year of this calendar.

• quarter is the quarter, 1 to 4.

Returns

• A Date.Range.t/0, or

• {:error, %Calendrical.InvalidDateError{}} for a quarter or a year the calendar does not have, or

• {:error, %Calendrical.MissingFieldsError{}} where the year or the quarter is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> quarter = Calendrical.Islamic.Observational.quarter_of_year(date.year, date.month, date.day)
iex> date in Calendrical.Islamic.Observational.quarter(date.year, quarter)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.quarter(date.year, 5)

Returns the quarter of the year a date falls in (Calendrical.Period.quarter_of_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• The quarter, 1 to 4, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for a missing year or month.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.quarter_of_year(date.year, date.month, date.day) in 1..4
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.quarter_of_year(date.year, date.month, 0)

Returns the related Gregorian year of a date (Calendrical.Era.related_gregorian_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• The Gregorian year the date's calendar year begins in, or

• {:error, %Calendrical.InvalidDateError{}} for a year the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for no year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:ok, first_day} = Date.convert(Calendrical.Islamic.Observational.year(date.year).first, Calendrical.Gregorian)
iex> Calendrical.Islamic.Observational.related_gregorian_year(date.year, date.month, date.day) == first_day.year
true

Returns the days of a semester of a year (Calendrical.Period.semester/3).

Arguments

• year is a year of this calendar.

• semester is the semester, 1 or 2.

Returns

• A Date.Range.t/0, or

• {:error, %Calendrical.InvalidDateError{}} for a semester or a year the calendar does not have, or

• {:error, %Calendrical.MissingFieldsError{}} where the year or the semester is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.semester(date.year, 1).first == Calendrical.Islamic.Observational.year(date.year).first
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.Observational.semester(date.year, 3)

Returns the date a number of years, quarters, months, weeks or days on from a date of this calendar, by position, with the traditional month kept across years and a day the resulting month lacks clamped to its last day unless clamp: false (Calendrical.Shift.shift/7).

Arguments

• year, month and day are a date of this calendar.

• date_part is one of :years, :quarters, :months, :weeks or :days.

• increment is the number of units, which may be negative.

• options is a keyword list of options.

Options

• :clamp is whether a day the resulting month lacks becomes its last day. The default is true.

Returns

• {year, month, day} of this calendar, or

• {:error, %Calendrical.InvalidDateError{}} where year, month and day are no date of this calendar, or

• {:error, %Calendrical.MissingFieldsError{}} where a field is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> Calendrical.Islamic.Observational.shift(date.year, date.month, date.day, :days, 0)
{date.year, date.month, date.day}

Shifts a date by a duration: its years and months together, as shift/6 adds months, and then its weeks and days.

Arguments

• year, month and day are a date of this calendar.

• duration is a Duration.t/0.

Returns

• {year, month, day} of this calendar.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> {year, month, day} = Calendrical.Islamic.Observational.shift_date(date.year, date.month, date.day, Duration.new!(day: 7))
iex> Date.new!(year, month, day, Calendrical.Islamic.Observational) == Date.add(date, 7)
true

Shifts a naive datetime by a duration: its date as shift_date/4 shifts it, and its time as Calendar.ISO does.

Arguments

• year, month and day are a date of this calendar.

• hour, minute, second and microsecond are a time of day, the microsecond as {microseconds, precision}.

• duration is a Duration.t/0.

Returns

• {year, month, day, hour, minute, second, microsecond} of this calendar.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.Observational)
iex> next_day = Date.add(date, 1)
iex> Calendrical.Islamic.Observational.shift_naive_datetime(date.year, date.month, date.day, 23, 0, 0, {0, 0}, Duration.new!(hour: 2)) ==
...>   {next_day.year, next_day.month, next_day.day, 1, 0, 0, {0, 0}}
true

Shifts a time by a duration, as Calendar.ISO does.

Arguments

• hour, minute, second and microsecond are a time of day, the microsecond as {microseconds, precision}.

• duration is a Duration.t/0 of time units.

Returns

• {hour, minute, second, microsecond}, wrapped around midnight.

Examples

iex> Calendrical.Islamic.Observational.shift_time(23, 0, 0, {0, 0}, Duration.new!(hour: 2))
{1, 0, 0, {0, 0}}