diff --git a/concepts/dates/.meta/config.json b/concepts/dates/.meta/config.json index 92048234c1..7f3da2f8e4 100644 --- a/concepts/dates/.meta/config.json +++ b/concepts/dates/.meta/config.json @@ -1,5 +1,5 @@ { "blurb": "JavaScript has a built-in `Date` object which stores date and time and provides methods to work with them.", - "authors": ["JaPatGitHub"], + "authors": ["SleeplessByte"], "contributors": [] } diff --git a/concepts/dates/about.md b/concepts/dates/about.md index b4ccad1414..ed1bba23db 100644 --- a/concepts/dates/about.md +++ b/concepts/dates/about.md @@ -1,248 +1,182 @@ -# About +# Introduction JavaScript has a built-in object `Date` which stores date and time, and provides methods for their management. + +~~~exercism/caution +It was based on Java's `java.util.Date` class, which was replaced in the early 2010s, but for backwards compatibility, JavaScript's `Date` sticks around. + +Because of how hard it is to work with Dates in general and because of how bad or non-existing timezone handling is, many libraries exist such as `moment.js`, `day.js`, `date-fns` and `luxon`. +None of these are available on Exercism. + +In your own projects, do not use a deprecated / unmaintained package such as `moment.js` but rely on more modern alternatives like `luxon`, or the not yet widely available [Temporal][mdn-temporal]. +This exercise focusses on `Date`, which will remain relevant until the end of JavaScript. + +[mdn-temporal]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal +~~~ + ## Creation -A `Date` object in an instance of the `Date` class. It can be created without passing any arguments to the constructor function. This results in a `Date` object that represents the current date and time: +A `Date` object in an instance of the `Date` class. +It can be created without passing any arguments to the constructor function. +This results in a `Date` object that represents the current date and time: ```javascript const now = new Date(); // => Thu Apr 14 2022 11:46:08 GMT+0530 (India Standard Time) - -// Shows current day, date and time in your time zone. +// Shows current day, date and time (in your time zone). ``` -However, different types of arguments can also be used to create date object, as follows: - -### Timestamp value - -> A timestamp is an integer number representing the number of **milliseconds** that has passed since **Jan 1st of 1970 [UTC][utc-defn]+0**, however, _with reference to your local time zone._ -> This can be used as an argument for the Date object. -> -> ```javascript -> const Jan01_1970 = new Date(0); -> // 0 means 01.01.1970 UTC+0 -> -> const Jan02_1970 = new Date(24 * 3600 * 1000); -> // adding 24 hours, we get 02.01.1970 UTC+0 -> -> // Note that the objects created here would show the corresponding time in your time zone. -> ``` -> -> [^1] - - -~~~~exercism/note -> January 1st, 1970 at 00:00:00 UTC is referred to as the Unix epoch. -> Unix is an operating system originally developed in the 1960s. -> Early Unix engineers picked that date arbitrarily because they needed to set a uniform date for the start of time, and > New Year's Day, 1970, seemed most convenient. [^2] -~~~~ - - -### Timestamp string +### Unix timestamp (number) -You can pass a string value representing a date to the `Date` constructor. -The string needs to follow a format that is recognized by the `Date.parse()` method. -You will learn more about this below. - -### Date object - -An existing date object can also be used as an argument. -This makes a copy of the existing `Date` object with the same date and time. +If a number is passed in, this will be interpreted as a `timestamp`. +A timestamp is an integer number representing the number of **milliseconds** that has passed since **1 January 1970 [UTC][defn-utc]+0**. ```javascript -const t1 = new Date(); -const t2 = new Date(t1); +const epoch = new Date(0); +// Thu Jan 01 1970 01:00:00 GMT+0100 (Central European Standard Time) -// Values of t1 and t2 will be the same. +const another = new Date(1749508766627); +// Tue Jun 10 2025 00:39:26 GMT+0200 (Central European Summer Time) ``` -### Individual date and time component values - -> Given at least a year and month, this form of `Date()` returns a `Date` object whose component values _(year, month, day, hour, minute, second, and millisecond)_ all come from the following parameters. -> Any missing fields are given the lowest possible value (1 for day and 0 for every other component). -> The parameter values are all evaluated against the _local time zone, rather than UTC_. -> -> - `year`: Integer values from 0 to 99 map to the years 1900 to 1999. -> All other values are the actual year. -> - `monthIndex`: Integer value representing the month, beginning with _0 for January to 11 for December_. -> If a value greater than 11 is passed in, then those months will be added to the date. -> For example, new Date(1990, 12, 1) will return January 1st, 1991. -> - `day` (Optional): Integer value representing the day of the month. -> The default is 1. -> - `hours` (Optional): Integer value between 0 and 23 representing the hour of the day. -> Defaults to 0. -> - `minutes` (Optional): Integer value representing the minute segment of a time. -> The default is 0 minutes past the hour. -> - `seconds` (Optional): Integer value representing the second segment of a time. -> The default is 0 seconds past the minute. -> - `milliseconds` (Optional): Integer value representing the millisecond segment of a time. -> The default is 0 milliseconds past the second. -> -> [^3] +One may expect `new Date(0)` to generate the "earliest" date object, but JavaScript will convert the date to your local timezone, which means that only those around [GMT / with an UTC+0][defn-gmt] timezone will actually get the [Unix epoch][defn-unix-epoch] value. -```javascript -const date1 = new Date(95, 11, 17); -// Creates Date for Dec 17 1995 00:00 if your local timezone is equivalent to UTC. +### ISO 8601 timestamp (string) -const date2 = new Date(2013, 12, 5, 13, 24, 0); -// Creates Date for Jan 5 2014 13:24 if your local timezone is equivalent to UTC. -``` +You can pass a string value representing a date to the `Date` constructor. +The **only** format that is consistent across implementations is the [simplified version][mdn-date-string-format] of the internationally recognized and standardized so-called [ISO 8601 timestamp strings][defn-iso8601]. -## `Date.parse()` +A moment in time at [UTC][defn-gmt] looks like this: -`Date.parse()` takes **string as a input and returns a timestamp** (number of milliseconds from 1 Jan 1970 UTC+0), provided the string is in the format YYYY-MM-DDTHH:mm:ss.sssZ, where: +```text +YYYY-MM-DDTHH:MM:SSZ +YYYYMMDDTHHMMSSZ +``` -> - `YYYY-MM-DD` - is the date: year-month-day. -> - `T` - The character "T" is used as the delimiter -> - `HH:mm:ss.sss` - is the time: hours, minutes, seconds and milliseconds. -> - `Z` - This _optional_ part denotes the time zone. -> If `Z` is present, the `Date` will be set to UTC. -> If `Z` is not present, it will be Local Time. -> -> If the format is invalid, `NaN` is returned. [^4] +Where the following substitutions take place: -Shorter variants are also possible, like `YYYY-MM-DD` or `YYYY-MM` or even `YYYY`. However, note that these variants **set the `Date` to UTC**, even though `Z` not mentioned. -To understand what exactly happens check out [this section][mdn-diff-assumed-timezone] of a MDN page. +| Key | Description | +| ---- | ------------------------------------------- | +| YYYY | The calendar year, represented in 4 digits | +| MM | The calendar month, represented in 2 digits | +| DD | The calendar day, represented in 2 digits | +| HH | The hours in a 24-hour clock, 2 digits | +| MM | The minutes, 2 digits | +| SS | The seconds, 2 digits | -```javascript -const d1 = Date.parse('2019-01-01'); -const d2 = Date.parse('2019-01-01T00:00:00.000Z'); +The letter `T` separates the date from the time. +The letter `Z` indicates UTC (no timezone, no Day Light Savings). -// Both d1 and d2 are of value 1546300800000, as times are set to UTC. + +~~~exercism/caution +Other formats that are accepted by `Date.parse` may or may not work. +When working with Dates in JavaScript, _always_ use an ISO 8601 timestamp when converting from a `string` to a `Date`. -const d3 = Date.parse('2019-01-01T00:00:00.000'); -// This would have a different value (unless you live in GMT) as -// it is set to your local time zone. -``` +Date-only forms are allowed, but not all ISO 8601 formats are supported. +Consult the [simplified version explanation page on MDN][mdn-date-string-format]. - -~~~~exercism/caution -The use of `Date.parse()` (and the timestamp string method which works similarly) is strongly discouraged due to browser differences and inconsistencies. [^5] -~~~~ - +[mdn-date-string-format]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format +~~~ -## Accessing `Date` components +If the timestamp does not end in `Z`, and it does not end with `+HH:MM` or `-HH:MM`, indicating a timezone offset, because of historical reasons, the following applies: -The following are the methods to access the year, month and so on from the Date object: +> When the time zone offset is absent, date-only forms are interpreted as a UTC time and date-time forms are interpreted as a local time. +> The interpretation as a UTC time is due to a historical spec error that was not consistent with ISO 8601 but could not be changed due to web compatibility. +> See [Broken Parser – A Web Reality Issue][ref-broken-parser]. -> - `getFullYear()`- Get the year (4 digits) -> - `getMonth()`- Get the month, from 0 to 11. -> - `getDate()`- Get the day of month, from 1 to 31. -> - `getHours()`, `getMinutes()`, `getSeconds()`, `getMilliseconds()`- Get the corresponding time components. -> - `getDay()`- Get the day of week, from 0 (Sunday) to 6 (Saturday). -> - `getTime()`- Get the number of milliseconds passed since 01.01.1970 UTC. -> -> [^6] - -```javascript -const date0 = new Date(0); //Jan 1 1970 00:00:00 -let month = date0.getMonth()); // => 0; as Jan is the month -let date = date0.getDay(); // Find out which day the new year of 1970 was! - -const date1 = new Date(2020, 11, 13, 5); // Dec 13 2020 5:00:00 -let millsecs = date1.getTime(); // find out how many have milliseconds passed since Jan 1 1890! -``` +### Date object - -~~~~exercism/caution -Many JavaScript engines implement a non-standard method `getYear()`. -**This method is deprecated.** -It returns a 2-digit year sometimes. -Hence, `getFullYear()` must always be used instead. -~~~~ - - -## Modifying `Date` components - -The following methods allow to modify date/time components : - -> - `setFullYear(year, [month], [date])` -> - `setMonth(month, [date])` -> - `setDate(date)` -> - `setHours(hour, [min], [sec], [ms])` -> - `setMinutes(min, [sec], [ms])` -> - `setSeconds(sec, [ms])` -> - `setMilliseconds(ms)` -> - `setTime(timestamp)` (sets the whole date by milliseconds since 01.01.1970 UTC) -> -> Parameters in `[]` above are _optional_. -> If not mentioned, the components are not modified. -> Every one of them except `setTime()` has a UTC-variant, for instance: `setUTCHours()`. [^7] +An existing date object can also be used as a constructor argument. +This makes a copy of the existing `Date` object with the same date and time. ```javascript -let today = new Date(); - -today.setHours(0); // still today, but only the hour is changed to 0 - -today.setHours(0, 0, 0, 0); // still today, now sharply 00:00:00 +const t1 = new Date(); +const t2 = new Date(t1); +// Values of t1 and t2 will be the same. ``` -## Calculating Time Difference and `Date.now()` +### Supplying individual date and time component values -To measure the time elapsed between two given dates, we can use the `Date.getTime()` method. +A date representing a date can be created by passing three numbers. +A date representing a date and time can be created by passing in 6 numbers. ```javascript -const d1 = new Date(2021, 12, 11, 5, 13, 32, 21); -const d2 = new Date(2021, 12, 23, 4, 12, 55); +const date1 = new Date(95, 11, 17); +// Creates Date for Dec 17 1995 00:00 if your local timezone is equivalent to UTC. -let timeElapsed = d2.getTime() - d1.getTime(); // => 1033162979 +const date2 = new Date(2013, 12, 5, 13, 24, 0); +// Creates Date for Jan 5 2014 13:24 if your local timezone is equivalent to UTC. ``` -Moreover, if we wish to measure the time taken on a live basis, for example the time taken for execution for program, we could use `Date.now()` which provides the timestamp of current time. +The second value is the `month`, which starts at `0` for January, up to `11` for December. -> As you might notice, this is semantically equivalent to `new Date().getTime()`, but it doesn’t create an intermediate `Date` object. -> Hence, it makes the code more efficient. [^8] +## `Date.parse()` -```javascript -const start = Date.now(); // milliseconds count from 1 Jan 1970 +You may find mentions of or references to a date parsing function `Date.parse`. +Because there are only a few invariants (truths) for this function and because the rest of the implementation is not specified (and thus not standard), one should not use it. -// execute a task -for (let i = 0; i < 100000; i++) { - let task = i * i * i * i; -} +## Accessing `Date` components -const end = Date.now(); // done +There are various methods on date objects that return the components of the date: -let duration = end - start; -// how long it took to run the loop, in seconds +```javascript +getFullYear(); // Get the year (4 digits) +getMonth(); // Get the month, from 0 to 11. +getDate(); // Get the day of month, from 1 to 31. +getHours(); // Get the hour in a 24 clock, from 0 to 23 +getMinutes(); // Get the minutes, from 0 to 59 +getSeconds(); // Get the seconds, from 0 to 59 +getMilliseconds(); // Get the milliseconds, from 0 and 999 +getDay(); // Get the day of week, from 0 (Sunday) to 6 (Saturday). ``` -## Comparing Dates - -We can use `<` and `>` operators to compare two `Date` objects, the date occuring _later being treated as greater_. - -The `==` or `===` do not work with `Date`, and output `false` in any case, even if dates are equal. -However, we could use the `Date.getTime()` method to obtain the timestamps (which is of the data type `number`) and compare them using equality operators. +Each of these has an applicable `set` variant (e.g. `setFullYear`) to update the value. +Any overflowing value rolls over to the next component: ```javascript -const d1 = new Date(2021, 12, 11); -const d2 = new Date(1990, 11, 23); +const date = new Date('2025-02-28T12:42:00Z'); +// => Fri Feb 28 2025 13:42:00 GMT+0100 (Central European Standard Time) -d1 > d2; // true +date.setDate(29); +// there was no February 29th in 2025. -const d1Copy = new Date(d1); // d1Copy will be same as d1 +date.getDate(); +// => 1 -d1Copy === d1; // false, even though they are same -d1Copy.getTime() === d1.getTime(); //true +date.toString(); +// => Sat Mar 01 2025 13:42:00 GMT+0100 (Central European Standard Time) ``` -[^1]: https://javascript.info/date +There are UTC variants for all the methods that disregard the local timezone. + +## Converting from date -[^2]: https://kb.narrative.io/what-is-unix-time +Date objects have a method `getTime()` that returns the UNIX timestamp in milliseconds, ie. amount of milliseconds the midnight at the beginning of January 1, 1970, UTC. +Additionally, a method `toISOString()` is available to convert from a date object to a ISO 8601 timestamp string. -[^3]: https://javascript.info/date#setting-date-components +## Comparing Dates -[^4]: https://javascript.info/date#date-parse-from-a-string +Greater than (`>`) and greater than or equals (`>=`) as well as less than (`<`) and less than or equals (`<=`) can be used directly between two dates or a date and a number. +This works because JavaScript will try to coerce the date to a primitive. -[^5]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#several_ways_to_create_a_date_object + +~~~exercism/advanced +When doing a comparison between two dates or date and a number, JavaScript calls [`[Symbol.toPrimitive]("number")`][mdn-to-primitive] which internally calls [`date.valueOf()`][mdn-date-value-of]. +The latter is the same as calling [`date.getTime()`][mdn-date-get-time]. -[^6]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#several_ways_to_create_a_date_object +If you do not want to rely on this behaviour, convert to a number using `getTime()` first. -[^7]: https://javascript.info/date#access-date-components +[mdn-to-primitive]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Symbol.toPrimitive +[mdn-date-value-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/valueOf +[mdn-date-get-time]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTime +~~~ -[^8]: https://javascript.info/date#date-now +Dates cannot be compared using equality (`==`, and `===`), but the result of `.getTime()` can. -[utc-defn]: https://simple.wikipedia.org/wiki/Coordinated_Universal_Time -[mdn-diff-assumed-timezone]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#differences_in_assumed_time_zone +[defn-utc]: https://simple.wikipedia.org/wiki/Coordinated_Universal_Time +[defn-gmt]: https://simple.wikipedia.org/wiki/Greenwich_Mean_Time +[defn-unix-epoch]: https://en.wikipedia.org/wiki/Epoch_%28computing%29 +[defn-iso8601]: https://en.wikipedia.org/wiki/ISO_8601 +[mdn-date-string-format]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format +[ref-broken-parser]: https://maggiepint.com/2017/04/11/fixing-javascript-date-web-compatibility-and-reality/ diff --git a/concepts/dates/introduction.md b/concepts/dates/introduction.md index ffe062e6c3..ed1bba23db 100644 --- a/concepts/dates/introduction.md +++ b/concepts/dates/introduction.md @@ -2,77 +2,104 @@ JavaScript has a built-in object `Date` which stores date and time, and provides methods for their management. + +~~~exercism/caution +It was based on Java's `java.util.Date` class, which was replaced in the early 2010s, but for backwards compatibility, JavaScript's `Date` sticks around. + +Because of how hard it is to work with Dates in general and because of how bad or non-existing timezone handling is, many libraries exist such as `moment.js`, `day.js`, `date-fns` and `luxon`. +None of these are available on Exercism. + +In your own projects, do not use a deprecated / unmaintained package such as `moment.js` but rely on more modern alternatives like `luxon`, or the not yet widely available [Temporal][mdn-temporal]. +This exercise focusses on `Date`, which will remain relevant until the end of JavaScript. + +[mdn-temporal]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal +~~~ + ## Creation -A `Date` object in an instance of the `Date` class. It can be created without passing any arguments to the constructor function. This results in a `Date` object that represents the current date and time: +A `Date` object in an instance of the `Date` class. +It can be created without passing any arguments to the constructor function. +This results in a `Date` object that represents the current date and time: ```javascript const now = new Date(); // => Thu Apr 14 2022 11:46:08 GMT+0530 (India Standard Time) - -// Shows current day, date and time in your time zone. +// Shows current day, date and time (in your time zone). ``` -However, different types of arguments can also be used to create date object, as follows: +### Unix timestamp (number) -### Timestamp value +If a number is passed in, this will be interpreted as a `timestamp`. +A timestamp is an integer number representing the number of **milliseconds** that has passed since **1 January 1970 [UTC][defn-utc]+0**. -> A timestamp is an integer number representing the number of **milliseconds** that has passed since **Jan 1st of 1970 [UTC][utc-defn]+0**, however, _with reference to your local time zone._ -> This can be used as an argument for the Date object. -> -> ```javascript -> const Jan01_1970 = new Date(0); -> // 0 means 01.01.1970 UTC+0 -> -> const Jan02_1970 = new Date(24 * 3600 * 1000); -> // adding 24 hours, we get 02.01.1970 UTC+0 -> -> // Note that the objects created here would show the corresponding time in your time zone. -> ``` -> -> [^1] +```javascript +const epoch = new Date(0); +// Thu Jan 01 1970 01:00:00 GMT+0100 (Central European Standard Time) -### Timestamp string +const another = new Date(1749508766627); +// Tue Jun 10 2025 00:39:26 GMT+0200 (Central European Summer Time) +``` + +One may expect `new Date(0)` to generate the "earliest" date object, but JavaScript will convert the date to your local timezone, which means that only those around [GMT / with an UTC+0][defn-gmt] timezone will actually get the [Unix epoch][defn-unix-epoch] value. + +### ISO 8601 timestamp (string) You can pass a string value representing a date to the `Date` constructor. -The string needs to follow a format that is recognized by the `Date.parse()` method. -You will learn more about this below. +The **only** format that is consistent across implementations is the [simplified version][mdn-date-string-format] of the internationally recognized and standardized so-called [ISO 8601 timestamp strings][defn-iso8601]. + +A moment in time at [UTC][defn-gmt] looks like this: + +```text +YYYY-MM-DDTHH:MM:SSZ +YYYYMMDDTHHMMSSZ +``` + +Where the following substitutions take place: + +| Key | Description | +| ---- | ------------------------------------------- | +| YYYY | The calendar year, represented in 4 digits | +| MM | The calendar month, represented in 2 digits | +| DD | The calendar day, represented in 2 digits | +| HH | The hours in a 24-hour clock, 2 digits | +| MM | The minutes, 2 digits | +| SS | The seconds, 2 digits | + +The letter `T` separates the date from the time. +The letter `Z` indicates UTC (no timezone, no Day Light Savings). + + +~~~exercism/caution +Other formats that are accepted by `Date.parse` may or may not work. +When working with Dates in JavaScript, _always_ use an ISO 8601 timestamp when converting from a `string` to a `Date`. + +Date-only forms are allowed, but not all ISO 8601 formats are supported. +Consult the [simplified version explanation page on MDN][mdn-date-string-format]. + +[mdn-date-string-format]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format +~~~ + +If the timestamp does not end in `Z`, and it does not end with `+HH:MM` or `-HH:MM`, indicating a timezone offset, because of historical reasons, the following applies: + +> When the time zone offset is absent, date-only forms are interpreted as a UTC time and date-time forms are interpreted as a local time. +> The interpretation as a UTC time is due to a historical spec error that was not consistent with ISO 8601 but could not be changed due to web compatibility. +> See [Broken Parser – A Web Reality Issue][ref-broken-parser]. ### Date object -An existing date object can also be used as an argument. +An existing date object can also be used as a constructor argument. This makes a copy of the existing `Date` object with the same date and time. ```javascript const t1 = new Date(); const t2 = new Date(t1); - // Values of t1 and t2 will be the same. ``` -### Individual date and time component values - -> Given at least a year and month, this form of `Date()` returns a `Date` object whose component values _(year, month, day, hour, minute, second, and millisecond)_ all come from the following parameters. -> Any missing fields are given the lowest possible value (1 for day and 0 for every other component). -> The parameter values are all evaluated against the _local time zone, rather than UTC_. -> -> - `year`: Integer values from 0 to 99 map to the years 1900 to 1999. -> All other values are the actual year. -> - `monthIndex`: Integer value representing the month, beginning with _0 for January to 11 for December_. -> If a value greater than 11 is passed in, then those months will be added to the date. -> For example, new Date(1990, 12, 1) will return January 1st, 1991. -> - `day` (Optional): Integer value representing the day of the month. -> The default is 1. -> - `hours` (Optional): Integer value between 0 and 23 representing the hour of the day. -> Defaults to 0. -> - `minutes` (Optional): Integer value representing the minute segment of a time. -> The default is 0 minutes past the hour. -> - `seconds` (Optional): Integer value representing the second segment of a time. -> The default is 0 seconds past the minute. -> - `milliseconds` (Optional): Integer value representing the millisecond segment of a time. -> The default is 0 milliseconds past the second. -> -> [^2] +### Supplying individual date and time component values + +A date representing a date can be created by passing three numbers. +A date representing a date and time can be created by passing in 6 numbers. ```javascript const date1 = new Date(95, 11, 17); @@ -82,118 +109,74 @@ const date2 = new Date(2013, 12, 5, 13, 24, 0); // Creates Date for Jan 5 2014 13:24 if your local timezone is equivalent to UTC. ``` -## `Date.parse()` - -`Date.parse()` takes **string as a input and returns a timestamp** (number of milliseconds from 1 Jan 1970 UTC+0), provided the string is in the format YYYY-MM-DDTHH:mm:ss.sssZ, where: - -> - `YYYY-MM-DD` - is the date: year-month-day. -> - `T` - The character "T" is used as the delimiter -> - `HH:mm:ss.sss` - is the time: hours, minutes, seconds and milliseconds. -> - `Z` - This _optional_ part denotes the time zone. -> If `Z` is present, the `Date` will be set to UTC. -> If `Z` is not present, it will be Local Time. -> -> If the format is invalid, `NaN` is returned. [^3] +The second value is the `month`, which starts at `0` for January, up to `11` for December. -Shorter variants are also possible, like `YYYY-MM-DD` or `YYYY-MM` or even `YYYY`. However, note that these variants **set the `Date` to UTC**, even though `Z` not mentioned. -To understand what exactly happens check out [this section][mdn-diff-assumed-timezone] of a MDN page. +## `Date.parse()` - -~~~~exercism/caution -The use of `Date.parse()` (and the timestamp string method which works similarly) is strongly discouraged due to browser differences and inconsistencies. [^4] -~~~~ - +You may find mentions of or references to a date parsing function `Date.parse`. +Because there are only a few invariants (truths) for this function and because the rest of the implementation is not specified (and thus not standard), one should not use it. ## Accessing `Date` components -The following are the methods to access the year, month and so on from the Date object: - -> - `getFullYear()`- Get the year (4 digits) -> - `getMonth()`- Get the month, from 0 to 11. -> - `getDate()`- Get the day of month, from 1 to 31. -> - `getHours()`, `getMinutes()`, `getSeconds()`, `getMilliseconds()`- Get the corresponding time components. -> - `getDay()`- Get the day of week, from 0 (Sunday) to 6 (Saturday). -> - `getTime()`- Get the number of milliseconds passed since 01.01.1970 UTC. -> -> [^5] +There are various methods on date objects that return the components of the date: ```javascript -const date0 = new Date(0); //Jan 1 1970 00:00:00 -let month = date0.getMonth()); // => 0; as Jan is the month -let date = date0.getDay(); // Find out which day the new year of 1970 was! - -const date1 = new Date(2020, 11, 13, 5); // Dec 13 2020 5:00:00 -let millsecs = date1.getTime(); // find out how many have milliseconds passed since Jan 1 1890! +getFullYear(); // Get the year (4 digits) +getMonth(); // Get the month, from 0 to 11. +getDate(); // Get the day of month, from 1 to 31. +getHours(); // Get the hour in a 24 clock, from 0 to 23 +getMinutes(); // Get the minutes, from 0 to 59 +getSeconds(); // Get the seconds, from 0 to 59 +getMilliseconds(); // Get the milliseconds, from 0 and 999 +getDay(); // Get the day of week, from 0 (Sunday) to 6 (Saturday). ``` -## Modifying `Date` components - -The following methods allow to modify date/time components : - -> - `setFullYear(year, [month], [date])` -> - `setMonth(month, [date])` -> - `setDate(date)` -> - `setHours(hour, [min], [sec], [ms])` -> - `setMinutes(min, [sec], [ms])` -> - `setSeconds(sec, [ms])` -> - `setMilliseconds(ms)` -> - `setTime(timestamp)` (sets the whole date by milliseconds since 01.01.1970 UTC) -> -> Parameters in `[]` above are _optional_. -> If not mentioned, the components are not modified. -> Every one of them except `setTime()` has a UTC-variant, for instance: `setUTCHours()`. [^6] +Each of these has an applicable `set` variant (e.g. `setFullYear`) to update the value. +Any overflowing value rolls over to the next component: ```javascript -let today = new Date(); - -today.setHours(0); // still today, but only the hour is changed to 0 - -today.setHours(0, 0, 0, 0); // still today, now sharply 00:00:00 -``` +const date = new Date('2025-02-28T12:42:00Z'); +// => Fri Feb 28 2025 13:42:00 GMT+0100 (Central European Standard Time) -## Calculating Time Difference and `Date.now()` +date.setDate(29); +// there was no February 29th in 2025. -To measure the time elapsed between two given dates, we can use the `Date.getTime()` method. +date.getDate(); +// => 1 -```javascript -const d1 = new Date(2021, 12, 11, 5, 13, 32, 21); -const d2 = new Date(2021, 12, 23, 4, 12, 55); - -let timeElapsed = d2.getTime() - d1.getTime(); // => 1033162979 +date.toString(); +// => Sat Mar 01 2025 13:42:00 GMT+0100 (Central European Standard Time) ``` -Moreover, if we wish to measure the time taken on a live basis, for example the time taken for execution for program, we could use `Date.now()` which provides the timestamp of current time. - -## Comparing Dates - -We can use `<` and `>` operators to compare two `Date` objects, the date occuring _later being treated as greater_. +There are UTC variants for all the methods that disregard the local timezone. -The `==` or `===` do not work with `Date`, and output `false` in any case, even if dates are equal. -However, we could use the `Date.getTime()` method to obtain the timestamps (which is of the data type `number`) and compare them using equality operators. +## Converting from date -```javascript -const d1 = new Date(2021, 12, 11); -const d2 = new Date(1990, 11, 23); +Date objects have a method `getTime()` that returns the UNIX timestamp in milliseconds, ie. amount of milliseconds the midnight at the beginning of January 1, 1970, UTC. +Additionally, a method `toISOString()` is available to convert from a date object to a ISO 8601 timestamp string. -d1 > d2; // true - -const d1Copy = new Date(d1); // d1Copy will be same as d1 - -d1Copy === d1; // false, even though they are same -d1Copy.getTime() === d1.getTime(); //true -``` - -[^1]: https://javascript.info/date +## Comparing Dates -[^2]: https://javascript.info/date#setting-date-components +Greater than (`>`) and greater than or equals (`>=`) as well as less than (`<`) and less than or equals (`<=`) can be used directly between two dates or a date and a number. +This works because JavaScript will try to coerce the date to a primitive. -[^3]: https://javascript.info/date#date-parse-from-a-string + +~~~exercism/advanced +When doing a comparison between two dates or date and a number, JavaScript calls [`[Symbol.toPrimitive]("number")`][mdn-to-primitive] which internally calls [`date.valueOf()`][mdn-date-value-of]. +The latter is the same as calling [`date.getTime()`][mdn-date-get-time]. -[^4]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#several_ways_to_create_a_date_object +If you do not want to rely on this behaviour, convert to a number using `getTime()` first. -[^5]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#several_ways_to_create_a_date_object +[mdn-to-primitive]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Symbol.toPrimitive +[mdn-date-value-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/valueOf +[mdn-date-get-time]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTime +~~~ -[^6]: https://javascript.info/date#access-date-components +Dates cannot be compared using equality (`==`, and `===`), but the result of `.getTime()` can. -[utc-defn]: https://simple.wikipedia.org/wiki/Coordinated_Universal_Time -[mdn-diff-assumed-timezone]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#differences_in_assumed_time_zone +[defn-utc]: https://simple.wikipedia.org/wiki/Coordinated_Universal_Time +[defn-gmt]: https://simple.wikipedia.org/wiki/Greenwich_Mean_Time +[defn-unix-epoch]: https://en.wikipedia.org/wiki/Epoch_%28computing%29 +[defn-iso8601]: https://en.wikipedia.org/wiki/ISO_8601 +[mdn-date-string-format]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format +[ref-broken-parser]: https://maggiepint.com/2017/04/11/fixing-javascript-date-web-compatibility-and-reality/ diff --git a/concepts/dates/links.json b/concepts/dates/links.json index 6b22e9127f..115304b685 100644 --- a/concepts/dates/links.json +++ b/concepts/dates/links.json @@ -4,11 +4,23 @@ "description": "javascript.info: Date" }, { - "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date", - "description": "MDN: Date() Constructor" + "url": "https://en.wikipedia.org/wiki/Epoch_%28computing%29", + "description": "Wikipedia: epoch (computing)" }, { - "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse", - "description": "MDN: Date.parse()" + "url": "https://en.wikipedia.org/wiki/ISO_8601", + "description": "Wikipedia: ISO 8601 format" + }, + { + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date", + "description": "MDN: Date" + }, + { + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format", + "description": "MDN: Date time string format" + }, + { + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal", + "description": "MDN: Temporal" } ] diff --git a/config.json b/config.json index ec946420c3..e6ec3b62a1 100644 --- a/config.json +++ b/config.json @@ -2682,11 +2682,6 @@ "slug": "arithmetic-operators", "name": "Arithmetic Operators" }, - { - "uuid": "e1b15569-387c-4833-8c3b-9a94e0ee1583", - "slug": "array-analysis", - "name": "Array Analysis" - }, { "uuid": "9f8f96bb-db13-485a-bfe4-6ae3fe2fbf46", "slug": "array-destructuring", @@ -2707,11 +2702,6 @@ "slug": "arrays", "name": "Arrays" }, - { - "uuid": "e7eea65d-5a13-44ee-aae6-113cfb234457", - "slug": "arrow-functions", - "name": "Arrow Functions" - }, { "uuid": "611d6b3d-1241-4432-90f6-8fcffb36917c", "slug": "basics", @@ -2802,6 +2792,21 @@ "slug": "classes", "name": "Prototypes & Classes" }, + { + "uuid": "efc895b2-8420-44f1-a385-5c637286f797", + "slug": "rest-and-spread", + "name": "Rest and Spread" + }, + { + "uuid": "e7eea65d-5a13-44ee-aae6-113cfb234457", + "slug": "arrow-functions", + "name": "Arrow Functions" + }, + { + "uuid": "e1b15569-387c-4833-8c3b-9a94e0ee1583", + "slug": "array-analysis", + "name": "Array Analysis" + }, { "uuid": "cfbc96fa-717e-4f29-a91d-760ebea88822", "slug": "recursion", @@ -2812,11 +2817,6 @@ "slug": "regular-expressions", "name": "Regular Expressions" }, - { - "uuid": "efc895b2-8420-44f1-a385-5c637286f797", - "slug": "rest-and-spread", - "name": "Rest and Spread" - }, { "uuid": "84e55c29-d403-4a90-8a2a-9960feae8ff3", "slug": "sets", diff --git a/exercises/concept/appointment-time/.docs/introduction.md b/exercises/concept/appointment-time/.docs/introduction.md index 2109d68510..ca8b452210 100644 --- a/exercises/concept/appointment-time/.docs/introduction.md +++ b/exercises/concept/appointment-time/.docs/introduction.md @@ -11,6 +11,8 @@ None of these are available on Exercism. In your own projects, do not use a deprecated / unmaintained package such as `moment.js` but rely on more modern alternatives like `luxon`, or the not yet widely available [Temporal][mdn-temporal]. This exercise focusses on `Date`, which will remain relevant until the end of JavaScript. + +[mdn-temporal]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal ~~~ ## Creation @@ -25,7 +27,7 @@ const now = new Date(); // Shows current day, date and time (in your time zone). ``` -### Unix timestamp (number) +### **Unix timestamp (number)** If a number is passed in, this will be interpreted as a `timestamp`. A timestamp is an integer number representing the number of **milliseconds** that has passed since **1 January 1970 [UTC][defn-utc]+0**. @@ -40,7 +42,7 @@ const another = new Date(1749508766627); One may expect `new Date(0)` to generate the "earliest" date object, but JavaScript will convert the date to your local timezone, which means that only those around [GMT / with an UTC+0][defn-gmt] timezone will actually get the [Unix epoch][defn-unix-epoch] value. -### ISO 8601 timestamp (string) +### **ISO 8601 timestamp (string)** You can pass a string value representing a date to the `Date` constructor. The **only** format that is consistent across implementations is the [simplified version][mdn-date-string-format] of the internationally recognized and standardized so-called [ISO 8601 timestamp strings][defn-iso8601]. @@ -73,6 +75,8 @@ When working with Dates in JavaScript, _always_ use an ISO 8601 timestamp when c Date-only forms are allowed, but not all ISO 8601 formats are supported. Consult the [simplified version explanation page on MDN][mdn-date-string-format]. + +[mdn-date-string-format]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format ~~~ If the timestamp does not end in `Z`, and it does not end with `+HH:MM` or `-HH:MM`, indicating a timezone offset, because of historical reasons, the following applies: @@ -81,7 +85,7 @@ If the timestamp does not end in `Z`, and it does not end with `+HH:MM` or `-HH: > The interpretation as a UTC time is due to a historical spec error that was not consistent with ISO 8601 but could not be changed due to web compatibility. > See [Broken Parser – A Web Reality Issue][ref-broken-parser]. -### Date object +### **Date object** An existing date object can also be used as a constructor argument. This makes a copy of the existing `Date` object with the same date and time. @@ -92,7 +96,7 @@ const t2 = new Date(t1); // Values of t1 and t2 will be the same. ``` -### Supplying individual date and time component values +### **Supplying individual date and time component values** A date representing a date can be created by passing three numbers. A date representing a date and time can be created by passing in 6 numbers. @@ -157,11 +161,15 @@ Greater than (`>`) and greater than or equals (`>=`) as well as less than (`<`) This works because JavaScript will try to coerce the date to a primitive. -~~~@exercism/advanced +~~~exercism/advanced When doing a comparison between two dates or date and a number, JavaScript calls [`[Symbol.toPrimitive]("number")`][mdn-to-primitive] which internally calls [`date.valueOf()`][mdn-date-value-of]. The latter is the same as calling [`date.getTime()`][mdn-date-get-time]. If you do not want to rely on this behaviour, convert to a number using `getTime()` first. + +[mdn-to-primitive]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Symbol.toPrimitive +[mdn-date-value-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/valueOf +[mdn-date-get-time]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTime ~~~ Dates cannot be compared using equality (`==`, and `===`), but the result of `.getTime()` can. @@ -170,10 +178,5 @@ Dates cannot be compared using equality (`==`, and `===`), but the result of `.g [defn-gmt]: https://simple.wikipedia.org/wiki/Greenwich_Mean_Time [defn-unix-epoch]: https://en.wikipedia.org/wiki/Epoch_%28computing%29 [defn-iso8601]: https://en.wikipedia.org/wiki/ISO_8601 -[mdn-temporal]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal -[mdn-diff-assumed-timezone]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#differences_in_assumed_time_zone [mdn-date-string-format]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format -[mdn-to-primitive]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Symbol.toPrimitive -[mdn-date-value-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/valueOf -[mdn-date-get-time]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTime [ref-broken-parser]: https://maggiepint.com/2017/04/11/fixing-javascript-date-web-compatibility-and-reality/ diff --git a/exercises/concept/appointment-time/appointment-time.js b/exercises/concept/appointment-time/appointment-time.js index 9b0b28ce0a..01af573b48 100644 --- a/exercises/concept/appointment-time/appointment-time.js +++ b/exercises/concept/appointment-time/appointment-time.js @@ -8,7 +8,7 @@ * * @returns {Date} the appointment */ -export function createAppointment(days, now = Date.now()) { +export function createAppointment(days, now = undefined) { throw new Error('Remove this line and implement the function'); }