Using Calends in JS/WASM

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() moment or instance. The rest are interfaces for extending the library’s functionality. These are covered in the Custom Calendars in JS/WASM section.

Σημείωση

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.

Create

class calends.Calends(stamp, calendar, format)
Παράμετροι

  • stamp (mixed()) – The value 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.

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

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 value can always be an associative array, where the 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 TAI64Time() instant, which the Calends() object sets to the appropriate internal value.

Read

Calends.date(calendar, format)
Παράμετροι

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

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

Επιστρέφει

The start date of the Calends() object

Επιστρεφόμενος τύπος

string

Προκαλεί

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)
Παράμετροι

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

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

Επιστρέφει

The end date of the Calends() object

Επιστρεφόμενος τύπος

string

Προκαλεί

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()
Επιστρέφει

The duration of the Calends() object

Επιστρεφόμενος τύπος

string

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

Update

Calends.withDate(stamp, calendar, format)
Παράμετροι

  • stamp (mixed()) – 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.

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

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(stamp, calendar, format)
Παράμετροι

  • stamp (mixed()) – 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.

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

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)
Παράμετροι

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

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

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

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)
Παράμετροι

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

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

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

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)
Παράμετροι

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

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

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

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)
Παράμετροι

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

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

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

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)
Παράμετροι

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

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

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

CalendsException() – when an error occurs

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

Calends.subtractFromEnd(offset, calendar)
Παράμετροι

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

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

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

CalendsException() – when an error occurs

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

Calends.next(offset, calendar)
Παράμετροι

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

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

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

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)
Παράμετροι

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

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

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

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(other)
Παράμετροι
Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

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 other.

Calends.intersect(other)
Παράμετροι
Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

CalendsException() – when an error occurs

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

Calends.gap(other)
Παράμετροι
Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Προκαλεί

CalendsException() – when an error occurs

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

Compare

Calends.difference(other, mode)
Παράμετροι

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

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

Επιστρέφει

The difference, as a decimal string

Επιστρεφόμενος τύπος

string

Returns the difference of the current Calends() object minus other, 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 other

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

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

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

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

Calends.compare(other, mode)
Παράμετροι

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

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

Επιστρέφει

A standard comparison result

Επιστρεφόμενος τύπος

int

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

Calends.contains(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Checks whether the current Calends() object contains all of other.

Calends.overlaps(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Checks whether the current Calends() object overlaps with other.

Calends.abuts(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

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

Calends.isSame(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Checks whether the current Calends() object covers the same span of time as other.

Calends.isShorter(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Compares the duration of the current Calends() object and other.

Calends.isSameDuration(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Compares the duration of the current Calends() object and other.

Calends.isLonger(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Compares the duration of the current Calends() object and other.

Calends.isBefore(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Compares the entirety of the current Calends() object with the start date of other.

Calends.startsBefore(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Compares the start date of the current Calends() object with the start date of other.

Calends.endsBefore(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Compares the end date of the current Calends() object with the start date of other.

Calends.isDuring(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Checks whether the entirety of the current Calends() object lies between the start and end dates of other.

Calends.startsDuring(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Checks whether the start date of the current Calends() object lies between the start and end dates of other.

Calends.endsDuring(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Checks whether the end date of the current Calends() object lies between the start and end dates of other.

Calends.isAfter(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Compares the entirety of the current Calends() object with the end date of other.

Calends.startsAfter(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Compares the start date of the current Calends() object with the end date of other.

Calends.endsAfter(other)
Παράμετροι
Επιστρέφει

The result of the comparison

Επιστρεφόμενος τύπος

bool

Compares the end date of the current Calends() object with the end date of other.

Export

It is possible to export Calends() objects for use later/elsewhere, or to import such values for use in your own code. There are two formats for this purpose: text encoding and JSON encoding. Needless to say, the JSON encoding is considerably more portable, and therefore preferred. Still, both are supported, and as such both are documented here. YMMV.

Calends.toText()
Επιστρέφει

The text encoding of the Calends() object.

Επιστρεφόμενος τύπος

string

Calends.fromText(stamp)
Παράμετροι

  • stamp – The text encoded value to import.

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

Calends.toJson()
Επιστρέφει

The JSON encoding of the Calends() object.

Επιστρεφόμενος τύπος

string

Calends.fromJson(stamp)
Παράμετροι

  • stamp – The JSON encoded value to import.

Επιστρέφει

A new Calends() object

Επιστρεφόμενος τύπος

Calends()

For logging, there’s also a toString() method; we don’t recommend using it directly since the output is neither human-readable nor machine-importable.

In addition to the above, there’s improved JSON support in JS (go figure) with the following methods:

JSON.stringify(objectWithMomentChildren);

JSON.parse(stored, Calends.reviver);

Error Handling

class calends.CalendsError()

A very simple error class, directly extending Error(). It is thrown by the library for all encountered errors.