Updated docs

rob-blackbourn · Jul 9, 2023 · e5ae9ef · e5ae9ef
1 parent 89fd204
commit e5ae9ef
Show file tree

Hide file tree

Showing 15 changed files with 247 additions and 206 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/general-usage.html b/docs/pages/guide/general-usage.html
@@ -29,7 +29,7 @@ <h2>Constructing Dates</h2>
   <h2>Deconstructing Dates</h2>
 </a>
 <p>The built in date class has accessor functions to get and set the date parts
-in local and UTC (e.g. 
+in local and UTC (e.g.
 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getMonth"><code>getMonth</code></a>,
 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getUTCMonth"><code>getUTCMonth</code></a>,
 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setMonth"><code>setMonth</code></a>,
@@ -55,8 +55,11 @@ <h2>Displaying Dates</h2>
 <p>This library provides two means of displaying dates: <a href="../../classes/Timezone.html#toISOString"><code>Timezone.toISOString</code></a>
 and <a href="../../modules.html#formatDate"><code>formatDate</code></a>. The <a href="../../classes/Timezone.html#toISOString"><code>Timezone.toISOString</code></a> differs from
 the built in method, in that it displays the date in the context of the provided
-timezone, rather than the local timezone to provide the correct DST offsets. The
-<a href="../../modules.html#formatDate"><code>formatDate</code></a> function is a typical <code>d-mmm-yy</code> style formatter.</p>
+timezone, rather than the local timezone. The
+<a href="../../modules.html#formatDate"><code>formatDate</code></a> function is a typical pattern-style formatter.</p>
+<p>The following demonstrates some of these functions.</p>
+<pre><code class="language-js"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">formatDate</span><span class="hl-1">, </span><span class="hl-2">fetchTimezone</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-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">tzTokyo</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;Asia/Tokyo&#39;</span><span class="hl-1">)</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">tzChicago</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;America/Chicago&#39;</span><span class="hl-1">)</span><br/><br/><span class="hl-8">// Make the dates for 6:30am local time.</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">dateTokyo</span><span class="hl-1"> = </span><span class="hl-2">tzTokyo</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">0</span><span class="hl-1">, </span><span class="hl-7">1</span><span class="hl-1">, </span><span class="hl-7">6</span><span class="hl-1">, </span><span class="hl-7">30</span><span class="hl-1">)</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">dateLondon</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">0</span><span class="hl-1">, </span><span class="hl-7">1</span><span class="hl-1">, </span><span class="hl-7">6</span><span class="hl-1">, </span><span class="hl-7">30</span><span class="hl-1">)</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">dateChicago</span><span class="hl-1"> = </span><span class="hl-2">tzChicago</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">0</span><span class="hl-1">, </span><span class="hl-7">1</span><span class="hl-1">, </span><span class="hl-7">6</span><span class="hl-1">, </span><span class="hl-7">30</span><span class="hl-1">)</span><br/><br/><span class="hl-8">// Show with toISOString.</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">([</span><br/><span class="hl-1">  </span><span class="hl-2">dateTokyo</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">(),</span><br/><span class="hl-1">  </span><span class="hl-2">dateLondon</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">(),</span><br/><span class="hl-1">  </span><span class="hl-2">dateChicago</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">()</span><br/><span class="hl-1">])</span><br/><span class="hl-8">// (3) [&#39;1999-12-31T21:30:00.000Z&#39;, &#39;2000-01-01T06:30:00.000Z&#39;, &#39;2000-01-01T12:30:00.000Z&#39;]</span><br/><br/><span class="hl-8">// The Timezone.toISOString shows them relative to the local timezone.</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">([</span><br/><span class="hl-1">  </span><span class="hl-2">tzTokyo</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">(</span><span class="hl-2">dateTokyo</span><span class="hl-1">),</span><br/><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">dateLondon</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-2">tzChicago</span><span class="hl-1">.</span><span class="hl-6">toISOString</span><span class="hl-1">(</span><span class="hl-2">dateChicago</span><span class="hl-1">)</span><br/><span class="hl-1">])</span><br/><span class="hl-8">// (3) [&#39;2000-01-01T06:30:00+09:00&#39;, &#39;2000-01-01T06:30:00+00:00&#39;, &#39;2000-01-01T06:30:00-06:00&#39;]</span><br/><br/><span class="hl-8">// The formatDate function also handles the timezone.</span><br/><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">([</span><br/><span class="hl-1">  </span><span class="hl-6">formatDate</span><span class="hl-1">(</span><span class="hl-2">dateTokyo</span><span class="hl-1">, </span><span class="hl-3">&#39;d-mmm-yy HH:MM p&#39;</span><span class="hl-1">, </span><span class="hl-2">tzTokyo</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">formatDate</span><span class="hl-1">(</span><span class="hl-2">dateLondon</span><span class="hl-1">, </span><span class="hl-3">&#39;d-mmm-yy HH:MM p&#39;</span><span class="hl-1">, </span><span class="hl-2">tzLondon</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">formatDate</span><span class="hl-1">(</span><span class="hl-2">dateChicago</span><span class="hl-1">, </span><span class="hl-3">&#39;d-mmm-yy HH:MM p&#39;</span><span class="hl-1">, </span><span class="hl-2">tzChicago</span><span class="hl-1">)</span><br/><span class="hl-1">])</span><br/><span class="hl-8">// (3) [&#39;1-Jan-00 06:30 -09:00&#39;, &#39;1-Jan-00 06:30 +00:00&#39;, &#39;1-Jan-00 06:30 +06:00&#39;]</span>
+</code></pre>
 
 <a href="#what-next-" id="what-next-" style="color: inherit; text-decoration: none;">
   <h2>What next ?</h2>

diff --git a/manual/guide/general-usage.md b/manual/guide/general-usage.md
@@ -44,11 +44,10 @@ const tzTokyo = await fetchTimezone('Asia/Tokyo')
 const d3 = parseDate("1-Jul-00 21:00:15.250", "d-mmm-yy HH:MM:SS.FFF", tzTokyo)
 ```
 
-
 ## Deconstructing Dates
 
 The built in date class has accessor functions to get and set the date parts
-in local and UTC (e.g. 
+in local and UTC (e.g.
 [`getMonth`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getMonth),
 [`getUTCMonth`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getUTCMonth),
 [`setMonth`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setMonth),
@@ -85,8 +84,47 @@ allows passing in the IANA timezone.
 This library provides two means of displaying dates: {@linkcode Timezone.toISOString}
 and {@linkcode formatDate}. The {@linkcode Timezone.toISOString} differs from
 the built in method, in that it displays the date in the context of the provided
-timezone, rather than the local timezone to provide the correct DST offsets. The
-{@linkcode formatDate} function is a typical `d-mmm-yy` style formatter.
+timezone, rather than the local timezone. The
+{@linkcode formatDate} function is a typical pattern-style formatter.
+
+The following demonstrates some of these functions.
+
+```js
+import { formatDate, fetchTimezone } from '@jetblack/date'
+
+const tzLondon = await fetchTimezone('Europe/London')
+const tzTokyo = await fetchTimezone('Asia/Tokyo')
+const tzChicago = await fetchTimezone('America/Chicago')
+
+// Make the dates for 6:30am local time.
+const dateTokyo = tzTokyo.makeDate(2000, 0, 1, 6, 30)
+const dateLondon = tzLondon.makeDate(2000, 0, 1, 6, 30)
+const dateChicago = tzChicago.makeDate(2000, 0, 1, 6, 30)
+
+// Show with toISOString.
+console.log([
+  dateTokyo.toISOString(),
+  dateLondon.toISOString(),
+  dateChicago.toISOString()
+])
+// (3) ['1999-12-31T21:30:00.000Z', '2000-01-01T06:30:00.000Z', '2000-01-01T12:30:00.000Z']
+
+// The Timezone.toISOString shows them relative to the local timezone.
+console.log([
+  tzTokyo.toISOString(dateTokyo),
+  tzLondon.toISOString(dateLondon),
+  tzChicago.toISOString(dateChicago)
+])
+// (3) ['2000-01-01T06:30:00+09:00', '2000-01-01T06:30:00+00:00', '2000-01-01T06:30:00-06:00']
+
+// The formatDate function also handles the timezone.
+console.log([
+  formatDate(dateTokyo, 'd-mmm-yy HH:MM p', tzTokyo),
+  formatDate(dateLondon, 'd-mmm-yy HH:MM p', tzLondon),
+  formatDate(dateChicago, 'd-mmm-yy HH:MM p', tzChicago)
+])
+// (3) ['1-Jan-00 06:30 -09:00', '1-Jan-00 06:30 +00:00', '1-Jan-00 06:30 +06:00']
+```
 
 ## What next ?