Calendrical.Hebrew (Calendrical v0.9.0)

Copy Markdown

Implementation of the Hebrew (Jewish) calendar.

The Hebrew calendar is a lunisolar calendar with 12 months in an ordinary year and 13 months in a leap year. The leap month (Adar I) is inserted before Adar (which becomes Adar II) in the 3rd, 6th, 8th, 11th, 14th, 17th and 19th years of each 19-year Metonic cycle.

Year length varies between 353, 354, 355 (ordinary) and 383, 384, 385 (leap) days. The variability comes from two of the twelve "fixed" months — Heshvan (month 2) and Kislev (month 3) — which can each be either 29 or 30 days, plus the molad of Tishri delay rules used to keep the calendar aligned with both the lunar and solar cycles and to prevent certain holidays from falling on prohibited days of the week.

Month numbering

Months are numbered to match the CLDR Hebrew calendar convention, with Tishri = 1 and the Hebrew year starting on 1 Tishri. The leap month, Adar I, occupies position 6 and is only valid in leap years. In an ordinary year, month 6 does not exist; the calendar goes directly from 5 (Shevat) to 7 (Adar).

#NameLengthNotes
1Tishri30Year start
2Heshvan29 / 30(long in 355- and 385-day years)
3Kislev30 / 29(short in 353- and 383-day years)
4Tevet29
5Shevat30
6Adar I30leap years only
7Adar / Adar II29"Adar" in ordinary years; "Adar II" in leap years
8Nisan30
9Iyar29
10Sivan30
11Tamuz29
12Av30
13Elul29

Days are assumed to begin at midnight rather than at sunset.

Reference

Algorithms are taken from Dershowitz & Reingold, Calendrical Calculations (4th ed.), Chapter 8, "The Hebrew Calendar". Note that Reingold uses Nisan = 1 month numbering internally, while this module uses CLDR's Tishri = 1 numbering at the public API; the conversion is handled transparently.

Summary

Types

day()
month()
year()

Functions

calendar_base()

Identifies whether this calendar is month or week based.

calendar_year(year, month, day)

Returns the calendar year as displayed on rendered calendars.

cldr_calendar_type()

Defines the CLDR calendar type for this calendar.

cyclic_year(year, month, day)

Returns the cyclic year as displayed on rendered calendars.

date_from_iso_days(iso_days)

Returns a Hebrew {year, month, day} tuple for the given ISO day number.

date_to_iso_days(year, month, day)

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

day_of_era(year, month, day)

Calculates the day and era from the given year, month, and day.

day_of_year(year, month, day)

Calculates the day of the year from the given year, month, and day.

days_in_month(month)

Returns how many days there are in the given month.

days_in_month(year, month)

Returns the number of days in the given Hebrew year and month.

days_in_week()

Returns the number days in a a week.

days_in_year(year)

Returns the total number of days in the given Hebrew year.

epoch()
epoch_day_of_week()
extended_year(year, month, day)

Returns the extended year as displayed on rendered calendars.

first_day_of_week()
hebrew_new_year(year)

Returns the ISO day number of 1 Tishri of the given Hebrew year (the start of the Hebrew year).

iso_week_of_year(year, month, day)

Calculates the ISO week of the year from the given year, month, and day.

last_day_of_week()
leap_year?(year)

Returns whether the given Hebrew year is a leap year (i.e. it contains the embolismic month Adar I).

month(year, month)

Returns a Date.Range.t/0 representing a given month of a year.

month_of_year(year, month, day)

Returns the month-of-year for the given Hebrew date.

months_in_leap_year()

Returns the number of months in a leap year.

months_in_ordinary_year()

Returns the number of months in a normal year.

months_in_year(year)

Returns the number of months in the given Hebrew year (12 in an ordinary year, 13 in a leap year).

naive_datetime_from_iso_days(arg)

Converts the t:Calendar.iso_days format to the datetime format specified by this calendar.

naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond)

Returns the t:Calendar.iso_days format of the specified date.

periods_in_year(year)

Returns the number of periods in a given year. A period corresponds to a month in month-based calendars and a week in week-based calendars.

plus(year, month, day, date_part, increment, options \\ [])

Adds an increment number of date_parts to a year-month-day.

quarter(year, quarter)

Returns a Date.Range.t/0 representing a given quarter of a year.

quarter_of_year(year, month, day)

Returns {:error, :not_defined} because the Hebrew calendar does not define quarters; the year has a variable number of months (12 or 13) and so does not divide evenly into four quarters.

related_gregorian_year(year, month, day)

Returns the related gregorain year as displayed on rendered calendars.

valid_date?(year, month, day)

Returns whether the given year, month, and day form a valid Hebrew date.

week(year, week)

Returns a Date.Range.t/0 representing a given week of a year.

week_of_month(year, month, day)

Calculates the week of the year from the given year, month, and day.

week_of_year(year, month, day)

Calculates the week of the year from the given year, month, and day.

weeks_in_year(year)

Returns the number of weeks in a given year.

year(year)

Returns a Date.Range.t/0 representing a given year.

year_of_era(year)

Calculates the year and era from the given year.

year_of_era(year, month, day)

Calculates the year and era from the given date.

Types

day()

@type day() :: 1..30

month()

@type month() :: 1..13

year()

@type year() :: pos_integer()

Functions

calendar_base()

Identifies whether this calendar is month or week based.

calendar_year(year, month, day)

@spec calendar_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.year()

Returns the calendar year as displayed on rendered calendars.

cldr_calendar_type()

Defines the CLDR calendar type for this calendar.

This type is used in support of Calendrical. localize/3.

cyclic_year(year, month, day)

@spec cyclic_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.year()

Returns the cyclic year as displayed on rendered calendars.

date_from_iso_days(iso_days)

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

Returns a Hebrew {year, month, day} tuple 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 Hebrew calendar.

Examples

iex> Calendrical.Hebrew.date_from_iso_days(739_500)
{5784, 13, 3}

date_to_iso_days(year, month, day)

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

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

Arguments

  • year is any positive Hebrew year as an integer.

  • month is a Hebrew month in the range 1..13.

  • day is a Hebrew day-of-month.

Returns

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

Examples

iex> Calendrical.Hebrew.date_to_iso_days(5785, 1, 1)
739527

day_of_era(year, month, day)

@spec day_of_era(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {day :: Calendar.day(), era :: Calendar.era()}

Calculates the day and era from the given year, month, and day.

By default we consider on two eras: before the epoch and on-or-after the epoch.

day_of_year(year, month, day)

@spec day_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.day()

Calculates the day of the year from the given year, month, and day.

days_in_month(month)

@spec days_in_month(Calendar.month()) ::
  Calendar.month()
  | {:ambiguous, Range.t() | [pos_integer()]}
  | {:error, :undefined}

Returns how many days there are in the given month.

Must be implemented in derived calendars because we cannot know what the calendar format is.

days_in_month(year, month)

@spec days_in_month(Calendar.year(), Calendar.month()) :: Calendar.month()
@spec days_in_month(year(), month()) :: 0..30

Returns the number of days in the given Hebrew year and month.

Month 6 (Adar I) only exists in leap years; the function returns 0 for month 6 in an ordinary year.

Arguments

  • year is any positive Hebrew year as an integer.

  • month is a Hebrew month in the range 1..13.

Returns

  • The number of days in the month, between 29 and 30 (or 0 for month 6 in an ordinary year).

Examples

iex> Calendrical.Hebrew.days_in_month(5785, 1)
30

iex> Calendrical.Hebrew.days_in_month(5784, 6)
30

iex> Calendrical.Hebrew.days_in_month(5785, 6)
0

days_in_week()

Returns the number days in a a week.

days_in_year(year)

@spec days_in_year(year()) :: 353..355 | 383..385

Returns the total number of days in the given Hebrew year.

Possible values are 353, 354, 355 (ordinary years) and 383, 384, 385 (leap years).

Arguments

  • year is any positive Hebrew year as an integer.

Returns

  • The number of days in the year.

Examples

iex> Calendrical.Hebrew.days_in_year(5785)
355

iex> Calendrical.Hebrew.days_in_year(5784)
383

epoch()

epoch_day_of_week()

extended_year(year, month, day)

@spec extended_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.year()

Returns the extended year as displayed on rendered calendars.

first_day_of_week()

hebrew_new_year(year)

@spec hebrew_new_year(year()) :: integer()

Returns the ISO day number of 1 Tishri of the given Hebrew year (the start of the Hebrew year).

Arguments

  • year is any positive Hebrew year as an integer.

Returns

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

Examples

iex> Calendrical.Hebrew.hebrew_new_year(5785)
739527

iso_week_of_year(year, month, day)

@spec iso_week_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {:error, :not_defined}

Calculates the ISO week of the year from the given year, month, and day.

By default this function always returns {:error, :not_defined}.

last_day_of_week()

leap_year?(year)

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

Returns whether the given Hebrew year is a leap year (i.e. it contains the embolismic month Adar I).

Leap years are determined by a 19-year Metonic cycle: years 3, 6, 8, 11, 14, 17, and 19 of each cycle are leap years.

Arguments

  • year is any positive Hebrew year as an integer.

Returns

  • true if the year contains 13 months; otherwise false.

Examples

iex> Calendrical.Hebrew.leap_year?(5784)
true

iex> Calendrical.Hebrew.leap_year?(5785)
false

month(year, month)

Returns a Date.Range.t/0 representing a given month of a year.

month_of_year(year, month, day)

@spec month_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.month() | {Calendar.month(), Calendrical.leap_month?()}

Returns the month-of-year for the given Hebrew date.

In a leap year, month 7 is Adar II and is returned as {7, :leap} so that Calendrical.localize/3 picks up the CLDR 7_yeartype_leap variant ("Adar II"). All other months are returned as plain integers.

Arguments

  • year is any positive Hebrew year as an integer.

  • month is a Hebrew month in the range 1..13.

  • day is a Hebrew day-of-month.

Returns

  • The plain month integer, or {7, :leap} for Adar II.

Examples

iex> Calendrical.Hebrew.month_of_year(5785, 7, 1)
7

iex> Calendrical.Hebrew.month_of_year(5784, 7, 1)
{7, :leap}

months_in_leap_year()

Returns the number of months in a leap year.

months_in_ordinary_year()

Returns the number of months in a normal year.

months_in_year(year)

@spec months_in_year(year()) :: 12..13

Returns the number of months in the given Hebrew year (12 in an ordinary year, 13 in a leap year).

Arguments

  • year is any positive Hebrew year as an integer.

Returns

  • 12 for an ordinary year or 13 for a leap year.

Examples

iex> Calendrical.Hebrew.months_in_year(5785)
12

iex> Calendrical.Hebrew.months_in_year(5784)
13

naive_datetime_from_iso_days(arg)

@spec naive_datetime_from_iso_days(Calendar.iso_days()) ::
  {Calendar.year(), Calendar.month(), Calendar.day(), Calendar.hour(),
   Calendar.minute(), Calendar.second(), Calendar.microsecond()}

Converts the t:Calendar.iso_days format to the datetime format specified by this calendar.

naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond)

@spec naive_datetime_to_iso_days(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond()
) :: Calendar.iso_days()

Returns the t:Calendar.iso_days format of the specified date.

periods_in_year(year)

Returns the number of periods in a given year. A period corresponds to a month in month-based calendars and a week in week-based calendars.

plus(year, month, day, date_part, increment, options \\ [])

Adds an increment number of date_parts to a year-month-day.

date_part can be :months only.

quarter(year, quarter)

Returns a Date.Range.t/0 representing a given quarter of a year.

quarter_of_year(year, month, day)

@spec quarter_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendrical.quarter()

Returns {:error, :not_defined} because the Hebrew calendar does not define quarters; the year has a variable number of months (12 or 13) and so does not divide evenly into four quarters.

Arguments

  • year is any positive Hebrew year as an integer.

  • month is a Hebrew month in the range 1..13.

  • day is a Hebrew day-of-month.

Returns

  • {:error, :not_defined}.

Examples

iex> Calendrical.Hebrew.quarter_of_year(5785, 1, 1)
{:error, :not_defined}

valid_date?(year, month, day)

Returns whether the given year, month, and day form a valid Hebrew date.

Month 6 (Adar I) is only valid in leap years.

Arguments

  • year is any Hebrew year as an integer.

  • month is a Hebrew month in the range 1..13.

  • day is a Hebrew day-of-month.

Returns

  • true if the date is valid; otherwise false.

Examples

iex> Calendrical.Hebrew.valid_date?(5785, 1, 30)
true

iex> Calendrical.Hebrew.valid_date?(5784, 6, 1)
true

iex> Calendrical.Hebrew.valid_date?(5785, 6, 1)
false

week(year, week)

Returns a Date.Range.t/0 representing a given week of a year.

week_of_month(year, month, day)

@spec week_of_month(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {pos_integer(), pos_integer()} | {:error, :not_defined}

Calculates the week of the year from the given year, month, and day.

By default this function always returns {:error, :not_defined}.

week_of_year(year, month, day)

@spec week_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {:error, :not_defined}

Calculates the week of the year from the given year, month, and day.

By default this function always returns {:error, :not_defined}.

weeks_in_year(year)

Returns the number of weeks in a given year.

year(year)

Returns a Date.Range.t/0 representing a given year.

year_of_era(year)

@spec year_of_era(Calendar.year()) :: {year :: Calendar.year(), era :: Calendar.era()}

Calculates the year and era from the given year.

year_of_era(year, month, day)

@spec year_of_era(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {year :: Calendar.year(), era :: Calendar.era()}

Calculates the year and era from the given date.