Custom Calendars in JS/WASM
Adding new calendars to Calends is a fairly straightforward process. Extend the
CalendarDefinition()
abstract class, and implement three methods.
Then, simply construct an instance of your calendar system, and Calends will do
the rest.
Define
Extend the CalendarDefinition()
class, implementing the following
methods:
- class calends.CalendarDefinition()
- CalendarDefinition.name
The name of the calendar system. Can be static or set in the
constructor()
.
- CalendarDefinition.defaultFormat
The default/fallback format for the calendar system. Can be static or set in the
constructor()
.
- CalendarDefinition.constructor()
This can do anything you like.
- CalendarDefinition.toInternal(stamp, format)
- Arguments
stamp (
any
) – The input. Should supportstring
s at the very minimum.format (
string
) – The format string for parsing the input date.
- Returns
The parsed internal timestamp.
- Return type
- Throws
CalendsException()
– when an error occurs
Converts an input date/time representation to an internal
TAI64Time()
.
- CalendarDefinition.fromInternal(instant, format)
- Arguments
instant (
TAI64Time()
) – The internal timestamp value.format (
string
) – The format string for formatting the output date.
- Returns
The formatted date/time.
- Return type
string
- Throws
CalendsException()
– when an error occurs
Converts an internal
TAI64Time()
to a date/time string.
- CalendarDefinition.offset(instant, offset)
- Arguments
instant (
TAI64Time()
) – The internal timestamp value.offset (
any
) – The input offset. Should supportstring
s at the very minimum.
- Returns
The adjusted internal timestamp.
- Return type
- Throws
CalendsException()
– when an error occurs
Adds the given offset to an internal
TAI64Time()
.
Registration
Register
Once it is registered with the library, your calendar system can be used from
anywhere in your application. To register a system, simply call
register()
on an object of your new class:
- CalendarDefinition.register()
Registers a calendar system instance with the internal Calends library.
Unregister
The way to unregister a calendar system is to do so manually, using the instance you created to register it with in the first place:
- CalendarDefinition.unregister()
Removes a calendar system from the callback list.
Check and List
- CalendarDefinition.isRegistered()
- Returns
Whether or not the calendar system is currently registered.
- Return type
bool
Returns whether or not a calendar system has been registered, yet.
- CalendarDefinition.registered()
- Returns
The sorted list of calendar systems currently registered.
- Return type
[string]
Returns the list of calendar systems currently registered.
Types and Values
Now we get to the inner workings that make calendar systems function – even the
built-in ones. The majority of the ”magic” comes from the TAI64Time()
object itself, as a reliable way of storing the exact instants being calculated,
and the only way times are handled by the library itself. A handful of methods
provide basic operations that calendar system developers can use to simplify
their conversions (adding and subtracting the values of other timestamps, and
importing/exporting timestamp values from/to string and numeric types, in
particular), and a couple of helpers exclusively handle adding and removing UTC
leap second offsets. As long as you can convert your dates to/from Unix
timestamps in a string or numeric type, the rest is handled entirely by these
helpers in the library itself.
- class calends.TAI64Time()
TAI64Time()
stores aTAI64NARUX
instant in a reliable, easily-converted format. Each 9-digit fractional segment is stored in a separate 32-bit integer to preserve its value with a very high degree of accuracy, without having to rely on string parsing or external arbitrary-precision mathematics libraries.- TAI64Time.seconds
The number of TAI seconds since
CE 1970-01-01 00:00:00 TAI
. Should be an integer value.Muista
TAI vs UTC
You may have noticed that a TAI64Time object stores times in
TAI seconds
, notUnix seconds
, with a timezone offset ofTAI
rather thanUTC
. This distinction is very important as it will affect internal calculations and comparisons to mix the two up. TAI time is very similar to Unix time (itself based on UTC time), with one major difference. While Unix/UTC seconds include the insertion and removal of ”leap seconds” to keep the solar zenith at local noon (which is useful for day-to-day living and planning), TAI seconds are a continuous count, unconcerned with dates whatsoever. Indeed, the only reason a date was given in the description above was to make it easier for human readers to know exactly when0 TAI
took place.In other words, once you have a Unix timestamp of your instant calculated, be sure to convert it using
fromUTC()
before returning the result to the rest of the library. And then, of course, you’ll also need to convert instants from the library back usingtoUTC()
before generating outputs.
- TAI64Time.nano
The first 9 digits of the timestamp’s fractional component.
- TAI64Time.atto
The 10th through 18th digits of the fractional component.
- TAI64Time.ronto
The 19th through 27th digits of the fractional component.
- TAI64Time.udecto
The 28th through 36th digits of the fractional component.
- TAI64Time.xindecto
The 37th through 45th digits of the fractional component.
- TAI64Time.add(z)
- Arguments
z (
TAI64Time()
) – The timestamp to add to the current one.
- Returns
The sum of the two timestamps.
- Return type
Calculates the sum of two
TAI64Time()
values.
- TAI64Time.sub(z)
- Arguments
z (
TAI64Time()
) – The timestamp to subtract from the current one.
- Returns
The difference of the two timestamps.
- Return type
Calculates the difference of two
TAI64Time()
values.
- TAI64Time.toString()
- Returns
The decimal string representation of the current timestamp.
- Return type
string
Returns the decimal string representation of the
TAI64Time()
value.
- TAI64Time.fromString(in)
- Arguments
in (
string
) – The decimal string representation of a timestamp to calculate.
- Returns
The calculated timestamp.
- Return type
Calculates a
TAI64Time()
from its decimal string representation.
- TAI64Time.toHex()
- Returns
The hexadecimal string representation of the current timestamp.
- Return type
string
Returns the hexadecimal string representation of the
TAI64Time()
value.
- TAI64Time.fromHex(in)
- Arguments
in (
string
) – The hexadecimal string representation of a timestamp to calculate.
- Returns
The calculated timestamp.
- Return type
Calculates a
TAI64Time()
from its hexadecimal string representation.
- TAI64Time.toNumber()
- Returns
The numeric representation of the current timestamp.
- Return type
number
Returns the
number
representation of theTAI64Time()
value.
- TAI64Time.fromNumber(in)
- Arguments
in (
number
) – The arbitrary-precision floating point representation of a timestamp to calculate.
- Returns
The calculated timestamp.
- Return type
Calculates a
TAI64Time()
from its numeric representation.
- TAI64Time.fromUTC()
- Returns
The calculated timestamp.
- Return type
Removes the UTC leap second offset from a TAI64Time value.
- TAI64Time.toUTC()
- Returns
The calculated timestamp.
- Return type
Adds the UTC leap second offset to a TAI64Time value.