Features in Calends
For a current indication of which of these features are fully implemented at the moment, check the README.
- Large range and high precision
Calends understands dates 262 seconds into the future or past, in units as small as 10-45 seconds – that’s over 146 billion years into the past or future (146 138 512 313 years, 169 days, 10 hours, 5 minutes, and 28 seconds from
CE 1970 Jan 01 00:00:00 TAI Gregorian
), at resolutions smaller than Planck Time (54×10-45 seconds, and the smallest meaningful duration even on the quantum scale). That encompasses well beyond the expected lifespan of the Universe, at resolutions enough to represent quantum events.
- Supports date (and time) values in multiple calendar systems
Supported out of the box are the following (all systems are proleptic – extrapolated beyond the officially-defined limits – unless specified otherwise):
- Unix time
A count of the number of seconds since
CE 1970 Jan 01 00:00:00 UTC Gregorian
- TAI64
Essentially Unix time plus 262, but using TAI seconds instead of UTC seconds, so times can be converted unambiguously (UTC uses leap seconds to keep the solar zenith at noon, while TAI is a simple, unadjusted count). Calends supports an extended version of this spec, with three more components, to encode out to 45 places instead of just 18; this is also actually the internal time scale used by Calends itself, which is how it can support such a broad range of dates at such a high resolution.
Automatic calculation of leap second offsets
Estimation of undefined past and future leap second insertions
Automatic updates for handling leap second insertions
- Gregorian
The current international standard calendar system
Disconnect from native
time.Time
implementation, and its limitations
- Julian
The previous version of the Gregorian calendar
- Julian Day Count
A count of days since
BCE 4713 Jan 01 12:00:00 UTC Julian (proleptic)
- Hebrew
- Persian
- Chinese
Several variants
- Meso-American
Commonly called Mayan, but used by several cultures in the region
- Discordian
- Stardate
Yes, the ones from Star Trek™; several variants exist
- Encodes both time spans and instants in a single interface
The library treats the time values it encodes as
[start, end)
sets (that is, thestart
point is included in the range, as is every point betweenstart
andend
, but theend
point itself is _not_ included in the range). This allowsduration
to accurately beend - start
in all cases. (And yes, that also means you can create spans withduration < 0
.)
- Supports calculations and comparisons on spans and instants
Addition, subtraction, intersection, combination, gap calculation, overlap detection, and similar operations are all supported directly on Calends values.
- Conversion to/from native date/time types
While this is possible by using a string representation as an intermediary, in either direction, some data and precision is lost in such a conversion. Instead, Calends supports conversion to and from such types directly, preserving as much data and accuracy as each native type provides.
- Geo-temporally aware
The library provides methods for passing a location instead of a calendar system, and selecting an appropriate calendar based on which was most common in that location at that point in time. (Some guess work is involved in this process when parsing dates, so it is still preferred to supply the calendar system, if known, when parsing.)
- Time zone support
- Well-defined interfaces for extending the library
Add more calendar systems, type conversions, or geo-temporal relationships without forking/modifying the library itself.
- Shared library (
.so
/.dll
/.dylib
) In order to use the library outside of Golang projects, we first need to export its functionality in a shared library, which can then be accessed from other programming evironments and applications, generally via FFI.
- Shared library (
- WebAssembly binary
In order to use the library in the browser, we first need to export its functionality in a WebAssembly (WASM) binary, which can then be accessed by JavaScript. (Go currently doesn’t support the WASI standard, so the functions are registered into the global namespace rather than being
export
ed by WebAssembly itself. More on that in the JS docs.)