Skip to content

Commit

Permalink
Add timezone back in. (#61)
Browse files Browse the repository at this point in the history
* Add timezone back in.

Update README with markdown generation step.

* Add `@unstable` feature gates for `timezone`

* Update wit/world.wit

---------

Co-authored-by: Yosh <[email protected]>
Co-authored-by: Dan Gohman <[email protected]>
  • Loading branch information
3 people authored Jun 14, 2024
1 parent ac8639d commit 4c5d1ef
Show file tree
Hide file tree
Showing 5 changed files with 137 additions and 1 deletion.
4 changes: 3 additions & 1 deletion .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,6 @@ jobs:
./wit-deps lock
git add -N wit/deps
git diff --exit-code
- uses: WebAssembly/wit-abi-up-to-date@v20
- uses: WebAssembly/wit-abi-up-to-date@v21
with:
features: clocks-timezone
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ WASI clocks must have at least two complete independent implementations.
- [[Alternative 2]](#alternative-2)
- [Stakeholder Interest & Feedback](#stakeholder-interest--feedback)
- [References & acknowledgements](#references--acknowledgements)
- [Development](#development)

### Introduction

Expand Down Expand Up @@ -132,3 +133,13 @@ Many thanks for valuable feedback and advice from:
- [Person 1]
- [Person 2]
- [etc.]

### Development

#### Generating imports.md

The file `imports.md` is generated using [wit-bindgen](https://github.com/bytecodealliance/wit-bindgen).

```bash
wit-bindgen markdown wit --html-in-md --features clocks-timezone
```
66 changes: 66 additions & 0 deletions imports.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
<li>interface <a href="#wasi_io_poll_0_2_0"><code>wasi:io/[email protected]</code></a></li>
<li>interface <a href="#wasi_clocks_monotonic_clock_0_2_0"><code>wasi:clocks/[email protected]</code></a></li>
<li>interface <a href="#wasi_clocks_wall_clock_0_2_0"><code>wasi:clocks/[email protected]</code></a></li>
<li>interface <a href="#wasi_clocks_timezone_0_2_0"><code>wasi:clocks/[email protected]</code></a></li>
</ul>
</li>
</ul>
Expand Down Expand Up @@ -158,3 +159,68 @@ also known as <a href="https://en.wikipedia.org/wiki/Unix_time">Unix Time</a>.</
<ul>
<li><a name="resolution.0"></a> <a href="#datetime"><a href="#datetime"><code>datetime</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>
<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>This information may vary within a single <code>timezone</code> to reflect daylight
saving time adjustments.</p>
<h5>Record Fields</h5>
<ul>
<li>
<p><a name="timezone_display.utc_offset"></a><a href="#utc_offset"><code>utc-offset</code></a>: <code>s32</code></p>
<p>The number of seconds difference between UTC time and the local
time of the timezone.
<p>The returned value will always be less than 86400 which is the
number of seconds in a day (24<em>60</em>60).</p>
<p>In implementations that do not expose an actual time zone, this
should return 0.</p>
</li>
<li>
<p><a name="timezone_display.name"></a><code>name</code>: <code>string</code></p>
<p>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.
<p>In implementations that do not expose an actual time zone, this
should be the string <code>UTC</code>.</p>
<p>In time zones that do not have an applicable name, a formatted
representation of the UTC offset may be returned, such as <code>-04:00</code>.</p>
</li>
<li>
<p><a name="timezone_display.in_daylight_saving_time"></a><code>in-daylight-saving-time</code>: <code>bool</code></p>
<p>Whether daylight saving time is active.
<p>In implementations that do not expose an actual time zone, this
should return false.</p>
</li>
</ul>
<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
<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>
</ul>
<h5>Return values</h5>
<ul>
<li><a name="display.0"></a> <a href="#timezone_display"><a href="#timezone_display"><code>timezone-display</code></a></a></li>
</ul>
<h4><a name="utc_offset"></a><code>utc-offset: func</code></h4>
<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>
</ul>
<h5>Return values</h5>
<ul>
<li><a name="utc_offset.0"></a> <code>s32</code></li>
</ul>
55 changes: 55 additions & 0 deletions wit/timezone.wit
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
package wasi:clocks@0.2.0;

@unstable(feature = clocks-timezone)
interface timezone {
@unstable(feature = clocks-timezone)
use wall-clock.{datetime};

/// 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.
@unstable(feature = clocks-timezone)
display: func(when: datetime) -> timezone-display;

/// The same as `display`, but only return the UTC offset.
@unstable(feature = clocks-timezone)
utc-offset: func(when: datetime) -> s32;

/// Information useful for displaying the timezone of a specific `datetime`.
///
/// This information may vary within a single `timezone` to reflect daylight
/// saving time adjustments.
@unstable(feature = clocks-timezone)
record timezone-display {
/// 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: s32,

/// 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,

/// 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,
}
}
2 changes: 2 additions & 0 deletions wit/world.wit
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,6 @@ package wasi:[email protected];
world imports {
import monotonic-clock;
import wall-clock;
@unstable(feature = clocks-timezone)
import timezone;
}

0 comments on commit 4c5d1ef

Please sign in to comment.