Calendrical.Kday (Calendrical v0.13.0)

Copy Markdown

Provide K-Day functions for Dates, DateTimes and NaiveDateTimes.

Summary

Types

kday_result()

The result of a k-day computation.

Functions

first_kday(date, k)

Returns the date of the first day_of_week on or after the specified date.

kday_after(date, k)

Returns the date of the day_of_week after the specified date.

kday_before(date, k)

Returns the date of the day_of_week before the specified date.

kday_nearest(date, k)

Returns the date of the day_of_week nearest the specified date.

kday_on_or_after(date, k)

Returns the date of the day_of_week on or after the specified date.

kday_on_or_before(date, k)

Returns the date of the day_of_week on or before the specified date.

last_kday(date, k)

Returns the date of the last day_of_week on or before the specified date.

nth_kday(date, n, k)

Returns the date of the nth day_of_week on or before/after the specified date.

Types

kday_result()

@type kday_result() ::
  Calendar.day() | Date.t() | {:error, :incompatible_calendars | :invalid_date}

The result of a k-day computation.

When a k-day function is given a date, the result is a date in the calendar of that date. When it is given an integer number of ISO days, the result is an integer number of ISO days. An error tuple is returned if the result cannot be expressed as a date.

Functions

first_kday(date, k)

@spec first_kday(Calendar.day() | Date.t(), Calendrical.day_of_week()) ::
  kday_result()

Returns the date of the first day_of_week on or after the specified date.

Arguments

Returns

Examples

# US election day
iex> Calendrical.Kday.first_kday(~D[2017-11-02], 2)
~D[2017-11-07]

# US Daylight savings end
iex> Calendrical.Kday.first_kday(~D[2017-11-01], 7)
~D[2017-11-05]

kday_after(date, k)

@spec kday_after(Calendar.day() | Date.t(), Calendrical.day_of_week()) ::
  kday_result()

Returns the date of the day_of_week after the specified date.

Arguments

Returns

Examples

iex> Calendrical.Kday.kday_after(~D[2016-02-29], 2)
~D[2016-03-01]

iex> Calendrical.Kday.kday_after(~D[2017-11-30], 1)
~D[2017-12-04]

iex> Calendrical.Kday.kday_after(~D[2017-06-30], 6)
~D[2017-07-01]

iex> Calendrical.Kday.kday_after(~D[2021-03-28], 7)
~D[2021-04-04]

kday_before(date, k)

@spec kday_before(Calendar.day() | Date.t(), Calendrical.day_of_week()) ::
  kday_result()

Returns the date of the day_of_week before the specified date.

Arguments

Returns

Examples

iex> Calendrical.Kday.kday_before(~D[2016-02-29], 2)
~D[2016-02-23]

iex> Calendrical.Kday.kday_before(~D[2017-11-30], 1)
~D[2017-11-27]

iex> Calendrical.Kday.kday_before(~D[2023-09-30], 5)
~D[2023-09-29]

iex> Calendrical.Kday.kday_before(~D[2017-06-30], 6)
~D[2017-06-24]

kday_nearest(date, k)

@spec kday_nearest(Calendar.day() | Date.t(), Calendrical.day_of_week()) ::
  kday_result()

Returns the date of the day_of_week nearest the specified date.

Arguments

Returns

Examples

iex> Calendrical.Kday.kday_nearest(~D[2016-02-29], 2)
~D[2016-03-01]

iex> Calendrical.Kday.kday_nearest(~D[2017-11-30], 1)
~D[2017-11-27]

iex> Calendrical.Kday.kday_nearest(~D[2017-06-30], 6)
~D[2017-07-01]

kday_on_or_after(date, k)

@spec kday_on_or_after(Calendar.day() | Date.t(), Calendrical.day_of_week()) ::
  kday_result()

Returns the date of the day_of_week on or after the specified date.

Arguments

Returns

Examples

iex> Calendrical.Kday.kday_on_or_after(~D[2016-02-29], 2)
~D[2016-03-01]

iex> Calendrical.Kday.kday_on_or_after(~D[2017-11-30], 1)
~D[2017-12-04]

iex> Calendrical.Kday.kday_on_or_after(~D[2017-06-30], 6)
~D[2017-07-01]

iex> Calendrical.Kday.kday_on_or_after(~D[2023-09-29], 5)
~D[2023-09-29]

kday_on_or_before(date, k)

@spec kday_on_or_before(Calendar.day() | Date.t(), Calendrical.day_of_week()) ::
  kday_result()

Returns the date of the day_of_week on or before the specified date.

Arguments

Returns

Examples

iex> Calendrical.Kday.kday_on_or_before(~D[2016-02-29], 2)
~D[2016-02-23]

iex> Calendrical.Kday.kday_on_or_before(~D[2017-11-30], 1)
~D[2017-11-27]

iex> Calendrical.Kday.kday_on_or_before(~D[2017-06-30], 6)
~D[2017-06-24]

iex> Calendrical.Kday.kday_on_or_before(~D[2023-09-29], 5)
~D[2023-09-29]

last_kday(date, k)

@spec last_kday(Calendar.day() | Date.t(), Calendrical.day_of_week()) :: kday_result()

Returns the date of the last day_of_week on or before the specified date.

Arguments

Returns

Examples

# Memorial Day in the US
iex> Calendrical.Kday.last_kday(~D[2017-05-31], 1)
~D[2017-05-29]

nth_kday(date, n, k)

@spec nth_kday(Calendar.day() | Date.t(), integer(), Calendrical.day_of_week()) ::
  kday_result()

Returns the date of the nth day_of_week on or before/after the specified date.

Arguments

  • date is Calendar.date/0, a DateTime.t/0, NaiveDateTime.t/0 or ISO days since epoch.

  • n is the cardinal number of k before (negative n) or after (positive n) the specified date.

  • k is an integer day of the week where 1 is Monday and 7 is Sunday.

Returns

Examples

# Thanksgiving in the US
iex> Calendrical.Kday.nth_kday(~D[2017-11-01], 4, 4)
~D[2017-11-23]

# Labor day in the US
iex> Calendrical.Kday.nth_kday(~D[2017-09-01], 1, 1)
~D[2017-09-04]

# Daylight savings time starts in the US
iex> Calendrical.Kday.nth_kday(~D[2017-03-01], 2, 7)
~D[2017-03-12]