Module calendrica-basic

Basic arithmetic and calendar utilities.

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

quotient (m, n) Whole part of m/n.
amod (x, y) The value of (x mod y) with y instead of 0.
mod3 (x, a, b) The value of x shifted into the range [a..b).
sum (expression, initial, condition) Sum expression(index) for index = initial and successive integers, as long as condition(index) holds.
next (initial, condition) First integer greater or equal to initial such that condition holds.
final (initial, condition) Last integer greater or equal to initial such that condition holds.
sigma (lists, body) Sum of body(i1,…,in) for indices running simultaneously through parallel lists.
invert_angular (f, y, r) Use bisection to find the inverse of angular function f at y within interval r.
binary_search (lo, hi, test, end_condition) Bisection search for x in [lo..hi] such that end_condition holds.
poly (x, a) Evaluate polynomial in x with coefficients a (from order 0 up).
sign (y) Sign of y: returns -1, 0, or 1.
round_half_to_even (x) Round x to the nearest integer using banker’s rounding (half-to-even).
rd (tee) Identity function for fixed dates/moments (Rata Die).
day_of_week_from_fixed (date) Day of the week of fixed date (0 = Sunday ..
standard_month (date) Month field of date = {year, month, day}.
standard_day (date) Day field of date = {year, month, day}.
standard_year (date) Year field of date = {year, month, day}.
fixed_from_moment (tee) Fixed date (floor) from moment tee.
time_from_moment (tee) Fractional time-of-day from moment tee.
to_radix (x, b[, c]) Convert x to mixed-radix notation with bases b (whole) and c (fraction).
interval (t0, t1) Half-open interval [t0..t1).
interval_closed (t0, t1) Closed interval [t0..t1].
begin (range) Start of interval range.
end_ (range) End of interval range.
in_range (tee, range) True if tee is in half-open range [t0..t1).
list_range (ell, range) Those moments in list ell that occur in range.
positions_in_range (p, c, cap_delta, range) List of occurrences of moment p of c-day cycle within range.
moment_from_jd (jd) Moment from Julian Day Number jd.
jd_from_moment (tee) Julian Day Number from moment tee.
fixed_from_jd (jd) Fixed date from Julian Day Number jd.
jd_from_fixed (date) Julian Day Number from fixed date.
fixed_from_mjd (mjd) Fixed date from Modified Julian Day Number mjd.
mjd_from_fixed (date) Modified Julian Day Number from fixed date.
unix_from_fixed (date) Unix timestamp (seconds) from fixed date.
fixed_from_unix (s) Fixed date from Unix timestamp s (seconds since 1970-01-01).
prod (expression, initial, condition) Product of expression(i) for i from initial while condition(i) holds.
from_radix (a, b[, c]) Convert mixed-radix digits a with bases b (whole) and c (fraction) to a number.
clock_from_moment (tee) Clock time {hour, minute, second} from moment tee.
time_from_clock (hms) Fractional day from clock time hms = {hour, minute, second}.
moment_from_unix (s) Moment from Unix timestamp s (seconds since 1970-01-01).
unix_from_moment (tee) Unix timestamp (seconds) from moment tee.
list_of_fixed_from_moments (ell) List of fixed dates from a list of moments (floors each moment).

Fields

BOGUS Sentinel value used to denote nonexistent dates.
FRIDAY Residue class for Friday.
MONDAY Residue class for Monday.
SATURDAY Residue class for Saturday.
SUNDAY Residue class for Sunday.
THURSDAY Residue class for Thursday.
TUESDAY Residue class for Tuesday.
WEDNESDAY Residue class for Wednesday.


Functions

quotient (m, n)
Whole part of m/n.

Parameters:

  • m number Dividend.
  • n number Divisor (non-zero).

Returns:

    number Integer quotient (floor division).
amod (x, y)
The value of (x mod y) with y instead of 0.

Parameters:

  • x number Dividend.
  • y number Modulus (non-zero).

Returns:

    number Result in range [1..y].
mod3 (x, a, b)
The value of x shifted into the range [a..b). Returns x if a = b.

Parameters:

  • x number Value to shift.
  • a number Lower bound.
  • b number Upper bound.

Returns:

    number
sum (expression, initial, condition)
Sum expression(index) for index = initial and successive integers, as long as condition(index) holds.

Parameters:

  • expression func Function mapping index to a number.
  • initial number Starting index.
  • condition func Predicate; iteration continues while true.

Returns:

    number
next (initial, condition)
First integer greater or equal to initial such that condition holds.

Parameters:

  • initial number Starting value.
  • condition func Predicate.

Returns:

    number
final (initial, condition)
Last integer greater or equal to initial such that condition holds.

Parameters:

  • initial number Starting value.
  • condition func Predicate; stops when false.

Returns:

    number
sigma (lists, body)
Sum of body(i1,…,in) for indices running simultaneously through parallel lists. lists is an array of arrays all of the same length; body receives one element from each list on each iteration.

Parameters:

  • lists table Array of equal-length arrays.
  • body func Function applied to one element from each list.

Returns:

    number
invert_angular (f, y, r)
Use bisection to find the inverse of angular function f at y within interval r.

Parameters:

  • f func Angular function to invert.
  • y number Target value.
  • r table Interval {lo, hi}.

Returns:

    number
binary_search (lo, hi, test, end_condition)
Bisection search for x in [lo..hi] such that end_condition holds. test determines when to go left.

Parameters:

  • lo number Lower bound.
  • hi number Upper bound.
  • test func Predicate; go left (upper = x) when true.
  • end_condition func Predicate on (l, u); stop when true.

Returns:

    number
poly (x, a)
Evaluate polynomial in x with coefficients a (from order 0 up).

Parameters:

  • x number Argument.
  • a table Array of coefficients, a[1] is the constant term.

Returns:

    number
sign (y)
Sign of y: returns -1, 0, or 1.

Parameters:

  • y number

Returns:

    number -1, 0, or 1.
round_half_to_even (x)
Round x to the nearest integer using banker’s rounding (half-to-even). Matches Common Lisp’s round, used in persian_from_fixed.

Parameters:

  • x number Value to round.

Returns:

    number Integer result.
rd (tee)
Identity function for fixed dates/moments (Rata Die). If internal timekeeping is shifted, change epoch inside this function.

Parameters:

  • tee number Moment or fixed date.

Returns:

    number
day_of_week_from_fixed (date)
Day of the week of fixed date (0 = Sunday .. 6 = Saturday).

Parameters:

  • date number Fixed date.

Returns:

    number Day-of-week residue class.
standard_month (date)
Month field of date = {year, month, day}.

Parameters:

  • date table Standard date tuple.

Returns:

    number Month.
standard_day (date)
Day field of date = {year, month, day}.

Parameters:

  • date table Standard date tuple.

Returns:

    number Day.
standard_year (date)
Year field of date = {year, month, day}.

Parameters:

  • date table Standard date tuple.

Returns:

    number Year.
fixed_from_moment (tee)
Fixed date (floor) from moment tee.

Parameters:

  • tee number Moment.

Returns:

    number Fixed date.
time_from_moment (tee)
Fractional time-of-day from moment tee.

Parameters:

  • tee number Moment.

Returns:

    number Time in [0, 1).
to_radix (x, b[, c])
Convert x to mixed-radix notation with bases b (whole) and c (fraction).

Parameters:

  • x number Value to convert.
  • b table Array of bases for the integer part.
  • c table Array of bases for the fractional part. (optional)

Returns:

    table Array of digits.
interval (t0, t1)
Half-open interval [t0..t1).

Parameters:

  • t0 number Start moment.
  • t1 number End moment (excluded).

Returns:

    table
interval_closed (t0, t1)
Closed interval [t0..t1].

Parameters:

  • t0 number Start moment.
  • t1 number End moment (included).

Returns:

    table
begin (range)
Start of interval range.

Parameters:

  • range table Interval {t0, t1}.

Returns:

    number t0.
end_ (range)
End of interval range. Named end_ to avoid the Lua keyword end.

Parameters:

  • range table Interval {t0, t1}.

Returns:

    number t1.
in_range (tee, range)
True if tee is in half-open range [t0..t1).

Parameters:

  • tee number Moment to test.
  • range table Interval {t0, t1}.

Returns:

    boolean
list_range (ell, range)
Those moments in list ell that occur in range.

Parameters:

  • ell table List of moments.
  • range table Interval {t0, t1}.

Returns:

    table Filtered list.
positions_in_range (p, c, cap_delta, range)
List of occurrences of moment p of c-day cycle within range. cap_delta is the position in the cycle of RD moment 0.

Parameters:

  • p number Position within the cycle.
  • c number Cycle length in days.
  • cap_delta number Cycle offset at RD 0.
  • range table Interval {t0, t1}.

Returns:

    table List of moments.
moment_from_jd (jd)
Moment from Julian Day Number jd.

Parameters:

  • jd number Julian Day Number.

Returns:

    number Moment.
jd_from_moment (tee)
Julian Day Number from moment tee.

Parameters:

  • tee number Moment.

Returns:

    number Julian Day Number.
fixed_from_jd (jd)
Fixed date from Julian Day Number jd.

Parameters:

  • jd number Julian Day Number.

Returns:

    number Fixed date.
jd_from_fixed (date)
Julian Day Number from fixed date.

Parameters:

  • date number Fixed date.

Returns:

    number Julian Day Number.
fixed_from_mjd (mjd)
Fixed date from Modified Julian Day Number mjd.

Parameters:

  • mjd number Modified Julian Day Number.

Returns:

    number Fixed date.
mjd_from_fixed (date)
Modified Julian Day Number from fixed date.

Parameters:

  • date number Fixed date.

Returns:

    number Modified Julian Day Number.
unix_from_fixed (date)
Unix timestamp (seconds) from fixed date.

Parameters:

  • date number Fixed date.

Returns:

    number Unix timestamp.
fixed_from_unix (s)
Fixed date from Unix timestamp s (seconds since 1970-01-01).

Parameters:

  • s number Unix timestamp.

Returns:

    number Fixed date.
prod (expression, initial, condition)
Product of expression(i) for i from initial while condition(i) holds.

Parameters:

  • expression func Function of i.
  • initial number 
    Starting value.
  • condition func Predicate.

Returns:

    number
from_radix (a, b[, c])
Convert mixed-radix digits a with bases b (whole) and c (fraction) to a number. Inverse of to_radix.

Parameters:

  • a table Digits.
  • b table Bases for integer part.
  • c table Bases for fractional part. (optional)

Returns:

    number
clock_from_moment (tee)
Clock time {hour, minute, second} from moment tee.

Parameters:

  • tee number Moment.

Returns:

    table {hour, minute, second}
time_from_clock (hms)
Fractional day from clock time hms = {hour, minute, second}.

Parameters:

  • hms table Clock time {hour, minute, second}.

Returns:

    number Fractional day.
moment_from_unix (s)
Moment from Unix timestamp s (seconds since 1970-01-01).

Parameters:

  • s number Unix timestamp.

Returns:

    number Moment.
unix_from_moment (tee)
Unix timestamp (seconds) from moment tee.

Parameters:

  • tee number Moment (fractional fixed date).

Returns:

    number Unix timestamp.
list_of_fixed_from_moments (ell)
List of fixed dates from a list of moments (floors each moment).

Parameters:

  • ell table List of moments.

Returns:

    table List of fixed dates.

Fields

BOGUS
Sentinel value used to denote nonexistent dates.
FRIDAY
Residue class for Friday.
MONDAY
Residue class for Monday.
SATURDAY
Residue class for Saturday.
SUNDAY
Residue class for Sunday.
THURSDAY
Residue class for Thursday.
TUESDAY
Residue class for Tuesday.
WEDNESDAY
Residue class for Wednesday.
generated by LDoc 1.5.0 Last updated 2026-10-01 02:01:33