libcalcal – Calendrical calculations in Go

About

libcalcal implements in Go the functions described and presented in:

Reingold, Edward M., and Nachum Dershowitz. 2018. Calendrical Calculations: The Ultimate Edition. 4th ed. Cambridge: Cambridge University Press.

The functions allow the computation of and conversion between dates from 31 calendars. Reingold/Dershowitz’ (authoritative) Common Lisp implementation Calendrica 4.0 is available from the book’s resource page (see “Source Code”).

libcalcal consists of roughly 430 functions distributed over 21 source files, with additional tests comparing the results of several date functions with the sample dates provided for reference in the appendix of Reingold/Dershowitz (2018). The sample data is available online from the book’s resource page.

Installation

Depending on whether you prefer to keep your $GOPATH clear of additional go packages, you may choose one of the following installation paths.

(a) Install with Go

Simply go get libcalcal and add it as a requirement to your project.

go get github.com/staudtlex/libcalcal

(b) Clone and modify your project’s go.mod

If you have a toy project where you want to use libcalcal, yet prefer to keep it outside of your $GOPATH: clone this repository and add a replace directive to your project’s go.mod file with the appropriate path to libcalcal, e.g.

module toyProjectName

go 1.16

replace github.com/staudtlex/libcalcal => /custom/path/to/libcalcal

// The `require` statement will be automatically inserted when running `go mod tidy`. No need to add it manually
require github.com/staudtlex/libcalcal v0.0.0.-...

Examples

A basic example application is located in the example subdirectory, further examples may be added in the future.

Limitations

Note that my primary motivation for writing libcalcal was to take first steps in understanding calendar-related algorithms and Go programming.

The code is currently not documented, although most functions have rather descriptive names. For more information, see Reingold/Dershowitz (2018) and their implementation in Common Lisp.

To ensure accuracy of the function results, I run tests comparing the results of around 105 functions with the sample dates provided by Reingold/Dershowitz. Currently, eight functions produce results that differ from Reingold/Dershowitz’ reference (see table below).

Function % of tests passed
MeshaSamkranti 0.00
EphemerisCorrection 39.39
EquationOfTime 24.24
SunsetInJerusalem 87.88
LunarLongitude 3.03
LunarLatitude 0.00
LunarAltitude 3.03
NextNewMoon 75.76

Note

Libcalcal may be used for personal, non-commercial purposes only. The same applies to any derivative work. Libcalcal is non-free software (see also the file LICENSE.md).

GitHub

View Github