From 90aba7f1d79f2f69a42c01b44b28f1579dc673a8 Mon Sep 17 00:00:00 2001 From: Justin Grant Date: Thu, 27 Aug 2020 13:37:22 -0700 Subject: [PATCH] document nanoseconds duration limit of 104 days --- docs/absolute.md | 8 +++++--- docs/datetime.md | 23 ++++++++++++++--------- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/absolute.md b/docs/absolute.md index 9ed9589c54..c119baea22 100644 --- a/docs/absolute.md +++ b/docs/absolute.md @@ -316,7 +316,8 @@ If you do need to calculate the difference between two `Temporal.Absolute`s in y For example, you might decide to base the calculation on your user's current time zone, or on UTC. Take care when using milliseconds, microseconds, or nanoseconds as the largest unit. -For some dates, the resulting value may overflow `Number.MAX_SAFE_INTEGER`. +For some durations, the resulting value may overflow `Number.MAX_SAFE_INTEGER` and will throw a `RangeError`. +For example, `Number.MAX_SAFE_INTEGER` in nanoseconds is only 104.25 days. Example usage: ```js @@ -333,8 +334,9 @@ missionLength.toLocaleString(); epoch = new Temporal.Absolute(0n); billion = Temporal.Absolute.fromEpochSeconds(1e9); billion.difference(epoch); // => PT1000000000S -billion.difference(epoch, { largestUnit: 'hours' }) // => PT277777H46M40S -billion.difference(epoch, { largestUnit: 'days' }) // => P11574DT1H46M40S +billion.difference(epoch, { largestUnit: 'hours' }); // => PT277777H46M40S +billion.difference(epoch, { largestUnit: 'days' }); // => P11574DT1H46M40S +billion.difference(epoch, { largestUnit: 'nanoseconds' }); // => overflow; throws RangeError // Calculate the difference in years, eliminating the ambiguity by // explicitly using the corresponding calendar date in UTC: diff --git a/docs/datetime.md b/docs/datetime.md index 724d0a3a28..05b14cfd41 100644 --- a/docs/datetime.md +++ b/docs/datetime.md @@ -455,22 +455,27 @@ By default, the largest unit in the result is days. This is because months and years can be different lengths depending on which month is meant and whether the year is a leap year. Take care when using milliseconds, microseconds, or nanoseconds as the largest unit. -For some dates, the resulting value may overflow `Number.MAX_SAFE_INTEGER`. +For some durations, the resulting value may overflow `Number.MAX_SAFE_INTEGER` and will throw a `RangeError`. +For example, `Number.MAX_SAFE_INTEGER` in nanoseconds is only 104.25 days. Usage example: ```javascript dt1 = Temporal.DateTime.from('1995-12-07T03:24:30.000003500'); dt2 = Temporal.DateTime.from('2019-01-31T15:30'); -dt2.difference(dt1); // => P8456DT12H5M29.999996500S -dt2.difference(dt1), { largestUnit: 'years' }) // => P23Y1M24DT12H5M29.999996500S -dt1.difference(dt2), { largestUnit: 'years' }) // => throws RangeError +dt2.difference(dt1); // => P8456DT12H5M29.999996500S +dt2.difference(dt1), { largestUnit: 'years' }); // => P23Y1M24DT12H5M29.999996500S +dt2.difference(dt1), { largestUnit: 'nanoseconds' }); // => overflow; throws RangeError +dt1.difference(dt2), { largestUnit: 'years' }); // => throws RangeError // Months and years can be different lengths -[jan1, feb1, mar1] = [1, 2, 3].map(month => Temporal.DateTime.from({year: 2020, month, day: 1})); -feb1.difference(jan1); // => P31D -feb1.difference(jan1, { largestUnit: 'months' }); // => P1M -mar1.difference(feb1); // => P29D -mar1.difference(feb1, { largestUnit: 'months' }); // => P1M +[jan1, feb1, mar1, apr1, may1] = + [1, 2, 3, 4, 5].map(month => Temporal.DateTime.from({ year: 2020, month, day: 1 })); +feb1.difference(jan1); // => P31D +feb1.difference(jan1, { largestUnit: 'months' }); // => P1M +mar1.difference(feb1); // => P29D +mar1.difference(feb1, { largestUnit: 'months' }); // => P1M +may1.difference(jan1); // => P121D +may1.difference(jan1), { largestUnit: 'nanoseconds' }); // => overflow; throws RangeError ``` ### datetime.**equals**(_other_: Temporal.DateTime) : boolean