diff --git a/docs/README.md b/docs/README.md index b38b6ea46b..b375605638 100644 --- a/docs/README.md +++ b/docs/README.md @@ -92,7 +92,7 @@ const zonedDateTime = Temporal.ZonedDateTime.from({ millisecond: 0, microsecond: 3, nanosecond: 500 -}); // => 1995-12-07T03:24:30.000003500+08:00[America/Los_Angeles] +}); // => '1995-12-07T03:24:30.0000035-08:00[America/Los_Angeles]' ``` As the broadest `Temporal` type, `Temporal.ZonedDateTime` can be considered a combination of `Temporal.TimeZone`, `Temporal.Instant`, and `Temporal.PlainDateTime` (which includes `Temporal.Calendar`). @@ -104,8 +104,8 @@ See [Temporal.ZonedDateTime Documentation](./zoneddatetime.md) for detailed docu A `Temporal.PlainDate` object represents a calendar date that is not associated with a particular time or time zone, e.g. August 24th, 2006. ```js -const date = Temporal.PlainDate.from({year: 2006, month: 8, day: 24}); // => 2006-08-24 -date.year // => 2006 +const date = Temporal.PlainDate.from({year: 2006, month: 8, day: 24}); // => '2006-08-24' +date.year // => '2006' date.inLeapYear // => false date.toString() // => "2006-08-24" ``` @@ -126,7 +126,7 @@ const time = Temporal.PlainTime.from({ millisecond: 68, microsecond: 346, nanosecond: 205 -}); // => 19:39:09.068346205 +}); // => '19:39:09.068346205' time.second // => 9 time.toString() // => "19:39:09.068346205" @@ -147,11 +147,11 @@ const dateTime = Temporal.PlainDateTime.from({ month: 12, day: 7, hour: 15 -}); // => 1995-12-07T15:00:00 +}); // => '1995-12-07T15:00:00' const dateTime1 = dateTime.with({ minute: 17, second: 19 -}); // => 1995-12-07T15:17:19 +}); // => '1995-12-07T15:17:19' ``` See [Temporal.PlainDateTime Documentation](./plaindatetime.md) for detailed documentation. @@ -162,7 +162,7 @@ A date without a day component. This is useful to express things like "the October 2020 meeting". ```js -const yearMonth = Temporal.PlainYearMonth.from({ year: 2020, month: 10 }); // => 2020-10 +const yearMonth = Temporal.PlainYearMonth.from({ year: 2020, month: 10 }); // => '2020-10' yearMonth.daysInMonth // => 31 yearMonth.daysInYear // => 366 ``` @@ -175,8 +175,8 @@ A date without a year component. This is useful to express things like "Bastille Day is on the 14th of July". ```js -const monthDay = Temporal.PlainMonthDay.from({ month: 7, day: 14 }); // => 07-14 -const date = monthDay.toPlainDate({ year: 2030 }); // => 2030-07-14 +const monthDay = Temporal.PlainMonthDay.from({ month: 7, day: 14 }); // => '07-14' +const date = monthDay.toPlainDate({ year: 2030 }); // => '2030-07-14' date.dayOfWeek // => 7 ``` @@ -214,9 +214,9 @@ It is also possible to implement your own time zones. ```js const timeZone = Temporal.TimeZone.from('Africa/Cairo'); -timeZone.getInstantFor('2000-01-01T00:00') // => 1999-12-31T22:00:00Z -timeZone.getPlainDateTimeFor('2000-01-01T00:00Z') // => 2000-01-01T02:00:00 -timeZone.getPreviousTransition(Temporal.now.instant()) // => 2014-09-25T21:00:00Z +timeZone.getInstantFor('2000-01-01T00:00') // => '1999-12-31T22:00:00Z' +timeZone.getPlainDateTimeFor('2000-01-01T00:00Z') // => '2000-01-01T02:00:00' +timeZone.getPreviousTransition(Temporal.now.instant()) // => '2014-09-25T21:00:00Z' timeZone.getNextTransition(Temporal.now.instant()) // => null ``` diff --git a/docs/ambiguity.md b/docs/ambiguity.md index 90c9808fc7..105a92ce7a 100644 --- a/docs/ambiguity.md +++ b/docs/ambiguity.md @@ -73,20 +73,20 @@ formatOptions = { }; zdt = instant.toZonedDateTimeISO('Asia/Tokyo'); - // => 2019-09-03T17:34:05+09:00[Asia/Tokyo] + // => '2019-09-03T17:34:05+09:00[Asia/Tokyo]' zdt.toLocaleString('en-us', { ...formatOptions, calendar: zdt.calendar }); // => "Sep 3, 2019 AD, 5:34:05 PM" zdt.year; // => 2019 -zdt = instant.toZonedDateTime('Asia/Tokyo', 'iso8601').toLocaleString('ja-jp', formatOptions); - // => 2019-09-03T17:34:05+09:00[Asia/Tokyo] +zdt = instant.toZonedDateTime({timeZone: 'Asia/Tokyo', calendar: 'iso8601'}).toLocaleString('ja-jp', formatOptions); + // => '西暦2019年9月3日 17:34:05' // this is identical to the result of toZonedDateTime() above -zdt = instant.toZonedDateTime('Asia/Tokyo', 'japanese'); - // => 2019-09-03T17:34:05+09:00[Asia/Tokyo][u-ca-japanese] +zdt = instant.toZonedDateTime({timeZone: 'Asia/Tokyo', calendar: 'japanese'}); + // => '2019-09-03T17:34:05+09:00[Asia/Tokyo][u-ca-japanese]' zdt.toLocaleString('en-us', { ...formatOptions, calendar: zdt.calendar }); // => "Sep 3, 1 Reiwa, 5:34:05 PM" -zdt.year; +zdt.eraYear; // => 1 ``` @@ -99,15 +99,15 @@ Conversions from calendar date and/or wall clock time to exact time are also sup date = Temporal.PlainDate.from('2019-12-17'); // If time is omitted, local time defaults to start of day zdt = date.toZonedDateTime('Asia/Tokyo'); - // => 2019-12-17T00:00+09:00[Asia/Tokyo] -zdt = date.toZonedDateTime({ timeZone: 'Asia/Tokyo', time: '10:00' }); - // => 2019-12-17T10:00+09:00[Asia/Tokyo] + // => '2019-12-17T00:00:00+09:00[Asia/Tokyo]' +zdt = date.toZonedDateTime({ timeZone: 'Asia/Tokyo', plainTime: '10:00' }); + // => '2019-12-17T10:00:00+09:00[Asia/Tokyo]' time = Temporal.PlainTime.from('14:35'); -zdt = time.toZonedDateTime({ timeZone: 'Asia/Tokyo', date: Temporal.PlainDate.from('2020-08-27') }); - // => 020-08-27T14:35+09:00[Asia/Tokyo] +zdt = time.toZonedDateTime({ timeZone: 'Asia/Tokyo', plainDate: Temporal.PlainDate.from('2020-08-27') }); + // => '2020-08-27T14:35:00+09:00[Asia/Tokyo]' dateTime = Temporal.PlainDateTime.from('2019-12-17T07:48'); zdt = dateTime.toZonedDateTime('Asia/Tokyo'); - // => 2019-12-17T07:48+09:00[Asia/Tokyo] + // => '2019-12-17T07:48:00+09:00[Asia/Tokyo]' // Get the exact time in seconds, milliseconds, or nanoseconds since the UNIX epoch. inst = zdt.toInstant(); @@ -144,17 +144,17 @@ In `Temporal`, if the exact time or time zone offset is known, then there is no ```javascript // No ambiguity possible because source is exact time in UTC inst = Temporal.Instant.from('2020-09-06T17:35:24.485Z'); - // => 2020-09-06T17:35:24.485Z + // => '2020-09-06T17:35:24.485Z' // An offset can make a local time "exact" with no ambiguity possible. inst = Temporal.Instant.from('2020-09-06T10:35:24.485-07:00'); - // => 2020-09-06T17:35:24.485Z + // => '2020-09-06T17:35:24.485Z' zdt = Temporal.ZonedDateTime.from('2020-09-06T10:35:24.485-07:00[America/Los_Angeles]'); - // => 2020-09-06T10:35:24.485-07:00[America/Los_Angeles] + // => '2020-09-06T10:35:24.485-07:00[America/Los_Angeles]' // if the source is an exact Temporal object, then no ambiguity is possible. zdt = inst.toZonedDateTimeISO('America/Los_Angeles'); - // => 2020-09-06T10:35:24.485-07:00[America/Los_Angeles] + // => '2020-09-06T10:35:24.485-07:00[America/Los_Angeles]' inst2 = zdt.toInstant(); - // => 2020-09-06T17:35:24.485Z + // => '2020-09-06T17:35:24.485Z' ``` @@ -173,11 +173,11 @@ zdt = dt.toZonedDateTime('America/Sao_Paulo'); // can be ambiguous // the offset is lost when converting from an exact type to a non-exact type zdt = Temporal.ZonedDateTime.from('2020-11-01T01:30-08:00[America/Los_Angeles]'); - // => 2020-11-01T01:30-08:00[America/Los_Angeles] + // => '2020-11-01T01:30:00-08:00[America/Los_Angeles]' dt = zdt.toPlainDateTime(); // offset is lost! - // => 2020-11-01T01:30 + // => '2020-11-01T01:30:00' zdtAmbiguous = dt.toZonedDateTime('America/Los_Angeles'); // can be ambiguous - // => 2020-11-01T01:30-07:00[America/Los_Angeles] + // => '2020-11-01T01:30:00-07:00[America/Los_Angeles]' // note that the offset is now -07:00 (Pacific Daylight Time) which is the "first" 1:30AM // not -08:00 (Pacific Standard Time) like the original time which was the "second" 1:30AM ``` @@ -228,17 +228,22 @@ In `'compatible'` mode, the same time is returned as `'later'` mode, which match // Offset of -07:00 is Daylight Saving Time, while offset of -08:00 indicates Standard Time. props = { timeZone: 'America/Los_Angeles', year: 2020, month: 3, day: 8, hour: 2, minute: 30 }; zdt = Temporal.ZonedDateTime.from(props, { disambiguation: 'compatible' }); - // => 2020-03-08T03:30-07:00[America/Los_Angeles] + // => '2020-03-08T03:30:00-07:00[America/Los_Angeles]' zdt = Temporal.ZonedDateTime.from(props); - // => 2020-03-08T03:30-07:00[America/Los_Angeles] ('compatible' is the default) + // => '2020-03-08T03:30:00-07:00[America/Los_Angeles]' + // ('compatible' is the default) earlier = Temporal.ZonedDateTime.from(props, { disambiguation: 'earlier' }); - // => 2020-03-08T01:30-08:00[America/Los_Angeles] (1:30 clock time; still in Standard Time) + // => '2020-03-08T01:30:00-08:00[America/Los_Angeles]' + // (1:30 clock time; still in Standard Time) later = Temporal.ZonedDateTime.from(props, { disambiguation: 'later' }); - // => 2020-03-08T03:30-07:00[America/Los_Angeles] ('later' is same as 'compatible' for backwards transitions) + // => '2020-03-08T03:30:00-07:00[America/Los_Angeles]' + // ('later' is same as 'compatible' for backwards transitions) later.toPlainDateTime().since(earlier.toPlainDateTime()); - // => PT2H (2 hour difference in clock time... + // => 'PT2H' + // (2 hour difference in clock time... later.since(earlier); - // => PT1H ... but 1 hour later in real-world time) + // => 'PT1H' + // ... but 1 hour later in real-world time) ``` @@ -254,22 +259,22 @@ In `'compatible'` mode, the same time is returned as `'earlier'` mode, which mat // Offset of -07:00 is Daylight Saving Time, while offset of -08:00 indicates Standard Time. props = { timeZone: 'America/Los_Angeles', year: 2020, month: 11, day: 1, hour: 1, minute: 30 }; zdt = Temporal.ZonedDateTime.from(props, { disambiguation: 'compatible' }); - // => 2020-11-01T01:30-07:00[America/Los_Angeles] + // => '2020-11-01T01:30:00-07:00[America/Los_Angeles]' zdt = Temporal.ZonedDateTime.from(props); - // => 2020-11-01T01:30-07:00[America/Los_Angeles] + // => '2020-11-01T01:30:00-07:00[America/Los_Angeles]' // 'compatible' is the default. earlier = Temporal.ZonedDateTime.from(props, { disambiguation: 'earlier' }); - // => 2020-11-01T01:30-07:00[America/Los_Angeles] + // => '2020-11-01T01:30:00-07:00[America/Los_Angeles]' // 'earlier' is same as 'compatible' for backwards transitions. later = Temporal.ZonedDateTime.from(props, { disambiguation: 'later' }); - // => 2020-11-01T01:30-08:00[America/Los_Angeles] + // => '2020-11-01T01:30:00-08:00[America/Los_Angeles]' // Same clock time, but one hour later. // -08:00 offset indicates Standard Time. later.toPlainDateTime().since(earlier.toPlainDateTime()); - // => PT0S + // => 'PT0S' // (same clock time... later.since(earlier); - // => PT1H + // => 'PT1H' // ... but 1 hour later in real-world time) ``` @@ -319,7 +324,7 @@ Let's assume the stored future time was noon on January 15, 2020 in São Paulo: ```javascript zdt = Temporal.ZonedDateTime.from({ year: 2020, month: 1, day: 15, hour: 12, timeZone: 'America/Sao_Paulo' }); zdt.toString(); - // => "2020-01-15T12:00-02:00[America/Sao_Paulo]" + // "2020-01-15T12:00:00-02:00[America/Sao_Paulo]" // Assume this string is saved in an external database. // Note that the offset is `-02:00` which is Daylight Saving Time @@ -344,13 +349,13 @@ zdt = Temporal.ZonedDateTime.from(savedUsingOldTzDefinition); zdt = Temporal.ZonedDateTime.from(savedUsingOldTzDefinition, { offset: 'reject' }); // => RangeError: Offset is invalid for '2020-01-01T12:00' in 'America/Sao_Paulo'. Provided: -02:00, expected: -03:00. zdt = Temporal.ZonedDateTime.from(savedUsingOldTzDefinition, { offset: 'use' }); - // => 2020-01-15T11:00-03:00[America/Sao_Paulo] + // => '2020-01-01T11:00:00-03:00[America/Sao_Paulo]' // Evaluate DateTime value using old offset, which keeps UTC time constant as local time changes to 11:00 zdt = Temporal.ZonedDateTime.from(savedUsingOldTzDefinition, { offset: 'ignore' }); - // => 2020-01-15T12:00-03:00[America/Sao_Paulo] + // => '2020-01-01T12:00:00-03:00[America/Sao_Paulo]' // Use current time zone rules to calculate offset, ignoring any saved offset zdt = Temporal.ZonedDateTime.from(savedUsingOldTzDefinition, { offset: 'prefer' }); - // => 2020-01-15T12:00-03:00[America/Sao_Paulo] + // => '2020-01-01T12:00:00-03:00[America/Sao_Paulo]' // Saved offset is invalid for current time zone rules, so use time zone to to calculate offset. ``` diff --git a/docs/balancing.md b/docs/balancing.md index a05da94d32..4185fd5a97 100644 --- a/docs/balancing.md +++ b/docs/balancing.md @@ -31,23 +31,29 @@ By default, `round()` will not enlarge a top-heavy unbalanced duration. By default, the largest unit in the input will be largest unit in the output. ```javascript -d = Temporal.Duration.from({ minutes: 80, seconds: 30 }); // => PT80M30S -d.round(); // => PT80M30S (unchanged) +d = Temporal.Duration.from({ minutes: 80, seconds: 30 }); // => 'PT80M30S' +d.round({largestUnit: 'auto'}); + // => 'PT80M30S' + // (unchanged) ``` However, `round()` will balance units smaller than the largest one. This only matters in the rare case that an unbalanced duration isn't top-heavy. ```javascript -d = Temporal.Duration.from({ minutes: 80, seconds: 90 }); // => PT80M90S -d.round(); // => PT81M30S (seconds balance to minutes, but not minutes=>hours) +d = Temporal.Duration.from({ minutes: 80, seconds: 90 }); // => 'PT80M90S' +d.round({largestUnit: 'auto'}); + // => 'PT81M30S' + // (seconds balance to minutes, but not minutes=>hours) ``` To fully balance a duration, use the `largestUnit` option: ```javascript -d = Temporal.Duration.from({ minutes: 80, seconds: 90 }); // => PT80M90S -d.round({ largestUnit: 'hours' }); // => PT1H21M30S (fully balanced) +d = Temporal.Duration.from({ minutes: 80, seconds: 90 }); // => 'PT80M90S' +d.round({ largestUnit: 'hours' }); + // => 'PT1H21M30S' + // (fully balanced) ``` ## Balancing Relative to a Reference Point @@ -63,10 +69,12 @@ To handle this potential ambiguity, the `relativeTo` option is used to provide a `relativeTo` is required when balancing to or from weeks, months, or years. ```javascript -d = Temporal.Duration.from({ days: 370 }); // => P370D +d = Temporal.Duration.from({ days: 370 }); // => 'P370D' d.round({ largestUnit: 'months' }); // => RangeError (`relativeTo` is required) -d.round({ largestUnit: 'months', relativeTo: '2019-01-01' }); // => P1Y5D -d.round({ largestUnit: 'months', relativeTo: '2020-01-01' }); // => P1Y4D (2020 is a leap year) +d.round({ largestUnit: 'months', relativeTo: '2019-01-01' }); // => 'P12M5D' +d.round({ largestUnit: 'months', relativeTo: '2020-01-01' }); + // => 'P12M4D' + // (2020 is a leap year) ``` `relativeTo` is optional when balancing to or from `days`, and if `relativeTo` is omitted then days are assumed to be 24 hours long. @@ -74,11 +82,12 @@ However, if the duration is timezone-specific, then it's recommended to use a `T ```javascript -d = Temporal.Duration.from({ hours: 48 }); // => PT48H +d = Temporal.Duration.from({ hours: 48 }); // => 'PT48H' d.round({ largestUnit: 'days' }); - // => P2D + // => 'P2D' d.round({ largestUnit: 'days', relativeTo: '2020-03-08T00:00-08:00[America/Los_Angeles]' }); - // => P2D1H (because one clock hour was skipped by DST starting) + // => 'P2DT1H' + // (because one clock hour was skipped by DST starting) ``` @@ -89,17 +98,19 @@ In addition to `round()` as described above, `add()` and `subtract()` also balan By default, `add()` and `subtract()` on `Temporal.Duration` instances will only balance up to the largest unit in either input duration. ```javascript -d1 = Temporal.Duration.from({ hours: 26, minutes: 45 }); // => PT26H45M -d2 = Temporal.Duration.from({ minutes: 30 }); // => PT30M -d1.add(d2); // => PT27H15M +d1 = Temporal.Duration.from({ hours: 26, minutes: 45 }); // => 'PT26H45M' +d2 = Temporal.Duration.from({ minutes: 30 }); // => 'PT30M' +d1.add(d2); // => 'PT27H15M' ``` The `largestUnit` option can be used to balance to larger units than the inputs. ```javascript -d1 = Temporal.Duration.from({ minutes: 80, seconds: 90 }); // => PT80M90S -d2 = Temporal.Duration.from({ minutes: 100, seconds: 15 }); // => PT100M15S -d1.add(d2, { largestUnit: 'hours' }); // => PT3H1M45S (fully balanced) +d1 = Temporal.Duration.from({ minutes: 80, seconds: 90 }); // => 'PT80M90S' +d2 = Temporal.Duration.from({ minutes: 100, seconds: 15 }); // => 'PT100M15S' +d1.add(d2).round({ largestUnit: 'hours' }); + // => 'PT3H1M45S' + // (fully balanced) ``` The `relativeTo` option can be used to balance to, or from, weeks, months or years (or days for timezone-aware durations). @@ -107,12 +118,13 @@ The `relativeTo` option can be used to balance to, or from, weeks, months or yea ```javascript -d1 = Temporal.Duration.from({ hours: 48 }); // => PT48H -d2 = Temporal.Duration.from({ hours: 24 }); // => PT24H -d1.add(d2, { largestUnit: 'days' }); - // => P3D -d1.add(d2, { largestUnit: 'days', relativeTo: '2020-03-08T00:00-08:00[America/Los_Angeles]' }); - // => P3D1H (because one clock hour was skipped by DST starting) +d1 = Temporal.Duration.from({ hours: 48 }); // => 'PT48H' +d2 = Temporal.Duration.from({ hours: 24 }); // => 'PT24H' +d1.add(d2).round({ largestUnit: 'days' }); + // => 'P3D' +d1.add(d2).round({ largestUnit: 'days', relativeTo: '2020-03-08T00:00-08:00[America/Los_Angeles]' }); + // => 'P3DT1H' + // (because one clock hour was skipped by DST starting) ``` diff --git a/docs/calendar.md b/docs/calendar.md index a330357798..5cb1991a19 100644 --- a/docs/calendar.md +++ b/docs/calendar.md @@ -124,7 +124,7 @@ Example usage: ```javascript cal = new Temporal.Calendar('iso8601'); cal = new Temporal.Calendar('gregory'); -/*⚠️*/ cal = new Temporal.Calendar('discordian'); // not a built-in calendar, throws +cal = new Temporal.Calendar('discordian'); // => throws, not a built-in calendar ``` ## Static methods @@ -168,8 +168,8 @@ cal2 = Temporal.Calendar.from(cal); // Custom calendar that is a plain object (this calendar does not do much) cal = Temporal.Calendar.from({ id: 'mycalendar' }); -/*⚠️*/ cal = Temporal.Calendar.from('discordian'); // not a built-in calendar, throws -/*⚠️*/ cal = Temporal.Calendar.from('[u-ca-iso8601]'); // lone annotation not a valid ISO 8601 string +cal = Temporal.Calendar.from('discordian'); // => throws, not a built-in calendar +cal = Temporal.Calendar.from('[u-ca-iso8601]'); // => throws, lone annotation not a valid ISO 8601 string ``` ## Properties @@ -273,7 +273,7 @@ date.year; // => 5779 date.month; // => 6 date.monthCode; // => "M05L" date.day; // => 18 -date.toString(); // => 2019-02-23[u-ca-hebrew] +date.toString(); // => '2019-02-23[u-ca-hebrew]' date.toLocaleString('en-US', { calendar: 'hebrew' }); // => "18 Adar I 5779" // same result, but calling the method directly and using month index instead of month code: @@ -320,7 +320,7 @@ date = Temporal.PlainDate.from('2020-05-29') date.year; // => 1441 date.month; // => 11 date.day; // => 7 -date.toString(); // => 2020-06-28[u-ca-islamic] +date.toString(); // => '2020-06-28[u-ca-islamic]' // same result, but calling the method directly: date = Temporal.Calendar.from('islamic').dateAdd( @@ -332,7 +332,7 @@ date = Temporal.Calendar.from('islamic').dateAdd( date.year; // => 1441 date.month; // => 11 date.day; // => 7 -date.toString(); // => 2020-06-28[u-ca-islamic] +date.toString(); // => '2020-06-28[u-ca-islamic]' ``` ### calendar.**dateUntil**(_one_: Temporal.PlainDate | object | string, _two_: Temporal.PlainDate | object | string, _options_: object) : Temporal.Duration @@ -366,14 +366,14 @@ For example: ```javascript d1 = Temporal.PlainDate.from('2020-07-29').withCalendar('chinese'); d2 = Temporal.PlainDate.from('2020-08-29').withCalendar('chinese'); -d1.until(d2, { largestUnit: 'months' }); // => P1M2D +d1.until(d2, { largestUnit: 'months' }); // => 'P1M2D' // same result, but calling the method directly: Temporal.Calendar.from('chinese').dateUntil( Temporal.PlainDate.from('2020-07-29'), Temporal.PlainDate.from('2020-08-29'), { largestUnit: 'months' } -); // => P1M2D +); // => 'P1M2D' ``` ### calendar.**fields**(_fields_: array) : array @@ -445,7 +445,7 @@ This method overrides `Object.prototype.toString()` and provides the calendar's Example usage: ```javascript -Temporal.PlainDate.from('2020-05-29[u-ca-gregory]').calendar.toString(); // => gregory +Temporal.PlainDate.from('2020-05-29[u-ca-gregory]').calendar.toString(); // => 'gregory' ``` ### calendar.**toJSON**() : string diff --git a/docs/cookbook/birthdayIn2030.mjs b/docs/cookbook/birthdayIn2030.mjs index 1962141b73..cbc2f425b5 100644 --- a/docs/cookbook/birthdayIn2030.mjs +++ b/docs/cookbook/birthdayIn2030.mjs @@ -3,5 +3,5 @@ const birthday = Temporal.PlainMonthDay.from('12-15'); const birthdayIn2030 = birthday.toPlainDate({ year: 2030 }); birthdayIn2030.dayOfWeek; // => 7 -assert(birthdayIn2030 instanceof Temporal.PlainDate); +assert.ok(birthdayIn2030 instanceof Temporal.PlainDate); assert.equal(birthdayIn2030.toString(), '2030-12-15'); diff --git a/docs/cookbook/getParseableZonedStringAtInstant.mjs b/docs/cookbook/getParseableZonedStringAtInstant.mjs index 7ffc150f02..cf765ee733 100644 --- a/docs/cookbook/getParseableZonedStringAtInstant.mjs +++ b/docs/cookbook/getParseableZonedStringAtInstant.mjs @@ -3,14 +3,14 @@ const instant = Temporal.Instant.from('2020-01-03T10:41:51Z'); const result = instant.toString(); assert.equal(result, '2020-01-03T10:41:51Z'); -assert(instant.equals(Temporal.Instant.from(result))); +assert.ok(instant.equals(Temporal.Instant.from(result))); // Include the UTC offset of a particular time zone: const result2 = instant.toString({ timeZone: 'America/Yellowknife' }); assert.equal(result2, '2020-01-03T03:41:51-07:00'); -assert(instant.equals(Temporal.Instant.from(result2))); +assert.ok(instant.equals(Temporal.Instant.from(result2))); // Include the UTC offset as well as preserving the time zone name: @@ -18,5 +18,5 @@ const zoned = instant.toZonedDateTimeISO('Asia/Seoul'); const result3 = zoned.toString(); assert.equal(result3, '2020-01-03T19:41:51+09:00[Asia/Seoul]'); -assert(instant.equals(Temporal.Instant.from(result3))); -assert(zoned.equals(Temporal.ZonedDateTime.from(result3))); +assert.ok(instant.equals(Temporal.Instant.from(result3))); +assert.ok(zoned.equals(Temporal.ZonedDateTime.from(result3))); diff --git a/docs/cookbook/getUtcOffsetStringAtInstant.mjs b/docs/cookbook/getUtcOffsetStringAtInstant.mjs index 5d25c0f8e8..8bd827fdbf 100644 --- a/docs/cookbook/getUtcOffsetStringAtInstant.mjs +++ b/docs/cookbook/getUtcOffsetStringAtInstant.mjs @@ -1,8 +1,8 @@ const instant = Temporal.Instant.from('2020-01-09T00:00Z'); const nyc = Temporal.TimeZone.from('America/New_York'); -nyc.getOffsetStringFor(instant); // => -05:00 +nyc.getOffsetStringFor(instant); // => '-05:00' // Can also be done with ZonedDateTime.offset: const source = instant.toZonedDateTimeISO(nyc); -source.offset; // => -05:00 +source.offset; // => '-05:00' diff --git a/docs/cookbook/noonOnDate.mjs b/docs/cookbook/noonOnDate.mjs index 81a8342a41..5e23e71abe 100644 --- a/docs/cookbook/noonOnDate.mjs +++ b/docs/cookbook/noonOnDate.mjs @@ -2,5 +2,5 @@ const date = Temporal.PlainDate.from('2020-05-14'); const noonOnDate = date.toPlainDateTime(Temporal.PlainTime.from({ hour: 12 })); -assert(noonOnDate instanceof Temporal.PlainDateTime); +assert.ok(noonOnDate instanceof Temporal.PlainDateTime); assert.equal(noonOnDate.toString(), '2020-05-14T12:00:00'); diff --git a/docs/duration.md b/docs/duration.md index 490587caf5..c10d324188 100644 --- a/docs/duration.md +++ b/docs/duration.md @@ -63,10 +63,10 @@ Otherwise `Temporal.Duration.from()` is probably more convenient because it acce Usage examples: ```javascript -new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 987, 654, 321); // => P1Y2M3W4DT5H6M7.987654321S -new Temporal.Duration(0, 0, 0, 40); // => P40D -new Temporal.Duration(undefined, undefined, undefined, 40); // => P40D -new Temporal.Duration(); // => PT0S +new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 987, 654, 321); // => 'P1Y2M3W4DT5H6M7.987654321S' +new Temporal.Duration(0, 0, 0, 40); // => 'P40D' +new Temporal.Duration(undefined, undefined, undefined, 40); // => 'P40D' +new Temporal.Duration(); // => 'PT0S' ``` ## Static methods @@ -96,17 +96,17 @@ Any non-object value is converted to a string, which is expected to be in ISO 86 Usage examples: ```javascript -d = Temporal.Duration.from({ years: 1, days: 1 }); // => P1Y1D -d = Temporal.Duration.from({ days: -2, hours: -12 }); // => -P2DT12H +d = Temporal.Duration.from({ years: 1, days: 1 }); // => 'P1Y1D' +d = Temporal.Duration.from({ days: -2, hours: -12 }); // => '-P2DT12H' -Temporal.Duration.from(d) === d; // => true +Temporal.Duration.from(d) === d; // => false -d = Temporal.Duration.from('P1Y1D'); // => P1Y1D -d = Temporal.Duration.from('-P2DT12H'); // => -P2DT12H -d = Temporal.Duration.from('P0D'); // => PT0S +d = Temporal.Duration.from('P1Y1D'); // => 'P1Y1D' +d = Temporal.Duration.from('-P2DT12H'); // => '-P2DT12H' +d = Temporal.Duration.from('P0D'); // => 'PT0S' // Mixed-sign values are never allowed, even if overall positive: -d = Temporal.Duration.from({ hours: 1, minutes: -30 }); // throws +d = Temporal.Duration.from({ hours: 1, minutes: -30 }); // => throws ``` ### Temporal.Duration.**compare**(_one_: Temporal.Duration | object | string, _two_: Temporal.Duration | object | string, _options_?: object) : number @@ -148,13 +148,13 @@ two = Temporal.Duration.from({ days: 3, hours: 7, seconds: 630 }); three = Temporal.Duration.from({ days: 3, hours: 6, minutes: 50 }); sorted = [one, two, three].sort(Temporal.Duration.compare); sorted.join(' '); -// => P3DT6H50M PT79H10M P3DT7H630S +// => 'P3DT6H50M PT79H10M P3DT7H630S' // Sorting relative to a date, taking DST changes into account: relativeTo = Temporal.ZonedDateTime.from('2020-11-01T00:00-07:00[America/Los_Angeles]'); sorted = [one, two, three].sort((one, two) => Temporal.Duration.compare(one, two, {relativeTo})); sorted.join(' '); -// => PT79H10M P3DT6H50M P3DT7H630S +// => 'PT79H10M P3DT6H50M P3DT7H630S' ``` ## Properties @@ -245,7 +245,7 @@ let { years, months } = duration; years += Math.floor(months / 12); months %= 12; duration = duration.with({ years, months }); - // => P4Y2M50DT50H100M + // => 'P4Y2M50DT50H100M' ``` @@ -284,24 +284,22 @@ Usage example: ```javascript hour = Temporal.Duration.from('PT1H'); -hour.add({ minutes: 30 }); // => PT1H30M +hour.add({ minutes: 30 }); // => 'PT1H30M' // Examples of balancing: one = Temporal.Duration.from({ hours: 1, minutes: 30 }); two = Temporal.Duration.from({ hours: 2, minutes: 45 }); -result = one.add(two); // => PT3H75M -result.with(result, { overflow: 'balance' }); // => PT4H15M +result = one.add(two); // => 'PT4H15M' fifty = Temporal.Duration.from('P50Y50M50DT50H50M50.500500500S'); -result = fifty.add(fifty); // => P100Y100M100DT100H100M101.001001S' -Temporal.Duration.from(result, { overflow: 'balance' }); -// => P100Y100M104DT5H41M41.001001S +result = fifty.add(fifty); // => throws, need relativeTo +result = fifty.add(fifty, {relativeTo: '1900-01-01'}); // => 'P108Y7M12DT5H41M41.001001S' // Example of converting ambiguous units relative to a start date oneAndAHalfMonth = Temporal.Duration.from({ months: 1, days: 15 }); -oneAndAHalfMonth.add(oneAndAHalfMonth); // throws -oneAndAHalfMonth.add(oneAndAHalfMonth, { relativeTo: '2000-02-01' }); // => P3M -oneAndAHalfMonth.add(oneAndAHalfMonth, { relativeTo: '2000-03-01' }); // => P2M30D +oneAndAHalfMonth.add(oneAndAHalfMonth); // => throws +oneAndAHalfMonth.add(oneAndAHalfMonth, { relativeTo: '2000-02-01' }); // => 'P3M' +oneAndAHalfMonth.add(oneAndAHalfMonth, { relativeTo: '2000-03-01' }); // => 'P2M30D' ``` @@ -341,19 +339,19 @@ Usage example: ```javascript hourAndAHalf = Temporal.Duration.from('PT1H30M'); -hourAndAHalf.subtract({ hours: 1 }); // => PT30M +hourAndAHalf.subtract({ hours: 1 }); // => 'PT30M' one = Temporal.Duration.from({ minutes: 180 }); two = Temporal.Duration.from({ seconds: 30 }); -one.subtract(two); // => PT179M30S -one.subtract(two, { overflow: 'balance' }); // => PT2H59M30S +one.subtract(two); // => 'PT179M30S' +one.subtract(two).round({largestUnit: 'hours'}); // => 'PT2H59M30S' // Example of converting ambiguous units relative to a start date threeMonths = Temporal.Duration.from({ months: 3 }); oneAndAHalfMonth = Temporal.Duration.from({ months: 1, days: 15 }); -threeMonths.subtract(oneAndAHalfMonth); // throws -threeMonths.subtract(oneAndAHalfMonth, { relativeTo: '2000-02-01' }); // => P1M16D -threeMonths.subtract(oneAndAHalfMonth, { relativeTo: '2000-03-01' }); // => P1M15D +threeMonths.subtract(oneAndAHalfMonth); // => throws +threeMonths.subtract(oneAndAHalfMonth, { relativeTo: '2000-02-01' }); // => 'P1M16D' +threeMonths.subtract(oneAndAHalfMonth, { relativeTo: '2000-03-01' }); // => 'P1M15D' ``` ### duration.**negated**() : Temporal.Duration @@ -463,12 +461,12 @@ Example usage: ```javascript // Balance a duration as far as possible without knowing a starting point d = Temporal.Duration.from({ minutes: 130 }); -d.round({ largestUnit: 'days' }); // => PT2H10M +d.round({ largestUnit: 'days' }); // => 'PT2H10M' // Round to the nearest unit d = Temporal.Duration.from({ minutes: 10, seconds: 52 }); -d.round({ smallestUnit: 'minutes' }); // => PT11M -d.round({ smallestUnit: 'minutes', roundingMode: 'trunc' }); // => PT10M +d.round({ smallestUnit: 'minutes' }); // => 'PT11M' +d.round({ smallestUnit: 'minutes', roundingMode: 'trunc' }); // => 'PT10M' // How many seconds in a multi-unit duration? d = Temporal.Duration.from('PT2H34M18S'); @@ -479,22 +477,24 @@ d = Temporal.Duration.from({ hours: 2756 }); d.round({ relativeTo: '2020-01-01T00:00+01:00[Europe/Rome]', largestUnit: 'years' -}); // => P114DT21H (one hour longer because DST skipped an hour) +}); // => 'P114DT21H' + // (one hour longer because DST skipped an hour) d.round({ relativeTo: '2020-01-01', largestUnit: 'years' -}); // => P114DT20H (one hour shorter if ignoring DST) +}); // => 'P114DT20H' + // (one hour shorter if ignoring DST) // Normalize days into months or years d = Temporal.Duration.from({ days: 190 }); refDate = Temporal.PlainDate.from('2020-01-01'); -d.round({ relativeTo: refDate, largestUnit: 'years' }); // => P6M6D +d.round({ relativeTo: refDate, largestUnit: 'years' }); // => 'P6M8D' // Same, but in a different calendar system d.round({ relativeTo: refDate.withCalendar('hebrew'), largestUnit: 'years' -}); // => P6M13D +}); // => 'P6M13D' // Round a duration up to the next 5-minute billing period d = Temporal.Duration.from({ minutes: 6 }); @@ -502,7 +502,7 @@ d.round({ smallestUnit: 'minutes', roundingIncrement: 5, roundingMode: 'ceil' -}); // ==> P10M +}); // => 'PT10M' // How many full 3-month quarters of this year, are in this duration? d = Temporal.Duration.from({ months: 10, days: 15 }); @@ -510,7 +510,7 @@ d = d.round({ smallestUnit: 'months', roundingIncrement: 3, roundingMode: 'trunc', - relativeTo: Temporal.now.plainDate() + relativeTo: Temporal.now.plainDate('iso8601') }); quarters = d.months / 3; quarters; // => 3 @@ -598,25 +598,25 @@ Usage examples: ```javascript d = Temporal.Duration.from({ years: 1, days: 1 }); -d.toString(); // => P1Y1D +d.toString(); // => 'P1Y1D' d = Temporal.Duration.from({ years: -1, days: -1 }); -d.toString(); // => -P1Y1D +d.toString(); // => '-P1Y1D' d = Temporal.Duration.from({ milliseconds: 1000 }); -d.toString(); // => PT1S +d.toString(); // => 'PT1S' // The output format always balances units under 1 s, even if the // underlying Temporal.Duration object doesn't. nobal = Temporal.Duration.from({ milliseconds: 3500 }); -console.log(`${nobal}`, nobal.seconds, nobal.milliseconds); // => PT3.500S 0 3500 -bal = Temporal.Duration.from({ milliseconds: 3500 }, { overflow: 'balance' }); -console.log(`${bal}`, bal.seconds, bal.milliseconds); // => PT3.500S 3 500 +console.log(`${nobal}`, nobal.seconds, nobal.milliseconds); // => 'PT3.5S 0 3500' +bal = Temporal.Duration.from({ milliseconds: 3500 }).round({largestUnit: 'years'}); // balance through round +console.log(`${bal}`, bal.seconds, bal.milliseconds); // => 'PT3.5S 3 500' d = Temporal.Duration.from('PT59.999999999S'); -d.toString({ smallestUnit: 'seconds' }); // => PT59S -d.toString({ fractionalSecondDigits: 0 }); // => PT59S -d.toString({ fractionalSecondDigits: 4 }); // => PT59.9999S +d.toString({ smallestUnit: 'seconds' }); // => 'PT59S' +d.toString({ fractionalSecondDigits: 0 }); // => 'PT59S' +d.toString({ fractionalSecondDigits: 4 }); // => 'PT59.9999S' d.toString({ fractionalSecondDigits: 8, roundingMode: 'nearest' }); -// => PT60.00000000S +// => 'PT60.00000000S' ``` ### duration.**toJSON**() : string @@ -671,14 +671,13 @@ The `locales` and `options` arguments are the same as in the constructor to [`In > **NOTE**: This method requires that your JavaScript environment supports `Intl.DurationFormat`. > That is still an early-stage proposal and at the time of writing it is not supported anywhere. > If `Intl.DurationFormat` is not available, then the output of this method is the same as that of `duration.toString()`, and the `locales` and `options` arguments are ignored. - Usage examples: ```javascript d = Temporal.Duration.from('P1DT6H30M'); -d.toLocaleString(); // => 1 day 6 hours 30 minutes -d.toLocaleString('de-DE'); // => 1 Tag 6 Stunden 30 Minuten -d.toLocaleString('en-US', { day: 'numeric', hour: 'numeric' }); // => 1 day 6 hours +d.toLocaleString(); // => '1 day 6 hours 30 minutes' +d.toLocaleString('de-DE'); // => '1 Tag 6 Stunden 30 Minuten' +d.toLocaleString('en-US', { day: 'numeric', hour: 'numeric' }); // => '1 day 6 hours' ``` ### duration.**valueOf**() diff --git a/docs/instant.md b/docs/instant.md index 55522e1b55..3ebe2a195a 100644 --- a/docs/instant.md +++ b/docs/instant.md @@ -43,9 +43,9 @@ Example usage: ```js instant = new Temporal.Instant(1553906700000000000n); // When was the Unix epoch? -epoch = new Temporal.Instant(0n); // => 1970-01-01T00:00Z +epoch = new Temporal.Instant(0n); // => '1970-01-01T00:00:00Z' // Dates before the Unix epoch are negative -turnOfTheCentury = new Temporal.Instant(-2208988800000000000n); // => 1900-01-01T00:00Z +turnOfTheCentury = new Temporal.Instant(-2208988800000000000n); // => '1900-01-01T00:00:00Z' ``` ## Static methods @@ -71,11 +71,11 @@ Example usage: instant = Temporal.Instant.from('2019-03-30T01:45:00+01:00[Europe/Berlin]'); instant = Temporal.Instant.from('2019-03-30T01:45+01:00'); instant = Temporal.Instant.from('2019-03-30T00:45Z'); -instant === Temporal.Instant.from(instant); // => true +instant.equals(Temporal.Instant.from(instant)); // => true // Not enough information to denote an exact time: -/* WRONG */ instant = Temporal.Instant.from('2019-03-30'); // no time; throws -/* WRONG */ instant = Temporal.Instant.from('2019-03-30T01:45'); // no time zone; throws +/* WRONG */ instant = Temporal.Instant.from('2019-03-30'); // => throws, no time +/* WRONG */ instant = Temporal.Instant.from('2019-03-30T01:45'); // => throws, no time ``` @@ -98,8 +98,8 @@ Example usage: ```js // Same examples as in new Temporal.Instant(), but with seconds precision instant = Temporal.Instant.fromEpochSeconds(1553906700); -epoch = Temporal.Instant.fromEpochSeconds(0); // => 1970-01-01T00:00Z -turnOfTheCentury = Temporal.Instant.fromEpochSeconds(-2208988800); // => 1900-01-01T00:00Z +epoch = Temporal.Instant.fromEpochSeconds(0); // => '1970-01-01T00:00:00Z' +turnOfTheCentury = Temporal.Instant.fromEpochSeconds(-2208988800); // => '1900-01-01T00:00:00Z' ``` ### Temporal.Instant.**fromEpochMilliseconds**(_epochMilliseconds_: number) : Temporal.Instant @@ -117,7 +117,7 @@ However, for conversion from legacy `Date` to `Temporal.Instant`, use `Date.prot ```js legacyDate = new Date('December 17, 1995 03:24:00 GMT'); -instant = Temporal.Instant.fromEpochMilliseconds(legacyDate.getTime()); // => 1995-12-17T03:24Z +instant = Temporal.Instant.fromEpochMilliseconds(legacyDate.getTime()); // => '1995-12-17T03:24:00Z' instant = Temporal.Instant.fromEpochMilliseconds(+legacyDate); // valueOf() called implicitly instant = legacyDate.toTemporalInstant(); // recommended @@ -174,7 +174,7 @@ two = Temporal.Instant.fromEpochSeconds(1.1e9); three = Temporal.Instant.fromEpochSeconds(1.2e9); sorted = [three, one, two].sort(Temporal.Instant.compare); sorted.join(' '); -// => 2001-09-09T01:46:40Z 2004-11-09T11:33:20Z 2008-01-10T21:20Z +// => '2001-09-09T01:46:40Z 2004-11-09T11:33:20Z 2008-01-10T21:20:00Z' ``` ## Properties @@ -191,7 +191,7 @@ Example usage: ```js instant = Temporal.Instant.from('2019-03-30T01:45+01:00'); -instant.epochSeconds; // => 1554000300 +instant.epochSeconds; // => 1553906700 ``` ### instant.**epochMilliseconds** : number @@ -204,7 +204,7 @@ An example: ```js instant = Temporal.Instant.from('2019-03-30T00:45Z'); -new Date(instant.epochMilliseconds); // => 2019-03-30T00:45:00.000Z +new Date(instant.epochMilliseconds).toISOString(); // => '2019-03-30T00:45:00.000Z' ``` ### instant.**epochMicroseconds** : bigint @@ -244,9 +244,9 @@ Example usage: ```js // Converting a specific exact time to a calendar date / wall-clock time timestamp = Temporal.Instant.fromEpochSeconds(1553993100); -timestamp.toZonedDateTimeISO('Europe/Berlin'); // => 2019-03-31T01:45+02:00[Europe/Berlin] -timestamp.toZonedDateTimeISO('UTC'); // => 2019-03-31T00:45+00:00[UTC] -timestamp.toZonedDateTimeISO('-08:00'); // => 2019-03-30T16:45-08:00[-08:00] +timestamp.toZonedDateTimeISO('Europe/Berlin'); // => '2019-03-31T01:45:00+01:00[Europe/Berlin]' +timestamp.toZonedDateTimeISO('UTC'); // => '2019-03-31T00:45:00+00:00[UTC]' +timestamp.toZonedDateTimeISO('-08:00'); // => '2019-03-30T16:45:00-08:00[-08:00]' ``` ### instant.**toZonedDateTime**(_item_: object) : Temporal.ZonedDateTime @@ -274,15 +274,15 @@ Example usage: epoch = Temporal.Instant.fromEpochSeconds(0); timeZone = Temporal.TimeZone.from('America/New_York'); epoch.toZonedDateTime({ timeZone, calendar: 'gregory' }); - // => 1969-12-31T19:00-05:00[America/New_York][u-ca-gregory] + // => '1969-12-31T19:00:00-05:00[America/New_York][u-ca-gregory]' // What time was the Unix epoch in Tokyo in the Japanese calendar? timeZone = Temporal.TimeZone.from('Asia/Tokyo'); calendar = Temporal.Calendar.from('japanese'); zdt = epoch.toZonedDateTime({ timeZone, calendar }); - // => 1970-01-01T09:00+09:00[Asia/Tokyo][u-ca-japanese] -console.log(zdt.year, zdt.era); - // => 45 showa + // => '1970-01-01T09:00:00+09:00[Asia/Tokyo][u-ca-japanese]' +console.log(zdt.eraYear, zdt.era); + // => '45 showa' ``` @@ -403,8 +403,8 @@ Example usage: ```js startOfMoonMission = Temporal.Instant.from('1969-07-16T13:32:00Z'); endOfMoonMission = Temporal.Instant.from('1969-07-24T16:50:35Z'); -missionLength = startOfMoonMission.until(endOfMoonMission, { largestUnit: 'days' }); - // => PT195H18M35S +missionLength = startOfMoonMission.until(endOfMoonMission, { largestUnit: 'hours' }); + // => 'PT195H18M35S' missionLength.toLocaleString(); // example output: '195 hours 18 minutes 35 seconds' @@ -413,27 +413,28 @@ approxMissionLength = startOfMoonMission.until(endOfMoonMission, { largestUnit: 'hours', smallestUnit: 'hours' }); - // => P195H + // => 'PT195H' // A billion (10^9) seconds since the epoch in different units epoch = Temporal.Instant.fromEpochSeconds(0); billion = Temporal.Instant.fromEpochSeconds(1e9); epoch.until(billion); - // => PT1000000000S + // => 'PT1000000000S' epoch.until(billion, { largestUnit: 'hours' }); - // => PT277777H46M40S + // => 'PT277777H46M40S' ns = epoch.until(billion, { largestUnit: 'nanoseconds' }); - // => PT1000000000S + // => 'PT1000000000S' ns.add({ nanoseconds: 1 }); - // => PT1000000000S (lost precision) + // => 'PT1000000000S' + // (lost precision) // Calculate the difference in years, eliminating the ambiguity by // explicitly using the corresponding calendar date in UTC: epoch.toZonedDateTimeISO('UTC').until( - billion.toZonedDateTimeISO('UTC'), + billion.toZonedDateTimeISO('UTC'), { largestUnit: 'years' } ); - // => P31Y8M8DT1H46M40S + // => 'P31Y8M8DT1H46M40S' ``` @@ -470,7 +471,7 @@ Example usage: // A billion (10^9) seconds since the epoch in different units epoch = Temporal.Instant.fromEpochSeconds(0); billion = Temporal.Instant.fromEpochSeconds(1e9); -billion.since(epoch); // => PT1000000000S +billion.since(epoch); // => 'PT1000000000S' ``` ### instant.**round**(_options_: object) : Temporal.Instant @@ -517,13 +518,13 @@ Example usage: instant = Temporal.Instant.from('2019-03-30T02:45:59.999999999Z'); // Round to a particular unit -instant.round({ smallestUnit: 'second' }); // => 2019-03-30T02:46Z +instant.round({ smallestUnit: 'second' }); // => '2019-03-30T02:46:00Z' // Round to an increment of a unit, e.g. an hour: instant.round({ roundingIncrement: 60, smallestUnit: 'minute' }); - // => 2019-03-30T03:00Z + // => '2019-03-30T03:00:00Z' // Round to the same increment but round down instead: instant.round({ roundingIncrement: 60, smallestUnit: 'minute', roundingMode: 'floor' }); - // => 2019-03-30T02:00Z + // => '2019-03-30T02:00:00Z' ``` @@ -587,20 +588,20 @@ Example usage: ```js instant = Temporal.Instant.fromEpochMilliseconds(1574074321816); -instant.toString(); // => 2019-11-18T10:52:01.816Z +instant.toString(); // => '2019-11-18T10:52:01.816Z' instant.toString({ timeZone: Temporal.TimeZone.from('UTC') }); -// => 2019-11-18T10:52:01.816+00:00 +// => '2019-11-18T10:52:01.816+00:00' instant.toString({ timeZone: 'Asia/Seoul' }); -// => 2019-11-18T19:52:01.816+09:00 +// => '2019-11-18T19:52:01.816+09:00' instant.toString({ smallestUnit: 'minute' }); -// => 2019-11-18T10:52Z +// => '2019-11-18T10:52Z' instant.toString({ fractionalSecondDigits: 0 }); -// => 2019-11-18T10:52:01Z +// => '2019-11-18T10:52:01Z' instant.toString({ fractionalSecondDigits: 4 }); -// => 2019-11-18T10:52:01.8160Z +// => '2019-11-18T10:52:01.8160Z' instant.toString({ smallestUnit: 'second', roundingMode: 'nearest' }); -// => 2019-11-18T10:52:02Z +// => '2019-11-18T10:52:02Z' ``` ### instant.**toLocaleString**(_locales_?: string | array<string>, _options_?: object) : string @@ -626,8 +627,9 @@ Example usage: ```js instant = Temporal.Instant.from('2019-11-18T11:00:00.000Z'); -instant.toLocaleString(); // => example output: 2019-11-18, 3:00:00 a.m. -instant.toLocaleString('de-DE'); // => example output: 18.11.2019, 03:00:00 +instant.toLocaleString(); // => '11/18/2019, 3:00:00 AM' + // (if host environment's current locale is 'en-US') +instant.toLocaleString('de-DE'); // => '18.11.2019, 03:00:00' instant.toLocaleString('de-DE', { timeZone: 'Europe/Berlin', year: 'numeric', @@ -636,10 +638,10 @@ instant.toLocaleString('de-DE', { hour: 'numeric', minute: 'numeric', timeZoneName: 'long' -}); // => 18.11.2019, 12:00 Mitteleuropäische Normalzeit +}); // => '18.11.2019, 12:00 Mitteleuropäische Normalzeit' instant.toLocaleString('en-US-u-nu-fullwide-hc-h12', { timeZone: 'Asia/Kolkata' -}); // => 11/18/2019, 4:30:00 PM +}); // => '11/18/2019, 4:30:00 PM' ``` ### instant.**toJSON**() : string diff --git a/docs/package.json b/docs/package.json index 3818bb45c9..ccd810d6b0 100644 --- a/docs/package.json +++ b/docs/package.json @@ -26,5 +26,8 @@ "marked": "^1.2.0", "mkdirp": "^1.0.4", "prismjs": "^1.21.0" + }, + "dependencies": { + "acorn-loose": "^8.0.2" } } diff --git a/docs/parse-draft.md b/docs/parse-draft.md index faa6fc8b35..74bb035b2d 100644 --- a/docs/parse-draft.md +++ b/docs/parse-draft.md @@ -1,5 +1,5 @@ -This is a draft design document for a `Temporal.parse` API, which is not currently planned to be implemented for several reasons: -- `Temporal`'s approach to most operations—including parsing—is to encourage strong typing, e.g. `Temporal.Instant.from` vs. `Temporal.PlainDateTime.from`. A type-spanning "parse anything" API goes against that strongly-typed model. +This is a draft design document for a `Temporal.parse` API, which is not currently planned to be implemented for several reasons: +- `Temporal`'s approach to most operations—including parsing—is to encourage strong typing, e.g. `Temporal.Instant.from` vs. `Temporal.PlainDateTime.from`. A type-spanning "parse anything" API goes against that strongly-typed model. - The main use case beyond type-specific parsing that was identified for a `parse` API was handling "partially correct" ISO strings, e.g. where only one unit was out of range. Most of these use cases were addressed via the `overflow` option in the `from` method of all types which which either clamps out-of-range values (`'constrain'`) to the nearest in-range value or throws (`'reject'`) in that case. - The final remaining case for a `parse` API was resolving the case where a time zone and a time zone offset can be in conflict, as would happen for future `Temporal.ZonedDateTime` values stored before a country permanently abolishes DST. This use case is now handled via the `offset` option of `Temporal.ZonedDateTime.from`. diff --git a/docs/plaindate.md b/docs/plaindate.md index 0424241db0..8b779bf8a8 100644 --- a/docs/plaindate.md +++ b/docs/plaindate.md @@ -43,7 +43,7 @@ Usage examples: ```javascript // Pi day in 2020 -date = new Temporal.PlainDate(2020, 3, 14); // => 2020-03-14 +date = new Temporal.PlainDate(2020, 3, 14); // => '2020-03-14' ``` ## Static methods @@ -87,31 +87,33 @@ Additionally, if the result is earlier or later than the range of dates that `Te Example usage: ```javascript -date = Temporal.PlainDate.from('2006-08-24'); // => 2006-08-24 -date = Temporal.PlainDate.from('2006-08-24T15:43:27'); // => 2006-08-24 -date = Temporal.PlainDate.from('2006-08-24T15:43:27Z'); // => 2006-08-24 +date = Temporal.PlainDate.from('2006-08-24'); // => '2006-08-24' +date = Temporal.PlainDate.from('2006-08-24T15:43:27'); // => '2006-08-24' +date = Temporal.PlainDate.from('2006-08-24T15:43:27Z'); // => '2006-08-24' date = Temporal.PlainDate.from('2006-08-24T15:43:27+01:00[Europe/Brussels]'); - // => 2006-08-24 -date === Temporal.PlainDate.from(date) // => true + // => '2006-08-24' +date.equals(Temporal.PlainDate.from(date)); // => true -date = Temporal.PlainDate.from({year: 2006, month: 8, day: 24}); // => 2006-08-24 +date = Temporal.PlainDate.from({year: 2006, month: 8, day: 24}); // => '2006-08-24' date = Temporal.PlainDate.from(Temporal.PlainDateTime.from('2006-08-24T15:43:27')); - // => same as above; Temporal.PlainDateTime has year, month, and day properties + // => '2006-08-24' + // same as above; Temporal.PlainDateTime has year, month, and day properties calendar = Temporal.Calendar.from('islamic'); -date = Temporal.PlainDate.from({ year: 1427, month; 8, day: 1, calendar }); // => 2006-08-24[u-ca-islamic] +date = Temporal.PlainDate.from({ year: 1427, month: 8, day: 1, calendar }); // => '2006-08-24[u-ca-islamic]' date = Temporal.PlainDate.from({ year: 1427, month: 8, day: 1, calendar: 'islamic' }); - // => same as above + // => '2006-08-24[u-ca-islamic]' + // same as above // Different overflow modes date = Temporal.PlainDate.from({ year: 2001, month: 13, day: 1 }, { overflow: 'constrain' }) - // => 2001-12-01 -date = Temporal.PlainDate.from({ year: 2001, month: -1, day: 1 }, { overflow: 'constrain' }) - // => 2001-01-01 + // => '2001-12-01' +date = Temporal.PlainDate.from({ year: 2001, month: 1, day: 32 }, { overflow: 'constrain' }) + // => '2001-01-31' date = Temporal.PlainDate.from({ year: 2001, month: 13, day: 1 }, { overflow: 'reject' }) - // throws -date = Temporal.PlainDate.from({ year: 2001, month: -1, day: 1 }, { overflow: 'reject' }) - // throws + // => throws +date = Temporal.PlainDate.from({ year: 2001, month: 1, day: 32 }, { overflow: 'reject' }) + // => throws ``` ### Temporal.PlainDate.**compare**(_one_: Temporal.PlainDate | object | string, _two_: Temporal.PlainDate | object | string) : number @@ -143,7 +145,7 @@ one = Temporal.PlainDate.from('2006-08-24'); two = Temporal.PlainDate.from('2015-07-14'); three = Temporal.PlainDate.from('1930-02-18'); sorted = [one, two, three].sort(Temporal.PlainDate.compare); -sorted.join(' '); // => 1930-02-18 2006-08-24 2015-07-14 +sorted.join(' '); // => '1930-02-18 2006-08-24 2015-07-14' ``` ## Properties @@ -226,7 +228,7 @@ Usage example: ```javascript date = Temporal.PlainDate.from('2006-08-24'); -['MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT', 'SUN'][date.dayOfWeek - 1]; // => THU +['MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT', 'SUN'][date.dayOfWeek - 1]; // => 'THU' ``` ### date.**dayOfYear** : number @@ -239,7 +241,7 @@ Usage example: ```javascript date = Temporal.PlainDate.from('2006-08-24'); // ISO ordinal date -console.log(date.year, date.dayOfYear); // => 2006 236 +console.log(date.year, date.dayOfYear); // => '2006 236' ``` ### date.**weekOfYear** : number @@ -254,7 +256,7 @@ Usage example: ```javascript date = Temporal.PlainDate.from('2006-08-24'); // ISO week date -console.log(date.year, date.weekOfYear, date.dayOfWeek); // => 2006 34 4 +console.log(date.year, date.weekOfYear, date.dayOfWeek); // => '2006 34 4' ``` ### date.**daysInWeek** : number @@ -278,9 +280,10 @@ Usage example: ```javascript // Attempt to write some mnemonic poetry +({ calendar } = Intl.DateTimeFormat().resolvedOptions()); const monthsByDays = {}; for (let month = 1; month <= 12; month++) { - const date = Temporal.now.plainDate().with({ month }); + const date = Temporal.now.plainDate(calendar).with({ month }); monthsByDays[date.daysInMonth] = (monthsByDays[date.daysInMonth] || []).concat(date); } @@ -301,7 +304,8 @@ For the ISO 8601 calendar, this is 365 or 366, depending on whether the year is Usage example: ```javascript -date = Temporal.now.plainDate(); +({ calendar } = Intl.DateTimeFormat().resolvedOptions()); +date = Temporal.now.plainDate(calendar); percent = date.dayOfYear / date.daysInYear; `The year is ${percent.toLocaleString('en', { style: 'percent' })} over!`; // example output: "The year is 10% over!" @@ -328,7 +332,8 @@ Usage example: ```javascript // Is this year a leap year? -date = Temporal.now.plainDate(); +({ calendar } = Intl.DateTimeFormat().resolvedOptions()); +date = Temporal.now.plainDate(calendar); date.inLeapYear; // example output: true // Is 2100 a leap year? (no, because it's divisible by 100 and not 400) date.with({ year: 2100 }).inLeapYear; // => false @@ -365,10 +370,10 @@ Usage example: ```javascript date = Temporal.PlainDate.from('2006-01-24'); // What's the first day of this month? -date.with({ day: 1 }); // => 2006-01-01 +date.with({ day: 1 }); // => '2006-01-01' // What's the last day of the next month? const nextMonthDate = date.add({ months: 1 }); -nextMonthDate.with({ day: nextMonthDate.daysInMonth }); // => 2006-02-28 +nextMonthDate.with({ day: nextMonthDate.daysInMonth }); // => '2006-02-28' ``` ### date.**withCalendar**(_calendar_: object | string) : Temporal.PlainDate @@ -385,7 +390,7 @@ Usage example: ```javascript date = Temporal.PlainDate.from('2006-08-24[u-ca-japanese]'); -date.withCalendar('iso8601'); // => 2006-08-24 +date.withCalendar('iso8601'); // => '2006-08-24' ``` ### date.**add**(_duration_: Temporal.Duration | object | string, _options_?: object) : Temporal.PlainDate @@ -421,10 +426,10 @@ Usage example: ```javascript date = Temporal.PlainDate.from('2006-08-24'); -date.add({ years: 20, months: 4 }); // => 2026-12-24 +date.add({ years: 20, months: 4 }); // => '2026-12-24' date = Temporal.PlainDate.from('2019-01-31'); -date.add({ months: 1 }); // => 2019-02-28 +date.add({ months: 1 }); // => '2019-02-28' date.add({ months: 1 }, { overflow: 'reject' }); // => throws ``` @@ -461,10 +466,10 @@ Usage example: ```javascript date = Temporal.PlainDate.from('2006-08-24'); -date.subtract({ years: 20, months: 4 }); // => 1986-04-24 +date.subtract({ years: 20, months: 4 }); // => '1986-04-24' date = Temporal.PlainDate.from('2019-03-31'); -date.subtract({ months: 1 }); // => 2019-02-28 +date.subtract({ months: 1 }); // => '2019-02-28' date.subtract({ months: 1 }, { overflow: 'reject' }); // => throws ``` @@ -520,9 +525,9 @@ Usage example: ```javascript earlier = Temporal.PlainDate.from('2006-08-24'); later = Temporal.PlainDate.from('2019-01-31'); -earlier.until(later); // => P4543D -earlier.until(later, { largestUnit: 'years' }); // => P12Y5M7D -later.until(earlier, { largestUnit: 'years' }); // => -P12Y5M7D +earlier.until(later); // => 'P4543D' +earlier.until(later, { largestUnit: 'years' }); // => 'P12Y5M7D' +later.until(earlier, { largestUnit: 'years' }); // => '-P12Y5M7D' // If you really need to calculate the difference between two Dates in // hours, you can eliminate the ambiguity by explicitly choosing the @@ -530,7 +535,7 @@ later.until(earlier, { largestUnit: 'years' }); // => -P12Y5M7D // example, using noon: noon = Temporal.PlainTime.from('12:00'); earlier.toPlainDateTime(noon).until(later.toPlainDateTime(noon), { largestUnit: 'hours' }); - // => PT109032H + // => 'PT109032H' ``` @@ -567,7 +572,7 @@ Usage example: ```javascript earlier = Temporal.PlainDate.from('2006-08-24'); later = Temporal.PlainDate.from('2019-01-31'); -later.since(earlier); // => P4543D +later.since(earlier); // => 'P4543D' ``` ### date.**equals**(_other_: Temporal.PlainDate | object | string) : boolean @@ -620,7 +625,7 @@ Example usage: ```js date = Temporal.PlainDate.from('2006-08-24'); -date.toString(); // => 2006-08-24 +date.toString(); // => '2006-08-24' ``` ### date.**toLocaleString**(_locales_?: string | array<string>, _options_?: object) : string @@ -640,10 +645,10 @@ Example usage: ```js date = Temporal.PlainDate.from('2006-08-24'); -date.toLocaleString(); // => example output: 8/24/2006 -date.toLocaleString('de-DE'); // => example output: 24.8.2006 -date.toLocaleString('de-DE', { weekday: 'long' }); // => Donnerstag -date.toLocaleString('en-US-u-nu-fullwide'); // => 8/24/2006 +date.toLocaleString(); // example output: 8/24/2006 +date.toLocaleString('de-DE'); // => '24.8.2006' +date.toLocaleString('de-DE', { weekday: 'long' }); // => 'Donnerstag' +date.toLocaleString('en-US-u-nu-fullwide'); // => '8/24/2006' ``` ### date.**toJSON**() : string @@ -727,9 +732,9 @@ Usage example: plainDate = Temporal.PlainDate.from('2006-08-24'); plainTime = Temporal.PlainTime.from('15:23:30.003'); plainDate.toZonedDateTime({ timeZone: 'America/Los_Angeles', plainTime }); -// => 2006-08-24T15:23:30.003-07:00[America/Los_Angeles] +// => '2006-08-24T15:23:30.003-07:00[America/Los_Angeles]' plainDate.toZonedDateTime({ timeZone: 'America/Los_Angeles' }); -// => 2006-08-24T00:00-07:00[America/Los_Angeles] +// => '2006-08-24T00:00:00-07:00[America/Los_Angeles]' ``` ### date.**toPlainDateTime**(_time_?: Temporal.PlainTime | object | string) : Temporal.PlainDateTime @@ -753,8 +758,8 @@ Usage example: ```javascript date = Temporal.PlainDate.from('2006-08-24'); time = Temporal.PlainTime.from('15:23:30.003'); -date.toPlainDateTime(time); // => 2006-08-24T15:23:30.003 -date.toPlainDateTime(); // => 2006-08-24T00:00 +date.toPlainDateTime(time); // => '2006-08-24T15:23:30.003' +date.toPlainDateTime(); // => '2006-08-24T00:00:00' ``` ### date.**toPlainYearMonth**() : Temporal.PlainYearMonth @@ -772,8 +777,8 @@ Usage example: ```javascript date = Temporal.PlainDate.from('2006-08-24'); -date.toPlainYearMonth(); // => 2006-08 -date.toPlainMonthDay(); // => 08-24 +date.toPlainYearMonth(); // => '2006-08' +date.toPlainMonthDay(); // => '08-24' ``` ### date.**getISOFields**(): { isoYear: number, isoMonth: number, isoDay: number, calendar: object } diff --git a/docs/plaindatetime.md b/docs/plaindatetime.md index 2ca1894b82..26133f2fe6 100644 --- a/docs/plaindatetime.md +++ b/docs/plaindatetime.md @@ -71,7 +71,7 @@ Usage examples: ```javascript // Leet hour on pi day in 2020 -datetime = new Temporal.PlainDateTime(2020, 3, 14, 13, 37); // => 2020-03-14T13:37 +datetime = new Temporal.PlainDateTime(2020, 3, 14, 13, 37); // => '2020-03-14T13:37:00' ``` ## Static methods @@ -123,10 +123,11 @@ Example usage: ```javascript dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30'); -dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30Z'); // => 1995-12-07T03:24:30 +dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30Z'); // => '1995-12-07T03:24:30' dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30+01:00[Europe/Brussels]'); - // => same as above; time zone is ignored -dt === Temporal.PlainDateTime.from(dt); // => true + // => '1995-12-07T03:24:30' + // same as above; time zone is ignored +dt.equals(Temporal.PlainDateTime.from(dt)); // => true dt = Temporal.PlainDateTime.from({ year: 1995, @@ -138,34 +139,34 @@ dt = Temporal.PlainDateTime.from({ millisecond: 0, microsecond: 3, nanosecond: 500 -}); // => 1995-12-07T03:24:30.000003500 -dt = Temporal.PlainDateTime.from({ year: 1995, month: 12, day: 7 }); // => 1995-12-07T00:00 +}); // => '1995-12-07T03:24:30.0000035' +dt = Temporal.PlainDateTime.from({ year: 1995, month: 12, day: 7 }); // => '1995-12-07T00:00:00' dt = Temporal.PlainDateTime.from(Temporal.PlainDate.from('1995-12-07T03:24:30')); - // => same as above; Temporal.PlainDate has year, month, and day properties + // => '1995-12-07T00:00:00' + // same as above; Temporal.PlainDate has year, month, and day properties calendar = Temporal.Calendar.from('hebrew'); dt = Temporal.PlainDateTime.from({ year: 5756, month: 3, day: 14, hour: 3, minute: 24, second: 30, calendar }); - // => 1995-12-07T03:24:30[u-ca-hebrew] + // => '1995-12-07T03:24:30[u-ca-hebrew]' dt = Temporal.PlainDateTime.from({ year: 5756, month: 3, day: 14, hour: 3, minute: 24, second: 30, calendar: 'hebrew' }); - // => same as above + // => '1995-12-07T03:24:30[u-ca-hebrew]' + // same as above // Different overflow modes dt = Temporal.PlainDateTime.from({ year: 2001, month: 13, day: 1 }, { overflow: 'constrain' }); - // => 2001-12-01T00:00 -dt = Temporal.PlainDateTime.from({ year: 2001, month: -1, day: 1 }, { overflow: 'constrain' }); - // => 2001-01-01T00:00 + // => '2001-12-01T00:00:00' +dt = Temporal.PlainDateTime.from({ year: 2001, month: 1, day: 32 }, { overflow: 'constrain' }); + // => '2001-01-31T00:00:00' dt = Temporal.PlainDateTime.from({ year: 2001, month: 1, day: 1, hour: 25 }, { overflow: 'constrain' }); - // => 2001-01-01T23:00 + // => '2001-01-01T23:00:00' dt = Temporal.PlainDateTime.from({ year: 2001, month: 1, day: 1, minute: 60 }, { overflow: 'constrain' }); - // => 2001-01-01T00:59 -dt = Temporal.PlainDateTime.from({ year: 2001, month: 1, day: 1, minute: 60 }, { overflow: 'constrain' }); - // => 2001-01-01T01:00 + // => '2001-01-01T00:59:00' dt = Temporal.PlainDateTime.from({ year: 2001, month: 13, day: 1 }, { overflow: 'reject' }); - // throws -dt = Temporal.PlainDateTime.from({ year: 2001, month: -1, day: 1 }, { overflow: 'reject' }); - // throws + // => throws +dt = Temporal.PlainDateTime.from({ year: 2001, month: 1, day: 32 }, { overflow: 'reject' }); + // => throws dt = Temporal.PlainDateTime.from({ year: 2001, month: 1, day: 1, hour: 25 }, { overflow: 'reject' }); - // throws + // => throws dt = Temporal.PlainDateTime.from({ year: 2001, month: 1, day: 1, minute: 60 }, { overflow: 'reject' }); // => throws ``` @@ -201,7 +202,7 @@ two = Temporal.PlainDateTime.from('1995-12-07T01:24'); three = Temporal.PlainDateTime.from('2015-12-07T01:24'); sorted = [one, two, three].sort(Temporal.PlainDateTime.compare); sorted.join(' '); -// => 1995-12-07T01:24 1995-12-07T03:24 2015-12-07T01:24 +// => '1995-12-07T01:24:00 1995-12-07T03:24:00 2015-12-07T01:24:00' ``` ## Properties @@ -277,7 +278,7 @@ dt.millisecond; // => 0 dt.microsecond; // => 3 dt.nanosecond; // => 500 -dt = Temporal.PlainDate.from('2019-02-23T03:24:30.000003500[u-ca-hebrew]'); +dt = Temporal.PlainDateTime.from('2019-02-23T03:24:30.000003500[u-ca-hebrew]'); dt.year; // => 5779 dt.month; // => 6 dt.monthCode; // => "M05L" @@ -324,7 +325,7 @@ Usage example: ```javascript dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); -['MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT', 'SUN'][dt.dayOfWeek - 1]; // => THU +['MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT', 'SUN'][dt.dayOfWeek - 1]; // => 'THU' ``` ### datetime.**dayOfYear** : number @@ -337,7 +338,7 @@ Usage example: ```javascript dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); // ISO ordinal date -console.log(dt.year, dt.dayOfYear); // => 1995 341 +console.log(dt.year, dt.dayOfYear); // => '1995 341' ``` ### datetime.**weekOfYear** : number @@ -352,7 +353,7 @@ Usage example: ```javascript dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); // ISO week date -console.log(dt.year, dt.weekOfYear, dt.dayOfWeek); // => 1995 49 4 +console.log(dt.year, dt.weekOfYear, dt.dayOfWeek); // => '1995 49 4' ``` ### datetime.**daysInWeek** : number @@ -376,9 +377,10 @@ Usage example: ```javascript // Attempt to write some mnemonic poetry +({ calendar } = Intl.DateTimeFormat().resolvedOptions()); const monthsByDays = {}; for (let month = 1; month <= 12; month++) { - const dt = Temporal.now.plainDateTime().with({ month }); + const dt = Temporal.now.plainDateTime(calendar).with({ month }); monthsByDays[dt.daysInMonth] = (monthsByDays[dt.daysInMonth] || []).concat(dt); } @@ -399,7 +401,8 @@ For the ISO 8601 calendar, this is 365 or 366, depending on whether the year is Usage example: ```javascript -dt = Temporal.now.plainDateTime(); +({ calendar } = Intl.DateTimeFormat().resolvedOptions()); +dt = Temporal.now.plainDateTime(calendar); percent = dt.dayOfYear / dt.daysInYear; `The year is ${percent.toLocaleString('en', { style: 'percent' })} over!`; // example output: "The year is 10% over!" @@ -426,7 +429,7 @@ Usage example: ```javascript // Is this year a leap year? -dt = Temporal.now.plainDateTime(); +dt = Temporal.now.plainDateTime('iso8601'); dt.inLeapYear; // example output: true // Is 2100 a leap year? (no, because it's divisible by 100 and not 400) dt.with({ year: 2100 }).inLeapYear; // => false @@ -462,7 +465,7 @@ Usage example: ```javascript dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); -dt.with({ year: 2015, second: 31 }); // => 2015-12-07T03:24:31.000003500 +dt.with({ year: 2015, second: 31 }); // => '2015-12-07T03:24:31.0000035' ``` ### datetime.**withPlainTime**(_plainTime_?: object | string) : Temporal.PlainDateTime @@ -488,13 +491,13 @@ Usage example: ```javascript dt = Temporal.PlainDateTime.from('2015-12-07T03:24:30.000003500'); -dt.withPlainTime({ hour: 10 }); // => 2015-12-07T10:00:00 +dt.withPlainTime({ hour: 10 }); // => '2015-12-07T10:00:00' time = Temporal.PlainTime.from('11:22'); -dt.withPlainTime(time); // => 2015-12-07T11:22:00 -dt.withPlainTime('12:34'); // => 2015-12-07T12:34:00 +dt.withPlainTime(time); // => '2015-12-07T11:22:00' +dt.withPlainTime('12:34'); // => '2015-12-07T12:34:00' // easier for chaining -dt.add({ days: 2, hours: 22 }).withPlainTime('00:00'); // => 2015-12-10T00:00:00 +dt.add({ days: 2, hours: 22 }).withPlainTime('00:00'); // => '2015-12-10T00:00:00' ``` ### datetime.**withPlainDate**(_plainDate_: object | string) : Temporal.PlainDateTime @@ -527,17 +530,17 @@ Usage example: ```javascript dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30'); -dt.withPlainDate({ year: 2000, month: 6, day: 1 }); // => 2000-06-01T03:24:30 +dt.withPlainDate({ year: 2000, month: 6, day: 1 }); // => '2000-06-01T03:24:30' date = Temporal.PlainDate.from('2020-01-23'); -dt.withPlainDate(date); // => 2020-01-23T03:24:30 -dt.withPlainDate('2018-09-15'); // => 2018-09-15T03:24:30 +dt.withPlainDate(date); // => '2020-01-23T03:24:30' +dt.withPlainDate('2018-09-15'); // => '2018-09-15T03:24:30' // easier for chaining -dt.add({ hours: 12 }).withPlainDate('2000-06-01'); // => 2000-06-01T15:24:30 +dt.add({ hours: 12 }).withPlainDate('2000-06-01'); // => '2000-06-01T15:24:30' // result contains a non-ISO calendar if present in the input -dt.withCalendar('japanese').withPlainDate('2008-09-06'); // => 2008-09-06T03:24:30[u-ca-japanese] -dt.withPlainDate('2017-09-06[u-ca-japanese]'); // => 2017-09-06T03:24:30[u-ca-japanese] +dt.withCalendar('japanese').withPlainDate('2008-09-06'); // => '2008-09-06T03:24:30[u-ca-japanese]' +dt.withPlainDate('2017-09-06[u-ca-japanese]'); // => '2017-09-06T03:24:30[u-ca-japanese]' dt.withCalendar('japanese').withPlainDate('2017-09-06[u-ca-hebrew]'); // => RangeError (calendar conflict) ``` @@ -555,7 +558,7 @@ Usage example: ```javascript dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500[u-ca-japanese]'); -dt.withCalendar('iso8601'); // => 1995-12-07T03:24:30.000003500 +dt.withCalendar('iso8601'); // => '1995-12-07T03:24:30.0000035' ``` ### datetime.**add**(_duration_: Temporal.Duration | object | string, _options_?: object) : Temporal.PlainDateTime @@ -591,10 +594,10 @@ Usage example: ```javascript dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); -dt.add({ years: 20, months: 4, nanoseconds: 500 }); // => 2016-04-07T03:24:30.000004 +dt.add({ years: 20, months: 4, nanoseconds: 500 }); // => '2016-04-07T03:24:30.000004' dt = Temporal.PlainDateTime.from('2019-01-31T15:30'); -dt.add({ months: 1 }); // => 2019-02-28T15:30 +dt.add({ months: 1 }); // => '2019-02-28T15:30:00' dt.add({ months: 1 }, { overflow: 'reject' }); // => throws ``` @@ -631,11 +634,11 @@ Usage example: ```javascript dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); -dt.subtract({ years: 20, months: 4, nanoseconds: 500 }); // => 1975-08-07T03:24:30.000003 +dt.subtract({ years: 20, months: 4, nanoseconds: 500 }); // => '1975-08-07T03:24:30.000003' dt = Temporal.PlainDateTime.from('2019-03-31T15:30'); -dt.subtract({ months: 1 }, { overflow: 'constrain' }); // => 2019-02-28T15:30 -dt.subtract({ months: 1 }); // => throws +dt.subtract({ months: 1 }); // => '2019-02-28T15:30:00' +dt.subtract({ months: 1 }, { overflow: 'reject' }); // => throws ``` ### datetime.**until**(_other_: Temporal.PlainDateTime | object | string, _options_?: object) : Temporal.Duration @@ -693,26 +696,27 @@ Usage example: dt1 = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); dt2 = Temporal.PlainDateTime.from('2019-01-31T15:30'); dt1.until(dt2); - // => P8456DT12H5M29.999996500S + // => 'P8456DT12H5M29.9999965S' dt1.until(dt2, { largestUnit: 'years' }); - // => P23Y1M24DT12H5M29.999996500S + // => 'P23Y1M24DT12H5M29.9999965S' dt2.until(dt1, { largestUnit: 'years' }); - // => -P23Y1M24DT12H5M29.999996500S + // => '-P23Y1M24DT12H5M29.9999965S' dt1.until(dt2, { largestUnit: 'nanoseconds' }); - // => PT730641929.999996544S (precision lost) + // => 'PT730641929.999996544S' + // (precision lost) // Rounding, for example if you don't care about sub-seconds dt1.until(dt2, { smallestUnit: 'seconds' }); - // => P8456DT12H5M29S + // => 'P8456DT12H5M29S' // Months and years can be different lengths -[jan1, feb1, mar1] = [1, 2, 3].map((month) => +let [jan1, feb1, mar1] = [1, 2, 3].map((month) => Temporal.PlainDateTime.from({ year: 2020, month, day: 1 })); -jan1.until(feb1); // => P31D -jan1.until(feb1, { largestUnit: 'months' }); // => P1M -feb1.until(mar1); // => P29D -feb1.until(mar1, { largestUnit: 'months' }); // => P1M -jan1.until(mar1); // => P60D +jan1.until(feb1); // => 'P31D' +jan1.until(feb1, { largestUnit: 'months' }); // => 'P1M' +feb1.until(mar1); // => 'P29D' +feb1.until(mar1, { largestUnit: 'months' }); // => 'P1M' +jan1.until(mar1); // => 'P60D' ``` @@ -749,7 +753,7 @@ Usage example: ```javascript dt1 = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); dt2 = Temporal.PlainDateTime.from('2019-01-31T15:30'); -dt2.since(dt1); // => P8456DT12H5M29.999996500S +dt2.since(dt1); // => 'P8456DT12H5M29.9999965S' ``` ### datetime.**round**(_options_: object) : Temporal.PlainDateTime @@ -799,13 +803,13 @@ Example usage: dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); // Round to a particular unit -dt.round({ smallestUnit: 'hour' }); // => 1995-12-07T03:00 +dt.round({ smallestUnit: 'hour' }); // => '1995-12-07T03:00:00' // Round to an increment of a unit, e.g. half an hour: dt.round({ roundingIncrement: 30, smallestUnit: 'minute' }); - // => 1995-12-07T03:30 + // => '1995-12-07T03:30:00' // Round to the same increment but round down instead: dt.round({ roundingIncrement: 30, smallestUnit: 'minute', roundingMode: 'floor' }); - // => 1995-12-07T03:00 + // => '1995-12-07T03:00:00' ``` @@ -885,13 +889,13 @@ dt = Temporal.PlainDateTime.from({ microsecond: 999, nanosecond: 999 }); -dt.toString(); // => 1999-12-31T23:59:59.999999999 +dt.toString(); // => '1999-12-31T23:59:59.999999999' -dt.toString({ smallestUnit: 'minute' }); // => 1999-12-31T23:59 -dt.toString({ fractionalSecondDigits: 0 }); // => 1999-12-31T23:59:59 -dt.toString({ fractionalSecondDigits: 4 }); // => 1999-12-31T23:59:59.9999 +dt.toString({ smallestUnit: 'minute' }); // => '1999-12-31T23:59' +dt.toString({ fractionalSecondDigits: 0 }); // => '1999-12-31T23:59:59' +dt.toString({ fractionalSecondDigits: 4 }); // => '1999-12-31T23:59:59.9999' dt.toString({ fractionalSecondDigits: 8, roundingMode: 'nearest' }); -// => 2000-01-01T00:00:00.00000000 +// => '2000-01-01T00:00:00.00000000' ``` @@ -916,10 +920,10 @@ Example usage: ```js dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); -dt.toLocaleString(); // => example output: 1995-12-07, 3:24:30 a.m. -dt.toLocaleString('de-DE'); // => example output: 7.12.1995, 03:24:30 -dt.toLocaleString('de-DE', { timeZone: 'Europe/Berlin', weekday: 'long' }); // => Donnerstag -dt.toLocaleString('en-US-u-nu-fullwide-hc-h12'); // => 12/7/1995, 3:24:30 AM +dt.toLocaleString(); // example output: 1995-12-07, 3:24:30 a.m. +dt.toLocaleString('de-DE'); // example output: 7.12.1995, 03:24:30 +dt.toLocaleString('de-DE', { timeZone: 'Europe/Berlin', weekday: 'long' }); // => 'Donnerstag' +dt.toLocaleString('en-US-u-nu-fullwide-hc-h12'); // => '12/7/1995, 3:24:30 AM' ``` ### datetime.**toJSON**() : string @@ -1024,10 +1028,10 @@ Usage example: ```javascript dt = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500'); -dt.toPlainDate(); // => 1995-12-07 -dt.toPlainYearMonth(); // => 1995-12 -dt.toPlainMonthDay(); // => 12-07 -dt.toPlainTime(); // => 03:24:30.000003500 +dt.toPlainDate(); // => '1995-12-07' +dt.toPlainYearMonth(); // => '1995-12' +dt.toPlainMonthDay(); // => '12-07' +dt.toPlainTime(); // => '03:24:30.0000035' ``` ### datetime.**getISOFields**(): { isoYear: number, isoMonth: number, isoDay: number, isoHour: number, isoMinute: number, isoSecond: number, isoMillisecond: number, isoMicrosecond: number, isoNanosecond: number, calendar: object } diff --git a/docs/plainmonthday.md b/docs/plainmonthday.md index 7698c7edd5..dc8f93a0e3 100644 --- a/docs/plainmonthday.md +++ b/docs/plainmonthday.md @@ -41,9 +41,9 @@ Usage examples: ```javascript // Pi day -md = new Temporal.PlainMonthDay(3, 14); // => 03-14 +md = new Temporal.PlainMonthDay(3, 14); // => '03-14' // Leap day -md = new Temporal.PlainMonthDay(2, 29); // => 02-29 +md = new Temporal.PlainMonthDay(2, 29); // => '02-29' ``` ## Static methods @@ -89,41 +89,43 @@ The `overflow` option is ignored if `thing` is a string. Example usage: ```javascript -md = Temporal.PlainMonthDay.from('08-24'); // => 08-24 -md = Temporal.PlainMonthDay.from('2006-08-24'); // => 08-24 -md = Temporal.PlainMonthDay.from('2006-08-24T15:43:27'); // => 08-24 -md = Temporal.PlainMonthDay.from('2006-08-24T15:43:27Z'); // => 08-24 +md = Temporal.PlainMonthDay.from('08-24'); // => '08-24' +md = Temporal.PlainMonthDay.from('2006-08-24'); // => '08-24' +md = Temporal.PlainMonthDay.from('2006-08-24T15:43:27'); // => '08-24' +md = Temporal.PlainMonthDay.from('2006-08-24T15:43:27Z'); // => '08-24' md = Temporal.PlainMonthDay.from('2006-08-24T15:43:27+01:00[Europe/Brussels]'); -// => 08-24 -md === Temporal.PlainMonthDay.from(md); // => true +// => '08-24' +md.equals(Temporal.PlainMonthDay.from(md)); // => true -md = Temporal.PlainMonthDay.from({ monthCode: 'M08', day: 24 }); // => 08-24 +md = Temporal.PlainMonthDay.from({ monthCode: 'M08', day: 24 }); // => '08-24' md = Temporal.PlainMonthDay.from(Temporal.PlainDate.from('2006-08-24')); -// => same as above; Temporal.PlainDate has month and day properties +// => '08-24' +// (same as above; Temporal.PlainDate has month and day properties) // Different overflow modes md = Temporal.PlainMonthDay.from({ month: 13, day: 1, year: 2000 }, { overflow: 'constrain' }); -// => 12-01 -md = Temporal.PlainMonthDay.from({ month: -1, day: 1, year: 2000 }, { overflow: 'constrain' }); -// => 01-01 +// => '12-01' +md = Temporal.PlainMonthDay.from({ month: 1, day: 32, year: 2000 }, { overflow: 'constrain' }); +// => '01-31' md = Temporal.PlainMonthDay.from({ month: 13, day: 1, year: 2000 }, { overflow: 'reject' }); -// throws -md = Temporal.PlainMonthDay.from({ month: -1, day: 1, year: 2000 }, { overflow: 'reject' }); -// throws +// => throws +md = Temporal.PlainMonthDay.from({ month: 1, day: 32, year: 2000 }, { overflow: 'reject' }); +// => throws md = Temporal.PlainMonthDay.from({ month: 2, day: 29, year: 2001 }, { overflow: 'reject' }); -// throws (this year is not a leap year in the ISO calendar) +// => throws (this year is not a leap year in the ISO calendar) // non-ISO calendars md = Temporal.PlainMonthDay.from({ monthCode: 'M05L', day: 15, calendar: 'hebrew' }); -// => 2019-02-20[u-ca-hebrew] +// => '2019-02-20[u-ca-hebrew]' md = Temporal.PlainMonthDay.from({ month: 6, day: 15, year: 5779, calendar: 'hebrew' }); -// => 2019-02-20[u-ca-hebrew] +// => '2019-02-20[u-ca-hebrew]' md = Temporal.PlainMonthDay.from({ month: 6, day: 15, calendar: 'hebrew' }); // => throws (either year or monthCode is required) md = Temporal.PlainMonthDay.from('2019-02-20[u-ca-hebrew]'); md.monthCode; // => "M05L" md.day; // => 15 -md.month; // undefined (month property is not present in this type; use monthCode instead) +md.month; // undefined +// (month property is not present in this type; use monthCode instead) ``` ## Properties @@ -202,8 +204,8 @@ Usage example: ```javascript md = Temporal.PlainMonthDay.from('11-15'); // What's the last day of that month? -md.with({ day: 31 }); // => 11-30 -Temporal.PlainMonthDay.from('02-01').with({ day: 31 }); // => 02-29 +md.with({ day: 31 }); // => '11-30' +Temporal.PlainMonthDay.from('02-01').with({ day: 31 }); // => '02-29' ``` ### monthDay.**equals**(_other_: Temporal.PlainMonthDay | object | string) : boolean @@ -254,7 +256,7 @@ Example usage: ```js md = Temporal.PlainMonthDay.from('08-24'); -md.toString(); // => 08-24 +md.toString(); // => '08-24' ``` ### monthDay.**toLocaleString**(_locales_?: string | array<string>, _options_?: object) : string @@ -286,15 +288,16 @@ monthDay.toLocaleString(); Example usage: ```js +let calendar; ({ calendar } = new Intl.DateTimeFormat().resolvedOptions()); md = Temporal.PlainMonthDay.from({ monthCode: 'M08', day: 24, calendar }); -md.toLocaleString(); // => example output: 08-24 +md.toLocaleString(); // => '8/24' // Same as above, but explicitly specifying the calendar: -md.toLocaleString(undefined, { calendar }); +md.toLocaleString(undefined, { calendar }); // => '8/24' -md.toLocaleString('de-DE', { calendar }); // => example output: 24.8. -md.toLocaleString('de-DE', { month: 'long', day: 'numeric', calendar }); // => 24. August -md.toLocaleString(`en-US-u-nu-fullwide-u-ca-${calendar}`); // => 8/24 +md.toLocaleString('de-DE', { calendar }); // => '24.8.' +md.toLocaleString('de-DE', { month: 'long', day: 'numeric', calendar }); // => '24. August' +md.toLocaleString(`en-US-u-nu-fullwide-ca-${calendar}`); // => '8/24' ``` ### monthDay.**toJSON**() : string @@ -352,11 +355,11 @@ Usage example: ```javascript md = Temporal.PlainMonthDay.from('08-24'); -md.toPlainDate({ year: 2017 }); // => 2017-08-24 +md.toPlainDate({ year: 2017 }); // => '2017-08-24' md = Temporal.PlainMonthDay.from('02-29'); -md.toPlainDate({ year: 2020 }); // => 2020-02-29 -md.toPlainDate({ year: 2017 }); // => 2017-02-28 +md.toPlainDate({ year: 2020 }); // => '2020-02-29' +md.toPlainDate({ year: 2017 }); // => '2017-02-28' ``` In calendars where more information than just the year is needed to convert a `Temporal.PlainMonthDay` to a `Temporal.PlainDate`, you can pass the necessary properties in the _year_ object. @@ -370,7 +373,7 @@ md = Temporal.PlainMonthDay.from({ day: 1 }); -date = md.toPlainDate({ era: 'reiwa', eraYear: 2 }); +date = md.toPlainDate({ era: 'reiwa', eraYear: 2 }); // => '2020-01-01[u-ca-japanese]' ``` ### monthDay.**getISOFields**(): { isoYear: number, isoMonth: number, isoDay: number, calendar: object } diff --git a/docs/plaintime.md b/docs/plaintime.md index a7fdf4a554..7e3dbfaa86 100644 --- a/docs/plaintime.md +++ b/docs/plaintime.md @@ -37,7 +37,7 @@ Usage examples: ```javascript // Leet hour -time = new Temporal.PlainTime(13, 37); // => 13:37 +time = new Temporal.PlainTime(13, 37); // => '13:37:00' ``` ## Static methods @@ -81,12 +81,13 @@ Example usage: ```javascript -time = Temporal.PlainTime.from('03:24:30'); // => 03:24:30 -time = Temporal.PlainTime.from('1995-12-07T03:24:30'); // => 03:24:30 -time = Temporal.PlainTime.from('1995-12-07T03:24:30Z'); // => 03:24:30 +time = Temporal.PlainTime.from('03:24:30'); // => '03:24:30' +time = Temporal.PlainTime.from('1995-12-07T03:24:30'); // => '03:24:30' +time = Temporal.PlainTime.from('1995-12-07T03:24:30Z'); // => '03:24:30' time = Temporal.PlainTime.from('1995-12-07T03:24:30+01:00[Europe/Brussels]'); - // => same as above; time zone is ignored -time === Temporal.PlainTime.from(time); // => true + // => '03:24:30' + // (same as above; time zone is ignored) +time.equals(Temporal.PlainTime.from(time)); // => true time = Temporal.PlainTime.from({ hour: 19, @@ -95,20 +96,21 @@ time = Temporal.PlainTime.from({ millisecond: 68, microsecond: 346, nanosecond: 205 -}); // => 19:39:09.068346205 -time = Temporal.PlainTime.from({ hour: 19, minute: 39, second: 9 }); // => 19:39:09 +}); // => '19:39:09.068346205' +time = Temporal.PlainTime.from({ hour: 19, minute: 39, second: 9 }); // => '19:39:09' time = Temporal.PlainTime.from(Temporal.PlainDateTime.from('2020-02-15T19:39:09')); - // => same as above; Temporal.PlainDateTime has hour, minute, etc. properties + // => '19:39:09' + // (same as above; Temporal.PlainDateTime has hour, minute, etc. properties) // Different overflow modes time = Temporal.PlainTime.from({ hour: 15, minute: 60 }, { overflow: 'constrain' }); - // => 15:59 + // => '15:59:00' time = Temporal.PlainTime.from({ hour: 15, minute: -1 }, { overflow: 'constrain' }); - // => 15:00 + // => '15:00:00' time = Temporal.PlainTime.from({ hour: 15, minute: 60 }, { overflow: 'reject' }); - // throws + // => throws time = Temporal.PlainTime.from({ hour: 15, minute: -1 }, { overflow: 'reject' }); - // throws + // => throws ``` @@ -138,7 +140,7 @@ one = Temporal.PlainTime.from('03:24'); two = Temporal.PlainTime.from('01:24'); three = Temporal.PlainTime.from('01:24:05'); sorted = [one, two, three].sort(Temporal.PlainTime.compare); -sorted.join(' '); // => 01:24 01:24:05 03:24 +sorted.join(' '); // => '01:24:00 01:24:05 03:24:00' ``` ## Properties @@ -208,7 +210,7 @@ time.add({ hours: 1 }).with({ millisecond: 0, microsecond: 0, nanosecond: 0 -}); // => 20:00 +}); // => '20:00:00' ``` ### time.**add**(_duration_: Temporal.Duration | object | string) : Temporal.PlainTime @@ -231,7 +233,7 @@ Usage example: ```javascript time = Temporal.PlainTime.from('19:39:09.068346205'); -time.add({ minutes: 5, nanoseconds: 800 }); // => 19:44:09.068347005 +time.add({ minutes: 5, nanoseconds: 800 }); // => '19:44:09.068347005' ``` ### time.**subtract**(_duration_: Temporal.Duration | object | string) : Temporal.PlainTime @@ -254,7 +256,7 @@ Usage example: ```javascript time = Temporal.PlainTime.from('19:39:09.068346205'); -time.subtract({ minutes: 5, nanoseconds: 800 }); // => 19:34:09.068345405 +time.subtract({ minutes: 5, nanoseconds: 800 }); // => '19:34:09.068345405' ``` ### time.**until**(_other_: Temporal.PlainTime | object | string, _options_?: object) : Temporal.Duration @@ -302,12 +304,12 @@ Usage example: ```javascript time = Temporal.PlainTime.from('20:13:20.971398099'); -time.until(Temporal.PlainTime.from('22:39:09.068346205')); // => PT2H25M48.096948106S -time.until(Temporal.PlainTime.from('19:39:09.068346205')); // => -PT34M11.903051894S +time.until(Temporal.PlainTime.from('22:39:09.068346205')); // => 'PT2H25M48.096948106S' +time.until(Temporal.PlainTime.from('19:39:09.068346205')); // => '-PT34M11.903051894S' // Rounding, for example if you don't care about sub-seconds time.until(Temporal.PlainTime.from('22:39:09.068346205'), { smallestUnit: 'seconds' }); - // => PT2H25M48S + // => 'PT2H25M48S' ``` @@ -343,8 +345,8 @@ Usage example: ```javascript time = Temporal.PlainTime.from('20:13:20.971398099'); -time.since(Temporal.PlainTime.from('19:39:09.068346205')); // => PT34M11.903051894S -time.since(Temporal.PlainTime.from('22:39:09.068346205')); // => -PT2H25M48.096948106S +time.since(Temporal.PlainTime.from('19:39:09.068346205')); // => 'PT34M11.903051894S' +time.since(Temporal.PlainTime.from('22:39:09.068346205')); // => '-PT2H25M48.096948106S' ``` ### time.**round**(_options_: object) : Temporal.PlainTime @@ -392,13 +394,13 @@ Example usage: time = Temporal.PlainTime.from('19:39:09.068346205'); // Round to a particular unit -time.round({ smallestUnit: 'hour' }); // => 20:00 +time.round({ smallestUnit: 'hour' }); // => '20:00:00' // Round to an increment of a unit, e.g. half an hour: time.round({ roundingIncrement: 30, smallestUnit: 'minute' }); - // => 19:30 + // => '19:30:00' // Round to the same increment but round up instead: time.round({ roundingIncrement: 30, smallestUnit: 'minute', roundingMode: 'ceil' }); - // => 20:00 + // => '20:00:00' ``` @@ -459,13 +461,13 @@ Example usage: ```js time = Temporal.PlainTime.from('19:39:09.068346205'); -time.toString(); // => 19:39:09.068346205 +time.toString(); // => '19:39:09.068346205' -time.toString({ smallestUnit: 'minute' }); // => 19:39 -time.toString({ fractionalSecondDigits: 0 }); // => 19:39:09 -time.toString({ fractionalSecondDigits: 4 }); // => 19:39:09.0683 +time.toString({ smallestUnit: 'minute' }); // => '19:39' +time.toString({ fractionalSecondDigits: 0 }); // => '19:39:09' +time.toString({ fractionalSecondDigits: 4 }); // => '19:39:09.0683' time.toString({ fractionalSecondDigits: 5, roundingMode: 'nearest' }); - // => 19:39:09.06835 + // => '19:39:09.06835' ``` @@ -488,10 +490,10 @@ Example usage: ```js time = Temporal.PlainTime.from('19:39:09.068346205'); -time.toLocaleString(); // => example output: 7:39:09 p.m. -time.toLocaleString('de-DE'); // => example output: 19:39:09 -time.toLocaleString('de-DE', { timeZone: 'Europe/Berlin' }); // => 19:39:09 -time.toLocaleString('en-US-u-nu-fullwide-hc-h24'); // => 19:39:09 +time.toLocaleString(); // => '7:39:09 PM' +time.toLocaleString('de-DE'); // => '19:39:09' +time.toLocaleString('de-DE', { timeZone: 'Europe/Berlin' }); // => '19:39:09' +time.toLocaleString('en-US-u-nu-fullwide-hc-h24'); // => '19:39:09' ``` ### time.**toJSON**() : string @@ -575,7 +577,7 @@ Usage example: plainTime = Temporal.PlainTime.from('15:23:30.003'); plainDate = Temporal.PlainDate.from('2006-08-24'); plainTime.toZonedDateTime({ timeZone: 'America/Los_Angeles', plainDate }); -// => 2006-08-24T15:23:30.003-07:00[America/Los_Angeles] +// => '2006-08-24T15:23:30.003-07:00[America/Los_Angeles]' ``` ### time.**toPlainDateTime**(_date_: Temporal.PlainDate | object | string) : Temporal.PlainDateTime @@ -598,7 +600,7 @@ Usage example: ```javascript time = Temporal.PlainTime.from('15:23:30.003'); date = Temporal.PlainDate.from('2006-08-24'); -time.toPlainDateTime(date); // => 2006-08-24T15:23:30.003 +time.toPlainDateTime(date); // => '2006-08-24T15:23:30.003' ``` ### time.**getISOFields**(): { isoHour: number, isoMinute: number, isoSecond: number, isoMillisecond: number, isoMicrosecond: number, isoNanosecond: number, calendar: Temporal.Calendar } diff --git a/docs/plainyearmonth.md b/docs/plainyearmonth.md index 58d5f2e559..a2f75d7c50 100644 --- a/docs/plainyearmonth.md +++ b/docs/plainyearmonth.md @@ -46,7 +46,7 @@ Usage examples: ```javascript // The June 2019 meeting ym = new Temporal.PlainYearMonth(2019, 6); -// => 2019-06 +// => '2019-06' ``` ## Static methods @@ -91,27 +91,24 @@ Example usage: ```javascript -ym = Temporal.PlainYearMonth.from('2019-06'); // => 2019-06 -ym = Temporal.PlainYearMonth.from('2019-06-24'); // => 2019-06 -ym = Temporal.PlainYearMonth.from('2019-06-24T15:43:27'); // => 2019-06 -ym = Temporal.PlainYearMonth.from('2019-06-24T15:43:27Z'); // => 2019-06 +ym = Temporal.PlainYearMonth.from('2019-06'); // => '2019-06' +ym = Temporal.PlainYearMonth.from('2019-06-24'); // => '2019-06' +ym = Temporal.PlainYearMonth.from('2019-06-24T15:43:27'); // => '2019-06' +ym = Temporal.PlainYearMonth.from('2019-06-24T15:43:27Z'); // => '2019-06' ym = Temporal.PlainYearMonth.from('2019-06-24T15:43:27+01:00[Europe/Brussels]'); - // => 2019-06 -ym === Temporal.PlainYearMonth.from(ym); // => true + // => '2019-06' +ym.equals(Temporal.PlainYearMonth.from(ym)); // => true -ym = Temporal.PlainYearMonth.from({ year: 2019, month: 6 }); // => 2019-06 +ym = Temporal.PlainYearMonth.from({ year: 2019, month: 6 }); // => '2019-06' ym = Temporal.PlainYearMonth.from(Temporal.PlainDate.from('2019-06-24')); - // => same as above; Temporal.PlainDate has year and month properties + // => '2019-06' + // (same as above; Temporal.PlainDate has year and month properties) // Different overflow modes ym = Temporal.PlainYearMonth.from({ year: 2001, month: 13 }, { overflow: 'constrain' }); - // => 2001-12 -ym = Temporal.PlainYearMonth.from({ year: 2001, month: -1 }, { overflow: 'constrain' }); - // => 2001-01 + // => '2001-12' ym = Temporal.PlainYearMonth.from({ year: 2001, month: 13 }, { overflow: 'reject' }); - // throws -ym = Temporal.PlainYearMonth.from({ year: 2001, month: -1 }, { overflow: 'reject' }); - // throws + // => throws ``` @@ -144,7 +141,7 @@ one = Temporal.PlainYearMonth.from('2006-08'); two = Temporal.PlainYearMonth.from('2015-07'); three = Temporal.PlainYearMonth.from('1930-02'); sorted = [one, two, three].sort(Temporal.PlainYearMonth.compare); -sorted.join(' '); // => 1930-02 2006-08 2015-07 +sorted.join(' '); // => '1930-02 2006-08 2015-07' ``` ## Properties @@ -185,7 +182,6 @@ ym = Temporal.PlainYearMonth.from('2019-02-23[u-ca-hebrew]'); ym.year; // => 5779 ym.month; // => 6 ym.monthCode; // => "M05L" -ym.day; // => 18 ``` ### yearMonth.**calendar** : object @@ -220,9 +216,10 @@ Usage example: ```javascript // Attempt to write some mnemonic poetry +({ calendar } = Intl.DateTimeFormat().resolvedOptions()); const monthsByDays = {}; for (let month = 1; month <= 12; month++) { - const ym = Temporal.PlainYearMonth.from({ year: 2020, month }); + const ym = Temporal.PlainYearMonth.from({ year: 2020, month, calendar }); monthsByDays[ym.daysInMonth] = (monthsByDays[ym.daysInMonth] || []).concat(ym); } @@ -244,10 +241,11 @@ Usage example: ```javascript -ym = Temporal.PlainYearMonth.from('2019-06'); +({ calendar } = Intl.DateTimeFormat().resolvedOptions()); +ym = Temporal.PlainYearMonth.from({ year: 2019, month: 6, calendar}); percent = ym.daysInMonth / ym.daysInYear; `${ym.toLocaleString('en', {month: 'long', year: 'numeric'})} was ${percent.toLocaleString('en', {style: 'percent'})} of the year!` - // => example output: "June 2019 was 8% of the year!" + // => "June 2019 was 8% of the year!" ``` @@ -259,7 +257,7 @@ For the ISO 8601 calendar, this is always 12, but in other calendar systems it m Usage example: ```javascript -ym = Temporal.PlainDate.from('1900-01'); +ym = Temporal.PlainYearMonth.from('1900-01'); ym.monthsInYear; // => 12 ``` @@ -310,7 +308,7 @@ Usage example: ```javascript ym = Temporal.PlainYearMonth.from('2019-06'); // Get December of that year -ym.with({ month: 12 }); // => 2019-12 +ym.with({ month: 12 }); // => '2019-12' ``` ### yearMonth.**add**(_duration_: Temporal.Duration | object | string, _options_?: object) : Temporal.PlainYearMonth @@ -343,7 +341,7 @@ Usage example: ```javascript ym = Temporal.PlainYearMonth.from('2019-06'); -ym.add({ years: 20, months: 4 }); // => 2039-10 +ym.add({ years: 20, months: 4 }); // => '2039-10' ``` ### yearMonth.**subtract**(_duration_: Temporal.Duration | object | string, _options_?: object) : Temporal.PlainYearMonth @@ -376,7 +374,7 @@ Usage example: ```javascript ym = Temporal.PlainYearMonth.from('2019-06'); -ym.subtract({ years: 20, months: 4 }); // => 1999-02 +ym.subtract({ years: 20, months: 4 }); // => '1999-02' ``` ### yearMonth.**until**(_other_: Temporal.PlainYearMonth | object | string, _options_?: object) : Temporal.Duration @@ -427,16 +425,16 @@ Usage example: ```javascript ym = Temporal.PlainYearMonth.from('2006-08'); other = Temporal.PlainYearMonth.from('2019-06'); -ym.until(other); // => P12Y10M -ym.until(other, { largestUnit: 'months' }); // => P154M -other.until(ym, { largestUnit: 'months' }); // => -P154M +ym.until(other); // => 'P12Y10M' +ym.until(other, { largestUnit: 'months' }); // => 'P154M' +other.until(ym, { largestUnit: 'months' }); // => '-P154M' // If you really need to calculate the difference between two YearMonths // in days, you can eliminate the ambiguity by explicitly choosing the // day of the month (and if applicable, the time of that day) from which // you want to reckon the difference. For example, using the first of // the month to calculate a number of days: -ym.toPlainDate({ day: 1 }).until(other.toPlainDate({ day: 1 }), { largestUnit: 'days' }); // => P4687D +ym.toPlainDate({ day: 1 }).until(other.toPlainDate({ day: 1 }), { largestUnit: 'days' }); // => 'P4687D' ``` @@ -473,7 +471,7 @@ Usage example: ```javascript ym = Temporal.PlainYearMonth.from('2019-06'); other = Temporal.PlainYearMonth.from('2006-08'); -ym.since(other); // => P12Y10M +ym.since(other); // => 'P12Y10M' ``` ### yearMonth.**equals**(_other_: Temporal.PlainYearMonth | object | string) : boolean @@ -526,7 +524,7 @@ Example usage: ```js ym = Temporal.PlainYearMonth.from('2019-06'); -ym.toString(); // => 2019-06 +ym.toString(); // => '2019-06' ``` ### yearMonth.**toLocaleString**(_locales_?: string | array<string>, _options_?: object) : string @@ -560,13 +558,13 @@ Example usage: ```js ({ calendar } = new Intl.DateTimeFormat().resolvedOptions()); ym = Temporal.PlainYearMonth.from({ year: 2019, month: 6, calendar }); -ym.toLocaleString(); // => example output: 2019-06 +ym.toLocaleString(); // => '6/2019' // Same as above, but explicitly specifying the calendar: ym.toLocaleString(undefined, { calendar }); -ym.toLocaleString('de-DE', { calendar }); // => example output: 6.2019 -ym.toLocaleString('de-DE', { month: 'long', year: 'numeric', calendar }); // => Juni 2019 -ym.toLocaleString(`en-US-u-nu-fullwide-u-ca-${calendar}`); // => 6/2019 +ym.toLocaleString('de-DE', { calendar }); // => '6.2019' +ym.toLocaleString('de-DE', { month: 'long', year: 'numeric', calendar }); // => 'Juni 2019' +ym.toLocaleString(`en-US-u-nu-fullwide-ca-${calendar}`); // => '6/2019' ``` ### yearMonth.**toJSON**() : string @@ -629,7 +627,7 @@ Usage example: ```javascript ym = Temporal.PlainYearMonth.from('2019-06'); -ym.toPlainDate({ day: 24 }); // => 2019-06-24 +ym.toPlainDate({ day: 24 }); // => '2019-06-24' ``` ### yearMonth.**getISOFields**(): { isoYear: number, isoMonth: number, isoDay: number, calendar: object } diff --git a/docs/timezone.md b/docs/timezone.md index c73165c6da..74ba1df174 100644 --- a/docs/timezone.md +++ b/docs/timezone.md @@ -63,7 +63,7 @@ tz = new Temporal.TimeZone('america/VANCOUVER'); tz = new Temporal.TimeZone('Asia/Katmandu'); // alias of Asia/Kathmandu tz = new Temporal.TimeZone('-04:00'); tz = new Temporal.TimeZone('+0645'); -/* WRONG */ tz = new Temporal.TimeZone('local'); // not a time zone, throws +/* WRONG */ tz = new Temporal.TimeZone('local'); // => throws, not a time zone ``` #### Difference between IANA time zones and UTC offsets @@ -76,8 +76,8 @@ For example: tz1 = new Temporal.TimeZone('-08:00'); tz2 = new Temporal.TimeZone('America/Vancouver'); inst = Temporal.ZonedDateTime.from({ year: 2020, month: 1, day: 1, timeZone: tz2 }).toInstant(); +tz2.getPreviousTransition(inst); // => '2020-03-08T10:00:00Z' tz1.getNextTransition(inst); // => null -tz2.getPreviousTransition(inst); // => 2020-03-08T10:00Z ``` ## Static methods @@ -122,9 +122,9 @@ tz = Temporal.TimeZone.from('2020-01-13T16:31:00.065858086-08:00[America/Vancouv // Existing TimeZone object tz2 = Temporal.TimeZone.from(tz); -/* WRONG */ tz = Temporal.TimeZone.from('local'); // not a time zone, throws -/* WRONG */ tz = Temporal.TimeZone.from('2020-01-14T00:31:00'); // ISO 8601 string without time zone offset part, throws -/* WRONG */ tz = Temporal.TimeZone.from('-08:00[America/Vancouver]'); // ISO 8601 string without date-time part, throws +/* WRONG */ tz = Temporal.TimeZone.from('local'); // => throws, not a time zone +/* WRONG */ tz = Temporal.TimeZone.from('2020-01-14T00:31:00'); // => throws, ISO 8601 string without time zone offset part +/* WRONG */ tz = Temporal.TimeZone.from('-08:00[America/Vancouver]'); // => throws, ISO 8601 string without date-time part ``` ## Properties @@ -196,11 +196,11 @@ Example usage: // Getting the UTC offset for a time zone at a particular time timestamp = Temporal.Instant.fromEpochSeconds(1553993100); tz = Temporal.TimeZone.from('Europe/Berlin'); -tz.getOffsetStringFor(timestamp); // => +01:00 +tz.getOffsetStringFor(timestamp); // => '+01:00' // TimeZone with a fixed UTC offset tz = Temporal.TimeZone.from('-08:00'); -tz.getOffsetStringFor(timestamp); // => -08:00 +tz.getOffsetStringFor(timestamp); // => '-08:00' ``` ### timeZone.**getPlainDateTimeFor**(_instant_: Temporal.Instant | string, _calendar_?: object | string) : Temporal.PlainDateTime @@ -225,12 +225,12 @@ Example usage: // Converting an exact time to a calendar date / wall-clock time timestamp = Temporal.Instant.fromEpochSeconds(1553993100); tz = Temporal.TimeZone.from('Europe/Berlin'); -tz.getPlainDateTimeFor(timestamp); // => 2019-03-31T01:45 +tz.getPlainDateTimeFor(timestamp); // => '2019-03-31T01:45:00' // What time was the Unix Epoch (timestamp 0) in Bell Labs (Murray Hill, New Jersey, USA)? epoch = Temporal.Instant.fromEpochSeconds(0); tz = Temporal.TimeZone.from('America/New_York'); -tz.getPlainDateTimeFor(epoch); // => 1969-12-31T19:00 +tz.getPlainDateTimeFor(epoch); // => '1969-12-31T19:00:00' ``` ### timeZone.**getInstantFor**(_dateTime_: Temporal.PlainDateTime | object | string, _options_?: object) : Temporal.Instant diff --git a/docs/zoneddatetime.md b/docs/zoneddatetime.md index d5d0ac1cc6..be6cdfddd6 100644 --- a/docs/zoneddatetime.md +++ b/docs/zoneddatetime.md @@ -47,8 +47,10 @@ Usage examples: ```javascript // UNIX epoch in California new Temporal.ZonedDateTime(0n, Temporal.TimeZone.from('America/Los_Angeles'), Temporal.Calendar.from('iso8601')); - // => 1969-12-31T16:00-08:00[America/Los_Angeles] -new Temporal.ZonedDateTime(0n, 'America/Los_Angeles'); // same, but shorter + // => '1969-12-31T16:00:00-08:00[America/Los_Angeles]' +new Temporal.ZonedDateTime(0n, 'America/Los_Angeles'); + // => '1969-12-31T16:00:00-08:00[America/Los_Angeles]' + // same, but shorter ``` @@ -101,7 +103,7 @@ The time zone ID is always required. To parse these string formats, use `Temporal.Instant`: ```javascript -Temporal.Instant.from('2020-08-05T20:06:13+0900').toZonedDateTime('Asia/Tokyo', 'iso8601'); +Temporal.Instant.from('2020-08-05T20:06:13+0900').toZonedDateTime({ timeZone: 'Asia/Tokyo', calendar: 'iso8601' }); ``` Usually a named IANA time zone like `Europe/Paris` or `America/Los_Angeles` is used, but there are cases where adjusting for DST or other time zone offset changes is not desired. @@ -111,9 +113,10 @@ For example, `Etc/GMT+8` would be used for cases where the UTC offset is always If a non-whole-hour single-offset time zone is needed, the offset can be used as the time zone ID of an offset time zone. ```javascript -Temporal.Instant.from('2020-08-05T20:06:13+05:45[+05:45]'); +Temporal.Instant.from('2020-08-05T20:06:13+05:45[+05:45]') // OR -Temporal.Instant('2020-08-05T20:06:13+05:45').toZonedDateTime('+05:45', 'iso8601'); +new Temporal.Instant(1596637273000000000n).toZonedDateTime({ timeZone: '+05:45', calendar: 'iso8601' }); +// => '2020-08-05T20:06:13+05:45[+05:45]' ``` Note that using `Temporal.ZonedDateTime` with a single-offset time zone will not adjust for Daylight Saving Time or other time zone changes. @@ -180,15 +183,15 @@ Example usage: ```javascript zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30+02:00[Africa/Cairo]'); zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30+02:00[Africa/Cairo][u-ca-islamic]'); -zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30'); // RangeError; time zone ID required -zdt = Temporal.ZonedDateTime.from('1995-12-07T01:24:30Z'); // RangeError; time zone ID required -zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30+02:00'); // RangeError; time zone ID required +zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30'); // => throws RangeError: time zone ID required +zdt = Temporal.ZonedDateTime.from('1995-12-07T01:24:30Z'); // => throws RangeError: time zone ID required +zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30+02:00'); // => throws RangeError: time zone ID required zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30+02:00[+02:00]'); // OK (offset time zone) but rarely used zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30+03:00[Africa/Cairo]'); // => RangeError: Offset is invalid for '1995-12-07T03:24:30' in 'Africa/Cairo'. Provided: +03:00, expected: +02:00. zdt = Temporal.ZonedDateTime.from({ - timeZone: 'America/Los_Angeles' + timeZone: 'America/Los_Angeles', year: 1995, month: 12, day: 7, @@ -198,17 +201,13 @@ zdt = Temporal.ZonedDateTime.from({ millisecond: 0, microsecond: 3, nanosecond: 500 -}); // => 1995-12-07T03:24:30.000003500+08:00[America/Los_Angeles] +}); // => '1995-12-07T03:24:30.0000035-08:00[America/Los_Angeles]' // Different overflow modes zdt = Temporal.ZonedDateTime.from({ timeZone: 'Europe/Paris', year: 2001, month: 13, day: 1 }, { overflow: 'constrain' }) - // => 2001-12-01T00:00+01:00[Europe/Paris] -zdt = Temporal.ZonedDateTime.from({ timeZone: 'Europe/Paris', year: 2001, month: -1, day: 1 }, { overflow: 'constrain' }) - // => 2001-01-01T00:00+01:00[Europe/Paris] + // => '2001-12-01T00:00:00+01:00[Europe/Paris]' zdt = Temporal.ZonedDateTime.from({ timeZone: 'Europe/Paris', year: 2001, month: 13, day: 1 }, { overflow: 'reject' }) // => throws RangeError -zdt = Temporal.ZonedDateTime.from({ timeZone: 'Europe/Paris', year: 2001, month: -1, day: 1 }, { overflow: 'reject' }) - // => throws RangeError ``` @@ -245,12 +244,13 @@ arr = [ ]; sorted = arr.sort(Temporal.ZonedDateTime.compare); JSON.stringify(sorted, undefined, 2); -// => "[ +// => +// '[ // "2020-02-01T12:30+01:00[Europe/Brussels]", // "2020-02-01T12:30+00:00[Europe/London]", // "2020-02-01T12:30-05:00[America/New_York]", // "2020-02-01T12:30-05:00[America/Toronto]" -// ]" +// ]' ``` Note that in unusual cases like the repeated clock hour after DST ends, values that are later in the real world can be earlier in clock time, or vice versa. @@ -262,11 +262,14 @@ For example: one = Temporal.ZonedDateTime.from('2020-11-01T01:45-07:00[America/Los_Angeles]'); two = Temporal.ZonedDateTime.from('2020-11-01T01:15-08:00[America/Los_Angeles]'); Temporal.ZonedDateTime.compare(one, two); - // => -1, because `one` is earlier in the real world + // => -1 + // (because `one` is earlier in the real world) Temporal.PlainDateTime.compare(one.toPlainDateTime(), two.toPlainDateTime()); - // => 1, because `one` is later in clock time + // => 1 + // (because `one` is later in clock time) Temporal.Instant.compare(one.toInstant(), two.toInstant()); - // => -1, because `Temporal.Instant` and `Temporal.ZonedDateTime` both compare real-world exact times + // => -1 + // (because `Temporal.Instant` and `Temporal.ZonedDateTime` both compare real-world exact times) ``` @@ -381,11 +384,11 @@ epochMs = zdt.epochMilliseconds; zdt.toInstant().epochMilliseconds; // => 1580527800000 legacyDate = new Date(epochMs); - // => Fri Jan 31 2020 19:30:00 GMT-0800 (Pacific Standard Time) + // => 'Fri Jan 31 2020 19:30:00 GMT-0800 (Pacific Standard Time)' // (if the system time zone is America/Los_Angeles) epochMicros = zdt.epochMicroseconds; // => 1580527800000000 -epochNanos = sdt.epochNanoseconds; +epochNanos = zdt.epochNanoseconds; // => 1580527800000000000 ``` @@ -442,17 +445,21 @@ zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24-08:00[America/Los_Angeles]') `Time zone is: ${zdt.timeZone}`; // => "Time zone is: America/Los_Angeles" zdt.withTimeZone('Asia/Singapore').timeZone; - // => Asia/Singapore + // => 'Asia/Singapore' zdt.withTimeZone('Asia/Chongqing').timeZone; - // => Asia/Shanghai (time zone IDs are normalized, e.g. Asia/Chongqing -> Asia/Shanghai) + // => 'Asia/Shanghai' + // (time zone IDs are normalized, e.g. Asia/Chongqing -> Asia/Shanghai) zdt.withTimeZone('+05:00').timeZone; - // => +05:00 + // => '+05:00' zdt.withTimeZone('+05').timeZone; - // => +05:00 (normalized to canonical form) + // => '+05:00' + // (normalized to canonical form) zdt.withTimeZone('utc').timeZone; - // => UTC (normalized to canonical form which is uppercase) + // => 'UTC' + // (normalized to canonical form which is uppercase) zdt.withTimeZone('GMT').timeZone; - // => UTC (normalized to canonical form) + // => 'UTC' + // (normalized to canonical form) ``` @@ -485,7 +492,7 @@ Usage example: ```javascript zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24-08:00[America/Los_Angeles]'); -['MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT', 'SUN'][zdt.dayOfWeek - 1]; // => THU +['MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT', 'SUN'][zdt.dayOfWeek - 1]; // => 'THU' ``` ### zonedDateTime.**dayOfYear** : number @@ -498,7 +505,7 @@ Usage example: ```javascript zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24-08:00[America/Los_Angeles]'); // ISO ordinal date -console.log(zdt.year, zdt.dayOfYear); // => 1995 341 +console.log(zdt.year, zdt.dayOfYear); // => '1995 341' ``` ### zonedDateTime.**weekOfYear** : number @@ -513,7 +520,7 @@ Usage example: ```javascript zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24-08:00[America/Los_Angeles]'); // ISO week date -console.log(zdt.year, zdt.weekOfYear, zdt.dayOfWeek); // => 1995 49 4 +console.log(zdt.year, zdt.weekOfYear, zdt.dayOfWeek); // => '1995 49 4' ``` ### zonedDateTime.**daysInWeek** : number @@ -537,9 +544,10 @@ Usage example: ```javascript // Attempt to write some mnemonic poetry +({ calendar } = Intl.DateTimeFormat().resolvedOptions()); const monthsByDays = {}; for (let month = 1; month <= 12; month++) { - const zdt = Temporal.now.zonedDateTime().with({ month }); + const zdt = Temporal.now.zonedDateTime(calendar).with({ month }); monthsByDays[zdt.daysInMonth] = (monthsByDays[zdt.daysInMonth] || []).concat(zdt); } @@ -560,7 +568,8 @@ For the ISO 8601 calendar, this is 365 or 366, depending on whether the year is Usage example: ```javascript -zdt = Temporal.now.zonedDateTime(); +({ calendar } = Intl.DateTimeFormat().resolvedOptions()); +zdt = Temporal.now.zonedDateTime(calendar); percent = zdt.dayOfYear / zdt.daysInYear; `The year is ${percent.toLocaleString('en', { style: 'percent' })} over!`; // example output: "The year is 10% over!" @@ -590,7 +599,7 @@ Usage example: ```javascript // Is this year a leap year? -zdt = Temporal.now.zonedDateTime(); +zdt = Temporal.now.zonedDateTime('iso8601'); zdt.inLeapYear; // example output: true // Is 2100 a leap year? (no, because it's divisible by 100 and not 400) zdt.with({ year: 2100 }).inLeapYear; // => false @@ -611,11 +620,14 @@ Usage example: ```javascript Temporal.ZonedDateTime.from('2020-01-01T12:00-08:00[America/Los_Angeles]').hoursInDay; - // => 24 (normal day) + // => 24 + // (normal day) Temporal.ZonedDateTime.from('2020-03-08T12:00-07:00[America/Los_Angeles]').hoursInDay; - // => 23 (DST starts on this day) + // => 23 + // (DST starts on this day) Temporal.ZonedDateTime.from('2020-11-01T12:00-08:00[America/Los_Angeles]').hoursInDay; - // => 25 (DST ends on this day) + // => 25 + // (DST ends on this day) ``` @@ -627,7 +639,7 @@ The local time of the result is almost always `00:00`, but in rare cases it coul ```javascript const zdt = Temporal.ZonedDateTime.from('2015-10-18T12:00-02:00[America/Sao_Paulo]'); -zdt.startOfDay(); // => 2015-10-18T01:00:00-02:00[America/Sao_Paulo] +zdt.startOfDay(); // => '2015-10-18T01:00:00-02:00[America/Sao_Paulo]' ``` Also note that some calendar systems (e.g. `ethiopic`) may not start days at `00:00`. @@ -636,10 +648,10 @@ Usage example: ```javascript -zdt = Temporal.ZonedDateTime.from('2020-01-01T12:00-08:00[America/Los_Angeles]').startOfDay; - // => 2020-01-01T00:00-08:00[America/Los_Angeles] -zdt = Temporal.ZonedDateTime.from('2018-11-04T12:00-02:00[America/Sao_Paulo]').startOfDay; - // => 2018-11-04T01:00-02:00[America/Sao_Paulo] +zdt = Temporal.ZonedDateTime.from('2020-01-01T12:00-08:00[America/Los_Angeles]').startOfDay(); + // => '2020-01-01T00:00:00-08:00[America/Los_Angeles]' +zdt = Temporal.ZonedDateTime.from('2018-11-04T12:00-02:00[America/Sao_Paulo]').startOfDay(); + // => '2018-11-04T01:00:00-02:00[America/Sao_Paulo]' // Note the 1:00AM start time because the first clock hour was skipped due to DST transition // that started at midnight. ``` @@ -658,7 +670,8 @@ The numeric `offsetNanoseconds` field is read-only and is ignored in `with` and ```javascript zdt = Temporal.ZonedDateTime.from('2020-11-01T01:30-07:00[America/Los_Angeles]'); zdt.offsetNanoseconds; - // => -25200000000000 (-7 * 3600 * 1e9) + // => -25200000000000 + // (-7 * 3600 * 1e9) ``` @@ -684,10 +697,10 @@ zdt.withTimeZone('Asia/Kolkata').offset; minus8Hours = '-08:00'; daylightTime0130 = Temporal.ZonedDateTime.from('2020-11-01T01:30-07:00[America/Los_Angeles]'); - // => 2020-11-01T01:30-07:00[America/Los_Angeles] + // => '2020-11-01T01:30:00-07:00[America/Los_Angeles]' // This is Pacific Daylight Time 1:30AM repeated0130 = daylightTime0130.with({ offset: minus8Hours }); - // => 2020-11-01T01:30-08:00[America/Los_Angeles] + // => '2020-11-01T01:30:00-08:00[America/Los_Angeles]' // This is Pacific Standard Time 1:30AM ``` @@ -750,8 +763,8 @@ Please see the documentation of `from` for more details on options behavior. Usage example: ```javascript -zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24-06:00[America/Chicago]'); -zdt.with({ year: 2015, minute: 31 }); // => 2015-12-07T03:31-06:00[America/Chicago] +zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:00-06:00[America/Chicago]'); +zdt.with({ year: 2015, minute: 31 }); // => '2015-12-07T03:31:00-06:00[America/Chicago]' ``` ### zonedDateTime.**withPlainTime**(_plainTime_?: object | string) : Temporal.PlainDateTime @@ -777,13 +790,13 @@ Usage example: ```javascript zdt = Temporal.ZonedDateTime.from('2015-12-07T03:24:30.000003500-08:00[America/Los_Angeles]'); -zdt.withPlainTime({ hour: 10 }); // => 2015-12-07T10:00:00-08:00[America/Los_Angeles] +zdt.withPlainTime({ hour: 10 }); // => '2015-12-07T10:00:00-08:00[America/Los_Angeles]' time = Temporal.PlainTime.from('11:22'); -zdt.withPlainTime(time); // => 2015-12-07T11:22:00-08:00[America/Los_Angeles] -zdt.withPlainTime('12:34'); // => 2015-12-07T12:34:00-08:00[America/Los_Angeles] +zdt.withPlainTime(time); // => '2015-12-07T11:22:00-08:00[America/Los_Angeles]' +zdt.withPlainTime('12:34'); // => '2015-12-07T12:34:00-08:00[America/Los_Angeles]' // easier for chaining -zdt.add({ days: 2, hours: 22 }).withPlainTime('00:00'); // => 2015-12-10T00:00:00-08:00[America/Los_Angeles] +zdt.add({ days: 2, hours: 22 }).withPlainTime('00:00'); // => '2015-12-10T00:00:00-08:00[America/Los_Angeles]' ``` ### zonedDateTime.**withPlainDate**(_plainDate_: object | string) : Temporal.ZonedDateTime @@ -816,17 +829,17 @@ Usage example: ```javascript zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30-08:00[America/Los_Angeles]'); -zdt.withPlainDate({ year: 2000, month: 6, day: 1 }); // => 2000-06-01T03:24:30-07:00[America/Los_Angeles] +zdt.withPlainDate({ year: 2000, month: 6, day: 1 }); // => '2000-06-01T03:24:30-07:00[America/Los_Angeles]' date = Temporal.PlainDate.from('2020-01-23'); -zdt.withPlainDate(date); // => 2020-01-23T03:24:30-08:00[America/Los_Angeles] -zdt.withPlainDate('2018-09-15'); // => 2018-09-15T03:24:30-07:00[America/Los_Angeles] +zdt.withPlainDate(date); // => '2020-01-23T03:24:30-08:00[America/Los_Angeles]' +zdt.withPlainDate('2018-09-15'); // => '2018-09-15T03:24:30-07:00[America/Los_Angeles]' // easier for chaining -zdt.add({ hours: 12 }).withPlainDate('2000-06-01'); // => 2000-06-01T15:24:30-07:00[America/Los_Angeles] +zdt.add({ hours: 12 }).withPlainDate('2000-06-01'); // => '2000-06-01T15:24:30-07:00[America/Los_Angeles]' // result contains a non-ISO calendar if present in the input -zdt.withCalendar('japanese').withPlainDate('2008-09-06'); // => 2008-09-06T03:24:30-07:00[America/Los_Angeles][u-ca-japanese] -zdt.withPlainDate('2017-09-06[u-ca-japanese]'); // => 2017-09-06T03:24:30-07:00[America/Los_Angeles][u-ca-japanese] +zdt.withCalendar('japanese').withPlainDate('2008-09-06'); // => '2008-09-06T03:24:30-07:00[America/Los_Angeles][u-ca-japanese]' +zdt.withPlainDate('2017-09-06[u-ca-japanese]'); // => '2017-09-06T03:24:30-07:00[America/Los_Angeles][u-ca-japanese]' zdt.withCalendar('japanese').withPlainDate('2017-09-06[u-ca-hebrew]'); // => RangeError (calendar conflict) ``` @@ -858,7 +871,7 @@ Usage example: ```javascript zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30.000003500+09:00[Asia/Tokyo][u-ca-japanese]'); -`${zdt.era} ${zdt.year}`; // => "heisei 7" +`${zdt.era} ${zdt.eraYear}`; // => "heisei 7" zdt.withCalendar('iso8601').year; // => 1995 ``` @@ -913,13 +926,14 @@ Usage example: zdt = Temporal.ZonedDateTime.from('2020-03-08T00:00-08:00[America/Los_Angeles]'); // Add a day to get midnight on the day after DST starts laterDay = zdt.add({ days: 1 }); - // => 2020-03-09T00:00:00-07:00[America/Los_Angeles]; + // => '2020-03-09T00:00:00-07:00[America/Los_Angeles]' // Note that the new offset is different, indicating the result is adjusted for DST. laterDay.since(zdt, { largestUnit: 'hours' }).hours; - // => 23, because one clock hour lost to DST + // => 23 + // because one clock hour lost to DST laterHours = zdt.add({ hours: 24 }); - // => 2020-03-09T01:00:00-07:00[America/Los_Angeles] + // => '2020-03-09T01:00:00-07:00[America/Los_Angeles]' // Adding time units doesn't adjust for DST. Result is 1:00AM: 24 real-world // hours later because a clock hour was skipped by DST. laterHours.since(zdt, { largestUnit: 'hours' }).hours; // => 24 @@ -977,13 +991,14 @@ Usage example: zdt = Temporal.ZonedDateTime.from('2020-03-09T00:00-07:00[America/Los_Angeles]'); // Add a day to get midnight on the day after DST starts earlierDay = zdt.subtract({ days: 1 }); - // => 2020-03-08T00:00:00-08:00[America/Los_Angeles] + // => '2020-03-08T00:00:00-08:00[America/Los_Angeles]' // Note that the new offset is different, indicating the result is adjusted for DST. earlierDay.since(zdt, { largestUnit: 'hours' }).hours; - // => -23, because one clock hour lost to DST + // => -23 + // because one clock hour lost to DST earlierHours = zdt.subtract({ hours: 24 }); - // => 2020-03-07T23:00:00-08:00[America/Los_Angeles] + // => '2020-03-07T23:00:00-08:00[America/Los_Angeles]' // Subtracting time units doesn't adjust for DST. Result is 11:00PM: 24 real-world // hours earlier because a clock hour was skipped by DST. earlierHours.since(zdt, { largestUnit: 'hours' }).hours; // => -24 @@ -1061,27 +1076,28 @@ Usage example: zdt1 = Temporal.ZonedDateTime.from('1995-12-07T03:24:30.000003500+05:30[Asia/Kolkata]'); zdt2 = Temporal.ZonedDateTime.from('2019-01-31T15:30+05:30[Asia/Kolkata]'); zdt1.until(zdt2); - // => PT202956H5M29.999996500S + // => 'PT202956H5M29.9999965S' zdt1.until(zdt2, { largestUnit: 'years' }); - // => P23Y1M24DT12H5M29.999996500S + // => 'P23Y1M24DT12H5M29.9999965S' zdt2.until(zdt1, { largestUnit: 'years' }); - // => -P23Y1M24DT12H5M29.999996500S + // => '-P23Y1M24DT12H5M29.9999965S' zdt1.until(zdt2, { largestUnit: 'nanoseconds' }); - // => PT730641929.999996544S (precision lost) + // => 'PT730641929.999996544S' + // (precision lost)' // Rounding, for example if you don't care about sub-seconds zdt1.until(zdt2, { smallestUnit: 'seconds' }); - // => PT202956H5M29S + // => 'PT202956H5M29S' // Months and years can be different lengths [jan1, feb1, mar1] = [1, 2, 3].map((month) => Temporal.ZonedDateTime.from({ year: 2020, month, day: 1, timeZone: 'Asia/Seoul' }) ); -jan1.until(feb1, { largestUnit: 'days' }); // => P31D -jan1.until(feb1, { largestUnit: 'months' }); // => P1M -feb1.until(mar1, { largestUnit: 'days' }); // => P29D -feb1.until(mar1, { largestUnit: 'months' }); // => P1M -jan1.until(mar1, { largestUnit: 'days' }); // => P60D +jan1.until(feb1, { largestUnit: 'days' }); // => 'P31D' +jan1.until(feb1, { largestUnit: 'months' }); // => 'P1M' +feb1.until(mar1, { largestUnit: 'days' }); // => 'P29D' +feb1.until(mar1, { largestUnit: 'months' }); // => 'P1M' +jan1.until(mar1, { largestUnit: 'days' }); // => 'P60D' ``` @@ -1117,7 +1133,7 @@ Usage example: ```javascript zdt1 = Temporal.ZonedDateTime.from('1995-12-07T03:24:30.000003500+05:30[Asia/Kolkata]'); zdt2 = Temporal.ZonedDateTime.from('2019-01-31T15:30+05:30[Asia/Kolkata]'); -zdt2.since(zdt1); // => PT202956H5M29.999996500S +zdt2.since(zdt1); // => 'PT202956H5M29.9999965S' ``` ### zonedDateTime.**round**(_options_: object) : Temporal.ZonedDateTime @@ -1167,13 +1183,13 @@ zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30.000003500-08:00[America/L // Round to a particular unit zdt.round({ smallestUnit: 'hour' }); - // => 1995-12-07T03:00:00-08:00[America/Los_Angeles] + // => '1995-12-07T03:00:00-08:00[America/Los_Angeles]' // Round to an increment of a unit, e.g. half an hour: zdt.round({ roundingIncrement: 30, smallestUnit: 'minute' }); - // => 1995-12-07T03:30:00-08:00[America/Los_Angeles] + // => '1995-12-07T03:30:00-08:00[America/Los_Angeles]' // Round to the same increment but round down instead: zdt.round({ roundingIncrement: 30, smallestUnit: 'minute', roundingMode: 'floor' }); - // => 1995-12-07T03:00:00-08:00[America/Los_Angeles] + // => '1995-12-07T03:00:00-08:00[America/Los_Angeles]' ``` @@ -1204,7 +1220,7 @@ zdt.withCalendar('iso8601').equals(other.withCalendar('iso8601')); To ignore both time zones and calendars, compare the instants of both: ```javascript -zdt.toInstant().equals(other.toInstant())); +zdt.toInstant().equals(other.toInstant()); ``` Example usage: @@ -1212,7 +1228,8 @@ Example usage: ```javascript zdt1 = Temporal.ZonedDateTime.from('1995-12-07T03:24:30.000003500+01:00[Europe/Paris]'); zdt2 = Temporal.ZonedDateTime.from('1995-12-07T03:24:30.000003500+01:00[Europe/Brussels]'); -zdt1.equals(zdt2); // => false (same offset but different time zones) +zdt1.equals(zdt2); // => false + // (same offset but different time zones) zdt1.equals(zdt1); // => true ``` @@ -1271,9 +1288,9 @@ Example usage: ```javascript zdt = Temporal.ZonedDateTime.from({ year: 2019, month: 12, day: 1, hour: 12, timeZone: 'Africa/Lagos' }); -zdt.toString(); // => 2019-12-01T12:00+01:00[Africa/Lagos] -zdt.withCalendar('japanese'); -zdt.toString(); // => 2019-12-01T12:00+01:00[Africa/Lagos][u-ca-japanese] +zdt.toString(); // => '2019-12-01T12:00:00+01:00[Africa/Lagos]' +zdt = zdt.withCalendar('japanese'); +zdt.toString(); // => '2019-12-01T12:00:00+01:00[Africa/Lagos][u-ca-japanese]' ``` ### zonedDateTime.**toLocaleString**(_locales_?: string | array<string>, _options_?: object) : string @@ -1298,14 +1315,14 @@ Example usage: ```javascript zdt = Temporal.ZonedDateTime.from('2019-12-01T12:00+01:00[Europe/Berlin]'); -zdt.toLocaleString(); // => example output: 12/1/2019, 12:00:00 PM -zdt.toLocaleString('de-DE'); // => 1.12.2019, 12:00:00 +zdt.toLocaleString(); // example output: 12/1/2019, 12:00:00 PM +zdt.toLocaleString('de-DE'); // => '1.12.2019, 12:00:00 MEZ' options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' }; -zdt.toLocaleString('de-DE', options); // => Sonntag, 1. Dezember 2019 +zdt.toLocaleString('de-DE', options); // => 'Sonntag, 1. Dezember 2019' zdt.toLocaleString('de-DE', { timeZone: 'Pacific/Auckland' }); // => RangeError: Time zone option Pacific/Auckland does not match actual time zone Europe/Berlin -zdt.withTimeZone('Pacific/Auckland').toLocaleString('de-DE'); // => 2.12.2019, 00:00:00 -zdt.toLocaleString('en-US-u-nu-fullwide-hc-h12'); // => 12/1/2019, 12:00:00 PM +zdt.withTimeZone('Pacific/Auckland').toLocaleString('de-DE'); // => '2.12.2019, 0:00:00 GMT+13' +zdt.toLocaleString('en-US-u-nu-fullwide-hc-h12'); // => '12/1/2019, 12:00:00 PM GMT+1' ``` @@ -1389,12 +1406,12 @@ Usage example: ```javascript zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30+02:00[Africa/Johannesburg]'); -zdt.toInstant(); // => 1995-12-07T01:24:30Z -zdt.toPlainDateTime(); // => 1995-12-07T03:24:30 -zdt.toPlainDate(); // => 1995-12-07 -zdt.toPlainYearMonth(); // => 1995-12 -zdt.toPlainMonthDay(); // => 12-07 -zdt.toPlainTime(); // => 03:24:30 +zdt.toInstant(); // => '1995-12-07T01:24:30Z' +zdt.toPlainDateTime(); // => '1995-12-07T03:24:30' +zdt.toPlainDate(); // => '1995-12-07' +zdt.toPlainYearMonth(); // => '1995-12' +zdt.toPlainMonthDay(); // => '12-07' +zdt.toPlainTime(); // => '03:24:30' ``` ### zonedDateTime.**getISOFields**(): { isoYear: number, isoMonth: number, isoDay: number, hour: number, minute: number, second: number, millisecond: number, microsecond: number, nanosecond: number, offset: string, timeZone: object, calendar: object } @@ -1411,7 +1428,7 @@ Usage example: zdt = Temporal.ZonedDateTime.from('1995-12-07T03:24:30.000003500+01:00[Europe/Paris]').withCalendar('japanese'); // Year in japanese calendar is year 7 of Heisei era -zdt.year; // => 7 +zdt.eraYear; // => 7 zdt.getISOFields().isoYear; // => 1995 // Instead of calling getISOFields, the pattern below is recommended for most use cases diff --git a/polyfill/lib/plainmonthday.mjs b/polyfill/lib/plainmonthday.mjs index 1f2533ed86..2c288304df 100644 --- a/polyfill/lib/plainmonthday.mjs +++ b/polyfill/lib/plainmonthday.mjs @@ -139,7 +139,7 @@ export class PlainMonthDay { const fields = ES.ToTemporalMonthDayFields(this, receiverFieldNames); const inputFieldNames = ES.CalendarFields(calendar, ['year']); - const entries = [['year']]; + const entries = [['year', undefined]]; // Add extra fields from the calendar at the end inputFieldNames.forEach((fieldName) => { if (!entries.some(([name]) => name === fieldName)) {