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

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

lastDateOfMonth(date) static method

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

Parameters:

  • date: Datethe target date

Returns: Date

midnightOnDate(date) static method

Returns midnight 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

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