Calendrical.Week (Calendrical v2.2.0)

Copy Markdown

The weeks of any calendar, computed once for every calendar from its kernel.

Every calendar's weeks follow one rule, TR35's: a week is seven days and begins on the day the calendar's Calendrical.info/0 names (info().weeks.first_day, 1 for Monday to 7 for Sunday); week 1 of a year is the first week holding at least the fewest days of the year the same facts state (info().weeks.min_days_in_first_week); the days before week 1 are the last week of the year before, and the days of the old year inside week 1 are week 1 of the new. A month's weeks are numbered the same way over the month. A calendar whose weeks are counted from the year's first day whatever its weekday (first_day: :first_day_of_year) begins week 1 with the year, so its last week is short.

Every function takes the calendar as its first argument and answers for every calendar Calendrical builds. The calendar modules carry a delegation to each for Localize, which reaches a calendar through its module alone.

Summary

Types

calendar()

A calendar module.

Functions

date_from_week_date(calendar, week_year, week, day)

Returns the date of a day of a week of a week-year: the inverse of week_date_from_date/4.

day_of_week(calendar, year, month, day, starting_on)

Returns the day of the week of a date, as Calendar.day_of_week/4 answers it: the day's number from the day weeks begin on, with the first and the last day of the week.

iso_week_of_year(calendar, year, month, day)

Returns the ISO 8601 week-year and week of the day a date names, whichever calendar names it: the week of the Gregorian year, from Monday, holding at least four days of it.

week(calendar, year, week)

Returns the days of a week of a year of the calendar.

week_date_from_date(calendar, year, month, day)

Returns the week-year, the week and the day of the week of a date.

week_of_month(calendar, year, month, day)

Returns the month and the week of the month a date is in.

week_of_year(calendar, year, month, day)

Returns the week-year and the week of the year a date is in.

weeks_in_week_year(calendar, week_year)

Returns the number of weeks in a week-year, as date_from_week_date/4 counts them: as many as the year has.

weeks_in_year(calendar, year)

Returns the number of weeks in a year of the calendar.

weeks_of_month(calendar, year, month)

Returns the weeks of a month of a year of the calendar, in order.

Types

calendar()

@type calendar() :: module()

A calendar module.

Functions

date_from_week_date(calendar, week_year, week, day)

@spec date_from_week_date(
  calendar(),
  Calendar.year(),
  Calendrical.week(),
  Calendar.day_of_week()
) ::
  Date.t() | {:error, Exception.t()}

Returns the date of a day of a week of a week-year: the inverse of week_date_from_date/4.

Arguments

  • calendar is a calendar module.

  • week_year and week are a week of the calendar.

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

Returns

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

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

Examples

iex> Calendrical.Week.date_from_week_date(Calendrical.ISOWeek, 2026, 25, 2)
~D[2026-06-16 Calendrical.ISOWeek]

# Week 1 of 5786 begins on the Sunday before 1 Tishri, 28 Elul 5785
iex> Calendrical.Week.date_from_week_date(Calendrical.Hebrew, 5786, 1, 1)
~D[5785-12-28 Calendrical.Hebrew]

day_of_week(calendar, year, month, day, starting_on)

@spec day_of_week(
  calendar(),
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  :default | atom()
) :: {Calendar.day_of_week(), 1, 7} | {:error, Exception.t()}

Returns the day of the week of a date, as Calendar.day_of_week/4 answers it: the day's number from the day weeks begin on, with the first and the last day of the week.

Arguments

  • calendar is a calendar module.

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

  • starting_on is :default for the day the calendar's own weeks begin on (info().weeks.first_day, or the weekday of the year's first day where its weeks are counted from it), or the name of a weekday, :monday to :sunday.

Returns

  • {day_of_week, 1, 7}, or {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or {:error, Calendrical.MissingFieldsError.t()} for a missing field.

Raises Calendrical.InvalidOptionValueError for a starting_on that is neither :default nor a weekday, as Date.day_of_week/2 expects.

Examples

iex> Calendrical.Week.day_of_week(Calendrical.Gregorian, 2026, 1, 1, :default)
{4, 1, 7}

iex> Calendrical.Week.day_of_week(Calendrical.Gregorian, 2026, 1, 1, :sunday)
{5, 1, 7}

iso_week_of_year(calendar, year, month, day)

@spec iso_week_of_year(calendar(), Calendar.year(), Calendar.month(), Calendar.day()) ::
  {Calendar.year(), Calendrical.week()} | {:error, Exception.t()}

Returns the ISO 8601 week-year and week of the day a date names, whichever calendar names it: the week of the Gregorian year, from Monday, holding at least four days of it.

Arguments

  • calendar is a calendar module.

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

Returns

  • {week_year, week} of ISO 8601, or

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

Examples

iex> Calendrical.Week.iso_week_of_year(Calendrical.Hebrew, 5786, 7, 15)
{2026, 14}

week(calendar, year, week)

@spec week(calendar(), Calendar.year(), Calendrical.week()) ::
  Date.Range.t() | {:error, Exception.t()}

Returns the days of a week of a year of the calendar.

Arguments

  • calendar is a calendar module.

  • year is a year of the calendar.

  • week is a week of that year.

Returns

  • A Date.Range.t/0 of the week's seven days, which may begin in the year before or end in the year after, or

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

Examples

iex> Calendrical.Week.week(Calendrical.ISOWeek, 2026, 25)
Date.range(~D[2026-06-15 Calendrical.ISOWeek], ~D[2026-06-21 Calendrical.ISOWeek])

iex> Calendrical.Week.week(Calendrical.Gregorian, 2025, 1)
Date.range(~D[2024-12-30 Calendrical.Gregorian], ~D[2025-01-05 Calendrical.Gregorian])

week_date_from_date(calendar, year, month, day)

@spec week_date_from_date(
  calendar(),
  Calendar.year(),
  Calendar.month(),
  Calendar.day()
) ::
  {Calendar.year(), Calendrical.week(), Calendar.day_of_week()}
  | {:error, Exception.t()}

Returns the week-year, the week and the day of the week of a date.

Arguments

  • calendar is a calendar module.

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

Returns

  • {week_year, week, day_of_week}, the day numbered from the day the calendar's weeks begin on, or

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

Examples

iex> Calendrical.Week.week_date_from_date(Calendrical.ISOWeek, 2026, 6, 16)
{2026, 25, 2}

week_of_month(calendar, year, month, day)

@spec week_of_month(calendar(), Calendar.year(), Calendar.month(), Calendar.day()) ::
  {Calendar.month(), Calendrical.week()} | {:error, Exception.t()}

Returns the month and the week of the month a date is in.

Arguments

  • calendar is a calendar module.

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

Returns

  • {month, week}, where the month is the one before or after where the date falls in that month's last or first week, or

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

Examples

iex> Calendrical.Week.week_of_month(Calendrical.Gregorian, 2026, 1, 15)
{1, 3}

# The week holding 1 February is February's week 1
iex> Calendrical.Week.week_of_month(Calendrical.Gregorian, 2026, 1, 31)
{2, 1}

week_of_year(calendar, year, month, day)

@spec week_of_year(calendar(), Calendar.year(), Calendar.month(), Calendar.day()) ::
  {Calendar.year(), Calendrical.week()} | {:error, Exception.t()}

Returns the week-year and the week of the year a date is in.

Arguments

  • calendar is a calendar module.

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

Returns

  • {week_year, week}, where the week-year is the year before or after where the date falls in that year's last or first week, or

  • {:error, exception} for a date the calendar does not have: a Calendrical.MissingFieldsError for a date missing a field, and a Calendrical.InvalidDateError otherwise.

Examples

iex> Calendrical.Week.week_of_year(Calendrical.Gregorian, 2025, 12, 31)
{2026, 1}

iex> Calendrical.Week.week_of_year(Calendrical.Hebrew, 5786, 7, 15)
{5786, 28}

# 29 Elul 5786 is in week 1 of 5787, which begins on the Sunday before 1 Tishri
iex> Calendrical.Week.week_of_year(Calendrical.Hebrew, 5786, 12, 29)
{5787, 1}

weeks_in_week_year(calendar, week_year)

@spec weeks_in_week_year(calendar(), Calendar.year()) ::
  pos_integer() | {:error, Exception.t()}

Returns the number of weeks in a week-year, as date_from_week_date/4 counts them: as many as the year has.

Arguments

  • calendar is a calendar module.

  • week_year is a week-year of the calendar.

Returns

  • The number of weeks, or

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

Examples

iex> Calendrical.Week.weeks_in_week_year(Calendrical.ISOWeek, 2026)
53

weeks_in_year(calendar, year)

@spec weeks_in_year(calendar(), Calendar.year()) ::
  pos_integer() | {:error, Exception.t()}

Returns the number of weeks in a year of the calendar.

Arguments

  • calendar is a calendar module.

  • year is a year of the calendar.

Returns

  • The number of weeks, or

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

Examples

iex> Calendrical.Week.weeks_in_year(Calendrical.Gregorian, 2026)
52

iex> Calendrical.Week.weeks_in_year(Calendrical.ISO, 2026)
53

iex> Calendrical.Week.weeks_in_year(Calendrical.Hebrew, 5787)
55

weeks_of_month(calendar, year, month)

@spec weeks_of_month(calendar(), Calendar.year(), Calendar.month()) ::
  [Date.Range.t()] | {:error, Exception.t()}

Returns the weeks of a month of a year of the calendar, in order.

Arguments

  • calendar is a calendar module.

  • year and month are a month of the calendar.

Returns

  • A list of Date.Range.t/0, one for each week week_of_month/4 names for the month, the first of which may begin in the month before and the last run into the month after, or

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

Examples

iex> Calendrical.Week.weeks_of_month(Calendrical.Gregorian, 2026, 2) |> length()
4

iex> Calendrical.Week.weeks_of_month(Calendrical.Gregorian, 2026, 2) |> hd()
Date.range(~D[2026-01-26 Calendrical.Gregorian], ~D[2026-02-01 Calendrical.Gregorian])