lua-calendrica

# Module `calendrica-gregorian`

Gregorian calendar conversions and holidays.

Ported from "Calendrical Calculations" (4th edition) by Nachum Dershowitz and Edward M. Reingold. Original Lisp code (CALENDRICA 4.0) is Apache 2.0 licensed.

### Info:

- Release: 0.1 2026-07-19

## Functions

gregorian_date (year, month, day) | Construct a Gregorian date from year, month, and day.
gregorian_leap_year (g_year) | True if `g_year` is a leap year on the Gregorian calendar.
fixed_from_gregorian (g_date) | Fixed date equivalent to the Gregorian date `g_date`.
gregorian_year_from_fixed (date) | Gregorian year corresponding to the fixed `date`.
gregorian_from_fixed (date) | Gregorian date {year, month, day} corresponding to fixed `date`.
gregorian_new_year (g_year) | Fixed date of January 1 in `g_year`.
gregorian_year_end (g_year) | Fixed date of December 31 in `g_year`.
gregorian_year_range (g_year) | Half-open interval of fixed dates spanning Gregorian year `g_year`.
gregorian_date_difference (g_date1, g_date2) | Number of days from Gregorian date `g_date1` until `g_date2`.
kday_on_or_before (k, date) | Fixed date of the `k`-day on or before fixed `date`.
kday_on_or_after (k, date) | Fixed date of the `k`-day on or after fixed `date`.
kday_nearest (k, date) | Fixed date of the `k`-day nearest to fixed `date`.
kday_after (k, date) | Fixed date of the `k`-day strictly after fixed `date`.
kday_before (k, date) | Fixed date of the `k`-day strictly before fixed `date`.
nth_kday (n, k, g_date) | Return the `n`-th `k`-day relative to Gregorian date `g_date`.
first_kday (k, g_date) | Fixed date of the first `k`-day on or after Gregorian date `g_date`.
last_kday (k, g_date) | Fixed date of the last `k`-day on or before Gregorian date `g_date`.
independence_day (g_year) | Fixed date of United States Independence Day in Gregorian year `g_year`.
labor_day (g_year) | Fixed date of United States Labor Day in `g_year` (first Monday in September).
memorial_day (g_year) | Fixed date of United States Memorial Day in `g_year` (last Monday in May).
election_day (g_year) | Fixed date of United States Election Day in `g_year` (Tuesday after the first Monday in November).
daylight_saving_start (g_year) | Fixed date of start of US daylight saving time in `g_year` (second Sunday in March).
daylight_saving_end (g_year) | Fixed date of end of US daylight saving time in `g_year` (first Sunday in November).
christmas (g_year) | Fixed date of Christmas in Gregorian year `g_year`.
advent (g_year) | Fixed date of Advent in Gregorian year `g_year` (Sunday closest to November 30).
epiphany (g_year) | Fixed date of Epiphany in the US in Gregorian year `g_year` (first Sunday after January 1).
unlucky_fridays (g_year) | List of Friday-the-13ths in Gregorian year `g_year`.
day_number (g_date) | Day number (1..366) of Gregorian date `g_date` within its year.
days_remaining (g_date) | Days remaining in the year after Gregorian date `g_date`.
last_day_of_gregorian_month (g_year, g_month) | Last day of month `g_month` in Gregorian year `g_year`.

## Fields

JANUARY | January month number.
FEBRUARY | February month number.
MARCH | March month number.
APRIL | April month number.
MAY | May month number.
JUNE | June month number.
JULY | July month number.
AUGUST | August month number.
SEPTEMBER | September month number.
OCTOBER | October month number.
NOVEMBER | November month number.
DECEMBER | December month number.

## Functions

gregorian_date (year, month, day)
  Construct a Gregorian date from year, month, and day.

  ### Parameters:

  - year number Gregorian year.
  - month number Month (1–12).
  - day number Day of month.

  ### Returns:

  table {year, month, day}
gregorian_leap_year (g_year)
  True if `g_year` is a leap year on the Gregorian calendar.

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  boolean
fixed_from_gregorian (g_date)
  Fixed date equivalent to the Gregorian date `g_date`.

  ### Parameters:

  - g_date table Gregorian date {year, month, day}.

  ### Returns:

  number Fixed date.
gregorian_year_from_fixed (date)
  Gregorian year corresponding to the fixed `date`.

  ### Parameters:

  - date number Fixed date.

  ### Returns:

  number Gregorian year.
gregorian_from_fixed (date)
  Gregorian date {year, month, day} corresponding to fixed `date`.

  ### Parameters:

  - date number Fixed date.

  ### Returns:

  table {year, month, day}
gregorian_new_year (g_year)
  Fixed date of January 1 in `g_year`.

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
gregorian_year_end (g_year)
  Fixed date of December 31 in `g_year`.

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
gregorian_year_range (g_year)
  Half-open interval of fixed dates spanning Gregorian year `g_year`.

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  table Interval {jan1_of_year, jan1_of_next_year}.
gregorian_date_difference (g_date1, g_date2)
  Number of days from Gregorian date `g_date1` until `g_date2`.

  ### Parameters:

  - g_date1 table Start date {year, month, day}.
  - g_date2 table End date {year, month, day}.

  ### Returns:

  number Number of days.
kday_on_or_before (k, date)
  Fixed date of the `k`-day on or before fixed `date`.

  ### Parameters:

  - k number Day of week (0=Sunday..6=Saturday).
  - date number Fixed date.

  ### Returns:

  number Fixed date.
kday_on_or_after (k, date)
  Fixed date of the `k`-day on or after fixed `date`.

  ### Parameters:

  - k number Day of week.
  - date number Fixed date.

  ### Returns:

  number Fixed date.
kday_nearest (k, date)
  Fixed date of the `k`-day nearest to fixed `date`.

  ### Parameters:

  - k number Day of week.
  - date number Fixed date.

  ### Returns:

  number Fixed date.
kday_after (k, date)
  Fixed date of the `k`-day strictly after fixed `date`.

  ### Parameters:

  - k number Day of week.
  - date number Fixed date.

  ### Returns:

  number Fixed date.
kday_before (k, date)
  Fixed date of the `k`-day strictly before fixed `date`.

  ### Parameters:

  - k number Day of week.
  - date number Fixed date.

  ### Returns:

  number Fixed date.
nth_kday (n, k, g_date)
  Return the `n`-th `k`-day relative to Gregorian date `g_date`. If `n` > 0, the `n`-th k-day on or after `g_date`. If `n` < 0, the `n`-th k-day on or before `g_date`. If `n` = 0, returns bogus.

  ### Parameters:

  - n number Occurrence count (positive = after, negative = before).
  - k number Day of week.
  - g_date table Gregorian date.

  ### Returns:

  number Fixed date, or "bogus" when n = 0.
first_kday (k, g_date)
  Fixed date of the first `k`-day on or after Gregorian date `g_date`.

  ### Parameters:

  - k number Day of week.
  - g_date table Gregorian date.

  ### Returns:

  number Fixed date.
last_kday (k, g_date)
  Fixed date of the last `k`-day on or before Gregorian date `g_date`.

  ### Parameters:

  - k number Day of week.
  - g_date table Gregorian date.

  ### Returns:

  number Fixed date.
independence_day (g_year)
  Fixed date of United States Independence Day in Gregorian year `g_year`.

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
labor_day (g_year)
  Fixed date of United States Labor Day in `g_year` (first Monday in September).

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
memorial_day (g_year)
  Fixed date of United States Memorial Day in `g_year` (last Monday in May).

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
election_day (g_year)
  Fixed date of United States Election Day in `g_year` (Tuesday after the first Monday in November).

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
daylight_saving_start (g_year)
  Fixed date of start of US daylight saving time in `g_year` (second Sunday in March).

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
daylight_saving_end (g_year)
  Fixed date of end of US daylight saving time in `g_year` (first Sunday in November).

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
christmas (g_year)
  Fixed date of Christmas in Gregorian year `g_year`.

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
advent (g_year)
  Fixed date of Advent in Gregorian year `g_year` (Sunday closest to November 30).

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
epiphany (g_year)
  Fixed date of Epiphany in the US in Gregorian year `g_year` (first Sunday after January 1).

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  number Fixed date.
unlucky_fridays (g_year)
  List of Friday-the-13ths in Gregorian year `g_year`.

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  {number,...} Fixed dates of all Friday the 13ths in the year.
day_number (g_date)
  Day number (1..366) of Gregorian date `g_date` within its year.

  ### Parameters:

  - g_date table Gregorian date {year, month, day}.

  ### Returns:

  number Day number.
days_remaining (g_date)
  Days remaining in the year after Gregorian date `g_date`.

  ### Parameters:

  - g_date table Gregorian date {year, month, day}.

  ### Returns:

  number Days remaining.
last_day_of_gregorian_month (g_year, g_month)
  Last day of month `g_month` in Gregorian year `g_year`.

  ### Parameters:

  - g_year number Gregorian year.
  - g_month number Gregorian month.

  ### Returns:

  number Last day (28, 29, 30, or 31).

## Fields

JANUARY
  January month number.
FEBRUARY
  February month number.
MARCH
  March month number.
APRIL
  April month number.
MAY
  May month number.
JUNE
  June month number.
JULY
  July month number.
AUGUST
  August month number.
SEPTEMBER
  September month number.
OCTOBER
  October month number.
NOVEMBER
  November month number.
DECEMBER
  December month number.

generated by LDoc 1.5.0 Last updated 2026-07-19 03:28:25