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.
참고
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)
- 인수
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.- 예외
CalendsException()
– when an error occursCreates 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 stamp can also be a
Map
, where theString
keys are any two ofstart
,end
, andduration
. If all three are provided,duration
is ignored in favor of calculating it directly.The calendar system then converts
stamp
to a pair ofTAI64Time
instants, which theCalends
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 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)
- 인수
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 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)
- 인수
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.- 반환
A new
Calends
object- 반환 형식
- 예외
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 theString
→ value map option isn’t available, since you’re already specifically setting the start value explicitly.
- Calends.withEndDate(value, calendar, format)
- 인수
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.- 반환
A new
Calends
object- 반환 형식
- 예외
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 theString
→ value map option isn’t available, since you’re already specifically setting the end value explicitly.
- Calends.withDuration(duration, calendar)
- 인수
duration (
dynamic()
) – The value to parse the new duration from.calendar (
String()
) – The calendar system to parse the date/time with.- 반환
A new
Calends
object- 반환 형식
- 예외
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)
- 인수
duration (
dynamic()
) – The value to parse the new duration from.calendar (
String()
) – The calendar system to parse the date/time with.- 반환
A new
Calends
object- 반환 형식
- 예외
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)
- 인수
offset (
dynamic()
) – The value to parse the offset from.calendar (
String()
) – The calendar system to parse the date/time with.- 반환
A new
Calends
object- 반환 형식
- 예외
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)
- 인수
offset (
dynamic()
) – The value to parse the offset from.calendar (
String()
) – The calendar system to parse the date/time with.- 반환
A new
Calends
object- 반환 형식
- 예외
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)
- 인수
offset (
dynamic()
) – The value to parse the offset from.calendar (
String()
) – The calendar system to parse the date/time with.- 반환
A new
Calends
object- 반환 형식
- 예외
CalendsException()
– when an error occursWorks the same as
add()
, except it decreases the start date, rather than increasing it.
- Calends.subtractFromEnd(offset, calendar)
- 인수
offset (
dynamic()
) – The value to parse the offset from.calendar (
String()
) – The calendar system to parse the date/time with.- 반환
A new
Calends
object- 반환 형식
- 예외
CalendsException()
– when an error occursWorks the same as
addFromEnd()
, except it decreases the end date, rather than increasing it.
- Calends.next(offset, calendar)
- 인수
offset (
dynamic()
) – The value to parse the offset from.calendar (
String()
) – The calendar system to parse the date/time with.- 반환
A new
Calends
object- 반환 형식
- 예외
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)
- 인수
offset (
dynamic()
) – The value to parse the offset from.calendar (
String()
) – The calendar system to parse the date/time with.- 반환
A new
Calends
object- 반환 형식
- 예외
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(c2)
- 인수
- 반환
A new
Calends
object- 반환 형식
- 예외
CalendsException()
– when an error occursReturns a
Calends
object spanning from the earliest start date to the latest end date between the currentCalends
object andc2
.
- Calends.intersect(c2)
- 인수
- 반환
A new
Calends
object- 반환 형식
- 예외
CalendsException()
– when an error occursReturns a
Calends
object spanning the overlap between the currentCalends
object andc2
. If the current object andc2
don’t overlap, throws an error.
- Calends.gap(c2)
- 인수
- 반환
A new
Calends
object- 반환 형식
- 예외
CalendsException()
– when an error occursReturns a
Calends
object spanning the gap between the currentCalends
object andc2
. If the current object andc2
overlap (and there is, therefore, no gap to return), throws an error.
Compare
- Calends.difference(c2, mode)
- 인수
- 반환
The difference, as a decimal string
- 반환 형식
string
Returns the difference of the current
Calends
object minusc2
, usingmode
to select which values to use in the calculation. Validmode
s include:
start
- use the start date of both the current object andc2
duration
- use the duration of both the current object andc2
end
- use the end date of both the current object andc2
start-end
- use the start of the current object, and the end ofc2
end-start
- use the end of the current object, and the start ofc2
- Calends.compare(c2, mode)
- 인수
- 반환
A standard comparison result
- 반환 형식
int
Returns
-1
if the currentCalends
object is less thanc2
,0
if they are equal, and1
if the current object is greater thanc2
, usingmode
to select which values to use in the comparison. Validmode
s are the same as fordifference()
, above.
- Calends.abuts(c2)
Checks whether the current
Calends
object abutsc2
(that is, whether one begins at the same instant the other ends).
- Calends.isSame(c2)
Checks whether the current
Calends
object covers the same span of time asc2
. Also available via the==
operator.
- Calends.isBefore(c2)
Compares the entirety of the current
Calends
object with the start date ofc2
. Also available as the<
operator.
- Calends.startsBefore(c2)
Compares the start date of the current
Calends
object with the start date ofc2
.
- Calends.endsBefore(c2)
Compares the end date of the current
Calends
object with the start date ofc2
.
- Calends.isDuring(c2)
Checks whether the entirety of the current
Calends
object lies between the start and end dates ofc2
.
- Calends.startsDuring(c2)
Checks whether the start date of the current
Calends
object lies between the start and end dates ofc2
.
- Calends.endsDuring(c2)
Checks whether the end date of the current
Calends
object lies between the start and end dates ofc2
.
- Calends.isAfter(c2)
Compares the entirety of the current
Calends
object with the end date ofc2
. Also available as the>
operator.
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()
- 반환
The text-encoded value of the
Calends
instance.- 반환 형식
String
- 예외
CalendsException()
– when an error occurs
- Calends.decodeText(encoded)
- 인수
encoded (
String()
) – The text-encoded value to import.- 반환
A new
Calends
object- 반환 형식
- 예외
CalendsException()
– when an error occurs
- Calends.encodeJson()
- 반환
The JSON-encoded value of the
Calends
instance.- 반환 형식
String
- 예외
CalendsException()
– when an error occurs
- Calends.decodeJson(encoded)
- 인수
encoded (
String()
) – The JSON-encoded value to import.- 반환
A new
Calends
object- 반환 형식
- 예외
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()
- 반환
A non-portable representation of the
Calends
instance.- 반환 형식
String
- 예외
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.