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.
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`. |
| 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`. |
| 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). |
| 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:
- interval_closed (t0, t1)
-
Closed interval [`t0`..`t1`].
Parameters:
- t0 number Start moment.
- t1 number End moment (included).
Returns:
- 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:
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.
- 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.
- 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:
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.
- 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.