Overview
The visual representation of calendars varies quite a bit from place to
place; see the discussion at
CalendarMonth. The calendar helpers
provide some assistance in determining a locale's calendar presentation
preferences, and working with date math in general.
Where these functions take a locale string parameter, that should follow
the same format as the locales
argument
of the Intl internationalization API. Moreover, the locale should identify
at least a language and a region. Examples: "en-US" identifies US English,
while "en-GB" identifies English in Great Britain. The use of "en" on its own
would be insufficient.
API
datesdate1, date2) static method
Return true if both date object represent the same point in time or are both null.
Parameters:
- date1:
Date|null– - date2:
Date|null–
Returns: boolean
datelocale, options) static method
Create a DateTimeFormat object for the given location and options.
Parameters:
- locale:
string– - options:
Intl.DateTimeFormatOptions–
daysdate1, date2) static method
Return the number of days between the two dates.
Parameters:
- date1:
Date– - date2:
Date–
daysdate, locale) static method
Returns the number of days between the first day of the calendar week in the indicated locale and the given date. In other words, the result indicates which column of a typical calendar the date would appear in.
Example: Suppose the given date is a Monday. In the locale 'en-US', the first day of the calendar week is a Sunday, so this function would return 1. In the locale 'en-GB', the first day of the calendar week is a Monday, in which case this function would return 0.
Parameters:
- date:
Date– the target date - locale:
string– the calendar locale
Returns: number the number of days between the first day of the week in
the locale's calendar and the target date
firstdate) static method
Returns the first date of the month that contains the indicated target date.
Parameters:
- date:
Date– the target date
Returns: Date
firstdate, locale) static method
Return the date of the first day of the week in the locale's calendar that contains the given date.
Parameters:
- date:
Date– the target date - locale:
string– the calendar locale
Returns: Date
firstlocale) static method
Returns the first day of the week in a typical calendar in the indicated locale, where 0 is Sunday, 1 is Monday, ..., and 6 = Saturday.
Parameters:
- locale:
string– the calendar locale
Returns: number the number of the first day of the week in the locale
formatdate, options) static method
Format the given date using the DateTimeFormatOptions.
The options object includes a string locale and a dateTimeFormatOptions
of type DateTimeFormatOptions.
Parameters:
- date:
Date– - options:
PlainObject–
lastdate) static method
Returns the last date of the month that contains the indicated target date.
Parameters:
- date:
Date– the target date
Returns: Date
lastdate, locale) static method
Return the date of the last day of the week in the locale's calendar that contains the given date.
Parameters:
- date:
Date– the target date - locale:
string– the calendar locale
Returns: Date
midnightdate) static method
Returns midnight on the indicated target date.
Parameters:
- date:
Date– the target date
Returns: Date
noondate) static method
Returns noon on the indicated target date.
Parameters:
- date:
Date– the target date
Returns: Date
offsetdate, days) static method
Return the result of adding/subtracting a number of days to a date.
Parameters:
- date:
Date– the target date - days:
number– the number of days to add/subtract
Returns: Date
offsetdate, months) static method
TODO: Docs
Parameters:
- date:
Date– - months:
number–
Returns: Date
parse(text, dateTimeFormat) static method
Parse a text string as a date using the formatting preferences of the
indicated locale and the Intl.DateTimeFormat formatting options.
The Intl.DateTimeFormat facility can format dates as text; this parse
function performs the reverse operation.
Parsing is limited to supporting numeric day/month/year formats. The locale and options only dictate the presence of the day, month, and year, and the order in which they will be expected. Missing day/month/year values will be inferred from the current date.
Parameters:
- text:
string– the text to parse as a date - dateTimeFormat:
Intl.DateTimeFormat– the format to parse
Returns: Datenull - the parsed date
parsetext, dateTimeFormat, timeBias) static method
Parse the indicated text as a date, first as a full date that includes the year or, if that fails to parse, as an abbreviated date that omits the year.
Parameters:
- text:
string– the text to parse as a date - dateTimeFormat:
Intl.DateTimeFormat– the format to parse - timeBias:
'future'|'past'– bias towards future if true, past if false
Returns: Datenull - the parsed date
samedate1, date2) static method
Return true if the two dates fall in the same month and year.
Parameters:
- date1:
Date– the first date to compare - date2:
Date– the second date to compare
Returns: boolean
today() static method
Returns midnight today.
Returns: Date
weekendlocale) static method
Returns the day of week (0 = Sunday, 1 = Monday, etc.) for the last day of the weekend in the indicated locale.
Parameters:
- locale:
string– the calendar locale
Returns: number
weekendlocale) static method
Returns the day of week (0 = Sunday, 1 = Monday, etc.) for the first day of the weekend in the indicated locale.
Parameters:
- locale:
string– the calendar locale
Returns: number