Class: module:extdate

module:extdate(calendaropt, dateArgumentsopt)

ExtDate (default exported class): extends the Date object with the flavour of Temporal proposal, using custom calendars. All methods of the Date object are also available. However, with the built-in methods, the figure that represents the month begins with 0, with the extended ones, it begins with 1.

Constructor

new module:extdate(calendaropt, dateArgumentsopt)

Parameters:
Name Type Attributes Description
calendar string | object <optional>
 the calendar object that describes the custom calendar, or a string that refers to a built-in calendar; if undefined, set to "iso8601"; In this version, the string for a built-in calendar may only be "iso8601" (default) or "gregory".
dateArguments string | Array.<number> <optional>
 same parameter list as would be passed to the legacy Date object: empty -> now; one numerical argument: Posix counter in milliseconds, as for Date; one string argument: an ISO string for the date, passed to Date; several numerical arguments: the arguments of Date constructor, as would be passed to Date, but year is an algebraic full year, e.g. 1 means year 0001, not year 1901, and negative numbers may be used; first month is always 1, not 0; default day is 1; default time elements are 0; the date elements are those of the target calendar, which may differ from ISO 8601; the date elements passed are considered those of the local date, i.e. of the terminal's time zone.
Version:
  • M2022-08-06
Author:
  • Louis A. de Fouquières https://github.com/Louis-Aime
License:
  • MIT 2016-2022
Source:
See:
Requires:
  • module:chronos.js
  • module:time-units.js

Extends

  • Date.

Requires

  • module:chronos.js
  • module:time-units.js

Methods

(static) fullUTC(fullYearopt, monthopt, dayopt, hoursopt, minutesopt, secondsopt, millisecondsopt) → {number}

Basic utility fonction: get UTC date from ISO 8601 UTC date figures, including full year, i.e. 2-digit year is a year of the first century. Please notice the slight differences with the legacy Date.UTC() function.
Parameters:
Name Type Attributes Default Description
fullYear number <optional>
 0 The year expressed as an algebraic unambiguous number, as specified by ISO 8601.
month number <optional>
 1 The month number, 1 to 12 for Jan. to Dec.
day number <optional>
 1 The day number in the month.
hours number <optional>
 0 The UTC hour
minutes number <optional>
 0 The UTC minutes
seconds number <optional>
 0 The UTC seconds
milliseconds number <optional>
 0 The UTC milliseconds
Source:
Returns:
the Posix timestamp corresponding to the specified UTC date.
Type
number

(static) numericFields() → {Object}

Give the list of numeric fields in a date object, and of their respective default values.
Source:
Returns:
( name_of_field : field default value )
Type
Object

(static) numericWeekFields() → {Object}

Give the list of numeric fields in a week day date object, and of their respective default values.
Source:
Returns:
( name_of_field : field default value )
Type
Object

day(TZopt) → {number}

Get day number in month.
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
day number, first day of month is 1.
Type
number

era(TZopt) → {string}

Get era code, if existing for this calendar.
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
era code.
Type
string

fullYear(TZopt) → {number}

Get year as an unambiguous signed integer.
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
year, unambiguous signed integer.
Type
number

getFields(TZopt) → {Object}

calendar date fields generator method from Date.valueOf(), local or UTC. Month in range 1..12
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
object with date fields { (era if applicable), year, month (range 1..12), day, hours, minutes, seconds, milliseconds}
Type
Object

getISOFields(TZopt) → {Object}

ISO fields at UTC, like for Temporal.PlainDate
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
Date at TZ as Isofield object: isoYear, isoMonth (range 1..12), isoDay, hours, minutes, seconds, milliseconds
Type
Object

getRealTZmsOffset(TZopt) → {number}

Compute the system time zone offset at this date, or the time zone offset of a named time zone in ms. This method is defined because there are discrepancies among navigators for the ***Date.prototype.getTimezoneOffset()*** function, when used for date before 1847 in UK or even later in most other countries. As there were no time zones, the real offset is computed to the second, but the legacy method may round to minutes, depending on the navigator.
Parameters:
Name Type Attributes Description
TZ string <optional>
 the named time zone. If undefined or "", system timezone. "UTC" is always accepted.
Source:
Returns:
the time zone offset in milliseconds: UTC - local (same sign as TimezoneOffset).
Type
number

getWeekFields(TZopt) → {Object}

week fields generator method from Date.valueOf(), local or UTC.
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
object with week fields for the date at TZ, { weekNumber: number (1..53) of the week. weekday : number (1..7, 1 = Monday) of the weekday, weekYearOffset : -1/0/1 shift fullYear by one to obtain the year the week belongs to, weeksInYear: number of weeks in the year the week belons to }
Type
Object

hours(TZopt) → {number}

Get hour in the day, in TZ
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
hour 0 to 23.
Type
number

inLeapYear(TZopt) → {Boolean}

is this date in a leap year of the calendar ?
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
whether the associated date's year is a leap year.
Type
Boolean

milliseconds(TZopt) → {number}

Get milliseconds of the hour in the day, in TZ
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
milliseconds 0 to 999.
Type
number

minutes(TZopt) → {number}

Get minutes of the hour in the day, in TZ
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
minutes 0 to 59.
Type
number

month(TZopt) → {number}

Get month number, the first number is 1.
Parameters:
Name Type Attributes Description
TZ string <optional>
 if "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
month number, number of first month is 1.
Type
number

seconds(TZopt) → {number}

Get seconds of the hour in the day, in TZ
Parameters:
Name Type Attributes Description
TZ string <optional>
 if "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
seconds 0 to 59.
Type
number

setFromFields(fields, TZopt) → {number}

setter method, from fields representing partially a date or time in the target calendar, change date and computie timestamp.
Parameters:
Name Type Attributes Description
fields Object that change from presently held date, i.e. undefined fields are extracted from present date with same TZ (system (blank) or 'UTC')
TZ String <optional>
 if "" or undefined (default value), local date and time. If 'UTC', UTC date and time. No other value possible.
Source:
Returns:
a new timestamp
Type
number

setFromWeekFields(week, TZopt) → {number}

setter method, from the fields representing the date in the target WEEK calendar, comput timestamp
Parameters:
Name Type Attributes Description
week Object fields that change from presently held date, i.e. undefined week fields are extracted from present date with same TZ.
TZ string <optional>
 If "" or undefined (default value), local date and time. If "UTC", UTC date and time. No other value possible.
Source:
Returns:
same as Date.setTime
Type
number

setFullTime(TZopt, hours, minutesopt, secondsopt, millisecondsopt) → {number}

Set time of the day in same day, local or UTC, using legacy setHours or setUTCHours.
Parameters:
Name Type Attributes Default Description
TZ string <optional>
 If "" or undefined (default value), set local time at same local date. If "UTC", set UTC time at same UTC date. No other value possible.
hours number the hours setting
minutes number <optional>
 current value the minutes setting
seconds number <optional>
 current value the seconds setting
milliseconds number <optional>
 current value the milliseconds setting
Source:
Returns:
the Date.valueOf result after operation.
Type
number

toCalString(TZopt) → {string}

extract a simple string with the calendar name, then era code (if applicable), then the figures for year, month, day, and time components.
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
the current date as a string
Type
string

toResolvedLocalDate(TZopt) → {Date}

Construct a date that represents the "best fit" value of the given date shifted as UTC to the named time zone. The computation of the time zone is that of Unicode, or of the standard TZOffset if Unicode's is not available.
Parameters:
Name Type Attributes Description
TZ string <optional>
 the named time zone. If undefined or "", system timezone. "UTC" is always accepted.
Source:
Returns:
the best possible result given by the navigator.
Type
Date

weekday(TZopt) → {number}

Get weekday number, under rules specified in weekRule.
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
weekday number.
Type
number

weekNumber(TZopt) → {number}

Get week number in year, under rules specified in weekRule.
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
week number.
Type
number

weeksInYear(TZopt) → {number}

Get number of weeks in this week calendar year, under rules specified in weekRule.
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
number of weeks.
Type
number

weekYear(TZopt) → {number}

Get year after the week calendar, under rules specified in weekRule.
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
year in the week calendar, unambiguous number (fullyear).
Type
number

year(TZopt) → {number}

Get year; may be ambiguous if era is not known.
Parameters:
Name Type Attributes Description
TZ string <optional>
 Named time zone. If "" or undefined (default value), local date and time. If "UTC", UTC date and time.
Source:
Returns:
year; era may be necessary for disambiguation.
Type
number