Calendrical

v0.1.2

Calendrical v0.1.2 Calendrical.Kday View Source

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

Link to this section Summary

Types

date_or_time()
day_names()
day_of_the_week()

Functions

day_cardinal(day_number)

Returns the integer representation of a day of the week

day_name(int)
first_kday(date, k)

Return the date of the first day_of_the_week on or after the specified date

kday_after(date, k)

Return the date of the day_of_the_week after the specified date

kday_before(date, k)

Return the date of the day_of_the_week before the specified date

kday_nearest(date, k)

Return the date of the day_of_the_week nearest the specified date

kday_on_or_after(date, k)

Return the date of the day_of_the_week on or after the specified date

kday_on_or_before(date, k)

Return the date of the day_of_the_week on or before the specified date

last_kday(date, k)

Return the date of the last day_of_the_week on or before the specified date

nth_kday(date, n, k)

Return the date of the nth day_of_the_week on or before/after the specified date

weeks(n)

Returns the number of days in n weeks

Link to this section Types

Link to this type date_or_time() View Source 
date_or_time() :: Date.t | NaiveDateTime.t | RataDie.t
Link to this type day_names() View Source 
day_names ::
  :monday |
  :tuesday |
  :wednesday |
  :thursday |
  :friday |
  :saturday |
  :sunday
Link to this type day_of_the_week() View Source 
day_of_the_week() :: 1..7

Link to this section Functions

Link to this function day_cardinal(day_number) View Source 
day_cardinal(day_of_the_week | day_names) :: day_of_the_week

Returns the integer representation of a day of the week.

Both an atom representing the name of a day or a number between 1 and 7 is acceptable with 1 meaning :monday and 7 meaning :sunday.

Exmaples 

iex(1)> Calendrical.Kday.day_cardinal :monday
1

iex(2)> Calendrical.Kday.day_cardinal :friday
5

iex(3)> Calendrical.Kday.day_cardinal 5
5
Link to this function first_kday(date, k) View Source 
first_kday(date_or_time, day_of_the_week) :: date_or_time

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

  • date is %Date{}, a %DateTime{}, %NaiveDateTime{} or a Rata Die

  • k is an integer or atom representation of the day of the week. See Calendrical.Kday.day_cardinal/1

Examples 

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

# US Daylight savings end
iex> Calendrical.Kday.first_kday(~D[2017-11-01], :sunday)
~D[2017-11-05]
Link to this function kday_after(date, k) View Source 
kday_after(date_or_time, day_of_the_week) :: date_or_time

Return the date of the day_of_the_week after the specified date.

  • date is %Date{}, a %DateTime{}, %NaiveDateTime{} or a Rata Die

  • k is an integer or atom representation of the day of the week. See Calendrical.Kday.day_cardinal/1

Examples 

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

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

# 6 means Saturday.  Use either the integer value or the atom form.
iex> Calendrical.Kday.kday_after(~D[2017-06-30], 6)
~D[2017-07-01]
Link to this function kday_before(date, k) View Source 
kday_before(date_or_time, day_of_the_week) :: date_or_time

Return the date of the day_of_the_week before the specified date.

  • date is %Date{}, a %DateTime{}, %NaiveDateTime{} or a Rata Die

  • k is an integer or atom representation of the day of the week. See Calendrical.Kday.day_cardinal/1

Examples 

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

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

# 6 means Saturday.  Use either the integer value or the atom form.
iex> Calendrical.Kday.kday_before(~D[2017-06-30], 6)
~D[2017-06-24]
Link to this function kday_nearest(date, k) View Source 
kday_nearest(date_or_time, day_of_the_week) :: date_or_time

Return the date of the day_of_the_week nearest the specified date.

  • date is %Date{}, a %DateTime{}, %NaiveDateTime{} or a Rata Die

  • k is an integer or atom representation of the day of the week. See Calendrical.Kday.day_cardinal/1

Examples 

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

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

# 6 means Saturday.  Use either the integer value or the atom form.
iex> Calendrical.Kday.kday_nearest(~D[2017-06-30], 6)
~D[2017-07-01]
Link to this function kday_on_or_after(date, k) View Source 
kday_on_or_after(date_or_time, day_of_the_week) :: date_or_time

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

  • date is %Date{}, a %DateTime{}, %NaiveDateTime{} or a Rata Die

  • k is an integer or atom representation of the day of the week. See Calendrical.Kday.day_cardinal/1

Examples 

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

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

# 6 means Saturday.  Use either the integer value or the atom form.
iex> Calendrical.Kday.kday_on_or_after(~D[2017-06-30], 6)
~D[2017-07-01]
Link to this function kday_on_or_before(date, k) View Source 
kday_on_or_before(date_or_time, day_of_the_week) :: date_or_time

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

  • date is %Date{}, a %DateTime{}, %NaiveDateTime{} or a Rata Die

  • k is an integer or atom representation of the day of the week. See Calendrical.Kday.day_cardinal/1

Examples 

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

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

# 6 means Saturday.  Use either the integer value or the atom form.
iex> Calendrical.Kday.kday_on_or_before(~D[2017-06-30], 6)
~D[2017-06-24]
Link to this function last_kday(date, k) View Source 
last_kday(date_or_time, day_of_the_week) :: date_or_time

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

  • date is %Date{}, a %DateTime{}, %NaiveDateTime{} or a Rata Die

  • k is an integer or atom representation of the day of the week. See Calendrical.Kday.day_cardinal/1

Example 

# Memorial Day in the US
Calendrical.Kday.last_kday(~[2017-05-31], :monday)
~D[2017-05-29]
Link to this function nth_kday(date, n, k) View Source 
nth_kday(date_or_time, integer, day_of_the_week) :: date_or_time

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

  • date is %Date{}, a %DateTime{}, %NaiveDateTime{} or a Rata Die

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

  • k is an integer or atom representation of the day of the week. See Calendrical.Kday.day_cardinal/1

Examples 

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

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

# Daylight savings time starts in the US
iex> Calendrical.Kday.nth_kday(~D[2017-03-01], 2, :sunday)
~D[2017-03-12]
Link to this function weeks(n) View Source 
weeks(integer) :: integer

Returns the number of days in n weeks

Example 

iex> Calendrical.Kday.weeks(2)
14