More docs

rob-blackbourn · Jul 15, 2023 · b87cd33 · b87cd33
1 parent a6856b1
commit b87cd33
Show file tree

Hide file tree

Showing 15 changed files with 242 additions and 237 deletions.
diff --git a/docs/classes/Calendar.html b/docs/classes/Calendar.html
diff --git a/docs/classes/Duration.html b/docs/classes/Duration.html
diff --git a/docs/classes/HolidayCalendar.html b/docs/classes/HolidayCalendar.html
diff --git a/docs/classes/IANATimezone.html b/docs/classes/IANATimezone.html
diff --git a/docs/classes/LocaleInfo.html b/docs/classes/LocaleInfo.html
diff --git a/docs/classes/Timezone.html b/docs/classes/Timezone.html
diff --git a/docs/classes/WeekendCalendar.html b/docs/classes/WeekendCalendar.html
diff --git a/docs/enums/BusinessDayConvention.html b/docs/enums/BusinessDayConvention.html
diff --git a/docs/interfaces/DatePartResponse.html b/docs/interfaces/DatePartResponse.html
diff --git a/docs/interfaces/DayPlurals.html b/docs/interfaces/DayPlurals.html
diff --git a/docs/interfaces/I18nSettings.html b/docs/interfaces/I18nSettings.html
diff --git a/docs/interfaces/TimezoneOffset.html b/docs/interfaces/TimezoneOffset.html
diff --git a/docs/modules.html b/docs/modules.html
diff --git a/docs/pages/guide/date-arithmetic.html b/docs/pages/guide/date-arithmetic.html
@@ -10,16 +10,13 @@ <h2>Start of Day</h2>
   <h2>Daylight Savings Time</h2>
 </a>
 <p>Daylight savings time (DST) presents an issue for date arithmetic.</p>
-<p>The following example adds two days to the Saturday before the clocks
-change using the local timezone (London) and UTC (which does not have DST).</p>
-<pre><code class="language-js"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">addDays</span><span class="hl-1">, </span><span class="hl-2">tzLocal</span><span class="hl-1">, </span><span class="hl-2">tzUtc</span><span class="hl-1"> }</span><br/><br/><span class="hl-8">// The local timezone here is London.</span><br/><span class="hl-8">// In London on Sunday March 26 2000 the clocks go forward 1 hour.</span><br/><br/><span class="hl-2">const</span><span class="hl-1"> </span><span class="hl-2">d1</span><span class="hl-1"> = </span><span class="hl-2">new</span><span class="hl-1"> </span><span class="hl-2">Date</span><span class="hl-1">(</span><span class="hl-3">&#39;2000-03-25T12:00:00&#39;</span><span class="hl-1">)</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-2">log</span><span class="hl-1">(</span><span class="hl-2">d1</span><span class="hl-1">.</span><span class="hl-2">toString</span><span class="hl-1">())</span><br/><span class="hl-8">// Sat Mar 25 2000 12:00:00 GMT+0000 (Greenwich Mean Time)</span><br/><br/><span class="hl-2">const</span><span class="hl-1"> </span><span class="hl-2">d2</span><span class="hl-1"> = </span><span class="hl-2">addDays</span><span class="hl-1">(</span><span class="hl-2">d1</span><span class="hl-1">, 2, </span><span class="hl-2">tzLocal</span><span class="hl-1">)</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-2">log</span><span class="hl-1">(</span><span class="hl-2">d2</span><span class="hl-1">.</span><span class="hl-2">toString</span><span class="hl-1">())</span><br/><span class="hl-8">// Mon Mar 27 2000 12:00:00 GMT+0100 (British Summer Time)</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-2">log</span><span class="hl-1">((</span><span class="hl-2">d2</span><span class="hl-1">.</span><span class="hl-2">getTime</span><span class="hl-1">() - </span><span class="hl-2">d1</span><span class="hl-1">.</span><span class="hl-2">getTime</span><span class="hl-1">()) / 1000 / 60 / 60 + </span><span class="hl-3">&#39; hours&#39;</span><span class="hl-1">)</span><br/><span class="hl-8">// 47 hours</span><br/><br/><span class="hl-2">const</span><span class="hl-1"> </span><span class="hl-2">d3</span><span class="hl-1"> = </span><span class="hl-2">addDays</span><span class="hl-1">(</span><span class="hl-2">d1</span><span class="hl-1">, 2, </span><span class="hl-2">tzUtc</span><span class="hl-1">)</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-2">log</span><span class="hl-1">(</span><span class="hl-2">d3</span><span class="hl-1">.</span><span class="hl-2">toString</span><span class="hl-1">())</span><br/><span class="hl-8">// Mon Mar 27 2000 13:00:00 GMT+0100 (British Summer Time)</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-2">log</span><span class="hl-1">((</span><span class="hl-2">d3</span><span class="hl-1">.</span><span class="hl-2">getTime</span><span class="hl-1">() - </span><span class="hl-2">d1</span><span class="hl-1">.</span><span class="hl-2">getTime</span><span class="hl-1">()) / 1000 / 60 / 60 + </span><span class="hl-3">&#39; hours&#39;</span><span class="hl-1">)</span><br/><span class="hl-8">// 48 hours</span>
+<p>The following example demonstrates how daylight savings time is handled.</p>
+<pre><code class="language-js"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">tzUtc</span><span class="hl-1">, </span><span class="hl-2">fetchTimezone</span><span class="hl-1">, </span><span class="hl-2">addDays</span><span class="hl-1">, </span><span class="hl-2">addHours</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&#39;@jetblack/date&#39;</span><br/><br/><span class="hl-8">// In London on Sunday March 26 2000 the clocks went forward 1 hour at 1am.</span><br/><br/><span class="hl-8">// At midnight the clocks have yet to be put forward.</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">tzLondon</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-6">fetchTimezone</span><span class="hl-1">(</span><span class="hl-3">&#39;Europe/London&#39;</span><span class="hl-1">)</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">mar26</span><span class="hl-1"> = </span><span class="hl-2">tzLondon</span><span class="hl-1">.</span><span class="hl-6">makeDate</span><span class="hl-1">(</span><span class="hl-7">2000</span><span class="hl-1">, </span><span class="hl-7">2</span><span class="hl-1">, </span><span class="hl-7">26</span><span class="hl-1">)</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-2">tzLondon</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">(</span><span class="hl-2">mar26</span><span class="hl-1">))</span><br/><span class="hl-8">// 2000-03-26T00:00:00+00:00</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-2">tzUtc</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">(</span><span class="hl-2">mar26</span><span class="hl-1">))</span><br/><span class="hl-8">// 2000-03-26T00:00:00.000Z</span><br/><br/><span class="hl-8">// Adding one hour from midnight takes the time to 2am as the clocks go forward</span><br/><span class="hl-8">// one hour at 1am.</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">mar26plus1h</span><span class="hl-1"> = </span><span class="hl-6">addHours</span><span class="hl-1">(</span><span class="hl-2">mar26</span><span class="hl-1">, </span><span class="hl-7">1</span><span class="hl-1">)</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-2">tzLondon</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">(</span><span class="hl-2">mar26plus1h</span><span class="hl-1">))</span><br/><span class="hl-8">// 2000-03-26T02:00:00+01:00</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-2">tzUtc</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">(</span><span class="hl-2">mar26plus1h</span><span class="hl-1">))</span><br/><span class="hl-8">// 2000-03-26T01:00:00.000Z</span><br/><br/><span class="hl-8">// Add a day in the context of the London time zone.</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">mar27</span><span class="hl-1"> = </span><span class="hl-6">addDays</span><span class="hl-1">(</span><span class="hl-2">mar26</span><span class="hl-1">, </span><span class="hl-7">1</span><span class="hl-1">, </span><span class="hl-2">tzLondon</span><span class="hl-1">)</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-2">tzLondon</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">(</span><span class="hl-2">mar27</span><span class="hl-1">))</span><br/><span class="hl-8">// 2000-03-27T00:00:00+01:00</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-2">tzUtc</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">(</span><span class="hl-2">mar27</span><span class="hl-1">))</span><br/><span class="hl-8">// 2000-03-26T23:00:00.000Z</span><br/><br/><span class="hl-8">// There were only 23 hours in the day of the 26th.</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">millisInHour</span><span class="hl-1"> = </span><span class="hl-7">1000</span><span class="hl-1"> * </span><span class="hl-7">60</span><span class="hl-1"> * </span><span class="hl-7">60</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">hours26to27</span><span class="hl-1"> = (</span><span class="hl-2">mar27</span><span class="hl-1">.</span><span class="hl-6">getTime</span><span class="hl-1">() - </span><span class="hl-2">mar26</span><span class="hl-1">.</span><span class="hl-6">getTime</span><span class="hl-1">()) / </span><span class="hl-2">millisInHour</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-2">hours26to27</span><span class="hl-1">)</span><br/><span class="hl-8">// 23</span>
 </code></pre>
-<p>When using the local timezone the time of day appears unchanged, and the offset
-become &quot;GMT+0100 (British Summer Time)&quot;. When using UTC the time looks wrong!
-Looking at the time differences we see that adding 2 days in the local timezone
-was 47 hours, while with UTC it was 48 hours.</p>
-<p>With the local timezone the &quot;naturally correct&quot; answer is returned.
-However, the elapsed time will be an hour less than when using UTC.</p>
+<p>The London timezone is the same as UTC in the winter, but an hour ahead in the
+summer. On the midnight of the day of the change London and UTC show the same
+time. Adding an hour shows how the time leaps to 2am in London, but only 1am
+in UTC. Adding a day and calculating the number of hours shows 23.</p>
 <p>Keeping the time change constant (as with UTC) can be useful when plotting
 data, or doing time series calculations (rolling averages, resampling, etc.).</p>
 

diff --git a/manual/guide/date-arithmetic.md b/manual/guide/date-arithmetic.md
@@ -8,39 +8,47 @@ the timezone.
 
 Daylight savings time (DST) presents an issue for date arithmetic.
 
-The following example adds two days to the Saturday before the clocks
-change using the local timezone (London) and UTC (which does not have DST).
+The following example demonstrates how daylight savings time is handled.
 
 ```js
-import { addDays, tzLocal, tzUtc }
-
-// The local timezone here is London.
-// In London on Sunday March 26 2000 the clocks go forward 1 hour.
-
-const d1 = new Date('2000-03-25T12:00:00')
-console.log(d1.toString())
-// Sat Mar 25 2000 12:00:00 GMT+0000 (Greenwich Mean Time)
-
-const d2 = addDays(d1, 2, tzLocal)
-console.log(d2.toString())
-// Mon Mar 27 2000 12:00:00 GMT+0100 (British Summer Time)
-console.log((d2.getTime() - d1.getTime()) / 1000 / 60 / 60 + ' hours')
-// 47 hours
-
-const d3 = addDays(d1, 2, tzUtc)
-console.log(d3.toString())
-// Mon Mar 27 2000 13:00:00 GMT+0100 (British Summer Time)
-console.log((d3.getTime() - d1.getTime()) / 1000 / 60 / 60 + ' hours')
-// 48 hours
+import { tzUtc, fetchTimezone, addDays, addHours } from '@jetblack/date'
+
+// In London on Sunday March 26 2000 the clocks went forward 1 hour at 1am.
+
+// At midnight the clocks have yet to be put forward.
+const tzLondon = await fetchTimezone('Europe/London')
+const mar26 = tzLondon.makeDate(2000, 2, 26)
+console.log(tzLondon.toISOString(mar26))
+// 2000-03-26T00:00:00+00:00
+console.log(tzUtc.toISOString(mar26))
+// 2000-03-26T00:00:00.000Z
+
+// Adding one hour from midnight takes the time to 2am as the clocks go forward
+// one hour at 1am.
+const mar26plus1h = addHours(mar26, 1)
+console.log(tzLondon.toISOString(mar26plus1h))
+// 2000-03-26T02:00:00+01:00
+console.log(tzUtc.toISOString(mar26plus1h))
+// 2000-03-26T01:00:00.000Z
+
+// Add a day in the context of the London time zone.
+const mar27 = addDays(mar26, 1, tzLondon)
+console.log(tzLondon.toISOString(mar27))
+// 2000-03-27T00:00:00+01:00
+console.log(tzUtc.toISOString(mar27))
+// 2000-03-26T23:00:00.000Z
+
+// There were only 23 hours in the day of the 26th.
+const millisInHour = 1000 * 60 * 60
+const hours26to27 = (mar27.getTime() - mar26.getTime()) / millisInHour
+console.log(hours26to27)
+// 23
 ```
 
-When using the local timezone the time of day appears unchanged, and the offset
-become "GMT+0100 (British Summer Time)". When using UTC the time looks wrong!
-Looking at the time differences we see that adding 2 days in the local timezone
-was 47 hours, while with UTC it was 48 hours.
-
-With the local timezone the "naturally correct" answer is returned.
-However, the elapsed time will be an hour less than when using UTC.
+The London timezone is the same as UTC in the winter, but an hour ahead in the
+summer. On the midnight of the day of the change London and UTC show the same
+time. Adding an hour shows how the time leaps to 2am in London, but only 1am
+in UTC. Adding a day and calculating the number of hours shows 23.
 
 Keeping the time change constant (as with UTC) can be useful when plotting
 data, or doing time series calculations (rolling averages, resampling, etc.).