JavaScript/Dates
In JavaScript, a Date is an object. Hence it must be explicitly created with the new operator.
Date contains a value that represents the number of milliseconds that have elapsed since January 1, 1970 UTC. It's worth mentioning what it does not contain: There is no information about a timezone within the object. Nevertheless, you can convert it to an appropriate string of any arbitrary time zone. Other methods can select parts like the month or the day of the week, or you can use the number for any computation, and more.
Constructor
[edit | edit source]The default constructor creates the Date object as of the current point in time of your computer.
const currentMilliSeconds = new Date(); // creates a new Date object as of 'now'
alert(currentMilliSeconds); // implicit conversion to string
alert(currentMilliSeconds.toString()); // explicit conversion to string
alert(currentMilliSeconds.valueOf()); // the real value
You can pass parameters to the constructor to generate a certain Date object.
// 1000 ms = 1 second after the beginning of JavaScript time
const pointInTime_1 = new Date(1000);
alert(pointInTime_1);
// begin of last minute in last century
const pointInTime_2 = new Date(1999, 11, 31, 23, 59);
alert(pointInTime_2);
Methods
[edit | edit source]Some often used methods of Date are:
Static methods
- Date.now(): Returns the number of milliseconds since January 1, 1970, 00:00:00 UTC calibrated (plus/minus some hours) to the timezone of your computer.
- Date.UTC(<parameters>): Returns the number of milliseconds since January 1, 1970, 00:00:00 UTC.
- Date.parse(text): Parsing of strings with Date.parse() is strongly discouraged due to browser differences and inconsistencies.
Instance methods
- toISOString(): Returns a string in ISO 8601 format.
- getFullYear(): Returns the full 4-digit year.
- getMonth(): Returns the current month. [0 - 11]
- getDate(): Returns the day of the month. [1 - 31]
- getDay(): Returns the day of the week. [0 - 6]. Sunday is 0, with the other days of the week taking the next value.
- getHours(): Returns hours [0 - 23] based on a 24-hour clock.
- getMinutes(): Returns minutes. [0 - 59]
- getSeconds(): Returns seconds. [0 - 59]
- getTime(): Returns the time in milliseconds since January 1, 1970.
- valueOf(): Returns the time in milliseconds since January 1, 1970. Equivalent to getTime().
- getTimezoneOffset(): Returns the difference in minutes between UTC and local time.
- setFullYear(year): Stores the full 4-digit year within the Date object.
- setMonth(month, day): Sets the month, and optionally the day within the month. '0' is January, ...
'As Integer'
[edit | edit source]The Date can be returned as an integer by the method valueOf() or by prefixing the constructor with a + sign, e.g., to use it for "seeding" a PRNG (Pseudo Random Number Generator) or to perform calculations.
const dateAsInteger_1 = new Date().valueOf();
alert(dateAsInteger_1);
const dateAsInteger_2 = +new Date();
alert(dateAsInteger_2);
Timezones
[edit | edit source]The Date object purely contains a whole number (Integer). It does not know anything about timezones. As long as you don't specify timezones in any form, you work in your local timezone.
But sometimes it's necessary to consider timezones.
// Example 1
// Create it in UTC: 27th of January, midnight
const date_1 = new Date(Date.UTC(2020, 00, 27, 0, 0, 0));
alert(date_1);
// show it in another timezone (Jakarta is +7) ...
const jakartaTime = new Intl.DateTimeFormat('en-GB', { timeZone: 'Asia/Jakarta', dateStyle: 'full', timeStyle: 'long' }).format(date_1);
alert(jakartaTime);
// ... the original value has not changed
alert(date_1);
// Example 2
// assume we are in New York timezone (-5 against UTC)
const date_2 = new Date();
console.log(date_2.toString());
// show it in another timezone (Los Angeles is -8 against UTC)
const laTime = new Intl.DateTimeFormat('en-GB', { timeZone: 'America/Los_Angeles', dateStyle: 'full', timeStyle: 'long' }).format(date_2);
console.log(laTime);
// ... the internal value has not changed
console.log(date_2.toString());
New API: Temporal
[edit | edit source]The object Date has some inconsistencies and shortcomings, especially: weak timezone support, no support for non-Gregorian calendars, missing calendar functions, and more. Possibly they will be fixed in a new Temporal API in one of the subsequent JavaScript versions.