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()

Результат

The name of the calendar system.

Тип результата

String

CalendarDefinition.get defaultFormat()

Результат

The defalt format of the calendar system.

Тип результата

String

CalendarDefinition.toInternal(dynamic stamp, String format)

Аргументы

• stamp (dynamic) – The input stamp. Should support strings at the very minimum.

• format (String) – The format string for parsing the input stamp.

Результат

The parsed internal timestamp.

Тип результата

TAI64Time

Бросает исключение

CalendsException() – when an error occurs

Converts an input date/time representation to an internal TAI64Time.

CalendarDefinition.fromInternal(TAI64Time stamp, String format)

Аргументы

• stamp (TAI64Time) – The internal timestamp value.

• format (String) – The format string for formatting the output date.

Результат

The formatted date/time.

Тип результата

String

Бросает исключение

CalendsException() – when an error occurs

Converts an internal TAI64Time to a date/time string.

CalendarDefinition.offset(TAI64Time stamp, dynamic offset)

Аргументы

• stamp (TAI64Time) – The internal timestamp value.

• offset (dynamic) – The input offset. Should support strings at the very minimum.

Результат

The adjusted internal timestamp.

Тип результата

TAI64Time

Бросает исключение

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()

Результат

Whether or not the calendar system is currently registered.

Тип результата

bool

Returns whether or not a calendar system has been registered, yet.

CalendarDefinition.listRegistered()

Результат

The sorted list of calendar systems currently registered.

Тип результата

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 a TAI64NARUX 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.

Примечание

TAI vs UTC

You may have noticed that a TAI64Time object stores times in TAI seconds, not Unix seconds, with a timezone offset of TAI rather than UTC. 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 when 0 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 using taiToUtc() 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)

Аргументы

• z (TAI64Time) – The timestamp to add to the current one.

Результат

The sum of the two timestamps.

Тип результата

TAI64Time

Calculates the sum of two TAI64Time values.

TAI64Time.sub(TAI64Time z)

Аргументы

• z (TAI64Time) – The timestamp to subtract from the current one.

Результат

The difference of the two timestamps.

Тип результата

TAI64Time

Calculates the difference of two TAI64Time values.

TAI64Time.toTAI64String()

Результат

The decimal string representation of the current timestamp.

Тип результата

String

Returns the decimal string representation of the TAI64Time value.

TAI64Time.fromTAI64String(String in)

Аргументы

• in (string()) – The decimal string representation of a timestamp to calculate.

Результат

The calculated timestamp.

Тип результата

TAI64Time

Calculates a TAI64Time from its decimal string representation.

TAI64Time.toHex()

Результат

The hexadecimal string representation of the current timestamp.

Тип результата

String

Returns the hexadecimal string representation of the TAI64Time value.

TAI64Time.fromHex(string in)

Аргументы

• in (string()) – The hexadecimal string representation of a timestamp to calculate.

Результат

The calculated timestamp.

Тип результата

TAI64Time

Calculates a TAI64Time from its hexadecimal string representation.

TAI64Time.toDouble()

Результат

The floating point representation of the current timestamp.

Тип результата

double

Returns the double representation of the TAI64Time value.

TAI64Time.fromDouble(double in)

Аргументы

• in (double) – The floating point representation of a timestamp to calculate.

Результат

The calculated timestamp.

Тип результата

TAI64Time

Calculates a TAI64Time from its double representation.

TAI64Time.utcToTai()

Результат

The calculated timestamp.

Тип результата

TAI64Time

Removes the UTC leap second offset from a TAI64Time value. Used when converting from Unix time to TAI time.

TAI64Time.taiToUtc()

Результат

The calculated timestamp.

Тип результата

TAI64Time

Adds the UTC leap second offset to a TAI64Time value. Used when converting from TAI time to Unix time.