Skip to content

Commit

Permalink
Correct + make runnable documentation code samples.
Browse files Browse the repository at this point in the history 
Running all the code samples in the docs through a tolerant markdown snippet parser + execution environment revealed many errors. #1395, #1391, #1380, and this patch's one-line fix in plainmonthday.mjs were all bugs revealed by the documentation code samples. Many of the changes in this patch are slight syntactic changes to make the samples testable and more clear.

Common classes of smaller issues fixed:
- Examples did not include seconds in string representations
- Examples contained extra zeroes of precision when not requested
- Old calling conventions used; arguments needed to be changed
- Some options bags are now used in dedicated places rather than alongside other methods
  • Loading branch information
@cjtenny
cjtenny committed Feb 27, 2021
1 parent 4b3e7fa commit 1cbe054
Show file tree
Hide file tree
Showing 20 changed files with 562 additions and 512 deletions.
24 changes: 12 additions & 12 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`).
Expand All @@ -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"
```
Expand All @@ -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"
Expand All @@ -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.
Expand All @@ -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
```
Expand All @@ -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
```

Expand Down Expand Up @@ -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
```

Expand Down
77 changes: 41 additions & 36 deletions docs/ambiguity.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
<!-- prettier-ignore-end -->
Expand All @@ -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();
Expand Down Expand Up @@ -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'
```
<!-- prettier-ignore-end -->

Expand All @@ -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
```
Expand Down Expand Up @@ -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)
```
<!-- prettier-ignore-end -->

Expand All @@ -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)
```
<!-- prettier-ignore-end -->
Expand Down Expand Up @@ -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

Expand All @@ -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.
```
<!-- prettier-ignore-end -->
60 changes: 36 additions & 24 deletions docs/balancing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -63,22 +69,25 @@ 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.
However, if the duration is timezone-specific, then it's recommended to use a `Temporal.ZonedDateTime` reference point to ensure that DST transitions are accounted for.

<!-- prettier-ignore-start -->
```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)
```
<!-- prettier-ignore-end -->

Expand All @@ -89,30 +98,33 @@ 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).
`relativeTo` is interpreted relative to `this`, not to `other`, which allows the same `relativeTo` value to be used for a chain of arithmetic operations.

<!-- prettier-ignore-start -->
```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)
```
<!-- prettier-ignore-end -->

Expand Down
Loading

0 comments on commit 1cbe054

Please sign in to comment.