From d66aa0cd76e11b6c71ba05ed82b7ef0b94935e0a Mon Sep 17 00:00:00 2001
From: Dan Gohman <dev@sunfishcode.online>
Date: Tue, 7 Feb 2023 14:43:05 -0800
Subject: [PATCH] Add a timezone API. (#32)

* Add a timezone API.

Add a small timezone API that returns the UTC offset, timezone name, and
daylight saving time status for a given `datetime` timestamp.

This is not a full timezone database API. It's designed so that
implementations that don't wish to do anything with timezones can just
support a single "UTC" time zone, which can be easily implemented.

It's also not a time formatting or locale API. It doesn't say how to
format a human-readable timestamp; it just provides the information that
would typically be formatted into a human-readable timestamp.

This API expects a `timezone` handle argument will be added to the
command entrypoint function, providing programs with a `timezone` to
provide timezone information about wall-clock timestamps.

Fixes #25.
---
 timezone.abi.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++
 timezone.wit.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 186 insertions(+)
 create mode 100644 timezone.abi.md
 create mode 100644 timezone.wit.md

diff --git a/timezone.abi.md b/timezone.abi.md
new file mode 100644
index 0000000..e3af485
--- /dev/null
+++ b/timezone.abi.md
@@ -0,0 +1,93 @@
+# Types
+
+## <a href="#datetime" name="datetime"></a> `datetime`: record
+
+  A time and date in seconds plus nanoseconds.
+  
+  TODO: Use the definition from the monotonic clock API instead of defining our own copy.
+
+Size: 16, Alignment: 8
+
+### Record Fields
+
+- <a href="datetime.seconds" name="datetime.seconds"></a> [`seconds`](#datetime.seconds): `u64`
+
+
+- <a href="datetime.nanoseconds" name="datetime.nanoseconds"></a> [`nanoseconds`](#datetime.nanoseconds): `u32`
+
+
+## <a href="#timezone_display" name="timezone_display"></a> `timezone-display`: record
+
+  Information useful for displaying the timezone of a specific `datetime`.
+  
+  This information may vary within a single `timezone` to reflect daylight
+  saving time adjustments.
+
+Size: 16, Alignment: 4
+
+### Record Fields
+
+- <a href="timezone_display.utc_offset" name="timezone_display.utc_offset"></a> [`utc-offset`](#timezone_display.utc_offset): `u32`
+
+  The number of seconds difference between UTC time and the local time of
+  the timezone.
+  
+  The returned value will always be less than 86400 which is the number of
+  seconds in a day (24*60*60).
+  
+  In implementations that do not expose an actual time zone, this should
+  return 0.
+
+- <a href="timezone_display.name" name="timezone_display.name"></a> [`name`](#timezone_display.name): `string`
+
+  The abbreviated name of the timezone to display to a user. The name `UTC`
+  indicates Coordinated Universal Time. Otherwise, this should reference
+  local standards for the name of the time zone.
+  
+  In implementations that do not expose an actual time zone, this should be
+  the string `UTC`.
+  
+  In time zones that do not have an applicable name, a formatted
+  representation of the UTC offset may be returned, such as `-04:00`.
+
+- <a href="timezone_display.in_daylight_saving_time" name="timezone_display.in_daylight_saving_time"></a> [`in-daylight-saving-time`](#timezone_display.in_daylight_saving_time): `bool`
+
+  Whether daylight saving time is active.
+  
+  In implementations that do not expose an actual time zone, this should
+  return false.
+
+# Functions
+
+----
+
+#### <a href="#timezone_display" name="timezone_display"></a> `timezone::display` 
+
+  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.
+  
+  If the timezone cannot be determined for the given `datetime`, return a
+  `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight
+  saving time.
+##### Params
+
+- <a href="#timezone_display.self" name="timezone_display.self"></a> `self`: handle<timezone>
+- <a href="#timezone_display.when" name="timezone_display.when"></a> `when`: [`datetime`](#datetime)
+##### Results
+
+- [`timezone-display`](#timezone_display)
+
+----
+
+#### <a href="#timezone_utc_offset" name="timezone_utc_offset"></a> `timezone::utc-offset` 
+
+  The same as `display`, but only return the UTC offset.
+##### Params
+
+- <a href="#timezone_utc_offset.self" name="timezone_utc_offset.self"></a> `self`: handle<timezone>
+- <a href="#timezone_utc_offset.when" name="timezone_utc_offset.when"></a> `when`: [`datetime`](#datetime)
+##### Results
+
+- `u32`
+
diff --git a/timezone.wit.md b/timezone.wit.md
new file mode 100644
index 0000000..af2c868
--- /dev/null
+++ b/timezone.wit.md
@@ -0,0 +1,93 @@
+# WASI Clocks Timezone API
+
+## `datetime`
+```wit
+/// A time and date in seconds plus nanoseconds.
+///
+/// TODO: Use the definition from the monotonic clock API instead of defining our own copy.
+record datetime {
+    seconds: u64,
+    nanoseconds: u32,
+}
+```
+
+## `timezone`
+```wit
+/// A timezone.
+///
+/// In timezones that recognize daylight saving time, also known as daylight
+/// time and summer time, the information returned from the functions varies
+/// over time to reflect these adjustments.
+resource timezone {
+```
+
+## `display`
+```wit
+    /// 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.
+    ///
+    /// If the timezone cannot be determined for the given `datetime`, return a
+    /// `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight
+    /// saving time.
+    display: func(when: datetime) -> timezone-display
+```
+
+## `utc-offset`
+```wit
+    /// The same as `display`, but only return the UTC offset.
+    utc-offset: func(when: datetime) -> u32
+```
+
+```wit
+}
+```
+
+## `timezone-display`
+```wit
+/// Information useful for displaying the timezone of a specific `datetime`.
+///
+/// This information may vary within a single `timezone` to reflect daylight
+/// saving time adjustments.
+record timezone-display {
+```
+
+## `utc-offset`
+```wit
+    /// The number of seconds difference between UTC time and the local time of
+    /// the timezone.
+    ///
+    /// The returned value will always be less than 86400 which is the number of
+    /// seconds in a day (24*60*60).
+    ///
+    /// In implementations that do not expose an actual time zone, this should
+    /// return 0.
+    utc-offset: u32,
+```
+
+## `name`
+```wit
+    /// The abbreviated name of the timezone to display to a user. The name `UTC`
+    /// indicates Coordinated Universal Time. Otherwise, this should reference
+    /// local standards for the name of the time zone.
+    ///
+    /// In implementations that do not expose an actual time zone, this should be
+    /// the string `UTC`.
+    ///
+    /// In time zones that do not have an applicable name, a formatted
+    /// representation of the UTC offset may be returned, such as `-04:00`.
+    name: string,
+```
+
+## `in-daylight-saving-time`
+```wit
+    /// Whether daylight saving time is active.
+    ///
+    /// In implementations that do not expose an actual time zone, this should
+    /// return false.
+    in-daylight-saving-time: bool,
+```
+
+```wit
+}
+```