-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 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.
- Loading branch information
1 parent
b0e2566
commit d66aa0c
Showing
2 changed files
with
186 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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` | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
} | ||
``` |