View Source Cldr.Calendar.Kday (Cldr Calendars v1.26.2)

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

Summary

Functions

first_kday(date, k)

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

kday_after(date, k)

Return the date of the day_of_week after the specified date.

kday_before(date, k)

Return the date of the day_of_week before the specified date.

kday_nearest(date, k)

Return the date of the day_of_week nearest the specified date.

kday_on_or_after(date, k)

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

kday_on_or_before(date, k)

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

last_kday(date, k)

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

nth_kday(date, n, k)

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

Functions

Link to this function

first_kday(date, k)

View Source 
@spec first_kday(Calendar.day() | Date.t(), Cldr.Calendar.day_of_week()) ::
  Calendar.day() | Date.t() | {:error, :incompatible_calendars | :invalid_date}

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

Arguments

Returns

  • A Date.t/0 in the calendar of the date provided as an argument.

Examples 

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

# US Daylight savings end
iex> Cldr.Calendar.Kday.first_kday(~D[2017-11-01], 7)
~D[2017-11-05]
Link to this function

kday_after(date, k)

View Source 
@spec kday_after(Calendar.day() | Date.t(), Cldr.Calendar.day_of_week()) ::
  Calendar.day() | Date.t() | {:error, :incompatible_calendars | :invalid_date}

Return the date of the day_of_week after the specified date.

Arguments

Returns

  • A Date.t/0 in the calendar of the date provided as an argument.

Examples 

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

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

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

iex> Cldr.Calendar.Kday.kday_after(~D[2021-03-28], 7)
~D[2021-04-04]
Link to this function

kday_before(date, k)

View Source 
@spec kday_before(Calendar.day() | Date.t(), Cldr.Calendar.day_of_week()) ::
  Calendar.day() | Date.t() | {:error, :incompatible_calendars | :invalid_date}

Return the date of the day_of_week before the specified date.

Arguments

Returns

  • A Date.t/0 in the calendar of the date provided as an argument.

Examples 

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

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

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

# 6 means Saturday.  Use either the integer value or the atom form.
iex> Cldr.Calendar.Kday.kday_before(~D[2017-06-30], 6)
~D[2017-06-24]
Link to this function

kday_nearest(date, k)

View Source 
@spec kday_nearest(Calendar.day() | Date.t(), Cldr.Calendar.day_of_week()) ::
  Calendar.day() | Date.t() | {:error, :incompatible_calendars | :invalid_date}

Return the date of the day_of_week nearest the specified date.

Arguments

Returns

  • A Date.t/0 in the calendar of the date provided as an argument.

Examples 

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

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

iex> Cldr.Calendar.Kday.kday_nearest(~D[2017-06-30], 6)
~D[2017-07-01]
Link to this function

kday_on_or_after(date, k)

View Source 
@spec kday_on_or_after(Calendar.day() | Date.t(), Cldr.Calendar.day_of_week()) ::
  Calendar.day() | Date.t() | {:error, :incompatible_calendars | :invalid_date}

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

Arguments

Returns

  • A Date.t/0 in the calendar of the date provided as an argument

Examples 

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

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

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

iex> Cldr.Calendar.Kday.kday_on_or_after(~D[2023-09-29], 5)
~D[2023-09-29]
Link to this function

kday_on_or_before(date, k)

View Source 
@spec kday_on_or_before(Calendar.day() | Date.t(), Cldr.Calendar.day_of_week()) ::
  Calendar.day() | Date.t() | {:error, :incompatible_calendars | :invalid_date}

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

Arguments

Returns

  • A Date.t/0 in the calendar of the date provided as an argument.

Examples 

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

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

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

iex> Cldr.Calendar.Kday.kday_on_or_before(~D[2023-09-29], 5)
~D[2023-09-29]
Link to this function

last_kday(date, k)

View Source 
@spec last_kday(Calendar.day() | Date.t(), Cldr.Calendar.day_of_week()) ::
  Calendar.day() | Date.t() | {:error, :incompatible_calendars | :invalid_date}

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

Arguments

Returns

  • A Date.t/0 in the calendar of the date provided as an argument

Example 

# Memorial Day in the US
iex> Cldr.Calendar.Kday.last_kday(~D[2017-05-31], 1)
~D[2017-05-29]
Link to this function

nth_kday(date, n, k)

View Source 
@spec nth_kday(Calendar.day() | Date.t(), integer(), Cldr.Calendar.day_of_week()) ::
  Calendar.day() | Date.t() | {:error, :incompatible_calendars | :invalid_date}

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

Arguments

  • date is Date.t/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

  • A Date.t/0 in the calendar of the date provided as an argument.

Examples 

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

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

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