Rename "datetime" to "instant"

Other possibilities: "system-clock-point", "clock-point" (analogous to
"monotonic-clock-point"), "exact-time", "absolute-time", "timestamp",
"epoch-time".

Author: ptomato

README.md

@@ -88,9 +88,9 @@ default-monotonic-clock: monotonic-clock
 #### Retrieving the timezone:
 
 ```rust
-    let datetime: Datetime = system_clock::now();
+    let instant: Instant = system_clock::now();
 
-    let timezone_display: TimezoneDisplay = timezone::display(datetime);
+    let timezone_display: TimezoneDisplay = timezone::display(instant);
 
     println!("the timezone is {}", timezone_display.name);
 ```

imports.md

@@ -123,19 +123,20 @@ elapsed from the time this function is invoked.</p>
 time. The clock is not necessarily monotonic as it may be reset.</p>
 <p>It is intended to be portable at least between Unix-family platforms and
 Windows.</p>
-<p>A wall clock is a clock which measures the date and time according to
-some external reference.</p>
+<p>An &quot;instant&quot;, or &quot;exact time&quot;, is a point in time without regard to any time
+zone: just the time since a particular external reference point, often
+called an &quot;epoch&quot;.</p>
 <p>External references may be reset, so this clock is not necessarily
 monotonic, making it unsuitable for measuring elapsed time.</p>
 <p>It is intended for reporting the current date and time for humans.</p>
 <hr />
 <h3>Types</h3>
-<h4><a name="datetime"></a><code>record datetime</code></h4>
-<p>A time and date in seconds plus nanoseconds.</p>
+<h4><a name="instant"></a><code>record instant</code></h4>
+<p>An exact time in seconds plus nanoseconds.</p>
 <h5>Record Fields</h5>
 <ul>
-<li><a name="datetime.seconds"></a><code>seconds</code>: <code>u64</code></li>
-<li><a name="datetime.nanoseconds"></a><code>nanoseconds</code>: <code>u32</code></li>
+<li><a name="instant.seconds"></a><code>seconds</code>: <code>u64</code></li>
+<li><a name="instant.nanoseconds"></a><code>nanoseconds</code>: <code>u32</code></li>
 </ul>
 <hr />
 <h3>Functions</h3>
@@ -149,23 +150,24 @@ also known as <a href="https://en.wikipedia.org/wiki/Unix_time">Unix Time</a>.</
 <p>The nanoseconds field of the output is always less than 1000000000.</p>
 <h5>Return values</h5>
 <ul>
-<li><a name="now.0"></a> <a href="#datetime"><a href="#datetime"><code>datetime</code></a></a></li>
+<li><a name="now.0"></a> <a href="#instant"><a href="#instant"><code>instant</code></a></a></li>
 </ul>
 <h4><a name="resolution"></a><code>resolution: func</code></h4>
 <p>Query the resolution of the clock.</p>
 <p>The nanoseconds field of the output is always less than 1000000000.</p>
 <h5>Return values</h5>
 <ul>
-<li><a name="resolution.0"></a> <a href="#datetime"><a href="#datetime"><code>datetime</code></a></a></li>
+<li><a name="resolution.0"></a> <a href="#instant"><a href="#instant"><code>instant</code></a></a></li>
 </ul>
 <h2><a name="wasi_clocks_timezone_0_2_0"></a>Import interface wasi:clocks/[email protected]</h2>
 <hr />
 <h3>Types</h3>
-<h4><a name="datetime"></a><code>type datetime</code></h4>
-<p><a href="#datetime"><a href="#datetime"><code>datetime</code></a></a></p>
+<h4><a name="instant"></a><code>type instant</code></h4>
+<p><a href="#instant"><a href="#instant"><code>instant</code></a></a></p>
 <p>
 #### <a name="timezone_display"></a>`record timezone-display`
-<p>Information useful for displaying the timezone of a specific <a href="#datetime"><code>datetime</code></a>.</p>
+<p>Information useful for displaying a specific <a href="#instant"><code>instant</code></a> in the currently
+configured time zone.</p>
 <p>This information may vary within a single <code>timezone</code> to reflect daylight
 saving time adjustments.</p>
 <h5>Record Fields</h5>
@@ -199,15 +201,15 @@ should return false.</p>
 <hr />
 <h3>Functions</h3>
 <h4><a name="display"></a><code>display: func</code></h4>
-<p>Return information needed to display the given <a href="#datetime"><code>datetime</code></a>. This includes
-the UTC offset, the time zone name, and a flag indicating whether
-daylight saving time is active.</p>
-<p>If the timezone cannot be determined for the given <a href="#datetime"><code>datetime</code></a>, return a
+<p>Return information needed to display the given <a href="#instant"><code>instant</code></a> in the
+currently configured time zone. This includes the UTC offset, the time
+zone name, and a flag indicating whether daylight saving time is active.</p>
+<p>If the currently configured timezone cannot be determined, return a
 <a href="#timezone_display"><code>timezone-display</code></a> for <code>UTC</code> with a <a href="#utc_offset"><code>utc-offset</code></a> of 0 and no daylight
 saving time.</p>
 <h5>Params</h5>
 <ul>
-<li><a name="display.when"></a><code>when</code>: <a href="#datetime"><a href="#datetime"><code>datetime</code></a></a></li>
+<li><a name="display.when"></a><code>when</code>: <a href="#instant"><a href="#instant"><code>instant</code></a></a></li>
 </ul>
 <h5>Return values</h5>
 <ul>
@@ -217,7 +219,7 @@ saving time.</p>
 <p>The same as <a href="#display"><code>display</code></a>, but only return the UTC offset.</p>
 <h5>Params</h5>
 <ul>
-<li><a name="utc_offset.when"></a><code>when</code>: <a href="#datetime"><a href="#datetime"><code>datetime</code></a></a></li>
+<li><a name="utc_offset.when"></a><code>when</code>: <a href="#instant"><a href="#instant"><code>instant</code></a></a></li>
 </ul>
 <h5>Return values</h5>
 <ul>

wit/system-clock.wit

@@ -5,18 +5,19 @@ package wasi:[email protected];
 /// It is intended to be portable at least between Unix-family platforms and
 /// Windows.
 ///
-/// A wall clock is a clock which measures the date and time according to
-/// some external reference.
+/// An "instant", or "exact time", is a point in time without regard to any time
+/// zone: just the time since a particular external reference point, often
+/// called an "epoch".
 ///
 /// External references may be reset, so this clock is not necessarily
 /// monotonic, making it unsuitable for measuring elapsed time.
 ///
 /// It is intended for reporting the current date and time for humans.
 @since(version = 0.2.0)
 interface system-clock {
-    /// A time and date in seconds plus nanoseconds.
+    /// An exact time in seconds plus nanoseconds.
     @since(version = 0.2.0)
-    record datetime {
+    record instant {
         seconds: u64,
         nanoseconds: u32,
     }
@@ -35,11 +36,14 @@ interface system-clock {
     /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16
     /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time
     @since(version = 0.2.0)
-    now: func() -> datetime;
+    now: func() -> instant;
 
     /// Query the resolution of the clock.
     ///
     /// The nanoseconds field of the output is always less than 1000000000.
     @since(version = 0.2.0)
-    resolution: func() -> datetime;
+    resolution: func() -> instant;
+    // NOTE: This return value doesn't represent an exact time, so maybe is not
+    // a correct use of the Instant type. Would it make sense to have a
+    // system-clock::duration analogous to monotonic-clock::duration?
 }

wit/timezone.wit

@@ -3,23 +3,24 @@ package wasi:[email protected];
 @unstable(feature = clocks-timezone)
 interface timezone {
     @unstable(feature = clocks-timezone)
-    use system-clock.{datetime};
+    use system-clock.{instant};
 
-    /// Return information needed to display the given `datetime`. This includes
-    /// the UTC offset, the time zone name, and a flag indicating whether
-    /// daylight saving time is active.
+    /// Return information needed to display the given `instant` in the
+    /// currently configured time zone. This includes the UTC offset, the time
+    /// zone name, and a flag indicating whether daylight saving time is active.
     ///
-    /// If the timezone cannot be determined for the given `datetime`, return a
+    /// If the currently configured timezone cannot be determined, return a
     /// `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight
     /// saving time.
     @unstable(feature = clocks-timezone)
-    display: func(when: datetime) -> timezone-display;
+    display: func(when: instant) -> timezone-display;
 
     /// The same as `display`, but only return the UTC offset.
     @unstable(feature = clocks-timezone)
-    utc-offset: func(when: datetime) -> s32;
+    utc-offset: func(when: instant) -> s32;
 
-    /// Information useful for displaying the timezone of a specific `datetime`.
+    /// Information useful for displaying a specific `instant` in the currently
+    /// configured time zone.
     ///
     /// This information may vary within a single `timezone` to reflect daylight
     /// saving time adjustments.