lua-calendrica

# 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.1 2026-07-19

## 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-07-19 03:28:25