Using Calends in Dart

Calends exposes a very small handful of things for use outside the library itself. One is the Calends class, documented here, which should be the only interface users of the library ever need to touch.

Another thing Calends exposes is the TAI64Time class, used to store and manipulate the instants of time which make up a Calends instance. The rest are interfaces for extending the library’s functionality. These are covered in the Custom Calendars in Dart section.

Not

Calends objects are immutable - all methods return a new Calends object where they might otherwise alter the current one. This has the side effect of using more memory to perform manipulations than updating values on an existing object would. It makes many operations safer, though, than mutable objects would allow.

class calends.Calends

The main entry point to Calends and its functionality.

Calends.initialize()

Sets up the error handling and otherwise preps the library for use. Run this before doing anything else!

Create

Calends.(stamp, calendar, format)
Bağımsız Değişkenler

  • stamp (dynamic()) – The timestamp to parse the date(s)/time(s) from.

  • calendar (String()) – The calendar system to parse the date(s)/time(s) with.

  • format (String()) – The format the date(s)/time(s) is/are expected to use.

Şunu verir:

CalendsException() – when an error occurs

Creates a new Calends object, using calendar to select a calendar system, and format to parse the contents of stamp into the Calends object’s internal instants. The type of stamp can vary based on the calendar system itself, but generally speaking can always be a string.

In any case, the stamp can also be a Map, where the String keys are any two of start, end, and duration. If all three are provided, duration is ignored in favor of calculating it directly.

The calendar system then converts stamp to a pair of TAI64Time instants, which the Calends object sets to the appropriate internal value.

Read

Calends.date(calendar, format)
Bağımsız Değişkenler

  • calendar (String()) – The calendar system to format the date/time with.

  • format (String()) – The format the date/time is expected to be in.

Dönüşler

The start date of the Calends object

Dönüş türü

string

Şunu verir:

CalendsException() – when an error occurs

Retrieves the start date of the Calends object as a string. The value is generated by the calendar system given in calendar, according to the format string in format.

Calends.endDate(calendar, format)
Bağımsız Değişkenler

  • calendar (String()) – The calendar system to format the date/time with.

  • format (String()) – The format the date/time is expected to be in.

Dönüşler

The end date of the Calends object

Dönüş türü

string

Şunu verir:

CalendsException() – when an error occurs

Retrieves the end date of the Calends object as a string. The value is generated by the calendar system given in calendar, according to the format string in format.

Calends.duration()
Dönüşler

The duration of the Calends object

Dönüş türü

string

Retrieves the duration of the Calends object as a decimal string. This value will be 0 if the Calends object contains an instant.

Update

Calends.withDate(stamp, calendar, format)
Bağımsız Değişkenler

  • stamp (dynamic()) – The value to parse the date/time from.

  • calendar (String()) – The calendar system to parse the date/time with.

  • format (String()) – The format the date/time is expected to use.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Returns a Calends object with a start date based on the current Calends object’s value. The inputs are the same as for Calends.(), above, except the String → value map option isn’t available, since you’re already specifically setting the start value explicitly.

Calends.withEndDate(value, calendar, format)
Bağımsız Değişkenler

  • stamp (dynamic()) – The value to parse the date/time from.

  • calendar (String()) – The calendar system to parse the date/time with.

  • format (String()) – The format the date/time is expected to use.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Returns a Calends object with an end date based on the current Calends object’s value. The inputs are the same as for Calends.(), above, except the String → value map option isn’t available, since you’re already specifically setting the end value explicitly.

Calends.withDuration(duration, calendar)
Bağımsız Değişkenler

  • duration (dynamic()) – The value to parse the new duration from.

  • calendar (String()) – The calendar system to parse the date/time with.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Returns a Calends object with a duration set by adjusting the current Calends object’s end point, and using its start point as an anchor. The duration value is interpreted by the calendar system given in calendar, so is subject to any of its rules.

Calends.withDurationFromEnd(duration, calendar)
Bağımsız Değişkenler

  • duration (dynamic()) – The value to parse the new duration from.

  • calendar (String()) – The calendar system to parse the date/time with.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Returns a Calends object with a duration set by adjusting the current Calends object’s start point, and using its end point as an anchor. The duration value is interpreted by the calendar system given in calendar, so is subject to any of its rules.

Manipulate

Calends.add(offset, calendar)
Bağımsız Değişkenler

  • offset (dynamic()) – The value to parse the offset from.

  • calendar (String()) – The calendar system to parse the date/time with.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Increases the end date of the Calends object’s current value by offset, as interpreted by the calendar system given in calendar, and returns a new Calends object with the result.

Calends.addFromEnd(offset, calendar)
Bağımsız Değişkenler

  • offset (dynamic()) – The value to parse the offset from.

  • calendar (String()) – The calendar system to parse the date/time with.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Increases the start date of the Calends object’s current value by offset, as interpreted by the calendar system given in calendar, and returns a new Calends object with the result.

Calends.subtract(offset, calendar)
Bağımsız Değişkenler

  • offset (dynamic()) – The value to parse the offset from.

  • calendar (String()) – The calendar system to parse the date/time with.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Works the same as add(), except it decreases the start date, rather than increasing it.

Calends.subtractFromEnd(offset, calendar)
Bağımsız Değişkenler

  • offset (dynamic()) – The value to parse the offset from.

  • calendar (String()) – The calendar system to parse the date/time with.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Works the same as addFromEnd(), except it decreases the end date, rather than increasing it.

Calends.next(offset, calendar)
Bağımsız Değişkenler

  • offset (dynamic()) – The value to parse the offset from.

  • calendar (String()) – The calendar system to parse the date/time with.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Returns a Calends object of offset duration (as interpreted by the calendar system given in calendar), which abuts the current Calends object’s value. If offset is empty, calendar is ignored, and the current object’s duration is used instead.

Calends.previous(offset, calendar)
Bağımsız Değişkenler

  • offset (dynamic()) – The value to parse the offset from.

  • calendar (String()) – The calendar system to parse the date/time with.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Returns a Calends object of offset duration (as interpreted by the calendar system given in calendar), which abuts the current Calends object’s value. If offset is empty, calendar is ignored, and the current object’s duration is used instead.

Combine

Calends.merge(c2)
Bağımsız Değişkenler
Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Returns a Calends object spanning from the earliest start date to the latest end date between the current Calends object and c2.

Calends.intersect(c2)
Bağımsız Değişkenler
Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Returns a Calends object spanning the overlap between the current Calends object and c2. If the current object and c2 don’t overlap, throws an error.

Calends.gap(c2)
Bağımsız Değişkenler
Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Returns a Calends object spanning the gap between the current Calends object and c2. If the current object and c2 overlap (and there is, therefore, no gap to return), throws an error.

Compare

Calends.difference(c2, mode)
Bağımsız Değişkenler

  • c2 (Calends()) – The Calends object to compare.

  • mode (String()) – The comparison mode.

Dönüşler

The difference, as a decimal string

Dönüş türü

string

Returns the difference of the current Calends object minus c2, using mode to select which values to use in the calculation. Valid modes include:

  • start - use the start date of both the current object and c2

  • duration - use the duration of both the current object and c2

  • end - use the end date of both the current object and c2

  • start-end - use the start of the current object, and the end of c2

  • end-start - use the end of the current object, and the start of c2

Calends.compare(c2, mode)
Bağımsız Değişkenler

  • c2 (Calends()) – The Calends object to compare.

  • mode (String()) – The comparison mode.

Dönüşler

A standard comparison result

Dönüş türü

int

Returns -1 if the current Calends object is less than c2, 0 if they are equal, and 1 if the current object is greater than c2, using mode to select which values to use in the comparison. Valid modes are the same as for difference(), above.

Calends.contains(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Checks whether the current Calends object contains all of c2.

Calends.overlaps(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Checks whether the current Calends object overlaps with c2.

Calends.abuts(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Checks whether the current Calends object abuts c2 (that is, whether one begins at the same instant the other ends).

Calends.isSame(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Checks whether the current Calends object covers the same span of time as c2. Also available via the == operator.

Calends.isShorter(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Compares the duration of the current Calends object and c2.

Calends.isSameDuration(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Compares the duration of the current Calends object and c2.

Calends.isLonger(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Compares the duration of the current Calends object and c2.

Calends.isBefore(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Compares the entirety of the current Calends object with the start date of c2. Also available as the < operator.

Calends.startsBefore(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Compares the start date of the current Calends object with the start date of c2.

Calends.endsBefore(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Compares the end date of the current Calends object with the start date of c2.

Calends.isDuring(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Checks whether the entirety of the current Calends object lies between the start and end dates of c2.

Calends.startsDuring(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Checks whether the start date of the current Calends object lies between the start and end dates of c2.

Calends.endsDuring(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Checks whether the end date of the current Calends object lies between the start and end dates of c2.

Calends.isAfter(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Compares the entirety of the current Calends object with the end date of c2. Also available as the > operator.

Calends.startsAfter(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Compares the start date of the current Calends object with the end date of c2.

Calends.endsAfter(c2)
Bağımsız Değişkenler
Dönüşler

The result of the comparison

Dönüş türü

bool

Compares the end date of the current Calends object with the end date of c2.

Export

It’s possible to export Calends values in a couple of ways, and then re-import them later/elsewhere. The text encoding is the less portable option, though, so we strongly recommend using JSON instead.

Calends.encodeText()
Dönüşler

The text-encoded value of the Calends instance.

Dönüş türü

String

Şunu verir:

CalendsException() – when an error occurs

Calends.decodeText(encoded)
Bağımsız Değişkenler

  • encoded (String()) – The text-encoded value to import.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

Calends.encodeJson()
Dönüşler

The JSON-encoded value of the Calends instance.

Dönüş türü

String

Şunu verir:

CalendsException() – when an error occurs

Calends.decodeJson(encoded)
Bağımsız Değişkenler

  • encoded (String()) – The JSON-encoded value to import.

Dönüşler

A new Calends object

Dönüş türü

Calends

Şunu verir:

CalendsException() – when an error occurs

If you just need a String value for display purposes, and can’t use the date() method to format it to a given calendar system, there is a fallback mechanism in the form of the toString() method. This value is neither human-readable nor machine-importable, so it should only be used for debugging.

Calends.toString()
Dönüşler

A non-portable representation of the Calends instance.

Dönüş türü

String

Şunu verir:

CalendsException() – when an error occurs

Error Handling

class calends.CalendsException

A very simple exception class, directly extending Exception. It is thrown by the library for all encountered errors.