lua-calendrica

• Index

Contents

• Functions
• Fields

Modules

• calendrica
• calendrica-akan
• calendrica-astro
• calendrica-astronomical-lunar
• calendrica-bahai
• calendrica-balinese
• calendrica-basic
• calendrica-chinese
• calendrica-coptic-ethiopic
• calendrica-ecclesiastical
• calendrica-egyptian-armenian
• calendrica-french-revolutionary
• calendrica-gregorian
• calendrica-hebrew
• calendrica-icelandic
• calendrica-islamic
• calendrica-iso
• calendrica-julian
• calendrica-mayan
• calendrica-modern-civil
• calendrica-modern-hindu
• calendrica-old-hindu
• calendrica-persian
• calendrica-tibetan

Topics

• manual
• calendars
• holidays

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.2 2026-09-21

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.