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.
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.
Create
- class calends.Calends(stamp, calendar, format)
- Argumente
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.
- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occurs
Creates a new
Calends()
object, usingcalendar
to select a calendar system, andformat
to parse the contents ofstamp
into theCalends()
object’s internal instants. The type ofstamp
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
, andduration
. If all three are provided,duration
is ignored in favor of calculating it directly.The calendar system then converts
stamp
to aTAI64Time()
instant, which theCalends()
object sets to the appropriate internal value.
Read
- Calends.date(calendar, format)
- Argumente
calendar (
string()
) – The calendar system to format the date/time with.format (
string()
) – The format the date/time is expected to be in.- Întoarce
The start date of the
Calends()
object- Tipul întors
string
- Generează
CalendsException()
– when an error occursRetrieves the start date of the
Calends()
object as a string. The value is generated by the calendar system given incalendar
, according to the format string informat
.
- Calends.endDate(calendar, format)
- Argumente
calendar (
string()
) – The calendar system to format the date/time with.format (
string()
) – The format the date/time is expected to be in.- Întoarce
The end date of the
Calends()
object- Tipul întors
string
- Generează
CalendsException()
– when an error occursRetrieves the end date of the
Calends()
object as a string. The value is generated by the calendar system given incalendar
, according to the format string informat
.
Update
- Calends.withDate(stamp, calendar, format)
- Argumente
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.- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursReturns a
Calends()
object with a start date based on the currentCalends()
object’s value. The inputs are the same as forCalends()
, 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)
- Argumente
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.- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursReturns a
Calends()
object with an end date based on the currentCalends()
object’s value. The inputs are the same as forCalends()
, above, except the string → value map option isn’t available, since you’re already specifically setting the end value explicitly.
- Calends.withDuration(duration, calendar)
- Argumente
duration (
string()
) – The value to parse the new duration from.calendar (
string()
) – The calendar system to parse the date/time with.- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursReturns a
Calends()
object with a duration set by adjusting the currentCalends()
object’s end point, and using its start point as an anchor. Theduration
value is interpreted by the calendar system given incalendar
, so is subject to any of its rules.
- Calends.withDurationFromEnd(duration, calendar)
- Argumente
duration (
string()
) – The value to parse the new duration from.calendar (
string()
) – The calendar system to parse the date/time with.- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursReturns a
Calends()
object with a duration set by adjusting the currentCalends()
object’s start point, and using its end point as an anchor. Theduration
value is interpreted by the calendar system given incalendar
, so is subject to any of its rules.
Manipulate
- Calends.add(offset, calendar)
- Argumente
offset (
string()
) – The value to parse the offset from.calendar (
string()
) – The calendar system to parse the date/time with.- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursIncreases the end date of the
Calends()
object’s current value byoffset
, as interpreted by the calendar system given incalendar
, and returns a newCalends()
object with the result.
- Calends.addFromEnd(offset, calendar)
- Argumente
offset (
string()
) – The value to parse the offset from.calendar (
string()
) – The calendar system to parse the date/time with.- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursIncreases the start date of the
Calends()
object’s current value byoffset
, as interpreted by the calendar system given incalendar
, and returns a newCalends()
object with the result.
- Calends.subtract(offset, calendar)
- Argumente
offset (
string()
) – The value to parse the offset from.calendar (
string()
) – The calendar system to parse the date/time with.- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursWorks the same as
add()
, except it decreases the start date, rather than increasing the end date.
- Calends.subtractFromEnd(offset, calendar)
- Argumente
offset (
string()
) – The value to parse the offset from.calendar (
string()
) – The calendar system to parse the date/time with.- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursWorks the same as
addFromEnd()
, except it decreases the end date, rather than increasing the start date.
- Calends.next(offset, calendar)
- Argumente
offset (
string()
) – The value to parse the offset from.calendar (
string()
) – The calendar system to parse the date/time with.- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursReturns a
Calends()
object ofoffset
duration (as interpreted by the calendar system given incalendar
), which abuts the currentCalends()
object’s value. Ifoffset
is empty,calendar
is ignored, and the current object’s duration is used instead.
- Calends.previous(offset, calendar)
- Argumente
offset (
string()
) – The value to parse the offset from.calendar (
string()
) – The calendar system to parse the date/time with.- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursReturns a
Calends()
object ofoffset
duration (as interpreted by the calendar system given incalendar
), which abuts the currentCalends()
object’s value. Ifoffset
is empty,calendar
is ignored, and the current object’s duration is used instead.
Combine
- Calends.merge(other)
- Argumente
- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursReturns a
Calends()
object spanning from the earliest start date to the latest end date between the currentCalends()
object andother
.
- Calends.intersect(other)
- Argumente
- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursReturns a
Calends()
object spanning the overlap between the currentCalends()
object andother
. If the current object andother
don’t overlap, throws an error.
- Calends.gap(other)
- Argumente
- Întoarce
A new
Calends()
object- Tipul întors
- Generează
CalendsException()
– when an error occursReturns a
Calends()
object spanning the gap between the currentCalends()
object andother
. If the current object andother
overlap (and there is, therefore, no gap to return), throws an error.
Compare
- Calends.difference(other, mode)
- Argumente
- Întoarce
The difference, as a decimal string
- Tipul întors
string
Returns the difference of the current
Calends()
object minusother
, usingmode
to select which values to use in the calculation. Validmode
s include:
start
- use the start date of both the current object andother
duration
- use the duration of both the current object andother
end
- use the end date of both the current object andother
start-end
- use the start of the current object, and the end ofother
end-start
- use the end of the current object, and the start ofother
- Calends.compare(other, mode)
- Argumente
- Întoarce
A standard comparison result
- Tipul întors
int
Returns
-1
if the currentCalends()
object is less thanother
,0
if they are equal, and1
if the current object is greater thanother
, usingmode
to select which values to use in the comparison. Validmode
s are the same as forCalends.difference()
, above.
- Calends.contains(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the current
Calends()
object contains all ofother
.
- Calends.overlaps(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the current
Calends()
object overlaps withother
.
- Calends.abuts(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the current
Calends()
object abutsother
(that is, whether one begins at the same instant the other ends).
- Calends.isSame(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the current
Calends()
object covers the same span of time asother
.
- Calends.isShorter(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the duration of the current
Calends()
object andother
.
- Calends.isSameDuration(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the duration of the current
Calends()
object andother
.
- Calends.isLonger(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the duration of the current
Calends()
object andother
.
- Calends.isBefore(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the entirety of the current
Calends()
object with the start date ofother
.
- Calends.startsBefore(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the start date of the current
Calends()
object with the start date ofother
.
- Calends.endsBefore(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the end date of the current
Calends()
object with the start date ofother
.
- Calends.isDuring(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the entirety of the current
Calends()
object lies between the start and end dates ofother
.
- Calends.startsDuring(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the start date of the current
Calends()
object lies between the start and end dates ofother
.
- Calends.endsDuring(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the end date of the current
Calends()
object lies between the start and end dates ofother
.
- Calends.isAfter(other)
- Argumente
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the entirety of the current
Calends()
object with the end date ofother
.
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.fromText(stamp)
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.