Custom Calendars in Dart
Adding new calendars to Calends is a fairly straightforward process. Extend the
CalendarDefinition
abstract class, and implement two getters and
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.get name()
- Retorna
The name of the calendar system.
- Tipus de retorn
String
- CalendarDefinition.get defaultFormat()
- Retorna
The defalt format of the calendar system.
- Tipus de retorn
String
- CalendarDefinition.toInternal(dynamic stamp, String format)
- Arguments
stamp (
dynamic
) – The input stamp. Should support strings at the very minimum.format (
String
) – The format string for parsing the input stamp.
- Retorna
The parsed internal timestamp.
- Tipus de retorn
- Throws
CalendsException()
– when an error occurs
Converts an input date/time representation to an internal
TAI64Time
.
- CalendarDefinition.fromInternal(TAI64Time stamp, String format)
- Arguments
stamp (
TAI64Time
) – The internal timestamp value.format (
String
) – The format string for formatting the output date.
- Retorna
The formatted date/time.
- Tipus de retorn
String
- Throws
CalendsException()
– when an error occurs
Converts an internal
TAI64Time
to a date/time string.
- CalendarDefinition.offset(TAI64Time stamp, dynamic offset)
- Arguments
stamp (
TAI64Time
) – The internal timestamp value.offset (
dynamic
) – The input offset. Should support strings at the very minimum.
- Retorna
The adjusted internal timestamp.
- Tipus de retorn
- 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:
- CalendarDefinition.register()
Adds a calendar system to the callback list.
Unregister
When you are done with a calendar system, it is best practice to free up resources by unregistering it:
- CalendarDefinition.unregister()
Removes a calendar system from the callback list.
Check and List
- CalendarDefinition.isRegistered()
- Retorna
Whether or not the calendar system is currently registered.
- Tipus de retorn
bool
Returns whether or not a calendar system has been registered, yet.
- CalendarDefinition.listRegistered()
- Retorna
The sorted list of calendar systems currently registered.
- Tipus de retorn
List<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
.Nota
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
utcToTai()
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 usingtaiToUtc()
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(TAI64Time z)
- Arguments
z (
TAI64Time
) – The timestamp to add to the current one.
- Retorna
The sum of the two timestamps.
- Tipus de retorn
Calculates the sum of two
TAI64Time
values.
- TAI64Time.sub(TAI64Time z)
- Arguments
z (
TAI64Time
) – The timestamp to subtract from the current one.
- Retorna
The difference of the two timestamps.
- Tipus de retorn
Calculates the difference of two
TAI64Time
values.
- TAI64Time.toTAI64String()
- Retorna
The decimal string representation of the current timestamp.
- Tipus de retorn
String
Returns the decimal string representation of the
TAI64Time
value.
- TAI64Time.fromTAI64String(String in)
- Arguments
in (
string()
) – The decimal string representation of a timestamp to calculate.
- Retorna
The calculated timestamp.
- Tipus de retorn
Calculates a
TAI64Time
from its decimal string representation.
- TAI64Time.toHex()
- Retorna
The hexadecimal string representation of the current timestamp.
- Tipus de retorn
String
Returns the hexadecimal string representation of the
TAI64Time
value.
- TAI64Time.fromHex(string in)
- Arguments
in (
string()
) – The hexadecimal string representation of a timestamp to calculate.
- Retorna
The calculated timestamp.
- Tipus de retorn
Calculates a
TAI64Time
from its hexadecimal string representation.
- TAI64Time.toDouble()
- Retorna
The floating point representation of the current timestamp.
- Tipus de retorn
double
Returns the
double
representation of theTAI64Time
value.
- TAI64Time.fromDouble(double in)
- Arguments
in (
double
) – The floating point representation of a timestamp to calculate.
- Retorna
The calculated timestamp.
- Tipus de retorn
Calculates a
TAI64Time
from itsdouble
representation.