calendar

Helpers for date math and locale-sensitive calendar preferences

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

datesEqual(date1, 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

dateTimeFormat(locale, options) static method

Create a DateTimeFormat object for the given location and options.

Parameters:

  • locale: string
  • options: Intl.DateTimeFormatOptions

daysBetweenDates(date1, date2) static method

Return the number of days between the two dates.

Parameters:

  • date1: Date
  • date2: Date

daysSinceFirstDayOfWeek(date, 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: Datethe target date
  • locale: stringthe calendar locale

Returns: number the number of days between the first day of the week in the locale's calendar and the target date

firstDateOfMonth(date) static method

Returns the first date of the month that contains the indicated target date.

Parameters:

  • date: Datethe target date

Returns: Date

firstDateOfWeek(date, 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: Datethe target date
  • locale: stringthe calendar locale

Returns: Date

firstDayOfWeek(locale) 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: stringthe calendar locale

Returns: number the number of the first day of the week in the locale

formatDate(date, 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

lastDateOfMonth(date) static method

Returns the last date of the month that contains the indicated target date.

Parameters:

  • date: Datethe target date

Returns: Date

lastDateOfWeek(date, 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: Datethe target date
  • locale: stringthe calendar locale

Returns: Date

midnightOnDate(date) static method

Returns midnight on the indicated target date.

Parameters:

  • date: Datethe target date

Returns: Date

noonOnDate(date) static method

Returns noon on the indicated target date.

Parameters:

  • date: Datethe target date

Returns: Date

offsetDateByDays(date, days) static method

Return the result of adding/subtracting a number of days to a date.

Parameters:

  • date: Datethe target date
  • days: numberthe number of days to add/subtract

Returns: Date

offsetDateByMonths(date, 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: stringthe text to parse as a date
  • dateTimeFormat: Intl.DateTimeFormatthe format to parse

Returns: Datenull - the parsed date

parseWithOptionalYear(text, 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: stringthe text to parse as a date
  • dateTimeFormat: Intl.DateTimeFormatthe format to parse
  • timeBias: 'future'|'past'bias towards future if true, past if false

Returns: Datenull - the parsed date

sameMonthAndYear(date1, date2) static method

Return true if the two dates fall in the same month and year.

Parameters:

  • date1: Datethe first date to compare
  • date2: Datethe second date to compare

Returns: boolean

today() static method

Returns midnight today.

Returns: Date

weekendEnd(locale) 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: stringthe calendar locale

Returns: number

weekendStart(locale) 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: stringthe calendar locale

Returns: number