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.Hebrew)
iex> {year, month, day, 12, 30, 0, {0, 0}} =
...>   Calendrical.Hebrew.add(date.year, date.month, date.day, 12, 30, 0, {0, 0}, :month, 1)
iex> {year, month, day} == Calendrical.Hebrew.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.Hebrew.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.Hebrew.calendar_from_cldr_calendar_type(:gregorian)
{:ok, Calendrical.Gregorian}

iex> {:error, %Localize.UnknownCalendarError{}} =
...>   Calendrical.Hebrew.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.Hebrew)
iex> {_year, _month, written_day} = Calendrical.Hebrew.written_date(date.year, date.month, date.day)
iex> Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.cardinal_month(1) == Calendrical.Hebrew.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.Hebrew)
iex> {written_year, _month, _day} = Calendrical.Hebrew.written_date(date.year, date.month, date.day)
iex> Calendrical.Hebrew.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.Hebrew.cldr_calendar_type() == Calendrical.Hebrew.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.Hebrew)
iex> in_effect = Calendrical.Info.in_effect(Calendrical.Hebrew, date.year, date.month, date.day)
iex> Calendrical.Hebrew.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.Hebrew)
iex> cldr_month = Calendrical.Hebrew.cldr_month(date.year, date.month)
iex> Calendrical.Hebrew.written_month_from_cldr_month(date.year, cldr_month) ==
...>   Calendrical.Hebrew.numeric_month(date.year, date.month, date.day)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Hebrew.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.Hebrew)
iex> cyclic_year = Calendrical.Hebrew.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.Hebrew.cyclic_year(nil, 1, 1)

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

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

The Jewish day begins at sunset — more precisely the date fully changes at nightfall (tzeit hakochavim) — so in the evening the Hebrew date is already the following day. This maps an absolute instant to the Hebrew date, choosing the boundary with the :day_start option. Unlike the Islamic calendars, whose boundary is a fixed canonical city, the Hebrew boundary is the observer's local sunset, so a :location is taken (defaulting to Jerusalem).

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 taken at :location.

Options

• :location is a Geo.PointZ.t/0 (or Geo.Point.t/0) giving the observer's location. The default is Jerusalem.

• :day_start selects the moment the Hebrew day begins:

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

  • :sunset — true sunset (shkiah, upper-limb) at :location.

  • :nightfall — nightfall (tzeit hakochavim), when the sun reaches a chosen depression below the horizon. See :nightfall_angle.

• :nightfall_angle is the sun's depression below the horizon, in degrees, that defines nightfall for day_start: :nightfall. The default is 8.5 (the common "three small stars" tzeit).

Returns

• {:ok, date} — a Hebrew Date.t/0.

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

• {: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

# Morning in Jerusalem: still the civil-day date.
iex> {:ok, date} = Calendrical.Hebrew.date_at(~U[2025-03-01 06:00:00Z])
iex> date.calendar
Calendrical.Hebrew

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.Hebrew)
iex> {year, month, day} = Calendrical.Hebrew.written_date(date.year, date.month, date.day)
iex> Calendrical.Hebrew.date_from_cardinal_date(year, month, day) == {date.year, date.month, date.day}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew)
iex> day_of_year = Calendrical.Hebrew.day_of_year(date.year, date.month, date.day)
iex> Calendrical.Hebrew.date_from_day_of_year(date.year, day_of_year) == date
true

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

@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}

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.Hebrew)
iex> {week_year, week, day} = Calendrical.Hebrew.week_date_from_date(date.year, date.month, date.day)
iex> Calendrical.Hebrew.date_from_week_date(week_year, week, day) == date
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew)
iex> {year, month, day} = Calendrical.Hebrew.written_date(date.year, date.month, date.day)
iex> Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.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 Hebrew year, month, and day.

Arguments

• year is any Hebrew year as an integer.

• month is the month's position in the year.

• 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

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.Hebrew)
iex> date in Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.day_numbers(date.year, date.month) ==
...>   [1..Calendrical.Hebrew.days_in_month(date.year, date.month)//1]
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> Calendrical.Hebrew.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.Hebrew)
iex> {day_of_era, era} = Calendrical.Hebrew.day_of_era(date.year, date.month, date.day)
iex> {_year_of_era, year_era} = Calendrical.Hebrew.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.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.day_of_week(date.year, date.month, date.day, :monday)
{6, 1, 7}

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew)
iex> first_day = Calendrical.Hebrew.year(date.year).first
iex> Calendrical.Hebrew.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.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew)
iex> {fewest, most} = Calendrical.Hebrew.days_in_month_bounds(date.month)
iex> case Calendrical.Hebrew.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.Hebrew.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 Hebrew year and month.

Arguments

• year is any Hebrew year as an integer.

• month is the month's position in the year, 1..months_in_year(year).

Returns

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

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

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

Examples

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

# Adar I, the 6th month of the leap year 5784
iex> Calendrical.Hebrew.days_in_month(5784, 6)
30

# Adar, the 6th month of the ordinary year 5785
iex> Calendrical.Hebrew.days_in_month(5785, 6)
29

# An ordinary year has no 13th month
iex> Calendrical.Hebrew.days_in_month(5785, 13)
{:error, %Calendrical.InvalidMonthError{calendar: Calendrical.Hebrew, year: 5785, month: 13}}

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.Hebrew)
iex> {fewest, most} = Calendrical.Hebrew.days_in_month_bounds(date.month)
iex> Calendrical.Hebrew.days_in_month(date.year, date.month) in fewest..most
true

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

Returns the number of days in a week.

Returns

• 7.

Examples

iex> Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.days_in_year(date.year) == Enum.count(Calendrical.Hebrew.year(date.year))
true

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

@spec diff({year(), month(), day()}, {year(), month(), day()}, atom()) ::
  integer() | {:error, Exception.t()}

Returns the whole number of date_parts from one {year, month, day} to another, as shift/6 adds them.

date_part can be :years, :quarters, :months, :weeks or :days. The count is the largest number shift/6, clamping the day into a shorter month, can add to the earlier date without passing the later one; it is negative when to is before from. Months count a leap year's Adar I, and come from the months elapsed before each year (235 in every 19), so a span of any length costs the same.

Arguments

• from is the starting {year, month, day}.

• to is the ending {year, month, day}.

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

Returns

• The whole number of date_parts from from to to, as an integer, 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

# 5784 is a leap year of thirteen months, 5785 an ordinary one
iex> Calendrical.Hebrew.diff({5784, 1, 1}, {5785, 1, 1}, :months)
13

iex> Calendrical.Hebrew.diff({5784, 1, 1}, {5786, 1, 1}, :months)
25

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.Hebrew.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.Hebrew.era_calendar_type() == Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.extended_year(date.year, date.month, date.day) == date.year
true

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

@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 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

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

Returns

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

Examples

iex> Calendrical.Hebrew.info().calendar
Calendrical.Hebrew

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.Hebrew)
iex> Calendrical.Hebrew.iso_week_of_year(date.year, date.month, date.day)
{2024, 22}

@spec leap_month(Calendar.year()) :: 6 | nil

Returns the position of the leap month, Adar I, in a Hebrew year.

Arguments

• year is a Hebrew year as an integer.

Returns

• 6, the position of Adar I, in a leap year.

• nil in an ordinary year, or for anything but an integer year.

Examples

iex> Calendrical.Hebrew.leap_month(5784)
6

iex> Calendrical.Hebrew.leap_month(5785)
nil

@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 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

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.Hebrew)
iex> Calendrical.Hebrew.lunar_month_of_year(date.year, date.month) ==
...>   Calendrical.Hebrew.traditional_month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Hebrew.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.Hebrew)
iex> date in Calendrical.Hebrew.month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew)
iex> traditional_month = Calendrical.Hebrew.traditional_month(date.year, date.month)
iex> Calendrical.Hebrew.month_from_traditional(date.year, traditional_month) == date.month
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.month_numbers(date.year) == [1..Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.month_of_year(date.year, date.month, date.day) == Calendrical.Hebrew.cldr_month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew.months_in_leap_year() >= Calendrical.Hebrew.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.Hebrew.months_in_ordinary_year() <= Calendrical.Hebrew.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.Hebrew.months_in_year() do
...>   months when is_integer(months) -> months == Calendrical.Hebrew.months_in_leap_year()
...>   {:ambiguous, fewest..most//1} -> {fewest, most} == Calendrical.Hebrew.info().months_in_year
...>   {:error, %Calendrical.NotDefinedError{}} -> is_list(Calendrical.Hebrew.info().members)
...> end
true

@spec months_in_year(year()) :: 12..13 | {:error, Exception.t()}

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

Arguments

• year is any Hebrew year as an integer.

Returns

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

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

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

Examples

iex> Calendrical.Hebrew.months_in_year(5785)
12

iex> Calendrical.Hebrew.months_in_year(5784)
13

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.Hebrew.months_in_year_bounds()
iex> fewest <= Calendrical.Hebrew.months_in_ordinary_year() and
...>   most >= Calendrical.Hebrew.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.Hebrew)
iex> {year, month, day, 12, 0, 0, {0, 6}} =
...>   Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.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.Hebrew)
iex> cldr_month = Calendrical.Hebrew.cldr_month(date.year, date.month)
iex> Calendrical.Hebrew.named_month(date.year, cldr_month) |> Enum.any?(&(date in &1))
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> Calendrical.Hebrew.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.Hebrew)
iex> {_year, written_month, _day} = Calendrical.Hebrew.written_date(date.year, date.month, date.day)
iex> Calendrical.Hebrew.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.Hebrew)
iex> traditional_month = Calendrical.Hebrew.traditional_month(date.year, date.month)
iex> Calendrical.Hebrew.ordinal_month_from_traditional(date.year, traditional_month) == {:ok, date.month}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.parse_date(Date.to_string(date)) == {:ok, {date.year, date.month, date.day}}
true

iex> Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.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.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.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.Hebrew.parsing_calendar() == Calendrical.Hebrew.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.Hebrew)
iex> in_effect = Calendrical.Info.in_effect(Calendrical.Hebrew, date.year, date.month, date.day)
iex> in_effect in Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.periods_in_year(date.year) == Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.quadrimester(date.year, 1).first == Calendrical.Hebrew.year(date.year).first
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew)
iex> quarter = Calendrical.Hebrew.quarter_of_year(date.year, date.month, date.day)
iex> date in Calendrical.Hebrew.quarter(date.year, quarter)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.quarter_of_year(date.year, date.month, date.day) in 1..4
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew)
iex> {:ok, first_day} = Date.convert(Calendrical.Hebrew.year(date.year).first, Calendrical.Gregorian)
iex> Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.semester(date.year, 1).first == Calendrical.Hebrew.year(date.year).first
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Hebrew)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Hebrew.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.Hebrew)
iex> Calendrical.Hebrew.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.Hebrew)
iex> {year, month, day} = Calendrical.Hebrew.shift_date(date.year, date.month, date.day, Duration.new!(day: 7))
iex> Date.new!(year, month, day, Calendrical.Hebrew) == 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.Hebrew)
iex> next_day = Date.add(date, 1)
iex> Calendrical.Hebrew.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